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.zcash?». 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.

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​

zNS 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​

import hashlib
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


def verify_resolution(entry, expected_root):
if entry["proof_terminal"] != "Occupied":
raise ValueError("a resolution must carry an Occupied terminal")

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(
entry["domain_name"],
entry["owner_pubkey"],
entry["target_address"],
int(entry["price"]),
int(entry["nonce"]),
)
root = fold(key_of(entry["domain_name"]), leaf, siblings)
return root.hex() == expected_root.lower()
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í.


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 ZCash de la última raíz
programVkey()0x09665ee7bytes32 — el circuito que impone el contrato
import requests


def is_root_valid(rpc_url, contract_address, smt_root):
"""Returns True if the anchor contract accepted this root and has not rolled it back."""
clean = smt_root.replace("0x", "").lower().rjust(64, "0")
payload = {
"jsonrpc": "2.0",
"method": "eth_call",
"params": [{"to": contract_address, "data": f"0x30ef41b4{clean}"}, "latest"],
"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']}")

result = r.get("result", "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

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.

É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 sincronizar cuando la época en la cadena supera la que revisó su operador, e informa de la época bajo la que sirve como anchored_epoch en Información del indexador. Un indexador que informe de una época distinta de la suya no es uno a través del cual resolver.


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/ZCashNames/zcash-name-prover
cd zcash-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/zns-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 ZCash que cubre.