Pular para o conteúdo principal

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.pivx?». 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. Nem um que responda com o registo autêntico de outro nome: as verificações abaixo ligam a resposta ao nome que pediu.

Há três passos independentes, e precisa dos três:

  1. A prova de Merkle liga o registo a uma raiz de estado.
  2. A verificação na cadeia liga essa raiz ao contrato âncora.
  3. 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 PiNS 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_depth irmãos — normalmente um punhado, não 128. Nunca presuma um comprimento fixo; leia proof_depth e confirme que corresponde a merkle_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:

TerminalSignificado
Occupiedali está a folha própria da chave — o nome existe
Vacantali está uma subárvore vazia — o nome não está registado
Blockedali 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​

O verificador recebe, além da resposta, o nome que pediu, e calcula o hash desse nome, nunca do domain_name que vem na resposta. Caso contrário, um indexador poderia responder com o registo e a prova autênticos de outro nome, que se verificam sem falha, e pagaria ao dono desse nome. Também recusa campos com a forma errada antes de calcular qualquer hash: a folha não tem prefixos de comprimento, pelo que um campo com o comprimento errado deslocaria bytes para o seu vizinho.

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()

Em JavaScript, JSON.parse lê de forma inexata os inteiros acima de 2^53, pelo que o exemplo recusa um price ou um nonce tão grandes (um preço acima de cerca de 90 milhões de PIVX) em vez de calcular o hash de outro número. Para verificar um registo assim, analise a resposta de modo a que ambos os valores se mantenham exatos (Node.js 21 ou posterior, browsers atuais):

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

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.

Depois, passe a resposta autêntica de um nome enquanto pede outro: o verificador tem de a recusar. Os exemplos também são verificados assim.


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.

ChamadaSeletorDevolve
isRootValid(bytes32)0x30ef41b4bool — aceite e não revertida desde então
currentRoot()0xfdab463dbytes32 — a última raiz aceite
verifyRootValidity(bytes32)0xc7179944(bool isValid, uint32 blockHeight)
currentBlockHeight()0x367bf2f9uint32 — altura PIVX da última raiz
programVkey()0x09665ee7bytes32 — o circuito que o contrato impõe

Os exemplos leem o contrato no bloco finalizado (finalized) mais recente, como fazem os indexadores: uma raiz aceite num bloco que ainda não é final pode ainda desaparecer numa reorganização da cadeia, e um pagamento feito com base nela não teria fundamento. Primeiro pedem o número desse bloco e depois leem nele, porque alguns endpoints públicos da BSC recusam a etiqueta finalized dentro de eth_call. Leia currentRoot() e as chamadas do Passo 3 nesse mesmo número, para que todas as respostas descrevam o mesmo bloco.

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)

Como interpretar a resposta​

isRootValidSignificadoO que fazer
true, e a raiz é igual a currentRoot()o indexador está totalmente sincronizadoaceitar
true, mas a raiz é anterior a currentRoot()o indexador está atrasado face à cadeianão envie fundos ainda — aguarde ou consulte outro indexador e verifique novamente
falseesta raiz nunca foi aceite na cadeia, ou foi revertidarejeitar 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 em rulesChangeActivatesAt().
  • 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 false para 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:

ChamadaSeletorDevolve
anchoredState()0x8d39310a(bytes32 root, uint32 blockHeight, uint32 currentEpoch)
epoch()0x900cf0cfuint32 — a época em vigor
rulesChangeActivatesAt()0x90b86556uint64 — 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.

Os exemplos abaixo acrescentam este passo aos do Passo 2 e reutilizam as suas funções. Num mesmo bloco finalizado leem anchoredState(), recusam qualquer época diferente da que fixou e depois classificam a raiz como a tabela do Passo 2: accept para a raiz atual, lagging para uma válida mais antiga e reject para uma que o contrato não aceita.

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)
ÉpocaO que fazer
igual à sua época fixadacontinue — os passos 1 e 2 valem sob regras que reviu
superior à sua época fixadapare 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 seguir a cadeia quando a época na cadeia ultrapassa a que o seu operador reviu, e indica essa época revista como anchored_epoch em Informação do indexador. É uma definição do nó, não a época da raiz que serve: um nó atualizado antes de uma alteração de regras agendada já indica a época seguinte enquanto a alteração cumpre o seu bloqueio temporal, e até lá serve um estado criado sob a época em vigor. Por isso, avalie uma resolução pela época lida do contrato juntamente com a raiz, como acima, e não por anchored_epoch; o Passo 2 mostra se a raiz do nó está atualizada.


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

aviso

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 PIVX que cobre.