Kiểm chứng bằng chứng
Trang này chỉ cách kiểm chứng một kết quả phân giải tên mà không cần tin trình lập chỉ mục đã trả về nó. Mọi ví dụ mã ở đây đều được chạy với một trình lập chỉ mục thật trước khi xuất bản.
Việc kiểm chứng mang lại điều gì
Một kết quả phân giải trả lời «richard.pivx trỏ tới địa chỉ nào?». Kiểm chứng nó chứng minh rằng
câu trả lời đúng là câu đã được cam kết vào gốc trạng thái — và rằng gốc đó là gốc hiện tại
của hợp đồng neo. Một trình lập chỉ mục bịa ra địa chỉ, trả về bản ghi cũ hay giấu một cái tên đều
không thể tạo ra bằng chứng vượt qua những kiểm tra này.
Một trình lập chỉ mục trả lời bằng bản ghi thật của một tên khác cũng không làm được: các kiểm tra bên dưới gắn câu trả lời với cái tên bạn đã hỏi.
Có ba bước độc lập, và bạn cần cả ba:
- Bằng chứng Merkle buộc bản ghi vào một gốc trạng thái.
- Việc kiểm tra trên chuỗi buộc gốc đó vào hợp đồng neo.
- Việc kiểm tra kỷ nguyên buộc quy tắc và lịch sử của hợp đồng vào những gì bạn đã xem xét.
Riêng bước 1 thì vô giá trị: một trình lập chỉ mục xấu có thể dựng nguyên một cây giả và trả về các bằng chứng nhất quán với gốc giả của chính nó. Chính bước 2 mới làm cho gốc có ý nghĩa, và bước 3 giữ cho ý nghĩa đó khi quy tắc thay đổi hoặc trạng thái bị hoàn tác.
Bước 1 — kiểm chứng bằng chứng Merkle
Cây
PiNS dùng một cây Merkle thưa nén trên không gian khóa 128 bit. Một khóa là 16 byte đầu của
SHA-256(domain_name). Khi viết bộ kiểm chứng, có hai tính chất quan trọng:
- Bằng chứng ngắn và có độ dài thay đổi. Một lá nằm ở độ sâu nông nhất mà tiền tố khóa của nó là
duy nhất, nên một bằng chứng mang
proof_depthanh em — thường chỉ vài cái, không phải 128. Đừng bao giờ giả định độ dài cố định; hãy đọcproof_depthvà kiểm tra rằng nó khớp vớimerkle_proof.length. - Một cây con rỗng là 32 byte 0 ở mọi độ cao. Không có bậc thang băm tiền tính cho các nút rỗng. Vì thế gốc của một cây rỗng toàn số 0.
Các hàm băm
Lá và nút trong được gắn thẻ để miền băm của chúng không chồng lấn. Bỏ sót byte thẻ là lỗi phổ biến nhất — nó tạo ra một băm trông hợp lý nhưng không bao giờ khớp với gốc.
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 và target_address là byte UTF-8 không có tiền tố độ dài; owner_pubkey là 32 byte thô;
price và nonce là số nguyên 64 bit không dấu dạng little-endian.
Cách duyệt
Đi từ lá ngược về gốc. Với n = proof_depth anh em, ở bước i bit quyết định bạn đang ở phía nào là
bit n - 1 - i của khóa, đếm từ bit có trọng số lớn nhất của byte 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] là anh em ở mức sâu nhất, gần lá nhất.
Terminal
Mọi bằng chứng đều mang một proof_terminal mô tả thứ nằm ở cuối đường đi:
| Terminal | Ý nghĩa |
|---|---|
Occupied | ở đó là lá của chính khóa — tên tồn tại |
Vacant | ở đó là một cây con rỗng — tên chưa được đăng ký |
Blocked | ở đó là lá của một tên khác — tên chưa được đăng ký, và phản hồi kèm bản ghi đầy đủ của tên kia |
Một kết quả phân giải thành công phải là Occupied. Vacant và Blocked là bằng chứng vắng mặt:
chúng cho phép bạn kiểm chứng rằng một cái tên thực sự chưa được đăng ký, thay vì tin lời «không tìm
thấy» của trình lập chỉ mục. Hãy từ chối mọi kết quả phân giải có terminal khác Occupied.
API phân giải hiện chưa trả về bằng chứng vắng mặt: với một tên nó không biết, nó trả lời
Domain not found mà không kèm bằng chứng nào. Cho tới khi điều đó thay đổi, hãy coi một câu
«not found» là chưa được kiểm chứng và kiểm tra lại bằng một trình lập chỉ mục thứ hai.
Mã
Bộ kiểm chứng nhận cả cái tên bạn đã hỏi lẫn câu trả lời, và băm chính cái tên đó, không bao giờ băm domain_name mà câu trả lời mang theo. Nếu không, một trình lập chỉ mục có thể trả lời bằng bản ghi và bằng chứng thật của một tên khác, vốn kiểm chứng hoàn hảo, và bạn sẽ trả tiền cho chủ sở hữu của tên đó. Nó cũng từ chối các trường sai dạng trước khi băm bất cứ thứ gì: lá không có tiền tố độ dài, nên một trường sai độ dài sẽ đẩy byte sang trường bên cạnh.
- 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();
}
Trong JavaScript, JSON.parse đọc không chính xác các số nguyên lớn hơn 2^53, nên ví dụ từ chối một price hoặc nonce lớn như vậy (một mức giá trên khoảng 90 triệu PIVX) thay vì băm một con số khác. Để kiểm chứng một bản ghi như vậy, hãy phân tích phản hồi sao cho cả hai giá trị vẫn chính xác (Node.js 21 trở lên, các trình duyệt hiện nay):
const body = JSON.parse(text, (key, value, context) =>
(key === "price" || key === "nonce") && typeof value === "number"
? BigInt(context.source)
: value);
Hãy thử bộ kiểm chứng của bạn trước hành vi sửa đổi
Một bộ kiểm chứng luôn trả về true sẽ vượt qua mọi bài kiểm tra dương tính. Trước khi tin bộ của
mình, hãy đổi một byte của target_address, owner_pubkey hoặc price trong một phản hồi thật và
xác nhận rằng giờ nó trả về false. Cả ba ví dụ ở trên đều được kiểm theo cách này.
Sau đó, hãy đưa vào câu trả lời thật của một tên trong khi hỏi một tên khác: bộ kiểm chứng phải từ chối nó. Các ví dụ cũng được kiểm theo cách này.
Bước 2 — đối chiếu gốc với hợp đồng neo
Một bằng chứng Merkle đã kiểm chứng chỉ nói «bản ghi này nằm trong một cây nào đó». Để biết nó nằm trong cây thật, hãy hỏi hợp đồng neo trên BNB Smart Chain xem gốc đó có hợp lệ không: đã được chấp nhận trên chuỗi và chưa bị hoàn tác (rollback) kể từ đó.
Dùng isRootValid(bytes32) — bộ chọn 0x30ef41b4. Nó trả về một giá trị boolean mã hóa ABI duy nhất: đó là tất cả những gì bước này cần, và dễ phân tích hơn cặp (bool, uint32) mà verifyRootValidity trả về.
| Lời gọi | Bộ chọn | Trả về |
|---|---|---|
isRootValid(bytes32) | 0x30ef41b4 | bool — đã được chấp nhận và chưa bị hoàn tác kể từ đó |
currentRoot() | 0xfdab463d | bytes32 — gốc được chấp nhận gần nhất |
verifyRootValidity(bytes32) | 0xc7179944 | (bool isValid, uint32 blockHeight) |
currentBlockHeight() | 0x367bf2f9 | uint32 — chiều cao PIVX của gốc gần nhất |
programVkey() | 0x09665ee7 | bytes32 — mạch mà hợp đồng bắt buộc |
Các ví dụ đọc hợp đồng tại khối đã hoàn tất (finalized) mới nhất, như các trình lập chỉ mục vẫn làm: một gốc được chấp nhận trong một khối chưa hoàn tất vẫn có thể biến mất khi chuỗi tái tổ chức, và một khoản thanh toán dựa trên nó sẽ chẳng có cơ sở gì. Chúng hỏi số của khối đó trước rồi đọc tại số đó, vì một số endpoint BSC công khai từ chối thẻ finalized bên trong eth_call. Hãy đọc currentRoot() và các lời gọi ở Bước 3 tại cùng số khối đó, để mọi câu trả lời đều mô tả cùng một khối.
- 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);
Diễn giải câu trả lời
isRootValid | Ý nghĩa | Nên làm gì |
|---|---|---|
true, và gốc bằng currentRoot() | trình lập chỉ mục đã đồng bộ hoàn toàn | chấp nhận |
true, nhưng gốc cũ hơn currentRoot() | trình lập chỉ mục đang tụt sau chuỗi | chưa gửi tiền — hãy chờ hoặc hỏi một trình lập chỉ mục khác, rồi kiểm chứng lại |
false | gốc này chưa bao giờ được chấp nhận trên chuỗi, hoặc đã bị hoàn tác | từ chối kết quả phân giải |
Một gốc hợp lệ cũ hơn là một trạng thái có thật trong quá khứ của sổ đăng ký, nhưng không phải
trạng thái hiện tại. Kể từ đó, cái tên có thể đã được chuyển nhượng, bán đi hoặc trỏ sang địa chỉ
mới, trong khi bằng chứng đối với gốc cũ vẫn cho ra câu trả lời trước đây. Một trình lập chỉ mục
chậm và một trình lập chỉ mục cố tình giấu bản cập nhật gần đây trông hoàn toàn giống nhau ở đây,
vì vậy trước khi thanh toán, hãy yêu cầu gốc phải bằng currentRoot(). Một trình lập chỉ mục
trung thực sẽ bắt kịp ngay sau mỗi lô mới. Hiển thị bản ghi để tham khảo, có đánh dấu là có thể đã
lỗi thời, thì không sao.
Giá trị false nghĩa là cái cây mà bạn đối chiếu không thuộc lịch sử của sổ đăng ký dưới góc nhìn
của giao thức: nó chưa từng được chấp nhận, hoặc đã bị bác bỏ qua một lần hoàn tác. Đó chính là
tình huống mà một trình lập chỉ mục do kẻ tấn công kiểm soát tạo ra, và bước này sinh ra đúng vì
lý do đó.
Bước 3 — kiểm tra kỷ nguyên
Bước 1 và 2 chứng minh một bản ghi nằm trong một cây mà hợp đồng đã chấp nhận. Có hai điều có thể thay đổi ý nghĩa của chứng minh đó mà không cần lô mới nào: một thay đổi quy tắc — mạch hoặc bộ xác minh mới, tức một định nghĩa mới về thế nào là đã được chứng minh — và một hoàn tác, thứ đưa một gốc cũ hơn trở lại làm gốc hiện hành và vì thế trỏ lại mọi tên đã thay đổi kể từ đó, không cần chữ ký của chủ sở hữu. Hợp đồng đếm cả hai trong epoch:
- Bộ đếm bắt đầu từ 1 và tăng một sau mỗi lần thay đổi quy tắc và mỗi lần hoàn tác. Nó không bao giờ giảm: một thay đổi và việc đảo ngược nó là hai kỷ nguyên, không phải quay về kỷ nguyên đầu.
- Thay đổi quy tắc được thông báo trước. Sự phê duyệt của chủ sở hữu khởi động một khóa thời gian cố định khi triển khai (
rulesTimelock, từ 7 đến 90 ngày), và thay đổi chỉ có thể được kích hoạt khi đã đến thời điểm ghi trongrulesChangeActivatesAt(). - Hoàn tác chỉ có thể nhắm đến một gốc mà hợp đồng đã chấp nhận trước đây, và chỉ khi việc nộp lô đang tạm dừng. Mọi gốc phía trên mục tiêu lập tức mất hiệu lực, và từ đó bước 2 trả về
falsecho từng gốc.
Vì vậy hãy ghim kỷ nguyên bạn đã xem xét, và từ chối phân giải dưới bất kỳ kỷ nguyên nào khác. Hãy đọc nó cùng với gốc, trong một lời gọi, để cả hai lấy từ cùng một khối:
| Lời gọi | Bộ chọn | Trả về |
|---|---|---|
anchoredState() | 0x8d39310a | (bytes32 root, uint32 blockHeight, uint32 currentEpoch) |
epoch() | 0x900cf0cf | uint32 — kỷ nguyên đang có hiệu lực |
rulesChangeActivatesAt() | 0x90b86556 | uint64 — thời điểm có thể kích hoạt một thay đổi quy tắc đã lên lịch; 0 khi không có thay đổi nào được lên lịch |
anchoredState() trả về ba từ 32 byte theo thứ tự: gốc, độ cao khối và kỷ nguyên. Kỷ nguyên là số nguyên trong từ thứ ba.
Các ví dụ dưới đây bổ sung bước này vào các ví dụ của Bước 2 và dùng lại các hàm của chúng. Tại
một khối đã hoàn tất, chúng đọc anchoredState(), từ chối kỷ nguyên khác với kỷ nguyên bạn đã
ghim, rồi phân loại gốc như bảng ở Bước 2: accept cho gốc hiện tại, lagging cho một gốc hợp
lệ cũ hơn, reject cho gốc mà hợp đồng không chấp nhận.
- 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);
| Kỷ nguyên | Nên làm gì |
|---|---|
| bằng kỷ nguyên bạn đã ghim | tiếp tục — bước 1 và 2 có hiệu lực theo các quy tắc bạn đã xem xét |
| lớn hơn kỷ nguyên bạn đã ghim | ngừng phân giải. Các sự kiện EpochAdvanced, RulesChanged và RootRolledBack cho biết điều gì đã xảy ra; hãy xem xét, rồi cập nhật kỷ nguyên đã ghim |
Trình lập chỉ mục áp dụng cùng quy tắc cho chính chúng: một nút ngừng theo dõi chuỗi khi kỷ nguyên trên chuỗi vượt qua kỷ nguyên mà người vận hành đã xem xét, và báo kỷ nguyên đã xem xét đó là anchored_epoch trong Thông tin trình lập chỉ mục. Đây là thiết lập của nút, không phải kỷ nguyên của gốc mà nút phục vụ: một nút được cập nhật trước một lần thay đổi quy tắc đã lên lịch sẽ báo ngay kỷ nguyên sắp tới trong khi thay đổi chờ hết khóa thời gian, và cho đến lúc đó phục vụ trạng thái được tạo dưới kỷ nguyên hiện hành. Vì vậy, hãy đánh giá kết quả phân giải theo kỷ nguyên đọc từ hợp đồng cùng với gốc như trên, không theo anchored_epoch; Bước 2 cho biết gốc của nút có còn mới nhất hay không.
Kiểm chứng chính cái mạch
Các bước ở trên chứng minh rằng một bản ghi thuộc về một gốc mà hợp đồng đã chấp nhận. Hợp đồng chỉ chấp nhận một gốc nếu đi kèm là một bằng chứng ZK hợp lệ — và bằng chứng đó được kiểm với programVkey, một cam kết 32 byte với đúng cái mạch đã biên dịch.
Bạn có thể xác nhận khóa đó tương ứng với mã nguồn đã công bố. Hãy biên dịch mạch trong Docker image của SP1, vốn cố định bộ công cụ và các đường dẫn biên dịch mà khóa phụ thuộc vào, rồi in ra khóa của nó:
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
So sánh khóa xác minh thu được với programVkey() (bộ chọn 0x09665ee7) trên hợp đồng neo. Nếu
chúng khớp nhau, hợp đồng đang bắt buộc đúng mã nguồn đó. Đổi một dòng duy nhất của mạch sẽ cho ra
khóa khác, nên không thể tráo một mạch đã sửa đổi mà thay đổi đó không lộ ra trên chuỗi.
Nó cũng không thể có hiệu lực một cách lặng lẽ: một khóa mới phải đi qua thay đổi quy tắc có khóa thời gian được mô tả ở Bước 3, và làm tăng kỷ nguyên.
README của prover liệt kê khóa của từng bản phát hành và commit dùng để biên dịch nó.
Hãy biên dịch không kèm tính năng bổ sung
Một bản biên dịch không kèm tính năng nào tạo ra mạch mainnet mà hợp đồng đã triển khai bắt buộc. Bất kỳ cờ tính năng nào cũng thay đổi chương trình đã biên dịch, và do đó thay đổi khóa xác minh của nó, khiến nó không còn khớp nữa. Một bản biên dịch ngoài Docker, hoặc với tag image khác, cũng có thể cho ra khóa khác.
Kiểm chứng trực tiếp một bằng chứng SP1
Các bằng chứng là bằng chứng SP1 Groth16 tiêu chuẩn và có thể kiểm bằng SDK của 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)?;
Các giá trị công khai là mã hóa ABI của (bytes32 old_root, bytes32 new_root, uint32 end_block_height) — phép chuyển trạng thái mà lô đã thực hiện, và chiều cao khối PIVX mà nó
bao phủ.