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.pivx?». 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.
Tampoco uno que responda con el registro auténtico de otro nombre: las comprobaciones de abajo vinculan la respuesta al nombre que usted pidió.
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
PiNS 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
El verificador recibe, además de la respuesta, el nombre que usted pidió, y calcula el hash de ese nombre, nunca del domain_name que trae la respuesta. De lo contrario, un indexador podría responder con el registro y la prueba auténticos de otro nombre, que se verifican sin fallo, y usted pagaría al propietario de ese nombre. También rechaza los campos con una forma incorrecta antes de calcular ningún hash: la hoja no tiene prefijos de longitud, así que un campo de longitud incorrecta desplazaría bytes a su vecino.
- 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();
}
En JavaScript, JSON.parse lee de forma inexacta los enteros mayores que 2^53, así que el ejemplo rechaza un price o un nonce tan grandes (un precio de más de unos 90 millones de PIVX) en lugar de calcular el hash de otro número. Para verificar un registro así, analice la respuesta de modo que ambos valores sigan siendo exactos (Node.js 21 o posterior, navegadores actuales):
const body = JSON.parse(text, (key, value, context) =>
(key === "price" || key === "nonce") && typeof value === "number"
? BigInt(context.source)
: value);
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í.
Después, pase la respuesta auténtica de un nombre mientras pide otro: el verificador debe rechazarla. Los ejemplos también 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 PIVX de la última raíz |
programVkey() | 0x09665ee7 | bytes32 — el circuito que impone el contrato |
Los ejemplos leen el contrato en el bloque finalizado (finalized) más reciente, como hacen los indexadores: una raíz aceptada en un bloque que aún no es definitivo todavía puede desaparecer en una reorganización de la cadena, y un pago hecho en base a ella no tendría fundamento. Primero piden el número de ese bloque y luego leen en él, porque algunos endpoints públicos de BSC rechazan la etiqueta finalized dentro de eth_call. Lea currentRoot() y las llamadas del Paso 3 en ese mismo número, para que todas las respuestas describan el mismo bloque.
- 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);
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.
Los ejemplos siguientes añaden este paso a los del Paso 2 y reutilizan sus funciones. En un
mismo bloque finalizado leen anchoredState(), rechazan cualquier época distinta de la que
fijó y después clasifican la raíz como la tabla del Paso 2: accept para la raíz actual,
lagging para una válida más antigua y reject para una que el contrato no acepta.
- 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 | 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 seguir la cadena cuando la época en la cadena supera la que revisó su operador, e informa de esa época revisada como anchored_epoch en Información del indexador. Es un ajuste del nodo, no la época de la raíz que sirve: un nodo actualizado antes de un cambio de reglas programado ya informa de la época venidera mientras el cambio cumple su bloqueo temporal, y hasta entonces sirve un estado creado bajo la época vigente. Por eso, juzgue una resolución por la época leída del contrato junto con la raíz, como se indica arriba, no por anchored_epoch; el Paso 2 muestra si la raíz del nodo está al día.
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/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 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
PIVX que cubre.