# BNSv2 如何运作

## 架构概览

BNSv2 是由两个 Clarity 合约实现的： `.BNS-V2` 和 `.zonefile-resolver` 这两个 Clarity 合约共同管理：

1. 命名空间注册与管理
2. 名称注册（预购/揭示和快速认领）
3. 记录存储（通过 zonefile-resolver）
4. 所有权转移
5. 续期
6. 市场功能（上架、下架、购买）
7. 主名称指定

所有状态都保存在链上，并且可公开验证。

<table><thead><tr><th width="162.8984375"></th><th>主网</th><th>测试网</th></tr></thead><tbody><tr><td>BNSv2</td><td><code>SP2QEZ06AGJ3RKJPBV14SY1V5BBFNAW33D96YPGZF.BNS-V2</code></td><td><code>ST2QEZ06AGJ3RKJPBV14SY1V5BBFNAW33D9SZJQ0M.BNS-V2</code></td></tr><tr><td>Zonefile 解析器</td><td><code>SP2QEZ06AGJ3RKJPBV14SY1V5BBFNAW33D96YPGZF.zonefile-resolver</code></td><td><code>ST2QEZ06AGJ3RKJPBV14SY1V5BBFNAW33D9SZJQ0M.zonefile-resolver</code></td></tr></tbody></table>

#### 名称解析

解析过程如下：

1. 用户使用名称和命名空间查询 zonefile-resolver 合约
2. 解析器检查该名称是否有效、未被撤销，并且仍在续期窗口内（跨合约调用 BNS-V2）
3. 返回 zonefile 数据（所有者、zonefile 缓冲区、撤销状态）
4. 应用程序解析 zonefile JSON 以提取地址、资料等。

对于名称所有权/属性（不含 zonefile 数据），你需要直接查询 BNS-V2 合约。正确性不需要任何中心化 DNS 服务器或链下依赖。

{% hint style="info" %}
BNSv2 已废弃 V1 风格的链下子域名（Atlas 网络 / TXT 记录）和 DID 合规性。子域名现在定义在名称的 zonefile 中，并存储在链上。有关 BNSv1 的旧版文档，请访问 [这里](https://docs.stacks.co/learn/network-fundamentals/bitcoin-name-system).
{% endhint %}

***

## Zonefile

在这个升级中，Zonefile 也有了明显不同的变化。

此前，BNS zonefile 是构建在“atlas”网络之上的。Atlas 是内置于 Stacks 节点软件中的一种协议，用于复制和分发 zonefile。在 BNSv1 中，BNS 应用和 API 只识别属于 Atlas 网络的 zonefile。

这个 `zonefile-resolver` 合约存储一个 `(optional (buff 8192))`。该合约本身没有任何特定于 IPFS 的逻辑。它存储原始字节——在应用层面，这些字节可以是完整的 JSON zonefile，或者是指向外部存储的 CID/URL。

总体而言，这种架构提供了一种灵活且可扩展的解决方案，将链上存储的安全性和即时性与去中心化链下存储的可扩展性和高效性结合起来。

这些变化可以从两个方面概括：

1. Zonefile，或指向 zonefile 的链接，现在都存储在链上
2. Zonefile 现在已从 BNS-V2 合约中解耦。Zonefile 现在链上存储，并位于其自己的合约中： `.zonefile-resolver`。该合约相当有限，只包含一个映射和三个函数： `resolve-name`, `update-zonefile` & `revoke-name`.

在这种设计下，一个专用智能合约负责管理所有与 zonefile 相关的功能。该合约支持直接在链上存储最多 8,192 字节（8 KB）的 zonefile，并将 zonefile 通过确定性方式与其对应的名称和命名空间关联起来。这确保较小的 zonefile 可以立即可用、难以篡改，并受到底层区块链保证的保护。

{% code title="名称的 zonefile 信息数据映射" %}

```clarity
;; zonefile map: 存储命名空间中每个名称的 zonefile 信息
;; 键：{name: (buff 48), namespace: (buff 20)}
;; 值：{owner: principal, zonefile: (optional (buff 8192)), revoked: bool}
(define-map zonefile {name: (buff 48), namespace: (buff 20)} 
    {
        owner: principal,
        zonefile: (optional (buff 8192)),
        revoked: bool
    }
)
```

{% endcode %}

Zonefile 在技术上以十六进制编码的 UTF-8 JSON 形式存储。合约中定义的最大长度为 8,192 字节（8 KB）。以下 JSON schema 是 BNSv2 应用和官方 API 使用的标准格式。合约本身只存储原始字节，不强制执行这种结构。

{% code title="Zonefile 结构" expandable="true" %}

```json
{
	"owner": "SP...",
	"btc": "bc1...",
	"bio": "用户简介...",
	"website": "www.url.com",
	"pfp": "www.mypfp.com/image.png", // 必须是有效的图片格式（例如 .png、.jpg、.svg）
	"name": "用户姓名",
	"location": "城市，国家",
	"social": [
		{
			"platform": "x", 
			"username": "用户名"
		},
		{
			"platform": "telegram", 
			"username": "用户名"
		}
		// ...
	],
	"addresses": [
		{
			"network": "btc",
			"address": "bc1...",
			"type": "payment"
		},
		{
			"network": "btc",
			"address": "bc1...",
			"type": "ordinal"
		},
		{
			"network": "eth",
			"address": "0x123...",
			"type": "wallet"
		}
		// ...
	],
	"meta": [
		{
			"name": "example",
			"value": "自定义数据"
		}
		// ...
	],
	"subdomains": [
		{
			"test": {
				"owner": "SP....",
				"bio": "子域名简介..",
				"website": "www.url.com",
				"pfp": "www.mypfp.com/image.png",
				"name": "用户姓名",
				"location": "城市，国家",
				"social": [
					{
						"platform": "x",
						"username": "@username"
					}
				],
				"addresses": [
					{
						"network": "比特币",
						"address": "bc1...",
						"type": "payment"
					}
				]
			}
		}
		// ...
	],
	"externalSubdomainsFile": "www.url.com/subdomains.json" // 可选：包含子域名定义的外部文件
}
```

{% endcode %}

API 层抽象了解析逻辑，会自动判断是直接从合约中检索 zonefile 数据，还是使用存储的 CID 通过 IPFS 检索。因此，客户端可以通过一致的接口解析任意给定名称和命名空间的 zonefile 信息，而无需手动管理存储差异。

查看 [BNSv2 SDK](https://github.com/Strata-Labs/bns-v2-sdk) 了解更多关于 zonefile 的信息。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.stacks.co/learn/zh/network-fundamentals/bitcoin-name-system/architecture.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.