# 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 %}

***

## Zonefiles

在此升级中，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 映射：存储命名空间中每个名称的 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 模式是 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": "Bitcoin",
						"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 的更多信息。