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.priceaparece apenas emLST.addressaparece apenas emREG,UPDeBUY.priceenoncesã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.
A regra é do próprio protocolo: o indexador e o circuito aplicam-na da mesma forma e exigem ainda o endereço em minúsculas — uma soma de verificação Bech32 ignora maiúsculas e minúsculas, pelo que, de outro modo, duas grafias do mesmo endereço dariam duas folhas diferentes da árvore. Não decorre da forma como o registador paga: os reembolsos e as receitas de vendas nunca vão para o endereço para o qual um nome aponta, mas para o saldo interno de uma chave Ed25519, de onde o seu titular os levanta.
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.
Um comando cujo nonce não seja superior ao registado é recusado, e o seu pagamento volta ao seu saldo interno, do qual cada levantamento custa uma taxa de serviço de 5%. Pode acontecer com um relógio atrasado, e também com dois comandos para o mesmo nome assinados dentro do mesmo segundo. Por isso, use o maior entre a hora atual e o último nonce do nome mais um segundo; esse último nonce é o nonce devolvido pela resolução de nomes ou o de um comando seu para o nome que ainda aguarda processamento, o que for posterior.
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:
REGtem de pagar exatamente a taxa de registo correspondente ao comprimento do nome.UPD,CHG,LST,ULTtêm de pagar exatamente a taxa de alteração.BUYtem 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, tal como um memo que não passe a
verificação de formato ou de assinatura. Ambos são reembolsados no seu saldo interno se pagarem
pelo menos 0.01 PIVX e ainda puderem ser lidos até esse ponto: o cabeçalho PiNS:1:, uma
operação conhecida e uma chave pública válida — num CHG, um nome que existe. Um CHG indica
o novo proprietário e não quem o assina, por isso o seu reembolso vai para o proprietário do
nome que o assinou, e um CHG que nenhum proprietário assinou não é reembolsado. Os reembolsos são
creditados após 120 confirmações e podem depois ser levantados — ver Perguntas e
respostas.
Um pagamento cujo memo tenha um único carácter fora do ASCII imprimível não é reembolsado automaticamente, pague o que pagar, nem um pagamento inferior a 0.01 PIVX: esses pagamentos são comunicados à equipa PIVX Name — 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. O registador não escolhe a ordem e não pode reordenar sem que todos os indexadores independentes calculem uma raiz diferente.
Uma transação transporta um comando: a primeira das suas saídas para o endereço do registador, por índice de saída, cujo memo seja um comando bem formado. Qualquer outra saída para o registador na mesma transação não é processada nem reembolsada automaticamente, por isso envie cada comando numa transação própria.
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.
Quando o pagamento tem 40 confirmações — cerca de 40 minutos —, o comando entra no lote
seguinte, que fecha cerca de dez minutos depois e é então provado e ancorado. A partir daí,
richard.pivx é resolvido através de qualquer indexador, com uma prova de Merkle que pode
verificar por si.