bns

BNS Skill

通过 BNS V2（推荐用于 .btc）并在必要时回退到 BNS V1，为 .btc 域名提供 Bitcoin Name System（BNS）操作。读取操作无需钱包。写入操作（claim-fast、preorder、register）需要已解锁的钱包。

用法

bun run bns/bns.ts <subcommand> [options]

子命令

lookup

将 .btc 域名解析为 Stacks 地址。

bun run bns/bns.ts lookup --name <name>

选项：

• --name（必填）— 要查询的 BNS 名称（例如，alice.btc 或 alice）

输出：

{
  "name": "alice.btc",
  "found": true,
  "address": "SP1...",
  "namespace": "btc",
  "expireBlock": 900000,
  "network": "mainnet"
}

reverse-lookup

获取某个地址拥有的所有 BNS 域名。

bun run bns/bns.ts reverse-lookup [--address <addr>]

选项：

• --address（可选）— 要查询的 Stacks 地址（若省略，则使用当前钱包）

输出：

{
  "address": "SP1...",
  "network": "mainnet",
  "namesCount": 2,
  "names": ["alice.btc", "myname.btc"]
}

get-info

获取 BNS 域名的详细信息。

bun run bns/bns.ts get-info --name <name>

选项：

• --name（必填）— 要查询的 BNS 名称（例如，alice.btc）

输出：

{
  "network": "mainnet",
  "found": true,
  "name": "alice.btc",
  "namespace": "btc",
  "address": "SP1...",
  "expireBlock": 900000,
  "gracePeriod": 0,
  "status": "active"
}

check-availability

检查 BNS 域名是否可注册。

bun run bns/bns.ts check-availability --name <name>

选项：

• --name（必填）— 要检查的 BNS 名称（例如，alice 或 alice.btc）

输出：

{
  "name": "alice.btc",
  "available": true,
  "network": "mainnet"
}

get-price

获取 BNS 域名的注册价格，单位为 STX。

bun run bns/bns.ts get-price --name <name>

选项：

• --name（必填）— 要检查的 BNS 名称（例如，alice 或 alice.btc）

输出：

{
  "name": "alice.btc",
  "network": "mainnet",
  "price": {
    "units": "ustx",
    "microStx": "2000000",
    "stx": "2 STX"
  }
}

list-user-domains

列出某个地址拥有的所有 BNS 域名。

bun run bns/bns.ts list-user-domains [--address <addr>]

选项：

• --address（可选）— 要检查的 Stacks 地址（若省略，则使用当前钱包）

输出：

{
  "address": "SP1...",
  "network": "mainnet",
  "domainsCount": 1,
  "domains": ["alice.btc"]
}

claim-fast

通过单笔交易注册 BNS 域名（推荐用于 .btc 名称）。以 STX 销毁该名称的价格，并原子化地铸造 BNS NFT。需要已解锁的钱包。

bun run bns/bns.ts claim-fast --name <name> [--send-to <addr>]

选项：

• --name（必填）— 要认领的 BNS 名称（例如，myname 或 myname.btc）
• --send-to（可选）— 接收方地址（默认为钱包自身地址）

输出：

{
  "success": true,
  "method": "name-claim-fast (single transaction)",
  "name": "myname.btc",
  "sendTo": "SP1...",
  "txid": "0xabc...",
  "network": "mainnet",
  "price": { "microStx": "2000000", "stx": "2 STX" },
  "message": "Name \"myname.btc\" claimed! Once confirmed (~10 min), it will be registered.",
  "explorerUrl": "https://explorer.hiro.so/txid/0xabc..."
}

preorder

预订 BNS 域名（两步注册的第 1 步）。仅在无法使用 claim-fast 时使用。请保存返回的 salt，注册步骤需要用到它。需要已解锁的钱包。

bun run bns/bns.ts preorder --name <name> [--salt <hex>]

选项：

• --name（必填）— 要预订的 BNS 名称
• --salt（可选）— 用于预订哈希的十六进制 salt（若省略则自动生成）

输出：

{
  "success": true,
  "step": "1 of 2 (preorder)",
  "name": "myname.btc",
  "salt": "a1b2c3...",
  "txid": "0xdef...",
  "network": "mainnet",
  "nextStep": "Wait ~10 minutes, then call register with the same name and salt."
}

register

预订得到确认后注册 BNS 域名（两步注册的第 2 步）。必须使用预订步骤中的同一个 salt。需要已解锁的钱包。

bun run bns/bns.ts register --name <name> --salt <hex>

选项：

• --name（必填）— 要注册的 BNS 名称（必须与预订的名称一致）
• --salt（必填）— 预订步骤中使用的十六进制 salt

输出：

{
  "success": true,
  "step": "2 of 2 (register)",
  "name": "myname.btc",
  "txid": "0xghi...",
  "network": "mainnet",
  "message": "Registration submitted! Once confirmed, \"myname.btc\" will be registered.",
  "explorerUrl": "https://explorer.hiro.so/txid/0xghi..."
}

注意事项

• 读取操作（lookup、reverse-lookup、get-info、check-availability、get-price、list-user-domains）无需钱包
• 写入操作（claim-fast、preorder、register）需要已解锁的钱包（bun run wallet/wallet.ts unlock）
• 注册 .btc 名称时，优先使用 claim-fast，它可通过单笔交易完成注册，无需等待
• 仅对非 .btc 命名空间，或无法使用 claim-fast 时，才使用两步 preorder/register 流程
• .btc 名称使用 BNS V2；其他命名空间则回退使用 BNS V1