Formato dos comandos

Todas as operações do PiNS são uma transação blindada PIVX dirigida ao endereço de protocolo do registador, em que o montante é o pagamento e o memo é o comando assinado. Ambos viajam na mesma nota, pelo que intenção e pagamento ficam ligados de forma atómica — não há qualquer referência ou fatura separada a correlacionar.

Esta página descreve o formato de transmissão exato. Um comando construído segundo ele será aceite tanto pelo registador como pelo circuito de conhecimento zero.

Anatomia

Todos os comandos são ASCII separado por dois pontos e começam pelo marcador de protocolo e pela versão:

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

Os campos intermédios dependem da operação:

Operação	Estrutura do memo	Montante pago
REG registar	PiNS:1:REG:{name}:{address}:{pubkey}:{nonce}:{sig}	taxa de registo para o comprimento do nome
UPD alterar endereço	PiNS:1:UPD:{name}:{address}:{pubkey}:{nonce}:{sig}	taxa de alteração
CHG transferir titular	PiNS:1:CHG:{name}:{new_pubkey}:{nonce}:{sig}	taxa de alteração
LST colocar à venda	PiNS:1:LST:{name}:{pubkey}:{price}:{nonce}:{sig}	taxa de alteração
ULT retirar da venda	PiNS:1:ULT:{name}:{pubkey}:{nonce}:{sig}	taxa de alteração
BUY comprar	PiNS:1:BUY:{name}:{address}:{pubkey}:{nonce}:{sig}	exatamente o preço listado

Em CHG, {new_pubkey} é a chave do titular que recebe, e a assinatura é feita pelo titular que cede — é o titular atual quem autoriza uma transferência.

A mensagem assinada

A assinatura cobre o comando sem o :{signature} final — isto é, tudo desde o marcador até ao nonce inclusive:

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

As regras são exatas, e um cliente que falhe qualquer uma delas produz uma assinatura que o circuito rejeita:

• pubkey é hex em minúsculas, 64 carateres.
• price aparece apenas em LST.
• address aparece apenas em REG, UPD e BUY.
• price e nonce são decimais, sem zeros à esquerda, sem sinal e sem preenchimento.
• A assinatura é Ed25519 sobre exatamente esses bytes, codificada em hex, 128 carateres.

A verificação é estrita: assinaturas não canónicas e chaves de ordem pequena são rejeitadas.

Regras dos campos

Nome

Regra	Valor
Carateres	a-z, 0-9, hífen
Comprimento	1–64 carateres incluindo a zona
Maiúsculas	apenas minúsculas — um nome é guardado e sujeito a hash em minúsculas
Hífenes	não no início, não no fim, nunca duplos
Zonas	.pivx, .private, .secure, .safe

É permitido exatamente um ponto, que separa a etiqueta da zona.

Endereço de destino

O endereço para o qual um nome é resolvido tem de ser um endereço de pagamento blindado PIVX Sapling na mainnet — bech32, prefixo legível ps, exatamente 78 carateres. Endereços transparentes e quaisquer outros são recusados.

O comprimento não é arbitrário. Um endereço de pagamento Sapling é uma carga útil de 43 bytes — um diversificador de 11 bytes mais um pk_d de 32 bytes — que o bech32 codifica como 69 carateres de dados mais 6 de soma de verificação, ou seja ps + separador + 69 + 6 = 78.

Exigir um endereço blindado é prático e não arbitrário: o registador recebe e paga através de material de chaves Sapling, pelo que um endereço a que não consegue pagar não serve nem para reembolsos nem para receitas de vendas.

dica

Só a forma bech32 moderna é aceite

A antiga forma de testnet ptestsapling… (88 carateres) é rejeitada em ambas as redes, e o circuito impõe a mesma regra que o registador. Qualquer carteira PIVX atual produz a forma ps… na mainnet.

Nonce

O nonce é uma marca temporal Unix em segundos no momento da assinatura.

• Tem de ser estritamente maior do que o nonce atualmente registado para esse nome. É isso que impede a repetição de um comando assinado antigo.
• Não pode adiantar-se mais de 300 segundos ao bloco que o transporta, margem que absorve o desvio habitual dos relógios sem permitir deixar um nonce muito no futuro.

Para um primeiro registo serve qualquer marca temporal atual.

Preço

Só o LST traz preço. É um número inteiro de satoshis (1 PIVX = 100 000 000 satoshis) e tem de ser maior que zero.

Voltar a listar um nome já listado a um novo preço é permitido — envie outro LST. Vence o mais recente.

Limite de tamanho

Um memo PIVX ocupa exatamente 512 bytes, e o comando inteiro tem de caber. As partes fixas consomem uma quantidade previsível:

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

Um endereço Sapling ocupa sempre 78 carateres, pelo que, ao contrário de um formato de comprimento variável, o orçamento é fácil de raciocinar: sobram cerca de 218 bytes para o nome, muito acima do máximo de 64 carateres que um nome pode usar. Na prática um comando cabe sempre. Ainda assim, os clientes devem calcular o orçamento em vez de o presumir, para que um campo futuro nunca transborde o memo em silêncio.

Pagamento

O montante determina a validade tanto quanto o memo:

• REG tem de pagar exatamente a taxa de registo correspondente ao comprimento do nome.
• UPD, CHG, LST, ULT têm de pagar exatamente a taxa de alteração.
• BUY tem de pagar exatamente o preço listado.

O comprimento é medido na etiqueta, sem a zona: ab.pivx é um nome de 2 carateres.

Um comando pago a menos ou a mais não é processado. Se a operação e a chave pública forem legíveis, o montante é creditado no seu saldo interno e pode ser levantado — ver Perguntas e respostas.

Ordem

Os comandos são processados pela ordem em que o PIVX os produziu: altura do bloco, depois índice da transação dentro do bloco, depois índice de entrada. O registador não escolhe a ordem e não pode reordenar sem que todos os indexadores independentes calculem uma raiz diferente.

Nas operações disputadas — dois REG para o mesmo nome, ou dois BUY sobre a mesma listagem — vence o primeiro nessa ordem e aos restantes é devolvido o montante para o saldo interno.

Exemplo resolvido

Registo de 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.

Em poucos minutos o comando é agrupado em lote, provado e ancorado. A partir daí, richard.pivx é resolvido através de qualquer indexador, com uma prova de Merkle que pode verificar por si.