Skip to main content

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

Гэтая старонка паказвае, як праверыць вырашэнне імя, не давяраючы індэксатару, які яго выдаў. Кожны прыклад кода тут перад публікацыяй выконваецца на жывым індэксатары.

Што дае праверка​

Вырашэнне імя адказвае на пытанне «на які адрас указвае richard.zcash?». Праверка даказвае, што гэты адказ — менавіта той, які зафіксаваны ў корані стану, і што гэты корань — бягучы корань якарнага кантракта. Індэксатар, які выдумае адрас, аддасць састарэлы запіс ці схавае імя, не зможа прад'явіць доказ, які праходзіць гэтыя праверкі.

Крокаў тры, яны незалежныя, і патрэбныя ўсе тры:

  1. Доказ Меркла звязвае запіс з коранем стану.
  2. Праверка ў блокчэйне звязвае гэты корань з якарным кантрактам.
  3. Праверка эпохі звязвае правілы і гісторыю кантракта з тымі, што вы праверылі.

Адзін толькі крок 1 бескарысны: шкодны індэксатар можа пабудаваць цэлае падробленае дрэва і выдаваць узгодненыя доказы адносна ўласнага падробленага кораня. Сэнс кораню надае менавіта крок 2, а крок 3 захоўвае гэты сэнс, калі мяняюцца правілы або стан адкочваецца.


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

Дрэва​

zNS выкарыстоўвае кампактнае разрэджанае дрэва Меркла над 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 resolve пакуль не вяртае доказаў адсутнасці: на імя, якога не ведае, ён адказвае Domain not found зусім без доказу. Пакуль гэта так, лічыце «not found» неправераным і правярайце яго праз другі індэксатар.

Код​

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

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

Верыфікатар, які заўсёды вяртае 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 — вышыня ZCash для апошняга кораня
programVkey()0x09665ee7bytes32 — схема, якую патрабуе кантракт
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

Як чытаць адказ​

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-байтавыя словы ў такім парадку: корань, вышыню блока і эпоху. Эпоха — гэта цэлы лік у трэцім слове.

ЭпохаШто рабіць
роўная зафіксаванай ваміпрацягвайце — крокі 1 і 2 дзейнічаюць паводле правілаў, якія вы праверылі
большая за зафіксаваную ваміспыніце вырашаць імёны. Падзеі EpochAdvanced, RulesChanged і RootRolledBack паказваюць, што адбылося; праверце гэта, потым абнавіце зафіксаваную эпоху

Індэксатары ўжываюць тое самае правіла да сябе: вузел спыняе сінхранізацыю, калі эпоха ў блокчэйне выходзіць за правераную яго аператарам, і паведамляе эпоху, пад якой працуе, як anchored_epoch у раздзеле Інфармацыя пра індэксатар. Індэксатар, які паведамляе эпоху, адрозную ад вашай, не падыходзіць для вырашэння імёнаў.


Праверка самой схемы​

Крокі вышэй даказваюць, што запіс належыць кораню, які прыняў кантракт. А корань кантракт прымае толькі разам з карэктным ZK-доказам, які правяраецца адносна programVkey — 32-байтавага абавязацельства да канкрэтнай скампіляванай схемы.

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

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

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

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

warning

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

Зборка без фіч дае схему асноўнай сеткі, якую патрабуе разгорнуты кантракт. Любы сцяг фічы мяняе скампіляваную праграму, а значыць і яе ключ верыфікацыі, які пасля гэтага не супадзе. Іншы ключ можа даць і зборка па-за 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): пераход стану, выкананы пакетам, і вышыня блока ZCash, якую ён пакрывае.