Zum Hauptinhalt springen

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:

  1. Der Merkle-Beweis bindet den Datensatz an einen Zustands-Root.
  2. Die On-Chain-Prüfung bindet diesen Root an den Anchor-Vertrag.
  3. 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_depth Geschwister — typischerweise eine Handvoll, nicht 128. Nehmen Sie nie eine feste Länge an; lesen Sie proof_depth und prüfen Sie, dass es zu merkle_proof.length passt.
  • 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:

TerminalBedeutung
Occupieddort steht das eigene Blatt des Schlüssels — der Name existiert
Vacantdort steht ein leerer Teilbaum — der Name ist nicht registriert
Blockeddort 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​

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

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.

AufrufSelektorRückgabe
isRootValid(bytes32)0x30ef41b4bool — angenommen und seitdem nicht zurückgerollt
currentRoot()0xfdab463dbytes32 — der zuletzt angenommene Root
verifyRootValidity(bytes32)0xc7179944(bool isValid, uint32 blockHeight)
currentBlockHeight()0x367bf2f9uint32 — ZCash-Höhe des letzten Roots
programVkey()0x09665ee7bytes32 — die Schaltung, die der Vertrag durchsetzt
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

Die Antwort deuten​

isRootValidBedeutungWas zu tun ist
true, und der Root entspricht currentRoot()der Indexer ist vollständig synchronisiertannehmen
true, aber der Root ist älter als currentRoot()der Indexer hinkt der Kette hinterhernoch keine Zahlung senden — warten oder einen anderen Indexer fragen, dann erneut prüfen
falsedieser Root wurde on-chain nie angenommen oder wurde zurückgerolltdie 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 in rulesChangeActivatesAt() 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:

AufrufSelektorRückgabe
anchoredState()0x8d39310a(bytes32 root, uint32 blockHeight, uint32 currentEpoch)
epoch()0x900cf0cfuint32 — die geltende Epoche
rulesChangeActivatesAt()0x90b86556uint64 — 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.

EpocheWas zu tun ist
entspricht Ihrer festgelegten Epocheweitermachen — die Schritte 1 und 2 gelten unter Regeln, die Sie geprüft haben
höher als Ihre festgelegte EpocheAuflö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.

warnung

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.