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.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:

  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​

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_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​

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.

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

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);
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.

Ü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.

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 — PIVX-Höhe des letzten Roots
programVkey()0x09665ee7bytes32 — 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.

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)

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.

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.

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)
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 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.

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 PIVX-Blockhöhe, die er abdeckt.