跳到主要内容

命令格式

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

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

结构​

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

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

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

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

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

被签名的消息​

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

PiNS:1:REG:richard.pivx:ps1f84lvgj…:0101…0101:1780000001

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

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

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

字段规则​

名称​

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

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

目标地址​

名称所解析到的地址必须是主网上的 PIVX Sapling 屏蔽支付地址——bech32 编码,人类可读前缀 ps,恰好 78 个字符。透明地址以及其他任何形式都会被拒绝。

这个长度并非随意规定。Sapling 支付地址是 43 字节的载荷——11 字节的多样化因子加上 32 字节的 pk_d——bech32 将其编码为 69 个数据字符再加 6 个校验字符,因此 ps + 分隔符 + 69 + 6 = 78。

这条规则属于协议本身:索引器和电路以相同方式执行它,并且还要求地址使用小写——Bech32 校验和不区分大小写,否则同一地址的两种写法会在树中得到两个不同的叶子。它并非源于注册方的付款方式:退款和销售所得从不会发往名称所指向的地址,而是记入某个 Ed25519 密钥的内部余额,由该密钥的持有者从中提取。

提示

只接受现代的 bech32 形式

旧的测试网形式 ptestsapling…(88 个字符)在两个网络上都会被拒绝,而且电路强制的规则与注册方 完全一致。任何当前版本的 PIVX 钱包在主网上都会生成 ps… 形式。

Nonce​

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

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

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

nonce 不大于已记录值的命令会被拒绝,其付款会退回到你的内部余额,而每次从内部余额提现都会扣除 5% 的服务费。时钟偏慢,或者在同一秒内为同一名称签名两条命令,都会导致这种情况。因此,请取当前时间与该名称最新 nonce 加一秒两者中的较大者;最新 nonce 指名称解析返回的 nonce,或你为该名称发出、仍在等待处理的命令的 nonce,以较晚者为准。

价格​

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

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

大小限制​

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

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

Sapling 地址固定为 78 个字符,因此与长度可变的地址格式不同,这个预算很容易推算:留给名称的 大约还有 218 字节,远多于名称最多可用的 64 个字符。实际上命令总能放得下。即便如此,客户端仍 应当计算这个预算而不是想当然,这样将来新增的字段才不会悄无声息地把备注撑爆。

付款​

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

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

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

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

备注中哪怕只含一个可打印 ASCII 以外字符的支付,无论金额多少都不会自动退款,低于 0.01 PIVX 的支付也不会:这类支付会报告给 PIVX Name 团队——参见问答。

顺序​

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

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

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

完整示例​

注册 richard.pivx:

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):

PiNS:1:REG:richard.pivx:ps1f84lvgj0awz…:3757ee1a…a53:1780000001

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

4. Append it to form the memo:

PiNS:1:REG:richard.pivx:ps1f84lvgj0awz…: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.

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