Перейти к основному содержимому

Проверка доказательств

Эта страница показывает, как проверить разрешение имени, не доверяя выдавшему его индексатору. Каждый пример кода здесь перед публикацией выполняется на живом индексаторе.

Что даёт проверка​

Разрешение имени отвечает на вопрос «на какой адрес указывает 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 разрешения имён пока не возвращает доказательств отсутствия: на имя, которого он не знает, он отвечает 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()
подсказка

Проверьте свою реализацию на подделке

Верификатор, который всегда возвращает 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, которую он покрывает.