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:
- 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 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_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
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.
- Python
- PHP
- JavaScript
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()
<?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(string $requestedName, array $entry, string $expectedRoot): bool
{
// 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 = strtolower($requestedName);
if ($entry['domain_name'] !== $name) {
throw new RuntimeException('the answer is for another name');
}
if ($entry['proof_terminal'] !== 'Occupied') {
throw new RuntimeException('a resolution must carry an Occupied terminal');
}
// The leaf has no length prefixes: refuse fields of the wrong shape before hashing.
// The D modifier keeps `$` from matching before a trailing newline.
$hex32 = static fn($v): bool => is_string($v) && preg_match('/^[0-9a-f]{64}$/D', $v) === 1;
if (!$hex32($entry['owner_pubkey'])) {
throw new RuntimeException('owner_pubkey is not 32 bytes of lowercase hex');
}
foreach (['price', 'nonce'] as $field) {
// json_decode gives a float for an integer above PHP_INT_MAX, refused here too.
if (!is_int($entry[$field]) || $entry[$field] < 0) {
throw new RuntimeException("$field is not an unsigned 64-bit integer");
}
}
foreach ($entry['merkle_proof'] as $sibling) {
if (!$hex32($sibling)) {
throw new RuntimeException('a sibling is not 32 bytes of lowercase hex');
}
}
$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($name, $entry['owner_pubkey'], $entry['target_address'],
$entry['price'], $entry['nonce']);
return bin2hex(fold(keyOf($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;
}
const HEX32 = /^[0-9a-f]{64}$/;
// price and nonce as exact u64 values. JSON.parse reads an integer above 2^53 inexactly,
// and hashing it would hash a different number: such a value is refused, unless the
// response was parsed to keep it exact, as a BigInt (see below).
function u64(value, field) {
const n = typeof value === "bigint" ? value
: Number.isSafeInteger(value) ? BigInt(value) : null;
if (n === null || n < 0n || n >= 2n ** 64n) {
throw new Error(`${field} is not an exact unsigned 64-bit integer`);
}
return n;
}
export function verifyResolution(requestedName, entry, expectedRoot) {
// 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.
const name = requestedName.toLowerCase();
if (entry.domain_name !== name) {
throw new Error("the answer is for another name");
}
if (entry.proof_terminal !== "Occupied") {
throw new Error("a resolution must carry an Occupied terminal");
}
// The leaf has no length prefixes: refuse fields of the wrong shape before hashing.
if (typeof entry.owner_pubkey !== "string" || !HEX32.test(entry.owner_pubkey)) {
throw new Error("owner_pubkey is not 32 bytes of lowercase hex");
}
const price = u64(entry.price, "price");
const nonce = u64(entry.nonce, "nonce");
if (!entry.merkle_proof.every((s) => typeof s === "string" && HEX32.test(s))) {
throw new Error("a sibling is not 32 bytes of lowercase hex");
}
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(name, entry.owner_pubkey, entry.target_address, price, nonce);
return fold(keyOf(name), leaf, siblings).toString("hex") === expectedRoot.toLowerCase();
}
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);
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.
| 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 PIVX da última raiz |
programVkey() | 0x09665ee7 | bytes32 — 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.
- Python
- PHP
- JavaScript
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)
<?php
function evmRpc(string $rpcUrl, string $method, array $params): mixed
{
$payload = ['jsonrpc' => '2.0', 'method' => $method, 'params' => $params, '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);
if ($response === false) {
throw new RuntimeException('RPC request failed: ' . curl_error($ch));
}
$data = json_decode($response, true);
if (isset($data['error'])) {
throw new RuntimeException('EVM RPC error: ' . $data['error']['message']);
}
return $data['result'] ?? null;
}
// 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").
function finalizedBlock(string $rpcUrl): string
{
$block = evmRpc($rpcUrl, 'eth_getBlockByNumber', ['finalized', false]);
if (!is_array($block) || !is_string($block['number'] ?? null)) {
throw new RuntimeException('the endpoint does not serve the finalized block');
}
return $block['number'];
}
function isRootValid(string $rpcUrl, string $contractAddress, string $smtRoot, string $block): bool
{
$clean = str_pad(str_replace('0x', '', strtolower($smtRoot)), 64, '0', STR_PAD_LEFT);
$result = evmRpc($rpcUrl, 'eth_call', [['to' => $contractAddress, 'data' => '0x30ef41b4' . $clean], $block]) ?? '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';
}
// $block = finalizedBlock($rpcUrl);
// isRootValid($rpcUrl, $contractAddress, $entry['smt_root'], $block);
async function evmRpc(rpcUrl, method, params) {
const response = await fetch(rpcUrl, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ jsonrpc: "2.0", method, params, 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}`);
return json.result;
}
// 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").
async function finalizedBlock(rpcUrl) {
const block = await evmRpc(rpcUrl, "eth_getBlockByNumber", ["finalized", false]);
if (typeof block?.number !== "string") {
throw new Error("the endpoint does not serve the finalized block");
}
return block.number;
}
async function isRootValid(rpcUrl, contractAddress, smtRoot, block) {
const clean = smtRoot.replace(/^0x/, "").toLowerCase().padStart(64, "0");
const result = await evmRpc(rpcUrl, "eth_call", [
{ to: contractAddress, data: `0x30ef41b4${clean}` },
block,
]);
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;
}
// const block = await finalizedBlock(rpcUrl);
// await isRootValid(rpcUrl, contractAddress, entry.smt_root, block);
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.
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.
- Python
- PHP
- JavaScript
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)
<?php
// anchoredState() at that block: [root as 64 hex digits, PIVX block height, epoch].
function anchoredState(string $rpcUrl, string $contractAddress, string $block): array
{
$result = evmRpc($rpcUrl, 'eth_call', [['to' => $contractAddress, 'data' => '0x8d39310a'], $block]) ?? '0x';
$words = is_string($result) ? substr($result, 2) : '';
// Three 32-byte words: nothing more, nothing less, and nothing but hex digits.
if (strlen($words) !== 192 || !ctype_xdigit($words)) {
throw new RuntimeException('unexpected anchoredState() answer');
}
return [strtolower(substr($words, 0, 64)), hexdec(substr($words, 64, 64)), hexdec(substr($words, 128, 64))];
}
// 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;
// throws when the epoch in force is not the one you pinned.
function checkAnchor(string $rpcUrl, string $contractAddress, string $smtRoot, int $pinnedEpoch): string
{
$block = finalizedBlock($rpcUrl);
[$root, , $epoch] = anchoredState($rpcUrl, $contractAddress, $block);
if ($epoch !== $pinnedEpoch) {
throw new RuntimeException("epoch $epoch is in force, not the reviewed $pinnedEpoch: stop resolving");
}
if (str_pad(str_replace('0x', '', strtolower($smtRoot)), 64, '0', STR_PAD_LEFT) === $root) {
return 'accept';
}
return isRootValid($rpcUrl, $contractAddress, $smtRoot, $block) ? 'lagging' : 'reject';
}
// checkAnchor($rpcUrl, $contractAddress, $entry['smt_root'], $pinnedEpoch);
// anchoredState() at that block: { root (64 hex digits), blockHeight, epoch }.
async function anchoredState(rpcUrl, contractAddress, block) {
const result = await evmRpc(rpcUrl, "eth_call", [{ to: contractAddress, data: "0x8d39310a" }, block]);
const words = typeof result === "string" ? result.slice(2) : "";
// Three 32-byte words: nothing more, nothing less, and nothing but hex digits.
if (!/^[0-9a-fA-F]{192}$/.test(words)) throw new Error("unexpected anchoredState() answer");
return {
root: words.slice(0, 64).toLowerCase(),
blockHeight: Number(BigInt(`0x${words.slice(64, 128)}`)),
epoch: Number(BigInt(`0x${words.slice(128)}`)),
};
}
// 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;
// throws when the epoch in force is not the one you pinned.
async function checkAnchor(rpcUrl, contractAddress, smtRoot, pinnedEpoch) {
const block = await finalizedBlock(rpcUrl);
const { root, epoch } = await anchoredState(rpcUrl, contractAddress, block);
if (epoch !== pinnedEpoch) {
throw new Error(`epoch ${epoch} is in force, not the reviewed ${pinnedEpoch}: stop resolving`);
}
if (smtRoot.replace(/^0x/, "").toLowerCase().padStart(64, "0") === root) return "accept";
return (await isRootValid(rpcUrl, contractAddress, smtRoot, block)) ? "lagging" : "reject";
}
// await checkAnchor(rpcUrl, contractAddress, entry.smt_root, pinnedEpoch);
| É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 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.
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.