Saltar al contenido principal

Formato de comandos

Toda operación de PiNS es una transacción blindada de PIVX dirigida a la dirección de protocolo del registrador, donde el importe es el pago y el memo es el comando firmado. Ambos viajan en la misma nota, de modo que intención y pago quedan atados de forma atómica: no hay una referencia o factura aparte que haya que correlacionar.

Esta página describe el formato de transmisión exacto. Un comando construido conforme a él será aceptado tanto por el registrador como por el circuito de conocimiento cero.

Anatomía​

Todos los comandos son ASCII separado por dos puntos y empiezan por el marcador de protocolo y la versión:

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

Los campos intermedios dependen de la operación:

OperaciónEstructura del memoImporte pagado
REG registrarPiNS:1:REG:{name}:{address}:{pubkey}:{nonce}:{sig}tarifa de registro según la longitud del nombre
UPD cambiar direcciónPiNS:1:UPD:{name}:{address}:{pubkey}:{nonce}:{sig}tarifa de modificación
CHG transferir titularPiNS:1:CHG:{name}:{new_pubkey}:{nonce}:{sig}tarifa de modificación
LST poner a la ventaPiNS:1:LST:{name}:{pubkey}:{price}:{nonce}:{sig}tarifa de modificación
ULT retirar de la ventaPiNS:1:ULT:{name}:{pubkey}:{nonce}:{sig}tarifa de modificación
BUY comprarPiNS:1:BUY:{name}:{address}:{pubkey}:{nonce}:{sig}exactamente el precio publicado

En CHG, {new_pubkey} es la clave del titular entrante, y la firma la hace el titular saliente: es el titular actual quien autoriza una transferencia.

El mensaje firmado​

La firma cubre el comando sin el :{signature} final, es decir, todo desde el marcador hasta el nonce incluido:

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

Las reglas son exactas, y un cliente que incumpla cualquiera de ellas produce una firma que el circuito rechaza:

  • pubkey es hex en minúsculas, 64 caracteres.
  • price aparece solo en LST.
  • address aparece solo en REG, UPD y BUY.
  • price y nonce son decimales, sin ceros a la izquierda, sin signo y sin relleno.
  • La firma es Ed25519 sobre esos bytes exactos, codificada en hex, 128 caracteres.

La verificación es estricta: se rechazan las firmas no canónicas y las claves de orden pequeño.

Reglas de los campos​

Nombre​

ReglaValor
Caracteresa-z, 0-9, guion
Longitud1–64 caracteres incluida la zona
Mayúsculassolo minúsculas: un nombre se almacena y se hashea en minúsculas
Guionesni al principio, ni al final, nunca dobles
Zonas.pivx, .private, .secure, .safe

Se permite exactamente un punto, que separa la etiqueta de la zona.

Dirección de destino​

La dirección a la que resuelve un nombre debe ser una dirección de pago blindada de PIVX Sapling en mainnet: bech32, prefijo legible ps, exactamente 78 caracteres. Las direcciones transparentes y cualquier otra cosa se rechazan.

La longitud no es arbitraria. Una dirección de pago Sapling es una carga útil de 43 bytes —un diversificador de 11 bytes más un pk_d de 32 bytes— que bech32 codifica como 69 caracteres de datos más 6 de suma de verificación, o sea ps + separador + 69 + 6 = 78.

La regla es del propio protocolo: el indexador y el circuito la aplican igual y, además, exigen la dirección en minúsculas — una suma de verificación Bech32 no distingue mayúsculas, así que, si no, dos grafías de una misma dirección darían dos hojas distintas del árbol. No se debe a cómo paga el registrador: los reembolsos y los ingresos por ventas nunca van a la dirección a la que apunta un nombre, sino al saldo interno de una clave Ed25519, desde el que su titular los retira.

tip

Solo se acepta la forma bech32 moderna

La antigua forma de testnet ptestsapling… (88 caracteres) se rechaza en ambas redes, y el circuito impone la misma regla que el registrador. Cualquier monedero PIVX actual produce la forma ps… en mainnet.

Nonce​

El nonce es una marca de tiempo Unix en segundos en el momento de firmar.

  • Debe ser estrictamente mayor que el nonce registrado en ese momento para ese nombre. Eso es lo que impide repetir un comando firmado antiguo.
  • No puede adelantarse más de 300 segundos al bloque que lo transporta, margen que absorbe el desfase habitual de reloj sin permitir dejar un nonce muy en el futuro.

Para un primer registro sirve cualquier marca de tiempo actual.

Un comando cuyo nonce no supere el registrado se rechaza, y su pago vuelve a su saldo interno, desde el que cada retiro cuesta una comisión de servicio del 5 %. Puede ocurrir con un reloj que atrasa, y también con dos comandos para un mismo nombre firmados dentro del mismo segundo. Por eso, tome el mayor entre la hora actual y el último nonce del nombre más un segundo; ese último nonce es el nonce que devuelve la resolución de nombres o el de un comando suyo para el nombre que aún espera ser procesado, el que sea posterior.

Precio​

Solo LST lleva precio. Es un número entero de satoshis (1 PIVX = 100 000 000 satoshis) y debe ser mayor que cero.

Volver a publicar un nombre ya publicado a otro precio está permitido: envíe otro LST. Gana el más reciente.

Límite de tamaño​

Un memo de PIVX ocupa exactamente 512 bytes, y el comando entero debe caber. Las partes fijas consumen una cantidad previsible:

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

Una dirección Sapling ocupa siempre 78 caracteres, así que, a diferencia de un formato de longitud variable, el presupuesto es fácil de razonar: quedan unos 218 bytes para el nombre, muy por encima del máximo de 64 caracteres que un nombre puede usar. En la práctica un comando siempre cabe. Aun así, los clientes deberían calcular el presupuesto en vez de darlo por supuesto, para que un campo futuro nunca desborde el memo en silencio.

Pago​

El importe determina la validez tanto como el memo:

  • REG debe pagar exactamente la tarifa de registro correspondiente a la longitud del nombre.
  • UPD, CHG, LST, ULT deben pagar exactamente la tarifa de modificación.
  • BUY debe pagar exactamente el precio publicado.

La longitud se mide sobre la etiqueta, sin la zona: ab.pivx es un nombre de 2 caracteres.

Un comando pagado de menos o de más no se procesa, como tampoco un memo que no supere la comprobación de formato o de firma. Ambos se reembolsan en su saldo interno si pagan al menos 0.01 PIVX y todavía pueden leerse hasta ese punto: la cabecera PiNS:1:, una operación conocida y una clave pública válida —en un CHG, un nombre que existe—. Un CHG nombra al nuevo propietario y no a quien lo firma, por lo que su reembolso va al propietario del nombre que lo firmó, y un CHG que no firmó ningún propietario no se reembolsa. Los reembolsos se abonan tras 120 confirmaciones y después pueden retirarse — consulte Preguntas y respuestas.

Un pago cuyo memo tenga un solo carácter fuera del ASCII imprimible no se reembolsa automáticamente, pague lo que pague, ni tampoco un pago inferior a 0.01 PIVX: esos pagos se notifican al equipo de PIVX Name — consulte Preguntas y respuestas.

Orden​

Los comandos se procesan en el orden en que PIVX los produjo: altura de bloque y después índice de transacción dentro del bloque. El registrador no elige el orden y no puede reordenar sin que todos los indexadores independientes calculen una raíz distinta.

Una transacción lleva un solo comando: la primera de sus salidas a la dirección del registrador, por índice de salida, cuyo memo sea un comando bien formado. Cualquier otra salida al registrador en la misma transacción no se procesa ni se reembolsa automáticamente, así que envíe cada comando en una transacción propia.

En las operaciones en disputa —dos REG para el mismo nombre, o dos BUY sobre la misma publicación— gana la primera según ese orden y a las demás se les reembolsa en el saldo interno.

Ejemplo resuelto​

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

Cuando el pago tiene 40 confirmaciones —unos 40 minutos—, el comando entra en el siguiente lote, que se cierra unos diez minutos después y entonces se demuestra y se ancla. A partir de ahí, richard.pivx resuelve a través de cualquier indexador, con una prueba de Merkle que usted mismo puede comprobar.