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.zcash?“ 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.
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
zNS 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
- Python
- PHP
- JavaScript
import hashlib
import struct
LEAF_TAG, NODE_TAG = b"\x00", b"\x01"
KEY_LEN, MAX_DEPTH = 16, 128
def hash_leaf(domain, owner_pubkey_hex, target_address, price, nonce):
h = hashlib.sha256()
h.update(LEAF_TAG)
h.update(domain.encode())
h.update(bytes.fromhex(owner_pubkey_hex))
h.update(target_address.encode())
h.update(struct.pack("<Q", price))
h.update(struct.pack("<Q", nonce))
return h.digest()
def hash_node(left, right):
h = hashlib.sha256()
h.update(NODE_TAG)
h.update(left)
h.update(right)
return h.digest()
def key_of(domain):
return hashlib.sha256(domain.encode()).digest()[:KEY_LEN]
def key_bit(key, i):
return (key[i // 8] >> (7 - (i % 8))) & 1
def fold(key, start, siblings):
h, n = start, len(siblings)
for i, sib in enumerate(siblings):
h = hash_node(sib, h) if key_bit(key, n - 1 - i) else hash_node(h, sib)
return h
def verify_resolution(entry, expected_root):
if entry["proof_terminal"] != "Occupied":
raise ValueError("a resolution must carry an Occupied terminal")
siblings = [bytes.fromhex(s) for s in entry["merkle_proof"]]
if len(siblings) != entry["proof_depth"]:
raise ValueError("proof_depth does not match the sibling count")
if entry["proof_depth"] > MAX_DEPTH:
raise ValueError("proof depth exceeds MAX_DEPTH")
leaf = hash_leaf(
entry["domain_name"],
entry["owner_pubkey"],
entry["target_address"],
int(entry["price"]),
int(entry["nonce"]),
)
root = fold(key_of(entry["domain_name"]), leaf, siblings)
return root.hex() == expected_root.lower()
<?php
const LEAF_TAG = "\x00";
const NODE_TAG = "\x01";
const KEY_LEN = 16;
const MAX_DEPTH = 128;
function hashLeaf(string $domain, string $ownerPubkeyHex, string $targetAddress, int $price, int $nonce): string
{
return hash('sha256',
LEAF_TAG
. $domain
. hex2bin($ownerPubkeyHex)
. $targetAddress
. pack('P', $price) // u64 little-endian
. pack('P', $nonce),
true);
}
function hashNode(string $left, string $right): string
{
return hash('sha256', NODE_TAG . $left . $right, true);
}
function keyOf(string $domain): string
{
return substr(hash('sha256', $domain, true), 0, KEY_LEN);
}
function keyBit(string $key, int $i): int
{
return (ord($key[intdiv($i, 8)]) >> (7 - ($i % 8))) & 1;
}
function fold(string $key, string $start, array $siblings): string
{
$h = $start;
$n = count($siblings);
foreach ($siblings as $i => $sib) {
$h = keyBit($key, $n - 1 - $i) === 1 ? hashNode($sib, $h) : hashNode($h, $sib);
}
return $h;
}
function verifyResolution(array $entry, string $expectedRoot): bool
{
if ($entry['proof_terminal'] !== 'Occupied') {
throw new RuntimeException('a resolution must carry an Occupied terminal');
}
$siblings = array_map('hex2bin', $entry['merkle_proof']);
if (count($siblings) !== (int)$entry['proof_depth']) {
throw new RuntimeException('proof_depth does not match the sibling count');
}
if ((int)$entry['proof_depth'] > MAX_DEPTH) {
throw new RuntimeException('proof depth exceeds MAX_DEPTH');
}
$leaf = hashLeaf($entry['domain_name'], $entry['owner_pubkey'], $entry['target_address'],
(int)$entry['price'], (int)$entry['nonce']);
return bin2hex(fold(keyOf($entry['domain_name']), $leaf, $siblings)) === strtolower($expectedRoot);
}
import crypto from "node:crypto";
const LEAF_TAG = 0x00;
const NODE_TAG = 0x01;
const KEY_LEN = 16;
const MAX_DEPTH = 128;
const sha256 = (...parts) =>
crypto.createHash("sha256").update(Buffer.concat(parts)).digest();
const u64le = (v) => {
const b = Buffer.alloc(8);
b.writeBigUInt64LE(BigInt(v));
return b;
};
function hashLeaf(domain, ownerPubkeyHex, targetAddress, price, nonce) {
return sha256(
Buffer.from([LEAF_TAG]),
Buffer.from(domain, "utf8"),
Buffer.from(ownerPubkeyHex, "hex"),
Buffer.from(targetAddress, "utf8"),
u64le(price),
u64le(nonce),
);
}
const hashNode = (l, r) => sha256(Buffer.from([NODE_TAG]), l, r);
const keyOf = (domain) =>
crypto.createHash("sha256").update(domain, "utf8").digest().subarray(0, KEY_LEN);
const keyBit = (key, i) => (key[Math.floor(i / 8)] >> (7 - (i % 8))) & 1;
function fold(key, start, siblings) {
let h = start;
const n = siblings.length;
for (let i = 0; i < n; i++) {
h = keyBit(key, n - 1 - i) ? hashNode(siblings[i], h) : hashNode(h, siblings[i]);
}
return h;
}
export function verifyResolution(entry, expectedRoot) {
if (entry.proof_terminal !== "Occupied") {
throw new Error("a resolution must carry an Occupied terminal");
}
const siblings = entry.merkle_proof.map((s) => Buffer.from(s, "hex"));
if (siblings.length !== entry.proof_depth) {
throw new Error("proof_depth does not match the sibling count");
}
if (entry.proof_depth > MAX_DEPTH) {
throw new Error("proof depth exceeds MAX_DEPTH");
}
const leaf = hashLeaf(
entry.domain_name,
entry.owner_pubkey,
entry.target_address,
Number(entry.price),
Number(entry.nonce),
);
return fold(keyOf(entry.domain_name), leaf, siblings).toString("hex")
=== expectedRoot.toLowerCase();
}
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.
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 — ZCash-Höhe des letzten Roots |
programVkey() | 0x09665ee7 | bytes32 — die Schaltung, die der Vertrag durchsetzt |
- Python
- PHP
- JavaScript
import requests
def is_root_valid(rpc_url, contract_address, smt_root):
"""Returns True if the anchor contract accepted this root and has not rolled it back."""
clean = smt_root.replace("0x", "").lower().rjust(64, "0")
payload = {
"jsonrpc": "2.0",
"method": "eth_call",
"params": [{"to": contract_address, "data": f"0x30ef41b4{clean}"}, "latest"],
"id": 1,
}
r = requests.post(rpc_url, json=payload, timeout=15).json()
if "error" in r:
raise RuntimeError(f"EVM RPC error: {r['error']['message']}")
result = r.get("result", "0x")
# A bool is ABI-encoded as a full 32-byte word: 0x00..01 for true.
return int(result, 16) == 1 if result not in ("", "0x") else False
<?php
function isRootValid(string $rpcUrl, string $contractAddress, string $smtRoot): bool
{
$clean = str_pad(str_replace('0x', '', strtolower($smtRoot)), 64, '0', STR_PAD_LEFT);
$payload = [
'jsonrpc' => '2.0',
'method' => 'eth_call',
'params' => [['to' => $contractAddress, 'data' => '0x30ef41b4' . $clean], 'latest'],
'id' => 1,
];
$ch = curl_init($rpcUrl);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_TIMEOUT => 15,
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
if (isset($data['error'])) {
throw new RuntimeException('EVM RPC error: ' . $data['error']['message']);
}
$result = $data['result'] ?? '0x';
if ($result === '' || $result === '0x') {
return false;
}
// A bool is ABI-encoded as a full 32-byte word: 0x00..01 for true. The whole word is
// compared, as in the Python and JavaScript versions: its last digit alone would read
// an answer such as 0x…11 as true.
$word = substr($result, 2);
return ctype_xdigit($word) && ltrim($word, '0') === '1';
}
async function isRootValid(rpcUrl, contractAddress, smtRoot) {
const clean = smtRoot.replace(/^0x/, "").toLowerCase().padStart(64, "0");
const response = await fetch(rpcUrl, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
jsonrpc: "2.0",
method: "eth_call",
params: [{ to: contractAddress, data: `0x30ef41b4${clean}` }, "latest"],
id: 1,
}),
});
if (!response.ok) throw new Error(`RPC request failed: ${response.statusText}`);
const json = await response.json();
if (json.error) throw new Error(`EVM RPC error: ${json.error.message}`);
const result = json.result;
if (!result || result === "0x") return false;
// A bool is ABI-encoded as a full 32-byte word: 0x00..01 for true.
return BigInt(result) === 1n;
}
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.
| 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 hört auf zu synchronisieren, wenn die On-Chain-Epoche über die von seinem Betreiber geprüfte hinausgeht, und meldet die Epoche, unter der er ausliefert, als anchored_epoch in Indexer-Info. Ein Indexer, der eine andere Epoche als Ihre meldet, ist keiner, über den Sie auflösen sollten.
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/ZCashNames/zcash-name-prover
cd zcash-name-prover/program
cargo prove build --docker --tag v6.9.0 # no features = mainnet
cargo prove vkey --elf ../target/elf-compilation/docker/riscv64im-succinct-zkvm-elf/release/zns-program
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 ZCash-Blockhöhe,
die er abdeckt.