Проверка доказательств
Эта страница показывает, как проверить разрешение имени, не доверяя выдавшему его индексатору. Каждый пример кода здесь перед публикацией выполняется на живом индексаторе.
Что даёт проверка
Разрешение имени отвечает на вопрос «на какой адрес указывает richard.pivx?». Проверка
доказывает, что этот ответ — именно тот, который зафиксирован в корне состояния, и что этот
корень — текущий корень якорного контракта. Индексатор, который выдумает адрес, отдаст устаревшую
запись или скроет имя, не сможет предъявить доказательство, проходящее эти проверки.
Не сможет и тот, кто ответит подлинной записью другого имени: проверки ниже привязывают ответ к имени, которое вы запросили.
Шагов три, они независимы, и нужны все три:
- Доказательство Меркла связывает запись с корнем состояния.
- Проверка в блокчейне связывает этот корень с якорным контрактом.
- Проверка эпохи связывает правила и историю контракта с теми, которые вы проверили.
Один только шаг 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 из ответа. Иначе индексатор мог бы ответить подлинной записью и доказательством другого имени, которые безупречно проходят проверку, и вы заплатили бы владельцу того имени. Кроме того, поля неправильного вида отклоняются ещё до хеширования: у листа нет префиксов длины, так что поле неправильной длины сдвинуло бы байты в соседнее.
- Python
- PHP
- JavaScript
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()
<?php
const LEAF_TAG = "\x00";
const NODE_TAG = "\x01";
const KEY_LEN = 16;
const MAX_DEPTH = 128;
function hashLeaf(string $domain, string $ownerPubkeyHex, string $targetAddress, int $price, int $nonce): string
{
return hash('sha256',
LEAF_TAG
. $domain
. hex2bin($ownerPubkeyHex)
. $targetAddress
. pack('P', $price) // u64 little-endian
. pack('P', $nonce),
true);
}
function hashNode(string $left, string $right): string
{
return hash('sha256', NODE_TAG . $left . $right, true);
}
function keyOf(string $domain): string
{
return substr(hash('sha256', $domain, true), 0, KEY_LEN);
}
function keyBit(string $key, int $i): int
{
return (ord($key[intdiv($i, 8)]) >> (7 - ($i % 8))) & 1;
}
function fold(string $key, string $start, array $siblings): string
{
$h = $start;
$n = count($siblings);
foreach ($siblings as $i => $sib) {
$h = keyBit($key, $n - 1 - $i) === 1 ? hashNode($sib, $h) : hashNode($h, $sib);
}
return $h;
}
function verifyResolution(string $requestedName, array $entry, string $expectedRoot): bool
{
// 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 = strtolower($requestedName);
if ($entry['domain_name'] !== $name) {
throw new RuntimeException('the answer is for another name');
}
if ($entry['proof_terminal'] !== 'Occupied') {
throw new RuntimeException('a resolution must carry an Occupied terminal');
}
// The leaf has no length prefixes: refuse fields of the wrong shape before hashing.
// The D modifier keeps `$` from matching before a trailing newline.
$hex32 = static fn($v): bool => is_string($v) && preg_match('/^[0-9a-f]{64}$/D', $v) === 1;
if (!$hex32($entry['owner_pubkey'])) {
throw new RuntimeException('owner_pubkey is not 32 bytes of lowercase hex');
}
foreach (['price', 'nonce'] as $field) {
// json_decode gives a float for an integer above PHP_INT_MAX, refused here too.
if (!is_int($entry[$field]) || $entry[$field] < 0) {
throw new RuntimeException("$field is not an unsigned 64-bit integer");
}
}
foreach ($entry['merkle_proof'] as $sibling) {
if (!$hex32($sibling)) {
throw new RuntimeException('a sibling is not 32 bytes of lowercase hex');
}
}
$siblings = array_map('hex2bin', $entry['merkle_proof']);
if (count($siblings) !== (int)$entry['proof_depth']) {
throw new RuntimeException('proof_depth does not match the sibling count');
}
if ((int)$entry['proof_depth'] > MAX_DEPTH) {
throw new RuntimeException('proof depth exceeds MAX_DEPTH');
}
$leaf = hashLeaf($name, $entry['owner_pubkey'], $entry['target_address'],
$entry['price'], $entry['nonce']);
return bin2hex(fold(keyOf($name), $leaf, $siblings)) === strtolower($expectedRoot);
}
import crypto from "node:crypto";
const LEAF_TAG = 0x00;
const NODE_TAG = 0x01;
const KEY_LEN = 16;
const MAX_DEPTH = 128;
const sha256 = (...parts) =>
crypto.createHash("sha256").update(Buffer.concat(parts)).digest();
const u64le = (v) => {
const b = Buffer.alloc(8);
b.writeBigUInt64LE(BigInt(v));
return b;
};
function hashLeaf(domain, ownerPubkeyHex, targetAddress, price, nonce) {
return sha256(
Buffer.from([LEAF_TAG]),
Buffer.from(domain, "utf8"),
Buffer.from(ownerPubkeyHex, "hex"),
Buffer.from(targetAddress, "utf8"),
u64le(price),
u64le(nonce),
);
}
const hashNode = (l, r) => sha256(Buffer.from([NODE_TAG]), l, r);
const keyOf = (domain) =>
crypto.createHash("sha256").update(domain, "utf8").digest().subarray(0, KEY_LEN);
const keyBit = (key, i) => (key[Math.floor(i / 8)] >> (7 - (i % 8))) & 1;
function fold(key, start, siblings) {
let h = start;
const n = siblings.length;
for (let i = 0; i < n; i++) {
h = keyBit(key, n - 1 - i) ? hashNode(siblings[i], h) : hashNode(h, siblings[i]);
}
return h;
}
const HEX32 = /^[0-9a-f]{64}$/;
// price and nonce as exact u64 values. JSON.parse reads an integer above 2^53 inexactly,
// and hashing it would hash a different number: such a value is refused, unless the
// response was parsed to keep it exact, as a BigInt (see below).
function u64(value, field) {
const n = typeof value === "bigint" ? value
: Number.isSafeInteger(value) ? BigInt(value) : null;
if (n === null || n < 0n || n >= 2n ** 64n) {
throw new Error(`${field} is not an exact unsigned 64-bit integer`);
}
return n;
}
export function verifyResolution(requestedName, entry, expectedRoot) {
// 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.
const name = requestedName.toLowerCase();
if (entry.domain_name !== name) {
throw new Error("the answer is for another name");
}
if (entry.proof_terminal !== "Occupied") {
throw new Error("a resolution must carry an Occupied terminal");
}
// The leaf has no length prefixes: refuse fields of the wrong shape before hashing.
if (typeof entry.owner_pubkey !== "string" || !HEX32.test(entry.owner_pubkey)) {
throw new Error("owner_pubkey is not 32 bytes of lowercase hex");
}
const price = u64(entry.price, "price");
const nonce = u64(entry.nonce, "nonce");
if (!entry.merkle_proof.every((s) => typeof s === "string" && HEX32.test(s))) {
throw new Error("a sibling is not 32 bytes of lowercase hex");
}
const siblings = entry.merkle_proof.map((s) => Buffer.from(s, "hex"));
if (siblings.length !== entry.proof_depth) {
throw new Error("proof_depth does not match the sibling count");
}
if (entry.proof_depth > MAX_DEPTH) {
throw new Error("proof depth exceeds MAX_DEPTH");
}
const leaf = hashLeaf(name, entry.owner_pubkey, entry.target_address, price, nonce);
return fold(keyOf(name), leaf, siblings).toString("hex") === expectedRoot.toLowerCase();
}
В 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) | 0x30ef41b4 | bool — принят и с тех пор не откачен |
currentRoot() | 0xfdab463d | bytes32 — последний принятый корень |
verifyRootValidity(bytes32) | 0xc7179944 | (bool isValid, uint32 blockHeight) |
currentBlockHeight() | 0x367bf2f9 | uint32 — высота PIVX для последнего корня |
programVkey() | 0x09665ee7 | bytes32 — схема, которую требует контракт |
Примеры читают контракт на последнем финализированном (finalized) блоке, как это делают индексаторы: корень, принятый в ещё не финальном блоке, может исчезнуть при реорганизации цепочки, и платёж, сделанный по нему, ни на чём бы не держался. Сначала они запрашивают номер этого блока и затем читают по нему, потому что некоторые публичные эндпоинты BSC отклоняют тег finalized внутри eth_call. Читайте currentRoot() и вызовы шага 3 по тому же номеру, чтобы все ответы описывали один и тот же блок.
- Python
- PHP
- JavaScript
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)
<?php
function evmRpc(string $rpcUrl, string $method, array $params): mixed
{
$payload = ['jsonrpc' => '2.0', 'method' => $method, 'params' => $params, 'id' => 1];
$ch = curl_init($rpcUrl);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_TIMEOUT => 15,
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException('RPC request failed: ' . curl_error($ch));
}
$data = json_decode($response, true);
if (isset($data['error'])) {
throw new RuntimeException('EVM RPC error: ' . $data['error']['message']);
}
return $data['result'] ?? null;
}
// 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").
function finalizedBlock(string $rpcUrl): string
{
$block = evmRpc($rpcUrl, 'eth_getBlockByNumber', ['finalized', false]);
if (!is_array($block) || !is_string($block['number'] ?? null)) {
throw new RuntimeException('the endpoint does not serve the finalized block');
}
return $block['number'];
}
function isRootValid(string $rpcUrl, string $contractAddress, string $smtRoot, string $block): bool
{
$clean = str_pad(str_replace('0x', '', strtolower($smtRoot)), 64, '0', STR_PAD_LEFT);
$result = evmRpc($rpcUrl, 'eth_call', [['to' => $contractAddress, 'data' => '0x30ef41b4' . $clean], $block]) ?? '0x';
if ($result === '' || $result === '0x') {
return false;
}
// A bool is ABI-encoded as a full 32-byte word: 0x00..01 for true. The whole word is
// compared, as in the Python and JavaScript versions: its last digit alone would read
// an answer such as 0x…11 as true.
$word = substr($result, 2);
return ctype_xdigit($word) && ltrim($word, '0') === '1';
}
// $block = finalizedBlock($rpcUrl);
// isRootValid($rpcUrl, $contractAddress, $entry['smt_root'], $block);
async function evmRpc(rpcUrl, method, params) {
const response = await fetch(rpcUrl, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ jsonrpc: "2.0", method, params, id: 1 }),
});
if (!response.ok) throw new Error(`RPC request failed: ${response.statusText}`);
const json = await response.json();
if (json.error) throw new Error(`EVM RPC error: ${json.error.message}`);
return json.result;
}
// 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").
async function finalizedBlock(rpcUrl) {
const block = await evmRpc(rpcUrl, "eth_getBlockByNumber", ["finalized", false]);
if (typeof block?.number !== "string") {
throw new Error("the endpoint does not serve the finalized block");
}
return block.number;
}
async function isRootValid(rpcUrl, contractAddress, smtRoot, block) {
const clean = smtRoot.replace(/^0x/, "").toLowerCase().padStart(64, "0");
const result = await evmRpc(rpcUrl, "eth_call", [
{ to: contractAddress, data: `0x30ef41b4${clean}` },
block,
]);
if (!result || result === "0x") return false;
// A bool is ABI-encoded as a full 32-byte word: 0x00..01 for true.
return BigInt(result) === 1n;
}
// const block = await finalizedBlock(rpcUrl);
// await isRootValid(rpcUrl, contractAddress, 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() | 0x900cf0cf | uint32 — действующая эпоха |
rulesChangeActivatesAt() | 0x90b86556 | uint64 — когда запланированную смену правил можно активировать; 0, если ничего не запланировано |
anchoredState() возвращает три 32-байтовых слова в таком порядке: корень, высоту блока и эпоху. Эпоха — это целое число в третьем слове.
Примеры ниже добавляют этот шаг к примерам шага 2 и используют их функции. В одном
финализированном блоке они читают anchoredState(), отказываются от эпохи, отличной от
зафиксированной вами, а затем относят корень к одному из случаев таблицы шага 2: accept для
текущего корня, lagging для более старого действительного, reject для корня, который
контракт не принимает.
- Python
- PHP
- JavaScript
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)
<?php
// anchoredState() at that block: [root as 64 hex digits, PIVX block height, epoch].
function anchoredState(string $rpcUrl, string $contractAddress, string $block): array
{
$result = evmRpc($rpcUrl, 'eth_call', [['to' => $contractAddress, 'data' => '0x8d39310a'], $block]) ?? '0x';
$words = is_string($result) ? substr($result, 2) : '';
// Three 32-byte words: nothing more, nothing less, and nothing but hex digits.
if (strlen($words) !== 192 || !ctype_xdigit($words)) {
throw new RuntimeException('unexpected anchoredState() answer');
}
return [strtolower(substr($words, 0, 64)), hexdec(substr($words, 64, 64)), hexdec(substr($words, 128, 64))];
}
// 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;
// throws when the epoch in force is not the one you pinned.
function checkAnchor(string $rpcUrl, string $contractAddress, string $smtRoot, int $pinnedEpoch): string
{
$block = finalizedBlock($rpcUrl);
[$root, , $epoch] = anchoredState($rpcUrl, $contractAddress, $block);
if ($epoch !== $pinnedEpoch) {
throw new RuntimeException("epoch $epoch is in force, not the reviewed $pinnedEpoch: stop resolving");
}
if (str_pad(str_replace('0x', '', strtolower($smtRoot)), 64, '0', STR_PAD_LEFT) === $root) {
return 'accept';
}
return isRootValid($rpcUrl, $contractAddress, $smtRoot, $block) ? 'lagging' : 'reject';
}
// checkAnchor($rpcUrl, $contractAddress, $entry['smt_root'], $pinnedEpoch);
// anchoredState() at that block: { root (64 hex digits), blockHeight, epoch }.
async function anchoredState(rpcUrl, contractAddress, block) {
const result = await evmRpc(rpcUrl, "eth_call", [{ to: contractAddress, data: "0x8d39310a" }, block]);
const words = typeof result === "string" ? result.slice(2) : "";
// Three 32-byte words: nothing more, nothing less, and nothing but hex digits.
if (!/^[0-9a-fA-F]{192}$/.test(words)) throw new Error("unexpected anchoredState() answer");
return {
root: words.slice(0, 64).toLowerCase(),
blockHeight: Number(BigInt(`0x${words.slice(64, 128)}`)),
epoch: Number(BigInt(`0x${words.slice(128)}`)),
};
}
// 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;
// throws when the epoch in force is not the one you pinned.
async function checkAnchor(rpcUrl, contractAddress, smtRoot, pinnedEpoch) {
const block = await finalizedBlock(rpcUrl);
const { root, epoch } = await anchoredState(rpcUrl, contractAddress, block);
if (epoch !== pinnedEpoch) {
throw new Error(`epoch ${epoch} is in force, not the reviewed ${pinnedEpoch}: stop resolving`);
}
if (smtRoot.replace(/^0x/, "").toLowerCase().padStart(64, "0") === root) return "accept";
return (await isRootValid(rpcUrl, contractAddress, smtRoot, block)) ? "lagging" : "reject";
}
// await checkAnchor(rpcUrl, contractAddress, entry.smt_root, pinnedEpoch);
| Эпоха | Что делать |
|---|---|
| равна зафиксированной вами | продолжайте — шаги 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,
которую он покрывает.