跳到主要内容

命令格式

每一个 zNS 操作都是一笔发往注册方协议地址的屏蔽 ZCash 交易,其中金额即付款,备注即已签名的命令。 两者同处一张票据之中,因此意图与付款被原子性地绑定在一起——不存在需要另行对账的单据或发票。

本页给出确切的传输格式。按此构造的命令,注册方与零知识电路都会接受。

结构​

所有命令都是以冒号分隔的 ASCII,以协议标记和版本开头:

zNS:1:{OP}:{name}:…:{ed25519_pubkey_hex}:…:{nonce}:{signature_hex}

中间的字段取决于具体操作:

操作备注结构应付金额
REG 注册zNS:1:REG:{name}:{address}:{pubkey}:{nonce}:{sig}按名称长度计的注册费
UPD 更改地址zNS:1:UPD:{name}:{address}:{pubkey}:{nonce}:{sig}变更费
CHG 转让持有者zNS:1:CHG:{name}:{new_pubkey}:{nonce}:{sig}变更费
LST 挂牌出售zNS:1:LST:{name}:{pubkey}:{price}:{nonce}:{sig}变更费
ULT 下架zNS:1:ULT:{name}:{pubkey}:{nonce}:{sig}变更费
BUY 购买zNS:1:BUY:{name}:{address}:{pubkey}:{nonce}:{sig}恰好为挂牌价格

对于 CHG,{new_pubkey} 是接收方持有者的密钥,而签名由转出方持有者做出——授权转让的是当前 持有者。

被签名的消息​

签名覆盖不含末尾 :{signature} 的命令——也就是从标记一直到 nonce(含)为止的全部内容:

zNS:1:REG:richard.zcash:u1…:0101…0101:1780000001

规则很严格,客户端只要违反其中任何一条,产生的签名都会被电路拒绝:

  • pubkey 为小写十六进制,64 个字符。
  • price 仅出现在 LST 中。
  • address 仅出现在 REG、UPD 和 BUY 中。
  • price 与 nonce 为十进制,无前导零、无符号、无补位。
  • 签名是对上述确切字节做出的 Ed25519 签名,十六进制编码,128 个字符。

验证是严格的:非规范签名与小阶密钥都会被拒绝。

字段规则​

名称​

规则取值
字符a-z、0-9、连字符
长度含区域在内共 1–64 个字符
大小写仅小写 — 名称以小写存储并哈希
连字符不在开头、不在结尾,且绝不连续
区域.zcash、.zec、.private、.secure、.safe

只允许出现恰好一个点,用于分隔标签与区域。

目标地址​

名称解析到的地址必须是主网上带有 Orchard 接收器的 Unified Address。不含该接收器的地址会被拒绝。

原因是实际需要而非随意规定:注册方通过 Orchard 密钥材料收款与付款,而按照 ZIP 229,该密钥材料同样覆盖 Ironwood 资金池。没有 Orchard 接收器的 地址无法收款,因此既不能用于退款,也不能用于销售所得。

提示

Ironwood 并未新增接收器

Ironwood 是一个新的价值池,而不是新的地址格式。钱包把票据迁移进去,而收款地址仍然是 Orchard 地址。 当前钱包的 Unified Address 无需改动即可使用。

Nonce​

nonce 是你签名那一刻的 Unix 时间戳(秒)。

  • 它必须严格大于该名称当前记录的 nonce。正是这一点阻止了旧的已签名命令被重放。
  • 它领先于承载它的区块不得超过 300 秒;这个余量足以吸收通常的时钟偏差,却不允许把 nonce 停放在遥远 的未来。

首次注册时,任何当前时间戳都可以。

价格​

只有 LST 携带价格。它是一个整数 zatoshi(1 ZEC = 100,000,000 zatoshi),且必须大于零。

允许以新价格重新挂出已挂牌的名称——再发送一条 LST 即可。以最近的一条为准。

大小限制​

ZCash 备注恰好占 512 字节,整条命令必须放得下。固定部分占用的空间是可预测的:

zNS:1:{OP}: … marker, version, operation 10 bytes
{pubkey} 64 hex characters 65 bytes with separator
{nonce} 10 digits today 11 bytes with separator
{signature} 128 hex characters 128 bytes

余下 296 字节,由名称和目标地址共同分享,各自后面的分隔符也计算在内。即使是最长的名称(64 个字符),也会给地址留下 232 个字符:多于只含 Orchard 接收器的地址所需的长度(106 个字符),但带有多个接收器的 Unified Address 可能很长,因此当名称很长时,很长的地址就可能放不下。客户端应当计算这个预算,并在用户付款之前给出提示,而不是让交易在事后失败。

付款​

金额与备注同样决定着有效性:

  • REG 必须恰好支付与名称长度对应的注册费。
  • UPD、CHG、LST、ULT 必须恰好支付变更费。
  • BUY 必须恰好支付挂牌价格。

长度按标签计算,不含区域:ab.zcash 是一个 2 字符的名称。

支付不足或超额的命令不会被处理,未通过格式或签名检查的备注也一样。只要支付至少 0.005 ZEC,且仍能读到这一步——zNS:1: 开头、已知的操作和有效的公钥(对 CHG 而言是一个存在的名称)——两者都会退回你的内部余额。CHG 写的是新所有者而不是签名者,因此它的退款会给签署它的那位名称所有者;没有任何所有者签署的 CHG 不予退款。退款在 120 个确认后记入,之后即可提现——参见问答。

顺序​

命令按 ZCash 产生它们的顺序处理:先按区块高度,再按区块内的交易索引。注册方并不选择顺序,也无法在不导致每个独立索引器算出不同根的前提下重新排序。

一笔交易只携带一条命令:在发往注册方的票据(note)中,按 action 顺序排在最前、且备注是格式正确的命令的那一个。同一交易中发往注册方的其他票据既不会被处理,也不会被自动退款,所以请每条命令单独用一笔交易发送。

对于相互竞争的操作——同一名称的两条 REG,或同一挂牌的两条 BUY——按该顺序排在最前的那条获胜,其余 的金额退回内部余额。

完整示例​

注册 richard.zcash:

1. Generate an Ed25519 keypair. The public key is your identity across all your names.

2. Build the message to sign (note: no trailing signature field):

zNS:1:REG:richard.zcash:u1mvnsq85wane…:3757ee1a…a53:1780000001

3. Sign it with the private key; hex-encode the 64-byte signature.

4. Append it to form the memo:

zNS:1:REG:richard.zcash:u1mvnsq85wane…:3757ee1a…a53:1780000001:cfec7a58…04

5. Send a shielded transaction to the registrar address, with that memo, paying the
registration fee for a 7-character name.

支付获得 20 个确认(约 25 分钟)后,命令进入下一个批次;批次约十分钟后关闭,随后被证明并锚定。此后 richard.zcash 就能通过任何索引器解析,并附带一份你可以自行验证的默克尔证明。