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

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

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

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

Разрешение имени отвечает на вопрос «на какой адрес указывает 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 прувера.

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): переход состояния, выполненный пакетом, и высота блока PIVX, которую он покрывает.