Beweise prüfen
Diese Seite zeigt, wie Sie eine Namensauflösung prüfen, ohne dem Indexer zu vertrauen, der sie geliefert hat. Jedes Codebeispiel hier wird vor der Veröffentlichung gegen einen laufenden Indexer ausgeführt.
Was die Prüfung Ihnen bringt
Eine Auflösung beantwortet: „Auf welche Adresse zeigt richard.pivx?“ Die Prüfung belegt,
dass die Antwort diejenige ist, auf die sich der Zustands-Root festgelegt hat — und dass der
Root der aktuelle Root des Anchor-Vertrags ist. Ein Indexer, der eine Adresse erfindet,
einen veralteten Datensatz liefert oder einen Namen unterschlägt, kann keinen Beweis
vorlegen, der diese Prüfungen besteht.
Ebenso wenig einer, der mit dem echten Eintrag eines anderen Namens antwortet: Die Prüfungen unten binden die Antwort an den Namen, nach dem Sie gefragt haben.
Es gibt drei unabhängige Schritte, und Sie brauchen alle drei:
- Der Merkle-Beweis bindet den Datensatz an einen Zustands-Root.
- Die On-Chain-Prüfung bindet diesen Root an den Anchor-Vertrag.
- Die Epochen-Prüfung bindet die Regeln und die Historie des Vertrags an die, die Sie geprüft haben.
Schritt 1 allein ist wertlos: Ein bösartiger Indexer kann einen kompletten gefälschten Baum bauen und dazu passende Beweise gegen seinen eigenen gefälschten Root liefern. Erst Schritt 2 macht den Root aussagekräftig, und Schritt 3 sorgt dafür, dass er es bleibt, wenn sich die Regeln ändern oder der Zustand zurückgerollt wird.
Schritt 1 — den Merkle-Beweis prüfen
Der Baum
PiNS nutzt einen kompakten Sparse Merkle Tree über einem 128-Bit-Schlüsselraum. Ein
Schlüssel sind die ersten 16 Bytes von SHA-256(domain_name). Beim Schreiben eines
Verifizierers sind zwei Eigenschaften wichtig:
- Beweise sind kurz und von variabler Länge. Ein Blatt sitzt auf der geringsten Tiefe, in
der sein Schlüsselpräfix eindeutig ist, ein Beweis trägt also
proof_depthGeschwister — typischerweise eine Handvoll, nicht 128. Nehmen Sie nie eine feste Länge an; lesen Sieproof_depthund prüfen Sie, dass es zumerkle_proof.lengthpasst. - Ein leerer Teilbaum ist auf jeder Höhe 32 Nullbytes. Es gibt keine Leiter vorberechneter Hashes für leere Knoten. Der Root eines leeren Baums besteht daher aus lauter Nullen.
Die Hashfunktionen
Blätter und innere Knoten werden markiert, damit sich ihre Hash-Domänen nicht überschneiden. Das Tag-Byte wegzulassen ist der mit Abstand häufigste Fehler — er erzeugt einen plausibel aussehenden Hash, der nie zum Root passt.
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 und target_address sind UTF-8-Bytes ohne Längenpräfix; owner_pubkey sind die
rohen 32 Bytes; price und nonce sind vorzeichenlose 64-Bit-Werte in Little-Endian.
Der Durchlauf
Gehen Sie vom Blatt zurück zum Root. Bei n = proof_depth Geschwistern entscheidet in Schritt
i das Bit n - 1 - i des Schlüssels darüber, auf welcher Seite Sie stehen, gezählt ab dem
höchstwertigen Bit von 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] ist das Geschwister auf der tiefsten Ebene, dem Blatt am nächsten.
Das Terminal
Jeder Beweis trägt ein proof_terminal, das beschreibt, was am Ende des Pfads steht:
| Terminal | Bedeutung |
|---|---|
Occupied | dort steht das eigene Blatt des Schlüssels — der Name existiert |
Vacant | dort steht ein leerer Teilbaum — der Name ist nicht registriert |
Blocked | dort steht das Blatt eines anderen Namens — der Name ist nicht registriert, und die Antwort enthält den vollständigen Datensatz jenes Namens |
Eine erfolgreiche Auflösung muss Occupied sein. Vacant und Blocked sind
Abwesenheits-Beweise: Sie erlauben es, zu prüfen, dass ein Name wirklich nicht registriert
ist, statt einem „nicht gefunden“ des Indexers zu glauben. Weisen Sie jede Auflösung zurück,
deren Terminal nicht Occupied ist.
Die Resolve-API liefert noch keine Abwesenheitsbeweise: Für einen Namen, den sie nicht kennt,
antwortet sie ganz ohne Beweis mit Domain not found. Bis sich das ändert, behandeln Sie ein
„not found“ als ungeprüft und prüfen Sie es mit einem zweiten Indexer.
Code
Der Verifizierer nimmt neben der Antwort auch den Namen entgegen, nach dem Sie gefragt haben, und hasht diesen Namen, nie den domain_name aus der Antwort. Sonst könnte ein Indexer mit dem echten Eintrag und Beweis eines anderen Namens antworten, die sich einwandfrei verifizieren lassen, und Sie würden an den Inhaber dieses Namens zahlen. Außerdem lehnt er Felder in falscher Form ab, bevor er irgendetwas hasht: Das Blatt hat keine Längenpräfixe, ein Feld falscher Länge würde also Bytes in sein Nachbarfeld verschieben.
- 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();
}
In JavaScript liest JSON.parse ganze Zahlen über 2^53 ungenau. Deshalb lehnt das Beispiel einen so großen price oder nonce (einen Preis über etwa 90 Millionen PIVX) ab, statt eine andere Zahl zu hashen. Um einen solchen Eintrag zu verifizieren, parsen Sie die Antwort so, dass beide Werte exakt bleiben (Node.js 21 oder neuer, aktuelle Browser):
const body = JSON.parse(text, (key, value, context) =>
(key === "price" || key === "nonce") && typeof value === "number"
? BigInt(context.source)
: value);
Testen Sie Ihre Implementierung gegen Manipulation
Ein Verifizierer, der immer true zurückgibt, besteht jeden positiven Test. Bevor Sie Ihrem
vertrauen: Ändern Sie in einer echten Antwort ein Byte von target_address, owner_pubkey
oder price und bestätigen Sie, dass er nun false liefert. Alle drei Beispiele oben sind so
geprüft.
Übergeben Sie danach die echte Antwort für einen Namen, während Sie nach einem anderen fragen: Der Verifizierer muss sie ablehnen. Auch darauf sind die Beispiele geprüft.
Schritt 2 — den Root gegen den Anchor-Vertrag prüfen
Ein verifizierter Merkle-Beweis sagt nur: „Dieser Datensatz liegt in irgendeinem Baum.“ Um zu wissen, dass er im echten Baum liegt, fragen Sie den Anchor-Vertrag auf der BNB Smart Chain, ob dieser Root gültig ist: on-chain angenommen und seitdem nicht zurückgerollt.
Verwenden Sie isRootValid(bytes32) — Selektor 0x30ef41b4. Er liefert einen einzelnen ABI-kodierten Boolean: alles, was dieser Schritt braucht, und einfacher auszuwerten als das (bool, uint32)-Paar, das verifyRootValidity zurückgibt.
| Aufruf | Selektor | Rückgabe |
|---|---|---|
isRootValid(bytes32) | 0x30ef41b4 | bool — angenommen und seitdem nicht zurückgerollt |
currentRoot() | 0xfdab463d | bytes32 — der zuletzt angenommene Root |
verifyRootValidity(bytes32) | 0xc7179944 | (bool isValid, uint32 blockHeight) |
currentBlockHeight() | 0x367bf2f9 | uint32 — PIVX-Höhe des letzten Roots |
programVkey() | 0x09665ee7 | bytes32 — die Schaltung, die der Vertrag durchsetzt |
Die Beispiele lesen den Vertrag am neuesten finalisierten Block (finalized), so wie es die Indexer tun: Ein Root, der in einem noch nicht finalen Block akzeptiert wurde, kann bei einer Reorganisation der Chain noch verschwinden, und eine darauf gestützte Zahlung hätte keine Grundlage. Sie fragen zuerst die Nummer dieses Blocks ab und lesen dann an ihr, weil manche öffentlichen BSC-Endpunkte das Tag finalized innerhalb von eth_call ablehnen. Lesen Sie currentRoot() und die Aufrufe aus Schritt 3 an derselben Nummer, damit jede Antwort denselben Block beschreibt.
- 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);
Die Antwort deuten
isRootValid | Bedeutung | Was zu tun ist |
|---|---|---|
true, und der Root entspricht currentRoot() | der Indexer ist vollständig synchronisiert | annehmen |
true, aber der Root ist älter als currentRoot() | der Indexer hinkt der Kette hinterher | noch keine Zahlung senden — warten oder einen anderen Indexer fragen, dann erneut prüfen |
false | dieser Root wurde on-chain nie angenommen oder wurde zurückgerollt | die Auflösung zurückweisen |
Ein älterer gültiger Root ist ein echter früherer Zustand des Registers, aber nicht der aktuelle.
Seitdem kann der Name übertragen, verkauft oder auf eine neue Adresse umgestellt worden sein, und
ein Beweis gegen den älteren Root zeigt weiterhin die frühere Antwort. Ein langsamer Indexer und
einer, der ein jüngstes Update zurückhält, sehen hier genau gleich aus. Verlangen Sie deshalb vor
einer Zahlung, dass der Root currentRoot() entspricht. Ein ehrlicher Indexer holt kurz nach
jedem neuen Batch auf. Den Datensatz zur Information anzuzeigen, als möglicherweise veraltet
gekennzeichnet, ist in Ordnung.
Ein false bedeutet, dass der Baum, gegen den Sie geprüft haben, aus Sicht des Protokolls nicht
zur Geschichte des Registers gehört: Er wurde nie angenommen, oder ein Rollback hat ihn
verworfen. Genau diesen Fall erzeugt ein von einem Angreifer kontrollierter Indexer, und genau
dafür ist dieser Schritt da.
Schritt 3 — die Epoche prüfen
Die Schritte 1 und 2 belegen, dass ein Datensatz in einem Baum steht, den der Vertrag angenommen hat. Zwei Dinge können ändern, was das belegt, ganz ohne neuen Batch: eine Regeländerung — eine neue Schaltung oder ein neuer Verifier und damit eine neue Definition dessen, was als bewiesen gilt — und ein Rollback, der einen älteren Root wieder zum aktuellen macht und damit jeden seither geänderten Namen umleitet, ohne Signatur seines Inhabers. Der Vertrag zählt beides in epoch:
- Der Zähler beginnt bei 1 und steigt mit jeder Regeländerung und jedem Rollback um eins. Er sinkt nie: Eine Änderung und ihre Rücknahme sind zwei Epochen, keine Rückkehr zur ersten.
- Eine Regeländerung wird im Voraus angekündigt. Die Zustimmung des Eigentümers startet einen beim Deployment festgelegten Timelock (
rulesTimelock, zwischen 7 und 90 Tagen), und die Änderung kann erst aktiviert werden, wenn der Zeitpunkt inrulesChangeActivatesAt()erreicht ist. - Ein Rollback kann nur auf einen Root zielen, den der Vertrag früher angenommen hat, und nur, während das Einreichen von Batches pausiert ist. Jeder Root oberhalb des Ziels verliert sofort seine Gültigkeit, und Schritt 2 liefert ab dann für jeden davon
false.
Legen Sie also die Epoche fest, die Sie geprüft haben, und verweigern Sie die Auflösung unter jeder anderen. Lesen Sie sie zusammen mit dem Root in einem einzigen Aufruf, damit beide aus demselben Block stammen:
| Aufruf | Selektor | Rückgabe |
|---|---|---|
anchoredState() | 0x8d39310a | (bytes32 root, uint32 blockHeight, uint32 currentEpoch) |
epoch() | 0x900cf0cf | uint32 — die geltende Epoche |
rulesChangeActivatesAt() | 0x90b86556 | uint64 — wann eine geplante Regeländerung aktiviert werden kann; 0, wenn keine geplant ist |
anchoredState() liefert drei 32-Byte-Wörter in dieser Reihenfolge: den Root, die Blockhöhe und die Epoche. Die Epoche ist die Ganzzahl im dritten Wort.
Die folgenden Beispiele ergänzen die aus Schritt 2 um diesen Schritt und verwenden deren
Funktionen. In einem finalisierten Block lesen sie anchoredState(), verweigern jede andere
Epoche als die festgelegte und ordnen den Root dann wie die Tabelle in Schritt 2 ein: accept
für den aktuellen Root, lagging für einen älteren gültigen, reject für einen, den der
Vertrag nicht annimmt.
- 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);
| Epoche | Was zu tun ist |
|---|---|
| entspricht Ihrer festgelegten Epoche | weitermachen — die Schritte 1 und 2 gelten unter Regeln, die Sie geprüft haben |
| höher als Ihre festgelegte Epoche | Auflösung stoppen. Die Events EpochAdvanced, RulesChanged und RootRolledBack zeigen, was passiert ist; prüfen Sie es und passen Sie dann Ihre Festlegung an |
Indexer wenden dieselbe Regel auf sich selbst an: Ein Knoten folgt der Kette nicht mehr, wenn die On-Chain-Epoche über die von seinem Betreiber geprüfte hinausgeht, und meldet diese geprüfte Epoche als anchored_epoch in Indexer-Info. Sie ist eine Einstellung des Knotens, nicht die Epoche des Roots, den er ausliefert: Ein Knoten, der vor einer angesetzten Regeländerung aktualisiert wurde, meldet bereits die kommende Epoche, während die Änderung ihren Timelock abwartet, und liefert bis dahin einen Zustand aus, der unter der geltenden Epoche entstanden ist. Beurteilen Sie eine Auflösung daher nach der Epoche, die Sie wie oben zusammen mit dem Root aus dem Vertrag lesen, nicht nach anchored_epoch; ob der Root des Knotens aktuell ist, zeigt Schritt 2.
Die Schaltung selbst prüfen
Die Schritte oben belegen, dass ein Datensatz zu einem Root gehört, den der Vertrag angenommen hat. Der Vertrag nimmt einen Root nur an, wenn ein gültiger ZK-Beweis dabei war — und dieser Beweis wird gegen programVkey geprüft, eine 32-Byte-Festlegung auf die exakt kompilierte Schaltung.
Dass dieser Schlüssel dem veröffentlichten Quellcode entspricht, können Sie bestätigen. Bauen Sie die Schaltung im Docker-Image von SP1, das die Toolchain und die Build-Pfade festlegt, von denen der Schlüssel abhängt, und geben Sie ihren Schlüssel aus:
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
Vergleichen Sie den entstandenen Verification Key mit programVkey() (Selektor 0x09665ee7)
im Anchor-Vertrag. Stimmen sie überein, setzt der Vertrag genau diesen Quellcode durch. Eine
einzige geänderte Zeile der Schaltung ergibt einen anderen Schlüssel, eine veränderte Schaltung
lässt sich also nicht unterschieben, ohne dass die Änderung on-chain sichtbar wird.
Unbemerkt in Kraft treten kann sie ebenso wenig: Ein neuer Schlüssel durchläuft die in Schritt 3 beschriebene Regeländerung mit Timelock und erhöht die Epoche.
Das README des Provers listet den Schlüssel jedes Releases und den Commit, aus dem er gebaut wurde.
Ohne zusätzliche Features bauen
Ein Build ohne Features erzeugt die Mainnet-Schaltung, die der bereitgestellte Vertrag durchsetzt. Jedes Feature-Flag verändert das kompilierte Programm und damit seinen Verification Key, der dann nicht mehr passt. Auch ein Build außerhalb von Docker oder mit einem anderen Image-Tag kann einen anderen Schlüssel ergeben.
Einen SP1-Beweis direkt prüfen
Die Beweise sind gewöhnliche SP1-Groth16-Beweise und lassen sich mit dem SP1-SDK prüfen:
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)?;
Die öffentlichen Werte sind die ABI-Kodierung von (bytes32 old_root, bytes32 new_root, uint32 end_block_height) — der vom Batch ausgeführte Zustandsübergang und die PIVX-Blockhöhe,
die er abdeckt.