bns

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

BNS Skill

Provides Bitcoin Name System (BNS) operations for .btc domain names using BNS V2 (recommended for .btc) with fallback to BNS V1. Read operations work without a wallet. Write operations (claim-fast, preorder, register) require an unlocked wallet.

该工具针对.btc域名提供比特币名称系统（BNS）操作，默认使用BNS V2（推荐用于.btc域名），并兼容BNS V1作为备选。查询类操作无需钱包即可使用。写入类操作（claim-fast、预注册、注册）需要解锁钱包。

Usage

使用方法

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

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

Subcommands

子命令

lookup

Resolve a .btc domain name to its Stacks address.

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

Options:

```
--name
```
(required) — BNS name to lookup (e.g.,
```
alice.btc
```
or
```
alice
```
)

Output:

json

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

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

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

选项：

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

输出：

json

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

reverse-lookup

Get all BNS domain names owned by an address.

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

Options:

```
--address
```
(optional) — Stacks address to lookup (uses active wallet if omitted)

Output:

json

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

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

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

选项：

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

输出：

json

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

get-info

Get detailed information about a BNS domain name.

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

Options:

```
--name
```
(required) — BNS name to look up (e.g.,
```
alice.btc
```
)

Output:

json

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

获取BNS域名的详细信息。

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

选项：

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

输出：

json

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

check-availability

Check if a BNS domain name is available for registration.

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

Options:

```
--name
```
(required) — BNS name to check (e.g.,
```
alice
```
or
```
alice.btc
```
)

Output:

json

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

检查BNS域名是否可注册。

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

选项：

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

输出：

json

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

get-price

Get the registration price for a BNS domain name in STX.

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

Options:

```
--name
```
(required) — BNS name to check (e.g.,
```
alice
```
or
```
alice.btc
```
)

Output:

json

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

获取BNS域名的注册价格（以STX为单位）。

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

选项：

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

输出：

json

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

list-user-domains

List all BNS domains owned by an address.

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

Options:

```
--address
```
(optional) — Stacks address to check (uses active wallet if omitted)

Output:

json

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

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

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

选项：

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

输出：

json

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

claim-fast

Register a BNS domain name in a single transaction (recommended method for .btc names). Burns the name price in STX and mints the BNS NFT atomically. Requires an unlocked wallet.

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

Options:

```
--name
```
(required) — BNS name to claim (e.g.,
```
myname
```
or
```
myname.btc
```
)
```
--send-to
```
(optional) — Recipient address (defaults to wallet's own address)

Output:

json

{
  "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..."
}

通过单交易注册BNS域名（.btc域名推荐使用此方法）。会销毁对应数量的STX作为域名费用，并自动铸造BNS NFT。需要解锁钱包。

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

选项：

```
--name
```
（必填）—— 要申领的BNS名称（例如：
```
myname
```
或
```
myname.btc
```
）
```
--send-to
```
（可选）—— 接收地址（默认使用钱包自身地址）

输出：

json

{
  "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

Preorder a BNS domain name (step 1 of 2-step registration). Use this only when claim-fast is unavailable. Save the returned salt — you need it for the register step. Requires an unlocked wallet.

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

Options:

```
--name
```
(required) — BNS name to preorder
```
--salt
```
(optional) — Hex salt for the preorder hash (auto-generated if omitted)

Output:

json

{
  "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."
}

预注册BNS域名（两步式注册流程的第一步）。仅当claim-fast不可用时使用。请保存返回的salt值——注册步骤需要用到它。需要解锁钱包。

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

选项：

```
--name
```
（必填）—— 要预注册的BNS名称
```
--salt
```
（可选）—— 预注册哈希的十六进制salt值（若省略则自动生成）

输出：

json

{
  "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

Register a BNS domain name after preorder is confirmed (step 2 of 2-step registration). Must use the same salt from the preorder step. Requires an unlocked wallet.

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

Options:

```
--name
```
(required) — BNS name to register (must match the preordered name)
```
--salt
```
(required) — The hex salt used in the preorder step

Output:

json

{
  "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..."
}

预注册确认后，注册BNS域名（两步式注册流程的第二步）。必须使用预注册步骤中相同的salt值。需要解锁钱包。

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

选项：

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

输出：

json

{
  "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..."
}

Notes

注意事项

Read operations (lookup, reverse-lookup, get-info, check-availability, get-price, list-user-domains) work without a wallet
Write operations (claim-fast, preorder, register) require an unlocked wallet (
```
bun run wallet/wallet.ts unlock
```
)
For .btc registration, prefer
```
claim-fast
```
— it registers in a single transaction without a waiting period
Use the 2-step preorder/register flow only for non-.btc namespaces or if claim-fast is unavailable
BNS V2 is used for .btc names; BNS V1 is used as fallback for other namespaces

查询类操作（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不可用时，才使用两步式预注册/注册流程
.btc域名使用BNS V2；其他命名空间默认使用BNS V1作为备选