Command Format

Every PiNS operation is a shielded PIVX transaction to the registrar's protocol address, where the amount is the payment and the memo is the signed command. Both travel in the same note, so intent and payment are atomically bound — there is no separate reference or invoice to correlate.

This page is the exact wire format. A command built to it is one both the registrar and the zero-knowledge circuit will accept.

Anatomy

All commands are colon-separated ASCII, beginning with the protocol marker and version:

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

The fields between depend on the operation:

Operation	Memo layout	Paid amount
REG register	PiNS:1:REG:{name}:{address}:{pubkey}:{nonce}:{sig}	registration fee for the name length
UPD update address	PiNS:1:UPD:{name}:{address}:{pubkey}:{nonce}:{sig}	update fee
CHG transfer owner	PiNS:1:CHG:{name}:{new_pubkey}:{nonce}:{sig}	update fee
LST list for sale	PiNS:1:LST:{name}:{pubkey}:{price}:{nonce}:{sig}	update fee
ULT delist	PiNS:1:ULT:{name}:{pubkey}:{nonce}:{sig}	update fee
BUY purchase	PiNS:1:BUY:{name}:{address}:{pubkey}:{nonce}:{sig}	exactly the listed price

For CHG, {new_pubkey} is the incoming owner's key, and the signature is made by the outgoing owner — it is the current owner who authorises a transfer.

The signed message

The signature covers the command without the trailing :{signature} — that is, everything from the marker up to and including the nonce:

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

The rules are exact, and a client that gets any of them wrong produces a signature the circuit rejects:

• pubkey is lowercase hex, 64 characters.
• price appears only for LST.
• address appears only for REG, UPD and BUY.
• price and nonce are decimal, with no leading zeros, no sign and no padding.
• The signature is Ed25519 over those exact bytes, hex-encoded, 128 characters.

Verification is strict: non-canonical signatures and small-order keys are rejected.

Field rules

Name

Rule	Value
Characters	a-z, 0-9, hyphen
Length	1–64 characters including the zone
Case	lowercase only — a name is stored and hashed lowercase
Hyphens	not leading, not trailing, never doubled
Zones	.pivx, .private, .secure, .safe

Exactly one dot is allowed, separating the label from the zone.

Target address

The address a name resolves to must be a PIVX Sapling shielded payment address on mainnet — bech32, human-readable prefix ps, exactly 78 characters. Transparent addresses and anything else are refused.

The length is not arbitrary. A Sapling payment address is a 43-byte payload — an 11-byte diversifier plus a 32-byte pk_d — which bech32 encodes as 69 data characters plus a 6-character checksum, so ps + separator + 69 + 6 = 78.

The reason a shielded address is required is practical rather than arbitrary: the registrar receives and pays through Sapling key material, so an address it cannot pay into cannot be used for refunds or sale proceeds.

tip

Only the modern bech32 form is accepted

The legacy testnet ptestsapling… form (88 characters) is rejected on both networks, and the circuit enforces the same rule as the registrar. Any current PIVX wallet produces the ps… form on mainnet.

Nonce

The nonce is a Unix timestamp in seconds at the moment you sign.

• It must be strictly greater than the nonce currently recorded for that name. This is what prevents replay of an old signed command.
• It may not run ahead of the block that carries it by more than 300 seconds, which absorbs ordinary clock skew without letting a nonce be parked far in the future.

For a first registration, any current timestamp works.

Price

Only LST carries a price. It is an integer number of satoshi (1 PIVX = 100,000,000 satoshi) and must be greater than zero.

Re-listing an already-listed name at a new price is allowed — send another LST. The most recent one wins.

Size limit

A PIVX memo is exactly 512 bytes, and the whole command must fit. The fixed parts consume a predictable amount:

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

A Sapling address is a fixed 78 characters, so unlike a variable-length address format the budget is easy to reason about: roughly 218 bytes remain for the name, which is far more than the 64-character maximum a name can use. In practice a command always fits. Clients should still compute the budget rather than assume it, so that a future field can never overflow the memo silently.

Payment

The amount decides validity as much as the memo does:

• REG must pay exactly the registration fee for the name length.
• UPD, CHG, LST, ULT must pay exactly the update fee.
• BUY must pay exactly the listed price.

Length is measured on the label, excluding the zone: ab.pivx is a 2-character name.

An underpaid or overpaid command is not processed. If the operation and public key are readable, the amount is credited to your internal balance and can be withdrawn — see Q&A.

Ordering

Commands are processed in the order PIVX produced them: block height, then transaction index within the block, then input index. The registrar does not choose the order, and cannot reorder without every independent indexer computing a different root.

For contested operations — two REGs for the same name, or two BUYs for the same listing — the first in that ordering wins and the others are refunded to internal balance.

Worked example

Registering 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.

Within a few minutes the command is batched, proven, and anchored. From then on richard.pivx resolves through any indexer, with a Merkle proof you can check yourself.