Перейти до основного вмісту

Перевірка доказів

Ця сторінка показує, як перевірити розв'язання імені, не довіряючи індексатору, який його видав. Кожен приклад коду тут перед публікацією виконується на живому індексаторі.

Що дає перевірка​

Розв'язання імені відповідає на запитання «на яку адресу вказує richard.pivx?». Перевірка доводить, що ця відповідь — саме та, яку зафіксовано в корені стану, і що цей корінь — поточний корінь якірного контракту. Індексатор, який вигадає адресу, віддасть застарілий запис чи приховає ім'я, не зможе пред'явити доказ, який проходить ці перевірки. Не зможе й той, хто відповість справжнім записом іншого імені: перевірки нижче прив'язують відповідь до імені, яке ви запитали.

Кроків три, вони незалежні, і потрібні всі три:

  1. Доказ Меркла пов'язує запис із коренем стану.
  2. Перевірка в блокчейні пов'язує цей корінь із якірним контрактом.
  3. Перевірка епохи пов'язує правила й історію контракту з тими, які ви перевірили.

Один лише крок 1 марний: шкідливий індексатор може побудувати ціле підроблене дерево і видавати узгоджені докази відносно власного підробленого кореня. Сенс кореню надає саме крок 2, а крок 3 зберігає цей сенс, коли змінюються правила або стан відкочується.


Крок 1 — перевірте доказ Меркла​

Дерево​

PiNS використовує компактне розріджене дерево Меркла над 128-бітовим простором ключів. Ключ — це перші 16 байтів SHA-256(domain_name). При написанні верифікатора важливі дві властивості:

  • Докази короткі та змінної довжини. Лист розміщується на мінімальній глибині, де префікс його ключа унікальний, тому доказ несе proof_depth сусідів — зазвичай кілька штук, а не 128. Ніколи не розраховуйте на фіксовану довжину; читайте proof_depth і перевіряйте, що воно збігається з merkle_proof.length.
  • Порожнє піддерево — це 32 нульові байти на будь-якій висоті. Жодних сходів заздалегідь обчислених хешів порожніх вузлів немає. Тому корінь порожнього дерева складається з самих нулів.

Хеш-функції​

Листи і внутрішні вузли позначаються тегами, щоб їхні області хешування не перетиналися. Пропуск байта тега — найчастіша помилка: вона дає правдоподібний на вигляд хеш, який ніколи не збіжиться з коренем.

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 і target_address — це байти UTF-8 без префікса довжини; owner_pubkey — сирі 32 байти; price і nonce — беззнакові 64-бітові little-endian.

Обхід​

Ідіть від листа назад до кореня. За n = proof_depth сусідів на кроці i бік визначає біт n - 1 - i ключа, рахуючи від старшого біта байта 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] — це сусід на найглибшому рівні, найближчий до листа.

Термінал​

Кожен доказ несе proof_terminal, що описує, яка річ розташована в кінці шляху:

ТерміналЗначення
Occupiedтам власний лист ключа — ім'я існує
Vacantтам порожнє піддерево — ім'я не зареєстроване
Blockedтам лист іншого імені — запитане ім'я не зареєстроване, а відповідь містить повний запис того імені

Успішне розв'язання має мати термінал Occupied. Vacant і Blocked — це докази відсутності: вони дозволяють переконатися, що ім'я справді не зареєстроване, а не приймати на віру «не знайдено» від індексатора. Відхиляйте будь-яке розв'язання, термінал якого відрізняється від Occupied.

API розв'язання імен поки що не повертає доказів відсутності: на ім'я, якого він не знає, він відповідає Domain not found зовсім без доказу. Поки це так, вважайте «not found» неперевіреним і перевіряйте його через другий індексатор.

Код​

Верифікатор приймає не лише відповідь, а й запитане вами ім'я, і хешує саме його, а не domain_name з відповіді. Інакше індексатор міг би відповісти справжнім записом і доказом іншого імені, які бездоганно проходять перевірку, і ви заплатили б власникові того імені. Крім того, поля неправильного вигляду відхиляються ще до хешування: лист не має префіксів довжини, тож поле неправильної довжини зсунуло б байти в сусіднє.

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

У JavaScript JSON.parse читає цілі числа понад 2^53 неточно, тому приклад відхиляє такі великі price або nonce (ціну понад приблизно 90 мільйонів PIVX), а не хешує інше число. Щоб перевірити такий запис, розберіть відповідь так, щоб обидва значення лишилися точними (Node.js 21 або новіший, сучасні браузери):

const body = JSON.parse(text, (key, value, context) =>
(key === "price" || key === "nonce") && typeof value === "number"
? BigInt(context.source)
: value);
порада

Перевірте свою реалізацію на підробці

Верифікатор, який завжди повертає true, проходить будь-який позитивний тест. Перш ніж довіряти своєму, змініть один байт у target_address, owner_pubkey чи price у реальній відповіді і переконайтеся, що тепер він повертає false. Усі три приклади вище перевірені саме так.

Потім передайте справжню відповідь для одного імені, запитавши інше: верифікатор мусить її відхилити. Приклади перевірено й на це.


Крок 2 — звірте корінь із якірним контрактом​

Перевірений доказ Меркла каже лише «цей запис є в якомусь дереві». Щоб дізнатися, що він у справжньому дереві, запитайте в якірного контракту в BNB Smart Chain, чи дійсний цей корінь: прийнятий у блокчейні й відтоді не відкочений.

Використовуйте isRootValid(bytes32) — селектор 0x30ef41b4. Він повертає одне логічне значення в ABI-кодуванні: це все, що потрібно цьому кроку, і розібрати його простіше, ніж пару (bool, uint32), яку повертає verifyRootValidity.

ВикликСелекторПовертає
isRootValid(bytes32)0x30ef41b4bool — прийнятий і відтоді не відкочений
currentRoot()0xfdab463dbytes32 — останній прийнятий корінь
verifyRootValidity(bytes32)0xc7179944(bool isValid, uint32 blockHeight)
currentBlockHeight()0x367bf2f9uint32 — висота PIVX для останнього кореня
programVkey()0x09665ee7bytes32 — схема, якої вимагає контракт

Приклади читають контракт на останньому фіналізованому (finalized) блоці, як це роблять індексатори: корінь, прийнятий у ще не фінальному блоці, може зникнути під час реорганізації ланцюжка, і платіж, зроблений за ним, ні на чому б не тримався. Спершу вони запитують номер цього блоку, а потім читають за ним, бо деякі публічні ендпоінти BSC відхиляють тег finalized усередині eth_call. Читайте currentRoot() і виклики кроку 3 за тим самим номером, щоб усі відповіді описували один і той самий блок.

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)

Як читати відповідь​

isRootValidЗначенняЩо робити
true, і корінь дорівнює currentRoot()індексатор повністю синхронізованийприйняти
true, але корінь старіший за currentRoot()індексатор відстає від ланцюжкапоки не надсилайте кошти — зачекайте або запитайте інший індексатор, потім перевірте знову
falseцей корінь ніколи не приймався в блокчейні або був відкоченийвідхилити розв'язання

Старіший дійсний корінь — це реальний минулий стан реєстру, але не поточний. Відтоді ім'я могли передати, продати чи спрямувати на нову адресу, а доказ відносно старого кореня й далі показує попередню відповідь. Повільний індексатор та індексатор, який приховує недавнє оновлення, тут виглядають однаково, тож перед оплатою вимагайте, щоб корінь збігався з currentRoot(). Чесний індексатор наздоганяє ланцюжок незабаром після кожного нового пакета. Показати запис для інформації, позначивши його як можливо застарілий, — припустимо.

Значення false означає, що дерево, відносно якого ви перевіряли, з погляду протоколу не входить до історії реєстру: його або ніколи не приймали, або від нього відмовилися під час відкату. Саме такий випадок створює індексатор під контролем зловмисника, і саме заради нього потрібен цей крок.


Крок 3 — перевірте епоху​

Кроки 1 і 2 доводять, що запис є в дереві, яке прийняв контракт. Дві речі можуть змінити те, що це доводить, без жодного нового батчу: зміна правил — нова схема чи верифікатор, а отже, нове визначення того, що вважається доведеним, — і відкат, який знову робить поточним старіший корінь і тим самим перенаправляє кожне ім'я, змінене відтоді, без підпису його власника. Контракт рахує і те, і інше в epoch:

  • Лічильник починається з 1 і зростає на одиницю з кожною зміною правил і кожним відкатом. Він ніколи не зменшується: зміна та її скасування — це дві епохи, а не повернення до першої.
  • Зміна правил оголошується заздалегідь. Схвалення власника запускає таймлок, заданий під час розгортання (rulesTimelock, від 7 до 90 днів), і активувати зміну можна лише після настання моменту, вказаного в rulesChangeActivatesAt().
  • Відкат може бути спрямований лише на корінь, який контракт приймав раніше, і лише поки надсилання батчів призупинено. Усі корені вище цілі одразу перестають бути дійсними, і відтоді крок 2 повертає для кожного з них false.

Тож зафіксуйте перевірену вами епоху й відмовляйтеся розв'язувати імена під будь-якою іншою. Читайте її разом із коренем, одним викликом, щоб обидва значення були взяті з одного блоку:

ВикликСелекторПовертає
anchoredState()0x8d39310a(bytes32 root, uint32 blockHeight, uint32 currentEpoch)
epoch()0x900cf0cfuint32 — чинна епоха
rulesChangeActivatesAt()0x90b86556uint64 — коли заплановану зміну правил можна активувати; 0, якщо нічого не заплановано

anchoredState() повертає три 32-байтові слова в такому порядку: корінь, висоту блоку й епоху. Епоха — це ціле число в третьому слові.

Приклади нижче додають цей крок до прикладів кроку 2 і використовують їхні функції. В одному фіналізованому блоці вони читають anchoredState(), відмовляються від епохи, відмінної від зафіксованої вами, а потім відносять корінь до одного з випадків таблиці кроку 2: accept для поточного кореня, lagging для старішого дійсного, reject для кореня, який контракт не приймає.

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)
ЕпохаЩо робити
дорівнює зафіксованій вамипродовжуйте — кроки 1 і 2 діють за правилами, які ви перевірили
більша за зафіксовану вамиприпиніть розв'язувати імена. Події EpochAdvanced, RulesChanged і RootRolledBack показують, що сталося; перевірте це, потім оновіть зафіксовану епоху

Індексатори застосовують те саме правило до себе: вузол перестає стежити за ланцюжком, коли епоха в блокчейні виходить за перевірену його оператором, і повідомляє цю перевірену епоху як anchored_epoch у розділі Інформація про індексатор. Це налаштування вузла, а не епоха кореня, який він віддає: вузол, оновлений заздалегідь під заплановану зміну правил, уже повідомляє майбутню епоху, поки зміна вичікує свій таймлок, і доти віддає стан, створений під чинною епохою. Тож оцінюйте результат за епохою, прочитаною з контракту разом із коренем, як описано вище, а не за anchored_epoch; чи актуальний корінь вузла, показує Крок 2.


Перевірка самої схеми​

Кроки вище доводять, що запис належить кореню, який прийняв контракт. А корінь контракт приймає лише разом із коректним ZK-доказом, який перевіряється відносно programVkey — 32-байтового зобов'язання до конкретної скомпільованої схеми.

Переконатися, що цей ключ відповідає опублікованому вихідному коду, можна так: зберіть схему в Docker-образі SP1, який фіксує тулчейн і шляхи збирання, від яких залежить ключ, і виведіть її ключ:

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

Порівняйте отриманий ключ верифікації з programVkey() (селектор 0x09665ee7) у якірному контракті. Якщо вони збігаються, контракт вимагає саме цей вихідний код. Зміна хоча б одного рядка схеми дає інший ключ, тому підмінити схему непомітно для блокчейну неможливо. І набути чинності непомітно вона теж не може: новий ключ проходить через зміну правил із таймлоком, описану в кроці 3, і збільшує епоху.

Ключ кожного релізу та коміт, з якого його зібрано, перелічено в README прувера.

попередження

Збирайте без додаткових фіч

Збирання без фіч дає схему основної мережі, якої вимагає розгорнутий контракт. Будь-який прапорець фічі змінює скомпільовану програму, а отже і її ключ верифікації, який після цього не збіжиться. Інший ключ може дати й збирання поза Docker або з іншим тегом образу.

Пряма перевірка доказу SP1​

Докази — це стандартні докази SP1 Groth16, і перевірити їх можна за допомогою SDK 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)?;

Публічні значення — це ABI-кодування (bytes32 old_root, bytes32 new_root, uint32 end_block_height): перехід стану, виконаний пакетом, і висота блоку PIVX, яку він покриває.