@blockula/sdk 0.3.0 → 1.0.0

package/dist/proof.d.ts

@@ -0,0 +1,170 @@
+/** Record namespaces (node/src/state/mod.rs `ns`): the first byte of every record's tree key. */
+export declare const NAMESPACES: {
+    readonly META: 0;
+    readonly ACCOUNTS: 1;
+    readonly NAMES: 2;
+    readonly VALIDATORS: 3;
+    readonly ACTIVE_SETS: 4;
+    readonly HUNTS: 5;
+    readonly GITHUB: 6;
+    readonly GITHUB_BY_ACCOUNT: 7;
+    readonly FAMILIARS: 8;
+    readonly REPOS: 16;
+    readonly SOULS: 17;
+    readonly VOUCHES: 18;
+    readonly SYBILS: 19;
+    readonly CLAIMS: 20;
+    readonly CLAIM_BY_PR: 21;
+    readonly HANDLES: 22;
+    readonly JURORS: 23;
+    readonly SEANCES: 24;
+    readonly GRANTS: 25;
+    readonly RESERVED_NAMES: 43;
+    readonly FEATURES: 47;
+    /** A program's record, keyed by its address as a string (as accounts are). */
+    readonly PROGRAMS: 66;
+    readonly PROGRAM_CODE: 67;
+    readonly PROGRAM_INTERFACES: 68;
+    readonly PROGRAM_STORAGE: 69;
+    readonly PROGRAM_BLOB_REFS: 72;
+};
+/** Hash of an empty subtree. */
+export declare const EMPTY_HASH: Uint8Array<ArrayBuffer>;
+/** A record key as bytes: strings are UTF-8 (addresses, names), as the node's `RecordKey`. */
+export declare function recordKey(key: string | Uint8Array): Uint8Array;
+/** Tree key of a record: BLAKE3(namespace ‖ key). */
+export declare function keyHash(namespace: number, key: Uint8Array): Uint8Array;
+/** Hash of a record's encoded value. */
+export declare function valueHash(value: Uint8Array): Uint8Array;
+/** A lone leaf: BLAKE3(0x00 ‖ k ‖ v). */
+export declare function leafHash(key: Uint8Array, value: Uint8Array): Uint8Array;
+/** An internal node: BLAKE3(0x01 ‖ left ‖ right). */
+export declare function nodeHash(left: Uint8Array, right: Uint8Array): Uint8Array;
+/**
+ * The root of a set of leaves `[key hash, value hash]`, straight from the definition (tree.rs
+ * `root_of`). Leaves are sorted here; duplicate keys are an error.
+ */
+export declare function rootOf(leaves: [Uint8Array, Uint8Array][]): Uint8Array;
+/** The leaf a proof's path ends at (hex), as the node serves it. */
+export interface ProofLeaf {
+    key: string;
+    value: string;
+}
+/** A Merkle proof (node/src/state/tree.rs `Proof`, JSON): sibling hashes from the root down, and where the path ends. */
+export interface Proof {
+    siblings: string[];
+    /** `null`: an empty subtree (the key is absent). Otherwise a lone leaf: the key's own, or another key with the same prefix (absent). */
+    leaf: ProofLeaf | null;
+}
+/**
+ * Checks that `(namespace, key)` holds `value` (`null`: is absent) under `root` (tree.rs
+ * `verify`). Never throws: malformed input is `false`.
+ */
+export declare function verifyProof(root: Uint8Array | string, namespace: number, key: string | Uint8Array, value: Uint8Array | null, proof: Proof): boolean;
+/** `/api/proof/{namespace}/{key}`: a record's value and its proof against the state root after block `height`. */
+export interface ProofResponse {
+    namespace: number;
+    /** The record key, hex. */
+    key: string;
+    /** The encoded value, hex; `null` if the record doesn't exist. */
+    value: string | null;
+    proof: Proof;
+    root: string;
+    height: number;
+    block_hash?: string;
+}
+/** A record checked against a state root. */
+export interface ProvenRecord {
+    /** The record's encoded value, or `null` if it provably doesn't exist. */
+    value: Uint8Array | null;
+    /** The state root it was proven against, and the block it's the root after. */
+    root: string;
+    height: number;
+}
+/**
+ * Checks a `/api/proof` response for the record you asked for: the node must answer for exactly
+ * `(namespace, key)` and its proof must verify against the root it reports. Throws otherwise.
+ * This proves the record is in the state with that root; whether the root is the chain's is a
+ * separate question (see `Client.provenRecord`'s `witnesses`).
+ */
+export declare function checkProofResponse(r: ProofResponse, namespace: number, key: string | Uint8Array): ProvenRecord;
+/** One key on an account, as proven. */
+export interface ProvenKey {
+    key_id: string;
+    label: string;
+    role: {
+        type: "owner";
+    } | {
+        type: "session";
+        limit: string;
+        period_blocks: number;
+        expires_at: number;
+    };
+    added_at: number;
+}
+/** The parts of an account record (chain.rs `Account`) a wallet needs: balance, nonce and keys. Later fields (locks) aren't read. */
+export interface AccountRecord {
+    balance: bigint;
+    nonce: number;
+    /** Authorized keys. Empty means only the key the address was derived from. */
+    keys: ProvenKey[];
+}
+export declare function decodeAccount(value: Uint8Array): AccountRecord;
+/**
+ * A name record (chain.rs `NameRecord`): the bare name, its owner, when it was registered, and
+ * the last height it resolves at (DEC-11; after it, a grace period in which only the owner can
+ * renew it, then anyone can register it). Later fields, if a version adds them, aren't read.
+ */
+export interface NameRecord {
+    name: string;
+    owner: string;
+    registered_at: number;
+    expires_at: number;
+    /** The account the owner offered the name to (`TransferName`); it's still the owner's until they accept it. */
+    offered_to?: string;
+    /**
+     * The grace (`name_grace_blocks`) it was registered or last renewed with. Its grace runs until
+     * `expires_at` plus the longer of this and the chain's `name_grace_blocks` now (`/api/name`'s
+     * `grace_until`), so lowering the parameter doesn't shorten it.
+     */
+    grace_blocks?: number;
+}
+export declare function decodeName(value: Uint8Array): NameRecord;
+/**
+ * A program's record as the state holds it (node/src/programs/state.rs `ProgramRecord`, format 1),
+ * decoded from the value `/api/proof/66/{address}` proves. `version_digest` isn't in the record:
+ * `Client.provenProgram` computes it from the record's own fields (`versionDigest`).
+ */
+export interface ProgramRecord {
+    /** The account whose transaction created it. */
+    creator: string;
+    created_at: number;
+    /** Lowercase hex, 64 characters. */
+    wasm_hash: string;
+    interface_hash: string;
+    version: number;
+    /** Stored as created, with no power until program upgrades exist. */
+    authority: string | null;
+    upgrade_delay_blocks: number;
+    /** 0 open, 1 additive. */
+    policy: "open" | "additive";
+    accepts_transfers: boolean;
+    /** Its storage entries: how many, Σ their accounted bytes, Σ their deposits (drops, as decimal strings). */
+    storage: {
+        items: number;
+        bytes: number;
+        deposit: string;
+    };
+    /** The part of those deposits the program paid itself. */
+    sponsored: string;
+    /** What its creator bonded for the record itself, and who. */
+    record_deposit: string;
+    record_payer: string;
+}
+/**
+ * Decodes a program record: the format byte (1: the only format this SDK reads, as the node's
+ * `Versioned` does) and the borsh body, field by field in the order the node writes them. Refuses
+ * a format it doesn't know, a bool or an option tag that isn't 0 or 1, text that isn't UTF-8 and
+ * bytes left over, so what it returns is what the state holds.
+ */
+export declare function decodeProgram(value: Uint8Array): ProgramRecord;

package/dist/proof.js

@@ -0,0 +1,317 @@
+// Light-client checks of state proofs. A port of node/src/state/tree.rs (the tree's definition is
+// a consensus rule): a compact binary sparse Merkle tree over BLAKE3, where a record
+// `(namespace, key) → value` is the leaf `k = BLAKE3(namespace ‖ key)`, `v = BLAKE3(value)`.
+// Shared vectors: sdk-ts/test/proof-vectors.json (written and checked by the node's
+// `state::proof_vectors` tests).
+import { blake3 } from "@noble/hashes/blake3.js";
+import { bytesToHex, hexToBytes } from "@noble/hashes/utils.js";
+/** Record namespaces (node/src/state/mod.rs `ns`): the first byte of every record's tree key. */
+export const NAMESPACES = {
+    META: 0,
+    ACCOUNTS: 1,
+    NAMES: 2,
+    VALIDATORS: 3,
+    ACTIVE_SETS: 4,
+    HUNTS: 5,
+    GITHUB: 6,
+    GITHUB_BY_ACCOUNT: 7,
+    FAMILIARS: 8,
+    REPOS: 16,
+    SOULS: 17,
+    VOUCHES: 18,
+    SYBILS: 19,
+    CLAIMS: 20,
+    CLAIM_BY_PR: 21,
+    HANDLES: 22,
+    JURORS: 23,
+    SEANCES: 24,
+    GRANTS: 25,
+    // 32–47 belong to the protocol v1 modules (staking 32–36, governance 37–42, econ 43, beacon
+    // 44–46, upgrade 47); see node/src/state/mod.rs for what each holds.
+    RESERVED_NAMES: 43,
+    FEATURES: 47,
+    // Programs (protocol v2, docs/PROGRAMS-V0.md §4.1): empty until programs first switch on.
+    /** A program's record, keyed by its address as a string (as accounts are). */
+    PROGRAMS: 66,
+    PROGRAM_CODE: 67,
+    PROGRAM_INTERFACES: 68,
+    PROGRAM_STORAGE: 69,
+    PROGRAM_BLOB_REFS: 72,
+};
+/** Hash of an empty subtree. */
+export const EMPTY_HASH = new Uint8Array(32);
+const utf8 = new TextEncoder();
+/** A record key as bytes: strings are UTF-8 (addresses, names), as the node's `RecordKey`. */
+export function recordKey(key) {
+    return typeof key === "string" ? utf8.encode(key) : key;
+}
+/** Tree key of a record: BLAKE3(namespace ‖ key). */
+export function keyHash(namespace, key) {
+    const b = new Uint8Array(1 + key.length);
+    b[0] = namespace;
+    b.set(key, 1);
+    return blake3(b);
+}
+/** Hash of a record's encoded value. */
+export function valueHash(value) {
+    return blake3(value);
+}
+const cat3 = (tag, a, b) => {
+    const out = new Uint8Array(65);
+    out[0] = tag;
+    out.set(a, 1);
+    out.set(b, 33);
+    return out;
+};
+/** A lone leaf: BLAKE3(0x00 ‖ k ‖ v). */
+export function leafHash(key, value) {
+    return blake3(cat3(0, key, value));
+}
+/** An internal node: BLAKE3(0x01 ‖ left ‖ right). */
+export function nodeHash(left, right) {
+    return blake3(cat3(1, left, right));
+}
+/** Bit `i` of a key hash, most significant first. */
+const bit = (h, i) => (h[i >> 3] >> (7 - (i & 7))) & 1;
+/** Whether two key hashes agree on their first `bits` bits. */
+function samePrefix(a, b, bits) {
+    const whole = bits >> 3;
+    const rest = bits & 7;
+    for (let i = 0; i < whole; i++)
+        if (a[i] !== b[i])
+            return false;
+    return rest === 0 || ((a[whole] ^ b[whole]) >> (8 - rest)) === 0;
+}
+const equal = (a, b) => a.length === b.length && a.every((x, i) => x === b[i]);
+const compare = (a, b) => {
+    for (let i = 0; i < 32; i++)
+        if (a[i] !== b[i])
+            return a[i] - b[i];
+    return 0;
+};
+/**
+ * The root of a set of leaves `[key hash, value hash]`, straight from the definition (tree.rs
+ * `root_of`). Leaves are sorted here; duplicate keys are an error.
+ */
+export function rootOf(leaves) {
+    const sorted = [...leaves].sort((x, y) => compare(x[0], y[0]));
+    for (let i = 1; i < sorted.length; i++)
+        if (compare(sorted[i - 1][0], sorted[i][0]) === 0)
+            throw new Error("duplicate leaf key");
+    const sub = (from, to, depth) => {
+        if (to === from)
+            return EMPTY_HASH;
+        if (to - from === 1)
+            return leafHash(sorted[from][0], sorted[from][1]);
+        let split = from;
+        while (split < to && bit(sorted[split][0], depth) === 0)
+            split++;
+        return nodeHash(sub(from, split, depth + 1), sub(split, to, depth + 1));
+    };
+    return sub(0, sorted.length, 0);
+}
+const hex32 = (s) => (typeof s === "string" && /^[0-9a-f]{64}$/.test(s) ? hexToBytes(s) : null);
+/**
+ * Checks that `(namespace, key)` holds `value` (`null`: is absent) under `root` (tree.rs
+ * `verify`). Never throws: malformed input is `false`.
+ */
+export function verifyProof(root, namespace, key, value, proof) {
+    const r = typeof root === "string" ? hex32(root) : root;
+    if (!r || r.length !== 32 || !Number.isInteger(namespace) || namespace < 0 || namespace > 255)
+        return false;
+    if (!proof || !Array.isArray(proof.siblings) || proof.siblings.length > 256)
+        return false;
+    const siblings = proof.siblings.map(hex32);
+    if (siblings.some((s) => s === null))
+        return false;
+    const k = keyHash(namespace, recordKey(key));
+    const depth = siblings.length;
+    let h;
+    if (proof.leaf) {
+        const lk = hex32(proof.leaf.key);
+        const lv = hex32(proof.leaf.value);
+        if (!lk || !lv)
+            return false;
+        if (value !== null && equal(lk, k) && equal(lv, valueHash(value)))
+            h = leafHash(lk, lv);
+        else if (value === null && !equal(lk, k) && samePrefix(lk, k, depth))
+            h = leafHash(lk, lv);
+        else
+            return false;
+    }
+    else if (value === null) {
+        h = EMPTY_HASH;
+    }
+    else {
+        return false;
+    }
+    for (let i = depth - 1; i >= 0; i--) {
+        const s = siblings[i];
+        h = bit(k, i) === 0 ? nodeHash(h, s) : nodeHash(s, h);
+    }
+    return equal(h, r);
+}
+/**
+ * Checks a `/api/proof` response for the record you asked for: the node must answer for exactly
+ * `(namespace, key)` and its proof must verify against the root it reports. Throws otherwise.
+ * This proves the record is in the state with that root; whether the root is the chain's is a
+ * separate question (see `Client.provenRecord`'s `witnesses`).
+ */
+export function checkProofResponse(r, namespace, key) {
+    const want = bytesToHex(recordKey(key));
+    if (!r || r.namespace !== namespace || typeof r.key !== "string" || r.key.toLowerCase() !== want)
+        throw new Error("the node answered for a different record than the one asked for");
+    if (!Number.isSafeInteger(r.height) || r.height < 0)
+        throw new Error("the proof has no valid height");
+    let value = null;
+    if (r.value !== null && r.value !== undefined) {
+        if (typeof r.value !== "string" || !/^([0-9a-f]{2})*$/.test(r.value))
+            throw new Error("the proof's value isn't hex");
+        value = hexToBytes(r.value);
+    }
+    if (!verifyProof(r.root, namespace, key, value, r.proof))
+        throw new Error(`the node's proof for this record doesn't verify against state root ${String(r.root).slice(0, 16)}…`);
+    return { value, root: r.root, height: r.height };
+}
+// ---- Decoding records (node/src/state/codec.rs: borsh, little-endian, u32 lengths) ----
+/** A strict little-endian reader over a record's bytes. */
+class Reader {
+    b;
+    at = 0;
+    view;
+    constructor(b) {
+        this.b = b;
+        this.view = new DataView(b.buffer, b.byteOffset, b.byteLength);
+    }
+    need(n) {
+        if (this.at + n > this.b.length)
+            throw new Error("record ends early");
+    }
+    u8() {
+        this.need(1);
+        return this.b[this.at++];
+    }
+    u32() {
+        this.need(4);
+        const v = this.view.getUint32(this.at, true);
+        this.at += 4;
+        return v;
+    }
+    u64() {
+        this.need(8);
+        const v = this.view.getBigUint64(this.at, true);
+        this.at += 8;
+        return v;
+    }
+    /** `n` raw bytes. */
+    fixed(n) {
+        this.need(n);
+        const v = this.b.subarray(this.at, this.at + n);
+        this.at += n;
+        return v;
+    }
+    /** A borsh bool: one byte, 0 or 1 and nothing else. */
+    bool() {
+        const v = this.u8();
+        if (v > 1)
+            throw new Error(`record holds ${v} where a bool should be`);
+        return v === 1;
+    }
+    str() {
+        const n = this.u32();
+        this.need(n);
+        const s = new TextDecoder("utf-8", { fatal: true }).decode(this.b.subarray(this.at, this.at + n));
+        this.at += n;
+        return s;
+    }
+}
+export function decodeAccount(value) {
+    const r = new Reader(value);
+    const balance = r.u64();
+    const nonce = Number(r.u64());
+    const n = r.u32();
+    if (n > 64)
+        throw new Error("account record lists too many keys");
+    const keys = [];
+    for (let i = 0; i < n; i++) {
+        const key_id = r.str();
+        const label = r.str();
+        const tag = r.u8();
+        let role;
+        if (tag === 0)
+            role = { type: "owner" };
+        else if (tag === 1)
+            role = { type: "session", limit: r.u64().toString(), period_blocks: Number(r.u64()), expires_at: Number(r.u64()) };
+        else
+            throw new Error(`bad key role tag ${tag}`);
+        const added_at = Number(r.u64());
+        r.u64(); // spent in the current window
+        r.u64(); // window start
+        keys.push({ key_id, label, role, added_at });
+    }
+    return { balance, nonce, keys };
+}
+export function decodeName(value) {
+    const r = new Reader(value);
+    const name = r.str();
+    const owner = r.str();
+    const registered_at = Number(r.u64());
+    // Saturated, so a never-expiring record (u64::MAX) compares as "later than any height".
+    const sat = (v) => (v > BigInt(Number.MAX_SAFE_INTEGER) ? Number.MAX_SAFE_INTEGER : Number(v));
+    const expires_at = sat(r.u64());
+    const rec = { name, owner, registered_at, expires_at };
+    // State schema 6 appended `offered_to` (an Option: 0, or 1 and the address), schema 7
+    // `grace_blocks`; older records end earlier.
+    if (r.at === value.length)
+        return rec;
+    const tag = r.u8();
+    if (tag > 1)
+        throw new Error(`name record: bad offered_to tag ${tag}`);
+    if (tag === 1)
+        rec.offered_to = r.str();
+    if (r.at === value.length)
+        return rec;
+    rec.grace_blocks = sat(r.u64());
+    return rec;
+}
+/** A number the record holds as a u64, which must be one JSON and JS carry exactly. */
+const exactCount = (v, what) => {
+    if (v > BigInt(Number.MAX_SAFE_INTEGER))
+        throw new Error(`a program record's ${what} (${v}) is past 2^53 − 1, which this SDK can't carry exactly`);
+    return Number(v);
+};
+/**
+ * Decodes a program record: the format byte (1: the only format this SDK reads, as the node's
+ * `Versioned` does) and the borsh body, field by field in the order the node writes them. Refuses
+ * a format it doesn't know, a bool or an option tag that isn't 0 or 1, text that isn't UTF-8 and
+ * bytes left over, so what it returns is what the state holds.
+ */
+export function decodeProgram(value) {
+    const r = new Reader(value);
+    const format = r.u8();
+    if (format !== 1)
+        throw new Error(`program record format ${format}: this SDK reads format 1`);
+    const creator = r.str();
+    const created_at = exactCount(r.u64(), "created_at");
+    const wasm_hash = bytesToHex(r.fixed(32));
+    const interface_hash = bytesToHex(r.fixed(32));
+    const version = r.u32();
+    const hasAuthority = r.u8();
+    if (hasAuthority > 1)
+        throw new Error(`a program record's authority has option tag ${hasAuthority}`);
+    const authority = hasAuthority === 1 ? r.str() : null;
+    const upgrade_delay_blocks = exactCount(r.u64(), "upgrade_delay_blocks");
+    const policyByte = r.u8();
+    if (policyByte > 1)
+        throw new Error(`a program record's policy is ${policyByte}: this SDK knows open (0) and additive (1)`);
+    const accepts_transfers = r.bool();
+    const items = exactCount(r.u64(), "items");
+    const bytes = exactCount(r.u64(), "bytes");
+    const deposit = r.u64().toString();
+    const sponsored = r.u64().toString();
+    const record_deposit = r.u64().toString();
+    const record_payer = r.str();
+    if (r.at !== value.length)
+        throw new Error("a program record has bytes after its last field");
+    return { creator, created_at, wasm_hash, interface_hash, version, authority, upgrade_delay_blocks, policy: policyByte === 0 ? "open" : "additive", accepts_transfers, storage: { items, bytes, deposit }, sponsored, record_deposit, record_payer };
+}

package/dist/release.d.ts

@@ -0,0 +1,15 @@
+export declare const RELEASE_SIGNATURE_FORMAT = "blockula-release-signature-v1";
+/** The contents of a `checksums.txt.sig` file. */
+export interface ReleaseSignature {
+    format: string;
+    key_id: string;
+    public_key: string;
+    signature: string;
+}
+/** What the release key signs: the domain, then the file's exact bytes. */
+export declare function releaseMessage(file: Uint8Array): Uint8Array;
+/**
+ * Throws unless `sig` is a valid release signature on `file` by the key whose id is
+ * `trustedKeyId` (the published release key id, never one taken from the signature itself).
+ */
+export declare function verifyReleaseSignature(sig: ReleaseSignature, file: Uint8Array, trustedKeyId: string): void;

package/dist/release.js

@@ -0,0 +1,41 @@
+// Release signatures (docs/OPERATIONS.md "Releases"): the offline ML-DSA-65 key signs each
+// release's checksums.txt. Same format and checks as scripts/release-sig.mjs, so tools that
+// install a release (the MCP's install_node) can verify it with the SDK alone:
+//   message   = "BLOCKULA_RELEASE_V1" ‖ file bytes
+//   signature = ML-DSA-65 (FIPS 204, empty context)
+//   key id    = hex BLAKE3(public key)
+//   .sig file = one JSON line: {"format","key_id","public_key","signature"} (hex)
+import { ml_dsa65 } from "@noble/post-quantum/ml-dsa.js";
+import { blake3 } from "@noble/hashes/blake3.js";
+import { bytesToHex, hexToBytes } from "@noble/hashes/utils.js";
+import { PUBLIC_KEY_LEN, SIGNATURE_LEN } from "./tx.js";
+export const RELEASE_SIGNATURE_FORMAT = "blockula-release-signature-v1";
+const DOMAIN = new TextEncoder().encode("BLOCKULA_RELEASE_V1");
+/** What the release key signs: the domain, then the file's exact bytes. */
+export function releaseMessage(file) {
+    const m = new Uint8Array(DOMAIN.length + file.length);
+    m.set(DOMAIN);
+    m.set(file, DOMAIN.length);
+    return m;
+}
+const isHex = (s, bytes) => typeof s === "string" && s.length === bytes * 2 && /^[0-9a-f]*$/.test(s);
+/**
+ * Throws unless `sig` is a valid release signature on `file` by the key whose id is
+ * `trustedKeyId` (the published release key id, never one taken from the signature itself).
+ */
+export function verifyReleaseSignature(sig, file, trustedKeyId) {
+    if (!sig || sig.format !== RELEASE_SIGNATURE_FORMAT)
+        throw new Error(`unknown release signature format ${String(sig?.format)}`);
+    if (!isHex(trustedKeyId, 32))
+        throw new Error("the trusted release key id must be 64 lowercase hex characters");
+    if (!isHex(sig.public_key, PUBLIC_KEY_LEN) || !isHex(sig.signature, SIGNATURE_LEN))
+        throw new Error("malformed ML-DSA-65 key or signature");
+    const publicKey = hexToBytes(sig.public_key);
+    const id = bytesToHex(blake3(publicKey));
+    if (sig.key_id !== id)
+        throw new Error("the signature's key_id doesn't match its public key");
+    if (id !== trustedKeyId)
+        throw new Error(`signed by key ${id}, not the release key ${trustedKeyId}`);
+    if (!ml_dsa65.verify(hexToBytes(sig.signature), releaseMessage(file), publicKey))
+        throw new Error("INVALID release signature");
+}