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:
- La prueba de Merkle vincula el registro con una raíz de estado.
- La comprobación en la cadena vincula esa raíz con el contrato ancla.
- 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_depthhermanos: por lo general un puñado, no 128. Nunca dé por supuesta una longitud fija; leaproof_depthy compruebe que coincide conmerkle_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:
| Terminal | Significado |
|---|---|
Occupied | ahí está la hoja propia de la clave: el nombre existe |
Vacant | ahí hay un subárbol vacío: el nombre no está registrado |
Blocked | ahí 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
- Python
- PHP
- JavaScript
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()
<?php
const LEAF_TAG = "\x00";
const NODE_TAG = "\x01";
const KEY_LEN = 16;
const MAX_DEPTH = 128;
function hashLeaf(string $domain, string $ownerPubkeyHex, string $targetAddress, int $price, int $nonce): string
{
return hash('sha256',
LEAF_TAG
. $domain
. hex2bin($ownerPubkeyHex)
. $targetAddress
. pack('P', $price) // u64 little-endian
. pack('P', $nonce),
true);
}
function hashNode(string $left, string $right): string
{
return hash('sha256', NODE_TAG . $left . $right, true);
}
function keyOf(string $domain): string
{
return substr(hash('sha256', $domain, true), 0, KEY_LEN);
}
function keyBit(string $key, int $i): int
{
return (ord($key[intdiv($i, 8)]) >> (7 - ($i % 8))) & 1;
}
function fold(string $key, string $start, array $siblings): string
{
$h = $start;
$n = count($siblings);
foreach ($siblings as $i => $sib) {
$h = keyBit($key, $n - 1 - $i) === 1 ? hashNode($sib, $h) : hashNode($h, $sib);
}
return $h;
}
function verifyResolution(array $entry, string $expectedRoot): bool
{
if ($entry['proof_terminal'] !== 'Occupied') {
throw new RuntimeException('a resolution must carry an Occupied terminal');
}
$siblings = array_map('hex2bin', $entry['merkle_proof']);
if (count($siblings) !== (int)$entry['proof_depth']) {
throw new RuntimeException('proof_depth does not match the sibling count');
}
if ((int)$entry['proof_depth'] > MAX_DEPTH) {
throw new RuntimeException('proof depth exceeds MAX_DEPTH');
}
$leaf = hashLeaf($entry['domain_name'], $entry['owner_pubkey'], $entry['target_address'],
(int)$entry['price'], (int)$entry['nonce']);
return bin2hex(fold(keyOf($entry['domain_name']), $leaf, $siblings)) === strtolower($expectedRoot);
}
import crypto from "node:crypto";
const LEAF_TAG = 0x00;
const NODE_TAG = 0x01;
const KEY_LEN = 16;
const MAX_DEPTH = 128;
const sha256 = (...parts) =>
crypto.createHash("sha256").update(Buffer.concat(parts)).digest();
const u64le = (v) => {
const b = Buffer.alloc(8);
b.writeBigUInt64LE(BigInt(v));
return b;
};
function hashLeaf(domain, ownerPubkeyHex, targetAddress, price, nonce) {
return sha256(
Buffer.from([LEAF_TAG]),
Buffer.from(domain, "utf8"),
Buffer.from(ownerPubkeyHex, "hex"),
Buffer.from(targetAddress, "utf8"),
u64le(price),
u64le(nonce),
);
}
const hashNode = (l, r) => sha256(Buffer.from([NODE_TAG]), l, r);
const keyOf = (domain) =>
crypto.createHash("sha256").update(domain, "utf8").digest().subarray(0, KEY_LEN);
const keyBit = (key, i) => (key[Math.floor(i / 8)] >> (7 - (i % 8))) & 1;
function fold(key, start, siblings) {
let h = start;
const n = siblings.length;
for (let i = 0; i < n; i++) {
h = keyBit(key, n - 1 - i) ? hashNode(siblings[i], h) : hashNode(h, siblings[i]);
}
return h;
}
export function verifyResolution(entry, expectedRoot) {
if (entry.proof_terminal !== "Occupied") {
throw new Error("a resolution must carry an Occupied terminal");
}
const siblings = entry.merkle_proof.map((s) => Buffer.from(s, "hex"));
if (siblings.length !== entry.proof_depth) {
throw new Error("proof_depth does not match the sibling count");
}
if (entry.proof_depth > MAX_DEPTH) {
throw new Error("proof depth exceeds MAX_DEPTH");
}
const leaf = hashLeaf(
entry.domain_name,
entry.owner_pubkey,
entry.target_address,
Number(entry.price),
Number(entry.nonce),
);
return fold(keyOf(entry.domain_name), leaf, siblings).toString("hex")
=== expectedRoot.toLowerCase();
}
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.
| Llamada | Selector | Devuelve |
|---|---|---|
isRootValid(bytes32) | 0x30ef41b4 | bool — aceptada y no revertida desde entonces |
currentRoot() | 0xfdab463d | bytes32 — la última raíz aceptada |
verifyRootValidity(bytes32) | 0xc7179944 | (bool isValid, uint32 blockHeight) |
currentBlockHeight() | 0x367bf2f9 | uint32 — altura de ZCash de la última raíz |
programVkey() | 0x09665ee7 | bytes32 — el circuito que impone el contrato |
- Python
- PHP
- JavaScript
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
<?php
function isRootValid(string $rpcUrl, string $contractAddress, string $smtRoot): bool
{
$clean = str_pad(str_replace('0x', '', strtolower($smtRoot)), 64, '0', STR_PAD_LEFT);
$payload = [
'jsonrpc' => '2.0',
'method' => 'eth_call',
'params' => [['to' => $contractAddress, 'data' => '0x30ef41b4' . $clean], 'latest'],
'id' => 1,
];
$ch = curl_init($rpcUrl);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_TIMEOUT => 15,
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
if (isset($data['error'])) {
throw new RuntimeException('EVM RPC error: ' . $data['error']['message']);
}
$result = $data['result'] ?? '0x';
if ($result === '' || $result === '0x') {
return false;
}
// A bool is ABI-encoded as a full 32-byte word: 0x00..01 for true. The whole word is
// compared, as in the Python and JavaScript versions: its last digit alone would read
// an answer such as 0x…11 as true.
$word = substr($result, 2);
return ctype_xdigit($word) && ltrim($word, '0') === '1';
}
async function isRootValid(rpcUrl, contractAddress, smtRoot) {
const clean = smtRoot.replace(/^0x/, "").toLowerCase().padStart(64, "0");
const response = await fetch(rpcUrl, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
jsonrpc: "2.0",
method: "eth_call",
params: [{ to: contractAddress, data: `0x30ef41b4${clean}` }, "latest"],
id: 1,
}),
});
if (!response.ok) throw new Error(`RPC request failed: ${response.statusText}`);
const json = await response.json();
if (json.error) throw new Error(`EVM RPC error: ${json.error.message}`);
const result = json.result;
if (!result || result === "0x") return false;
// A bool is ABI-encoded as a full 32-byte word: 0x00..01 for true.
return BigInt(result) === 1n;
}
Cómo interpretar la respuesta
isRootValid | Significado | Qué hacer |
|---|---|---|
true, y la raíz es igual a currentRoot() | el indexador está completamente sincronizado | aceptar |
true, pero la raíz es anterior a currentRoot() | el indexador va por detrás de la cadena | no envíe fondos todavía: espere o consulte otro indexador y vuelva a verificar |
false | esta raíz nunca se aceptó en la cadena, o fue revertida | rechazar 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 enrulesChangeActivatesAt(). - 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
falsepara 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:
| Llamada | Selector | Devuelve |
|---|---|---|
anchoredState() | 0x8d39310a | (bytes32 root, uint32 blockHeight, uint32 currentEpoch) |
epoch() | 0x900cf0cf | uint32 — la época vigente |
rulesChangeActivatesAt() | 0x90b86556 | uint64 — 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.
| Época | Qué hacer |
|---|---|
| igual a su época fijada | continúe — los pasos 1 y 2 valen bajo reglas que usted ha revisado |
| mayor que su época fijada | deje 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ó.
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.