Saltar al contenido principal

Verificar pruebas

Esta página muestra cómo verificar la resolución de un nombre sin confiar en el indexador que la sirvió. Todos los ejemplos de código que aparecen aquí se ejecutan contra un indexador real antes de publicarse.

Qué le aporta la verificación​

Una resolución responde a «¿a qué dirección apunta richard.pivx?». Verificarla demuestra que la respuesta es la comprometida en la raíz de estado, y que esa raíz es la raíz actual del contrato ancla. Un indexador que invente una dirección, sirva un registro obsoleto u omita un nombre no puede producir una prueba que supere estas comprobaciones. Tampoco uno que responda con el registro auténtico de otro nombre: las comprobaciones de abajo vinculan la respuesta al nombre que usted pidió.

Hay tres pasos independientes, y necesita los tres:

  1. La prueba de Merkle vincula el registro con una raíz de estado.
  2. La comprobación en la cadena vincula esa raíz con el contrato ancla.
  3. La comprobación de la época vincula las reglas y el historial del contrato con los que usted ha revisado.

El paso 1 por sí solo no vale nada: un indexador malicioso puede construir un árbol falso completo y servir pruebas coherentes con su propia raíz falsa. El paso 2 es lo que da sentido a la raíz, y el paso 3 es lo que se lo mantiene cuando cambian las reglas o el estado se revierte.


Paso 1 — verificar la prueba de Merkle​

El árbol​

PiNS usa un árbol de Merkle disperso compacto sobre un espacio de claves de 128 bits. Una clave son los primeros 16 bytes de SHA-256(domain_name). Al escribir un verificador importan dos propiedades:

  • Las pruebas son cortas y de longitud variable. Una hoja se sitúa a la menor profundidad en la que el prefijo de su clave es único, así que una prueba lleva proof_depth hermanos: por lo general un puñado, no 128. Nunca dé por supuesta una longitud fija; lea proof_depth y compruebe que coincide con merkle_proof.length.
  • Un subárbol vacío son 32 bytes a cero a cualquier altura. No hay una escalera de hashes precalculados para nodos vacíos. Por eso la raíz de un árbol vacío es toda ceros.

Las funciones hash​

Las hojas y los nodos internos van etiquetados para que sus dominios de hash no se solapen. Olvidar el byte de etiqueta es, con diferencia, el error más frecuente: produce un hash de aspecto plausible que jamás coincide con la raíz.

leaf = SHA-256( 0x00 ‖ domain ‖ owner_pubkey ‖ target_address ‖ price_le64 ‖ nonce_le64 )
node = SHA-256( 0x01 ‖ left ‖ right )
key = SHA-256( domain )[0..16]

domain y target_address son bytes UTF-8 sin prefijo de longitud; owner_pubkey son los 32 bytes en bruto; price y nonce son enteros de 64 bits sin signo en little-endian.

El recorrido​

Vaya de la hoja de vuelta a la raíz. Con n = proof_depth hermanos, en el paso i el bit que decide de qué lado está es el bit n - 1 - i de la clave, contando desde el bit más significativo del byte 0:

h = leaf
for i in 0..n:
h = key_bit(key, n-1-i) ? node(sibling[i], h) : node(h, sibling[i])

merkle_proof[0] es el hermano del nivel más profundo, el más cercano a la hoja.

El terminal​

Toda prueba lleva un proof_terminal que describe qué hay al final del camino:

TerminalSignificado
Occupiedahí está la hoja propia de la clave: el nombre existe
Vacantahí hay un subárbol vacío: el nombre no está registrado
Blockedahí está la hoja de un nombre distinto: el nombre no está registrado, y la respuesta incluye el registro completo de ese otro nombre

Una resolución correcta debe ser Occupied. Vacant y Blocked son pruebas de ausencia: permiten verificar que un nombre realmente no está registrado, en lugar de aceptar por fe el «no encontrado» de un indexador. Rechace toda resolución cuyo terminal no sea Occupied.

La API de resolución todavía no devuelve pruebas de ausencia: para un nombre que no conoce responde Domain not found sin prueba alguna. Mientras sea así, trate un «not found» como no verificado y compruébelo con un segundo indexador.

Código​

El verificador recibe, además de la respuesta, el nombre que usted pidió, y calcula el hash de ese nombre, nunca del domain_name que trae la respuesta. De lo contrario, un indexador podría responder con el registro y la prueba auténticos de otro nombre, que se verifican sin fallo, y usted pagaría al propietario de ese nombre. También rechaza los campos con una forma incorrecta antes de calcular ningún hash: la hoja no tiene prefijos de longitud, así que un campo de longitud incorrecta desplazaría bytes a su vecino.

import hashlib
import re
import struct

LEAF_TAG, NODE_TAG = b"\x00", b"\x01"
KEY_LEN, MAX_DEPTH = 16, 128


def hash_leaf(domain, owner_pubkey_hex, target_address, price, nonce):
h = hashlib.sha256()
h.update(LEAF_TAG)
h.update(domain.encode())
h.update(bytes.fromhex(owner_pubkey_hex))
h.update(target_address.encode())
h.update(struct.pack("<Q", price))
h.update(struct.pack("<Q", nonce))
return h.digest()


def hash_node(left, right):
h = hashlib.sha256()
h.update(NODE_TAG)
h.update(left)
h.update(right)
return h.digest()


def key_of(domain):
return hashlib.sha256(domain.encode()).digest()[:KEY_LEN]


def key_bit(key, i):
return (key[i // 8] >> (7 - (i % 8))) & 1


def fold(key, start, siblings):
h, n = start, len(siblings)
for i, sib in enumerate(siblings):
h = hash_node(sib, h) if key_bit(key, n - 1 - i) else hash_node(h, sib)
return h


HEX32 = re.compile(r"[0-9a-f]{64}")


def verify_resolution(requested_name, entry, expected_root):
# The name you asked for, never the one the answer carries: an indexer could answer
# with another name's genuine record and proof, which verify perfectly.
name = requested_name.lower()
if entry["domain_name"] != name:
raise ValueError("the answer is for another name")
if entry["proof_terminal"] != "Occupied":
raise ValueError("a resolution must carry an Occupied terminal")

# The leaf has no length prefixes: refuse fields of the wrong shape before hashing.
if not HEX32.fullmatch(entry["owner_pubkey"]):
raise ValueError("owner_pubkey is not 32 bytes of lowercase hex")
for field in ("price", "nonce"):
if type(entry[field]) is not int or not 0 <= entry[field] < 2**64:
raise ValueError(f"{field} is not an unsigned 64-bit integer")
if not all(isinstance(s, str) and HEX32.fullmatch(s) for s in entry["merkle_proof"]):
raise ValueError("a sibling is not 32 bytes of lowercase hex")

siblings = [bytes.fromhex(s) for s in entry["merkle_proof"]]
if len(siblings) != entry["proof_depth"]:
raise ValueError("proof_depth does not match the sibling count")
if entry["proof_depth"] > MAX_DEPTH:
raise ValueError("proof depth exceeds MAX_DEPTH")

leaf = hash_leaf(
name,
entry["owner_pubkey"],
entry["target_address"],
entry["price"],
entry["nonce"],
)
root = fold(key_of(name), leaf, siblings)
return root.hex() == expected_root.lower()

En JavaScript, JSON.parse lee de forma inexacta los enteros mayores que 2^53, así que el ejemplo rechaza un price o un nonce tan grandes (un precio de más de unos 90 millones de PIVX) en lugar de calcular el hash de otro número. Para verificar un registro así, analice la respuesta de modo que ambos valores sigan siendo exactos (Node.js 21 o posterior, navegadores actuales):

const body = JSON.parse(text, (key, value, context) =>
(key === "price" || key === "nonce") && typeof value === "number"
? BigInt(context.source)
: value);
tip

Pruebe su implementación frente a la manipulación

Un verificador que siempre devuelve true supera cualquier prueba positiva. Antes de fiarse del suyo, cambie un byte de target_address, owner_pubkey o price en una respuesta real y confirme que ahora devuelve false. Los tres ejemplos anteriores se comprueban así.

Después, pase la respuesta auténtica de un nombre mientras pide otro: el verificador debe rechazarla. Los ejemplos también se comprueban así.


Paso 2 — contrastar la raíz con el contrato ancla​

Una prueba de Merkle verificada solo dice «este registro está en algún árbol». Para saber que está en el árbol auténtico, pregunte al contrato ancla en BNB Smart Chain si esa raíz es válida: aceptada en la cadena y no revertida desde entonces.

Use isRootValid(bytes32) — selector 0x30ef41b4. Devuelve un único booleano codificado en ABI: todo lo que este paso necesita, y más sencillo de interpretar que el par (bool, uint32) que devuelve verifyRootValidity.

LlamadaSelectorDevuelve
isRootValid(bytes32)0x30ef41b4bool — aceptada y no revertida desde entonces
currentRoot()0xfdab463dbytes32 — la última raíz aceptada
verifyRootValidity(bytes32)0xc7179944(bool isValid, uint32 blockHeight)
currentBlockHeight()0x367bf2f9uint32 — altura de PIVX de la última raíz
programVkey()0x09665ee7bytes32 — el circuito que impone el contrato

Los ejemplos leen el contrato en el bloque finalizado (finalized) más reciente, como hacen los indexadores: una raíz aceptada en un bloque que aún no es definitivo todavía puede desaparecer en una reorganización de la cadena, y un pago hecho en base a ella no tendría fundamento. Primero piden el número de ese bloque y luego leen en él, porque algunos endpoints públicos de BSC rechazan la etiqueta finalized dentro de eth_call. Lea currentRoot() y las llamadas del Paso 3 en ese mismo número, para que todas las respuestas describan el mismo bloque.

import requests


def evm_rpc(rpc_url, method, params):
payload = {"jsonrpc": "2.0", "method": method, "params": params, "id": 1}
r = requests.post(rpc_url, json=payload, timeout=15).json()
if "error" in r:
raise RuntimeError(f"EVM RPC error: {r['error']['message']}")
return r.get("result")


def finalized_block(rpc_url):
"""The newest finalized block, as a hex number. Asked for by number, because some public
BSC nodes refuse the "finalized" tag inside eth_call ("missing trie node")."""
block = evm_rpc(rpc_url, "eth_getBlockByNumber", ["finalized", False])
if not block or "number" not in block:
raise RuntimeError("the endpoint does not serve the finalized block")
return block["number"]


def is_root_valid(rpc_url, contract_address, smt_root, block):
"""Returns True if the anchor contract accepted this root and has not rolled it back."""
clean = smt_root.replace("0x", "").lower().rjust(64, "0")
result = evm_rpc(rpc_url, "eth_call", [{"to": contract_address, "data": f"0x30ef41b4{clean}"}, block]) or "0x"
# A bool is ABI-encoded as a full 32-byte word: 0x00..01 for true.
return int(result, 16) == 1 if result not in ("", "0x") else False


# block = finalized_block(rpc_url)
# is_root_valid(rpc_url, contract_address, entry["smt_root"], block)

Cómo interpretar la respuesta​

isRootValidSignificadoQué hacer
true, y la raíz es igual a currentRoot()el indexador está completamente sincronizadoaceptar
true, pero la raíz es anterior a currentRoot()el indexador va por detrás de la cadenano envíe fondos todavía: espere o consulte otro indexador y vuelva a verificar
falseesta raíz nunca se aceptó en la cadena, o fue revertidarechazar la resolución

Una raíz válida más antigua es un estado pasado real del registro, no el actual. Desde entonces el nombre puede haberse transferido, vendido o apuntado a una nueva dirección, y una prueba contra la raíz antigua sigue mostrando la respuesta anterior. Un indexador lento y uno que oculta una actualización reciente se ven exactamente igual aquí, así que antes de pagar exija que la raíz sea igual a currentRoot(). Un indexador honesto se pone al día poco después de cada nuevo lote. Mostrar el registro a título informativo, marcado como posiblemente desactualizado, está bien.

Un false significa que el árbol contra el que verificó no forma parte de la historia del registro a efectos del protocolo: nunca se aceptó, o una reversión lo repudió. Ese es exactamente el caso que produce un indexador controlado por un atacante, y justo para eso sirve este paso.


Paso 3 — comprobar la época​

Los pasos 1 y 2 demuestran que un registro está en un árbol que el contrato aceptó. Dos cosas pueden cambiar lo que eso demuestra sin ningún lote nuevo: un cambio de reglas — un circuito o un verificador nuevos, y por tanto una nueva definición de qué cuenta como probado — y una reversión, que vuelve a hacer vigente una raíz anterior y con ello redirige cada nombre modificado desde entonces, sin una firma de su titular. El contrato cuenta ambas cosas en epoch:

  • El contador empieza en 1 y sube en uno con cada cambio de reglas y cada reversión. Nunca baja: un cambio y su anulación son dos épocas, no una vuelta a la primera.
  • Un cambio de reglas se anuncia con antelación. La aprobación del propietario inicia un bloqueo temporal fijado en el despliegue (rulesTimelock, entre 7 y 90 días), y el cambio solo puede activarse una vez alcanzado el momento indicado en rulesChangeActivatesAt().
  • Una reversión solo puede apuntar a una raíz que el contrato aceptó antes, y solo mientras el envío de lotes está en pausa. Toda raíz por encima del objetivo deja de ser válida de inmediato, y desde entonces el paso 2 devuelve false para cada una de ellas.

Así que fije la época que ha revisado y niéguese a resolver bajo cualquier otra. Léala junto con la raíz, en una sola llamada, para que ambas procedan del mismo bloque:

LlamadaSelectorDevuelve
anchoredState()0x8d39310a(bytes32 root, uint32 blockHeight, uint32 currentEpoch)
epoch()0x900cf0cfuint32 — la época vigente
rulesChangeActivatesAt()0x90b86556uint64 — cuándo puede activarse un cambio de reglas programado; 0 si no hay ninguno programado

anchoredState() devuelve tres palabras de 32 bytes en este orden: la raíz, la altura de bloque y la época. La época es el entero de la tercera palabra.

Los ejemplos siguientes añaden este paso a los del Paso 2 y reutilizan sus funciones. En un mismo bloque finalizado leen anchoredState(), rechazan cualquier época distinta de la que fijó y después clasifican la raíz como la tabla del Paso 2: accept para la raíz actual, lagging para una válida más antigua y reject para una que el contrato no acepta.

def anchored_state(rpc_url, contract_address, block):
"""anchoredState() at that block: (root as 64 hex digits, PIVX block height, epoch)."""
result = evm_rpc(rpc_url, "eth_call", [{"to": contract_address, "data": "0x8d39310a"}, block]) or "0x"
words = result[2:] if isinstance(result, str) else ""
# Three 32-byte words: nothing more, nothing less, and nothing but hex digits.
if len(words) != 192 or any(c not in "0123456789abcdefABCDEF" for c in words):
raise RuntimeError("unexpected anchoredState() answer")
return words[:64].lower(), int(words[64:128], 16), int(words[128:], 16)


def check_anchor(rpc_url, contract_address, smt_root, pinned_epoch):
"""Steps 2 and 3 at one finalized block. Returns "accept" for the current root, "lagging"
for an older valid one (do not send funds yet) and "reject" for one the contract does not
accept; raises when the epoch in force is not the one you pinned."""
block = finalized_block(rpc_url)
root, _height, epoch = anchored_state(rpc_url, contract_address, block)
if epoch != pinned_epoch:
raise RuntimeError(f"epoch {epoch} is in force, not the reviewed {pinned_epoch}: stop resolving")
if smt_root.replace("0x", "").lower().rjust(64, "0") == root:
return "accept"
return "lagging" if is_root_valid(rpc_url, contract_address, smt_root, block) else "reject"


# check_anchor(rpc_url, contract_address, entry["smt_root"], pinned_epoch)
ÉpocaQué hacer
igual a su época fijadacontinúe — los pasos 1 y 2 valen bajo reglas que usted ha revisado
mayor que su época fijadadeje de resolver. Los eventos EpochAdvanced, RulesChanged y RootRolledBack indican qué ocurrió; revíselo y después actualice la época fijada

Los indexadores se aplican la misma regla: un nodo deja de seguir la cadena cuando la época en la cadena supera la que revisó su operador, e informa de esa época revisada como anchored_epoch en Información del indexador. Es un ajuste del nodo, no la época de la raíz que sirve: un nodo actualizado antes de un cambio de reglas programado ya informa de la época venidera mientras el cambio cumple su bloqueo temporal, y hasta entonces sirve un estado creado bajo la época vigente. Por eso, juzgue una resolución por la época leída del contrato junto con la raíz, como se indica arriba, no por anchored_epoch; el Paso 2 muestra si la raíz del nodo está al día.


Verificar el propio circuito​

Los pasos anteriores demuestran que un registro pertenece a una raíz que el contrato aceptó. El contrato solo acepta una raíz si la acompañaba una prueba ZK válida, y esa prueba se comprueba contra programVkey, un compromiso de 32 bytes con el circuito compilado exacto.

Puede confirmar que esa clave corresponde al código fuente publicado. Compile el circuito en la imagen Docker de SP1, que fija la cadena de herramientas y las rutas de compilación de las que depende la clave, e imprima su clave:

git clone https://github.com/PIVX-Name/pivx-name-prover
cd pivx-name-prover/program
cargo prove build --docker --tag v6.9.0 # no features = mainnet
cargo prove vkey --elf ../target/elf-compilation/docker/riscv64im-succinct-zkvm-elf/release/pins-program

Compare la clave de verificación resultante con programVkey() (selector 0x09665ee7) en el contrato ancla. Si coinciden, el contrato está imponiendo exactamente ese código fuente. Cambiar una sola línea del circuito produce una clave distinta, así que no puede sustituirse un circuito modificado sin que el cambio se vea en la cadena. Tampoco puede entrar en vigor en silencio: una clave nueva pasa por el cambio de reglas con bloqueo temporal descrito en el Paso 3, y hace avanzar la época.

El README del prover enumera la clave de cada versión y el commit a partir del cual se compiló.

aviso

Compile sin características adicionales

Una compilación sin características produce el circuito de mainnet que impone el contrato desplegado. Cualquier indicador de característica cambia el programa compilado y, por tanto, su clave de verificación, que ya no coincidirá. Una compilación fuera de Docker, o con otra etiqueta de imagen, también puede dar una clave distinta.

Verificar una prueba SP1 directamente​

Las pruebas son pruebas SP1 Groth16 estándar y pueden comprobarse con el SDK de SP1:

use sp1_sdk::{ProverClient, SP1ProofWithPublicValues};

let client = ProverClient::from_env();
let (_, vk) = client.setup(ELF);
let proof = SP1ProofWithPublicValues::load("proof.bin")?;
client.verify(&proof, &vk)?;

Los valores públicos son la codificación ABI de (bytes32 old_root, bytes32 new_root, uint32 end_block_height): la transición de estado que realizó el lote y la altura de bloque de PIVX que cubre.