Verificar provas
Esta página mostra como verificar a resolução de um nome sem confiar no indexador que a serviu. Todos os exemplos de código aqui presentes são executados contra um indexador real antes da publicação.
O que a verificação lhe dá
Uma resolução responde a «para que endereço aponta richard.zcash?». Verificá-la prova que a
resposta é aquela com que a raiz de estado se comprometeu — e que essa raiz é a raiz
atual do contrato âncora. Um indexador que invente um endereço, sirva um registo desatualizado ou omita um
nome não consegue produzir uma prova que passe estas verificações.
Há três passos independentes, e precisa dos três:
- A prova de Merkle liga o registo a uma raiz de estado.
- A verificação na cadeia liga essa raiz ao contrato âncora.
- A verificação da época liga as regras e o histórico do contrato aos que reviu.
O passo 1 sozinho não vale nada: um indexador malicioso pode construir uma árvore falsa completa e servir provas coerentes com a sua própria raiz falsa. É o passo 2 que dá sentido à raiz, e é o passo 3 que lho mantém quando as regras mudam ou o estado é revertido.
Passo 1 — verificar a prova de Merkle
A árvore
O zNS usa uma árvore de Merkle esparsa compacta sobre um espaço de chaves de 128 bits. Uma
chave são os primeiros 16 bytes de SHA-256(domain_name). Ao escrever um verificador, importam
duas propriedades:
- As provas são curtas e de comprimento variável. Uma folha fica à menor profundidade em que
o prefixo da sua chave é único, pelo que uma prova traz
proof_depthirmãos — normalmente um punhado, não 128. Nunca presuma um comprimento fixo; leiaproof_depthe confirme que corresponde amerkle_proof.length. - Uma subárvore vazia são 32 bytes a zero a qualquer altura. Não há uma escada de hashes pré-calculados para nós vazios. Por isso a raiz de uma árvore vazia é toda a zeros.
As funções de hash
As folhas e os nós internos são etiquetados para que os seus domínios de hash não se sobreponham. Omitir o byte da etiqueta é, de longe, o erro mais comum — produz um hash de aspeto plausível que nunca corresponde à raiz.
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 e target_address são bytes UTF-8 sem prefixo de comprimento; owner_pubkey são os 32
bytes em bruto; price e nonce são inteiros de 64 bits sem sinal em little-endian.
O percurso
Vá da folha de volta à raiz. Com n = proof_depth irmãos, no passo i o bit que decide de que
lado está é o bit n - 1 - i da chave, contado a partir do bit mais significativo do 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] é o irmão do nível mais profundo, o mais próximo da folha.
O terminal
Todas as provas trazem um proof_terminal que descreve o que está no fim do caminho:
| Terminal | Significado |
|---|---|
Occupied | ali está a folha própria da chave — o nome existe |
Vacant | ali está uma subárvore vazia — o nome não está registado |
Blocked | ali está a folha de um nome diferente — o nome não está registado, e a resposta inclui o registo completo desse outro nome |
Uma resolução bem-sucedida tem de ser Occupied. Vacant e Blocked são provas de ausência:
permitem verificar que um nome realmente não está registado, em vez de aceitar por fé o «não
encontrado» de um indexador. Rejeite qualquer resolução cujo terminal não seja Occupied.
A API de resolução ainda não devolve provas de ausência: para um nome que não conhece responde
Domain not found sem qualquer prova. Enquanto assim for, trate um «not found» como não
verificado e confirme-o com um 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();
}
Teste a sua implementação contra adulteração
Um verificador que devolve sempre true passa em qualquer teste positivo. Antes de confiar no
seu, altere um byte de target_address, owner_pubkey ou price numa resposta real e confirme
que agora devolve false. Os três exemplos acima são verificados desta forma.
Passo 2 — comparar a raiz com o contrato âncora
Uma prova de Merkle verificada diz apenas «este registo está em alguma árvore». Para saber que está na árvore verdadeira, pergunte ao contrato âncora na BNB Smart Chain se essa raiz é válida: aceite na cadeia e não revertida desde então.
Use isRootValid(bytes32) — seletor 0x30ef41b4. Devolve um único booleano codificado em ABI: tudo o que este passo precisa, e mais simples de interpretar do que o par (bool, uint32) que verifyRootValidity devolve.
| Chamada | Seletor | Devolve |
|---|---|---|
isRootValid(bytes32) | 0x30ef41b4 | bool — aceite e não revertida desde então |
currentRoot() | 0xfdab463d | bytes32 — a última raiz aceite |
verifyRootValidity(bytes32) | 0xc7179944 | (bool isValid, uint32 blockHeight) |
currentBlockHeight() | 0x367bf2f9 | uint32 — altura ZCash da última raiz |
programVkey() | 0x09665ee7 | bytes32 — o circuito que o contrato impõe |
- 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;
}
Como interpretar a resposta
isRootValid | Significado | O que fazer |
|---|---|---|
true, e a raiz é igual a currentRoot() | o indexador está totalmente sincronizado | aceitar |
true, mas a raiz é anterior a currentRoot() | o indexador está atrasado face à cadeia | não envie fundos ainda — aguarde ou consulte outro indexador e verifique novamente |
false | esta raiz nunca foi aceite na cadeia, ou foi revertida | rejeitar a resolução |
Uma raiz válida mais antiga é um estado passado real do registo, não o atual. Desde então o nome
pode ter sido transferido, vendido ou apontado para um novo endereço, e uma prova contra a raiz
antiga continua a mostrar a resposta anterior. Um indexador lento e um que retém uma atualização
recente parecem exatamente iguais aqui, por isso, antes de pagar, exija que a raiz seja igual a
currentRoot(). Um indexador honesto põe-se a par pouco depois de cada novo lote. Mostrar o
registo apenas a título informativo, assinalado como possivelmente desatualizado, é aceitável.
Um false significa que a árvore contra a qual verificou não faz parte da história do registo do
ponto de vista do protocolo: nunca foi aceite, ou uma reversão repudiou-a. É exatamente o caso que
um indexador controlado por um atacante produz, e é precisamente para isso que serve este passo.
Passo 3 — verificar a época
Os passos 1 e 2 provam que um registo está numa árvore que o contrato aceitou. Duas coisas podem mudar o que isso prova sem qualquer lote novo: uma alteração de regras — um novo circuito ou verificador e, portanto, uma nova definição do que conta como provado — e uma reversão, que volta a tornar atual uma raiz mais antiga e, com isso, redireciona todos os nomes alterados desde então, sem uma assinatura do respetivo titular. O contrato conta ambas em epoch:
- O contador começa em 1 e sobe uma unidade a cada alteração de regras e a cada reversão. Nunca desce: uma alteração e a sua anulação são duas épocas, não um regresso à primeira.
- Uma alteração de regras é anunciada com antecedência. A aprovação do proprietário inicia um bloqueio temporal fixado na implementação (
rulesTimelock, entre 7 e 90 dias), e a alteração só pode ser ativada depois de atingido o momento indicado emrulesChangeActivatesAt(). - Uma reversão só pode ter como alvo uma raiz que o contrato aceitou antes, e só enquanto a submissão de lotes está em pausa. Todas as raízes acima do alvo deixam de ser válidas de imediato, e a partir daí o passo 2 devolve
falsepara cada uma delas.
Portanto, fixe a época que reviu e recuse resolver sob qualquer outra. Leia-a juntamente com a raiz, numa única chamada, para que ambas venham do mesmo bloco:
| Chamada | Seletor | Devolve |
|---|---|---|
anchoredState() | 0x8d39310a | (bytes32 root, uint32 blockHeight, uint32 currentEpoch) |
epoch() | 0x900cf0cf | uint32 — a época em vigor |
rulesChangeActivatesAt() | 0x90b86556 | uint64 — quando uma alteração de regras agendada pode ser ativada; 0 quando nenhuma está agendada |
anchoredState() devolve três palavras de 32 bytes por esta ordem: a raiz, a altura do bloco e a época. A época é o inteiro na terceira palavra.
| Época | O que fazer |
|---|---|
| igual à sua época fixada | continue — os passos 1 e 2 valem sob regras que reviu |
| superior à sua época fixada | pare de resolver. Os eventos EpochAdvanced, RulesChanged e RootRolledBack indicam o que aconteceu; reveja-o e depois atualize a época fixada |
Os indexadores aplicam a mesma regra a si próprios: um nó deixa de sincronizar quando a época na cadeia ultrapassa a que o seu operador reviu, e indica a época sob a qual serve como anchored_epoch em Informação do indexador. Um indexador que indique uma época diferente da sua não é um através do qual deva resolver.
Verificar o próprio circuito
Os passos acima provam que um registo pertence a uma raiz que o contrato aceitou. O contrato só aceita uma raiz se esta vier acompanhada de uma prova ZK válida — e essa prova é verificada contra a programVkey, um compromisso de 32 bytes com o circuito compilado exato.
Pode confirmar que essa chave corresponde ao código-fonte publicado. Compile o circuito na imagem Docker do SP1, que fixa a toolchain e os caminhos de compilação de que a chave depende, e mostre a sua chave:
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 a chave de verificação resultante com programVkey() (seletor 0x09665ee7) no contrato
âncora. Se coincidirem, o contrato está a impor exatamente esse código-fonte. Alterar uma única
linha do circuito produz uma chave diferente, pelo que um circuito modificado não pode ser
substituído sem que a alteração fique visível na cadeia.
Também não pode entrar em vigor discretamente: uma nova chave passa pela alteração de regras com bloqueio temporal descrita no Passo 3, e faz avançar a época.
O README do prover lista a chave de cada versão e o commit a partir do qual foi compilada.
Compile sem funcionalidades adicionais
Uma compilação sem funcionalidades produz o circuito de mainnet que o contrato implantado impõe. Qualquer flag de funcionalidade altera o programa compilado e, por conseguinte, a sua chave de verificação, que deixará de corresponder. Uma compilação fora do Docker, ou com outra tag de imagem, também pode dar uma chave diferente.
Verificar diretamente uma prova SP1
As provas são provas SP1 Groth16 padrão e podem ser verificadas com o SDK do 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)?;
Os valores públicos são a codificação ABI de (bytes32 old_root, bytes32 new_root, uint32 end_block_height) — a transição de estado que o lote realizou e a altura do bloco ZCash
que cobre.