@blockula/sdk 0.3.0 → 1.0.0

package/dist/tx.js

@@ -1,32 +1,196 @@
 // Canonical transaction encoding. Must stay byte-identical to node/src/types.rs `Tx::signing_bytes`.
+import { blake3 } from "@noble/hashes/blake3.js";
+import { bytesToHex, concatBytes, hexToBytes } from "@noble/hashes/utils.js";
+import { bech32m } from "@scure/base";
 export const PUBLIC_KEY_LEN = 1952;
 export const SIGNATURE_LEN = 3309;
+/** Domain of the unsigned ghost wire form (`private_transfer`, `unshield`). */
+export const GHOST_TX_DOMAIN = "BLOCKULA_GHOST_V1";
+export const GHOST_ENC_BYTES = 1401;
+export const GHOST_OUT_BYTES = 80;
+export const GHOST_ADDRESS_BYTES = 1216;
+/** The Action circuit the node verifies proofs against (blockula-ghost `CIRCUIT_ID`). */
+export const GHOST_CIRCUIT_ID = 1;
 export const DROPS_PER_FANG = 1000000000n;
 const utf8 = new TextEncoder();
+const U64_LIMIT = 1n << 64n;
+/**
+ * The largest value of a whole-number field a tx carries as a JSON number, not a string (ids,
+ * heights, PR numbers, the nonce): 2^53 − 1, what a JavaScript number holds exactly
+ * (node/src/types.rs `MAX_JSON_INT`). The chain refuses larger ones, so every stored proposal
+ * kind and multisig action reads back exactly here, and its digest can be computed.
+ */
+export const MAX_JSON_INT = (1n << 53n) - 1n;
+/** An optional field's JSON default (`#[serde(default)]` in node/src/types.rs): only when it's absent, never for `null`. */
+const orDefault = (v, d) => (v === undefined ? d : v);
+/**
+ * An unsigned integer field as the node reads it from JSON (node/src/types.rs: a JSON number,
+ * or for amounts a decimal string), checked to be in `0 ..= max`. Anything the node's JSON
+ * parser would refuse is refused here, so `signingBytes`/`txBytes` never encode a value other
+ * than the one in the tx object (no wrapping of negative or oversized numbers).
+ */
+export function uintField(v, max, what = "integer field") {
+    let n;
+    if (typeof v === "bigint")
+        n = v;
+    else if (typeof v === "number") {
+        if (!Number.isInteger(v))
+            throw new RangeError(`${what} must be a whole number, got ${v}`);
+        // Above 2^53 − 1 a JavaScript number may not be the value that was meant: pass a string of
+        // digits (where the field can be that large).
+        if (!Number.isSafeInteger(v)) {
+            if (max <= MAX_JSON_INT)
+                throw new RangeError(`${what} must be 0 to ${max}, got ${v}${v > Number.MAX_SAFE_INTEGER ? " (past 2^53 − 1: not even exact as a JavaScript number)" : ""}`);
+            throw new RangeError(`${what} must be 0 to ${Number.MAX_SAFE_INTEGER} as a number (larger values as a string of digits), got ${v}`);
+        }
+        n = BigInt(v);
+    }
+    else if (typeof v === "string") {
+        if (!/^\d+$/.test(v))
+            throw new RangeError(`${what} must be a decimal string of digits, got ${JSON.stringify(v)}`);
+        n = BigInt(v);
+    }
+    else
+        throw new RangeError(`${what} must be a number or a decimal string, got ${typeof v}`);
+    if (n < 0n || n > max)
+        throw new RangeError(`${what} must be 0 to ${max}, got ${n}`);
+    return n;
+}
+/** A u64 field (`uintField` up to 2^64 − 1). */
+export const u64Field = (v, what) => uintField(v, U64_LIMIT - 1n, what);
+/**
+ * A bytes field as the node's JSON carries it (node/src/types.rs `HexBytes`): lowercase hex, two
+ * digits a byte. The node's parser refuses uppercase and odd lengths, so this does too, instead of
+ * signing bytes the node can't read back from the JSON.
+ */
+function lowerHexBytes(v, what) {
+    if (typeof v !== "string")
+        throw new TypeError(`${what} must be a string of lowercase hex`);
+    if (!/^(?:[0-9a-f]{2})*$/.test(v))
+        throw new Error(`${what} must be lowercase hex, two digits a byte`);
+    return hexToBytes(v);
+}
+/** An entry of a list field (a program call, a binding, an initializer): a JSON object. */
+function fields(v, what) {
+    if (!v || typeof v !== "object" || Array.isArray(v))
+        throw new TypeError(`${what} must be an object`);
+    return v;
+}
 class Writer {
     parts = [];
     bytes(b) { for (const x of b)
         this.parts.push(x); }
-    u8(n) { this.parts.push(n & 0xff); }
-    u16(n) { this.u8(n); this.u8(n >> 8); }
-    u64(n) { for (let i = 0n; i < 8n; i++)
-        this.u8(Number((n >> (8n * i)) & 0xffn)); }
-    str(s) { const b = utf8.encode(s); this.u16(b.length); this.bytes(b); }
+    /** A byte the encoder chose (tags, bools, lengths' bytes): always in range. */
+    byte(n) { this.parts.push(n & 0xff); }
+    u8(n, what) { this.byte(Number(uintField(n, 0xffn, what))); }
+    u16(n, what) { const v = Number(uintField(n, 0xffffn, what)); this.byte(v); this.byte(v >> 8); }
+    u32(n, what) { const v = Number(uintField(n, 0xffffffffn, what)); this.byte(v); this.byte(v >> 8); this.byte(v >> 16); this.byte(v >>> 24); }
+    u64(n, what) { this.le64(u64Field(n, what)); }
+    /** A u64 the tx carries as a JSON number: at most `MAX_JSON_INT`, as the node's format rules require. */
+    int(n, what) { this.le64(uintField(n, MAX_JSON_INT, what)); }
+    le64(v) { for (let i = 0n; i < 8n; i++)
+        this.byte(Number((v >> (8n * i)) & 0xffn)); }
+    bool(b, what = "flag") {
+        if (typeof b !== "boolean")
+            throw new TypeError(`${what} must be true or false`);
+        this.byte(b ? 1 : 0);
+    }
+    str(s, what = "string field") {
+        if (typeof s !== "string")
+            throw new TypeError(`${what} must be a string`);
+        const b = utf8.encode(s);
+        if (b.length > 0xffff)
+            throw new Error(`${what} too long to encode`);
+        this.u16(b.length);
+        this.bytes(b);
+    }
+    ids(xs, what = "id list") {
+        if (!Array.isArray(xs))
+            throw new TypeError(`${what} must be an array`);
+        this.u16(xs.length, `${what} length`);
+        for (const x of xs)
+            this.int(x, what);
+    }
+    /** Raw bytes of exactly `len` bytes, from hex. */
+    fixed(hex, len) {
+        const b = hexToBytes(hex);
+        if (b.length !== len)
+            throw new Error(`expected ${len} bytes, got ${b.length}`);
+        this.bytes(b);
+    }
+    strs(xs, what = "string list") {
+        if (!Array.isArray(xs))
+            throw new TypeError(`${what} must be an array`);
+        this.u16(xs.length, `${what} length`);
+        for (const x of xs)
+            this.str(x, what);
+    }
+    /** Bytes with a u32 length (node/src/types.rs `put_bytes`: a program's code, interface and inputs), from lowercase hex. */
+    putBytes(hex, what = "bytes field") {
+        const b = lowerHexBytes(hex, what);
+        this.u32(b.length, `${what} length`);
+        this.bytes(b);
+    }
+    /** A u8 count, then each entry (a program action's calls and bindings). More than 255 are refused, never wrapped. */
+    entries(xs, what, each) {
+        if (!Array.isArray(xs))
+            throw new TypeError(`${what} must be an array`);
+        this.u8(xs.length, `${what} count`);
+        for (const x of xs)
+            each(fields(x, `each of ${what}`));
+    }
     done() { return Uint8Array.from(this.parts); }
 }
+/** A chain's genesis hash as its 32 bytes (`/api/status` `genesis_hash`, lowercase hex). */
+export function genesisHashBytes(genesisHash) {
+    if (typeof genesisHash !== "string" || !/^[0-9a-f]{64}$/.test(genesisHash)) {
+        throw new Error("genesis_hash must be the chain's genesis hash: 32 bytes of lowercase hex (genesis_hash in /api/status)");
+    }
+    return hexToBytes(genesisHash);
+}
+/** Unsigned ghost txs (`private_transfer`, `unshield`): no key signs them, their proof authorizes them. */
+export function isUnsignedAction(a) {
+    return a.type === "private_transfer" || a.type === "unshield";
+}
+/** A program action (tags 62–64 and 69, node/src/types.rs `Action::is_program`). */
+export function isProgramAction(a) {
+    return a.type === "upload_code" || a.type === "create_program" || a.type === "call_program" || a.type === "programs_pause";
+}
+/**
+ * The bytes a key signs (node/src/types.rs `Tx::signing_bytes`). For an unsigned ghost tx this is
+ * its whole wire form instead: `BLOCKULA_GHOST_V1 ‖ chain_id ‖ genesis hash ‖ fee ‖ tip ‖ valid_until ‖ action`.
+ */
 export function signingBytes(tx) {
     const w = new Writer();
-    w.bytes(utf8.encode("BLOCKULA_TX_V2"));
+    if (isUnsignedAction(tx.action)) {
+        w.bytes(utf8.encode(GHOST_TX_DOMAIN));
+        w.str(tx.chain_id);
+        w.bytes(genesisHashBytes(tx.genesis_hash));
+        w.u64(tx.fee, "fee");
+        w.u64(orDefault(tx.tip, "0"), "tip");
+        w.int(tx.valid_until, "valid_until");
+        encodeAction(w, tx.action);
+        return w.done();
+    }
+    w.bytes(utf8.encode("BLOCKULA_TX_V3"));
     w.str(tx.chain_id);
+    w.bytes(genesisHashBytes(tx.genesis_hash));
     w.str(tx.from);
-    w.u64(BigInt(tx.nonce));
-    w.u64(BigInt(tx.fee));
-    const a = tx.action;
+    w.int(tx.nonce, "nonce");
+    w.u64(tx.fee, "fee");
+    w.u64(orDefault(tx.tip, "0"), "tip");
+    w.int(tx.valid_until, "valid_until");
+    encodeAction(w, tx.action);
+    w.str(orDefault(tx.memo, ""), "memo");
+    return w.done();
+}
+/** An action's tag and fields, as inside the signing bytes (node/src/types.rs `Action::encode`). */
+function encodeAction(w, a) {
     switch (a.type) {
         case "transfer":
             w.u8(0);
             w.str(a.to);
-            w.u64(BigInt(a.amount));
+            w.u64(a.amount);
             break;
         case "register_name":
             w.u8(1);
@@ -40,10 +204,12 @@ export function signingBytes(tx) {
                 w.u8(0);
             else {
                 w.u8(1);
-                w.u64(BigInt(a.role.limit));
-                w.u64(BigInt(a.role.period_blocks));
-                w.u64(BigInt(a.role.expires_at));
+                w.u64(a.role.limit);
+                w.int(a.role.period_blocks, "period_blocks");
+                w.int(a.role.expires_at, "expires_at");
             }
+            w.str(a.public_key);
+            w.str(a.pop);
             break;
         case "remove_key":
             w.u8(3);
@@ -54,7 +220,7 @@ export function signingBytes(tx) {
             w.str(a.consensus_key);
             w.str(a.p2p_addr);
             w.str(a.http_addr);
-            w.u64(BigInt(a.bond));
+            w.u64(a.bond);
             w.str(a.pop);
             break;
         case "approve_validator":
@@ -81,34 +247,661 @@ export function signingBytes(tx) {
         case "create_hunt":
             w.u8(10);
             w.str(a.repo);
-            w.u64(BigInt(a.issue));
-            w.u64(BigInt(a.amount));
-            w.u64(BigInt(a.expires_at));
+            w.int(a.issue, "issue");
+            w.u64(a.amount);
+            w.int(a.expires_at, "expires_at");
             w.str(a.title);
             break;
         case "fund_hunt":
             w.u8(11);
-            w.u64(BigInt(a.hunt_id));
-            w.u64(BigInt(a.amount));
+            w.int(a.hunt_id, "hunt_id");
+            w.u64(a.amount);
             break;
         case "award_hunt":
             w.u8(12);
-            w.u64(BigInt(a.hunt_id));
+            w.int(a.hunt_id, "hunt_id");
             w.str(a.to);
-            w.u64(BigInt(a.pr));
+            w.int(a.pr, "pr");
             w.str(a.familiar_key ?? "");
             break;
         case "cancel_hunt":
             w.u8(13);
-            w.u64(BigInt(a.hunt_id));
+            w.int(a.hunt_id, "hunt_id");
             break;
         case "register_familiar":
             w.u8(14);
             w.str(a.key_id);
             w.str(a.label);
             break;
+        case "set_repo":
+            w.u8(15);
+            w.str(a.repo);
+            w.int(a.weight, "weight");
+            break;
+        case "grant_soul":
+            w.u8(16);
+            w.str(a.to);
+            w.int(a.amount, "amount");
+            w.str(a.reason);
+            break;
+        case "vouch":
+            w.u8(17);
+            w.str(a.account);
+            break;
+        case "unvouch":
+            w.u8(18);
+            w.str(a.account);
+            break;
+        case "flag_sybil":
+            w.u8(19);
+            w.str(a.account);
+            w.str(a.reason);
+            break;
+        case "submit_claim":
+            w.u8(20);
+            w.str(a.repo);
+            w.int(a.pr, "pr");
+            w.str(a.familiar_key ?? "");
+            break;
+        case "attest_claim":
+            w.u8(21);
+            w.int(a.claim_id, "claim_id");
+            w.bool(a.ok, "ok");
+            w.str(a.merge_sha);
+            w.str(orDefault(a.note, ""));
+            break;
+        case "reject_claim":
+            w.u8(22);
+            w.int(a.claim_id, "claim_id");
+            w.str(a.reason);
+            break;
+        case "join_jury":
+            w.u8(23);
+            w.u64(a.bond);
+            break;
+        case "leave_jury":
+            w.u8(24);
+            break;
+        case "commit_votes":
+            w.u8(25);
+            w.int(a.seance_id, "seance_id");
+            w.str(a.commitment);
+            w.str(a.pairs_digest);
+            break;
+        case "reveal_votes":
+            w.u8(26);
+            w.int(a.seance_id, "seance_id");
+            w.str(a.votes);
+            w.ids(a.spam, "spam");
+            w.str(a.salt);
+            break;
+        case "fund_pool":
+            w.u8(27);
+            w.u64(a.amount);
+            break;
+        case "withdraw_vested":
+            w.u8(28);
+            break;
+        case "clawback":
+            w.u8(29);
+            w.str(a.account);
+            w.str(a.reason);
+            break;
+        case "delegate":
+            w.u8(30);
+            w.str(a.validator);
+            w.u64(a.amount);
+            break;
+        case "undelegate":
+            w.u8(31);
+            w.str(a.validator);
+            w.u64(a.shares);
+            w.u64(orDefault(a.amount, "0"));
+            break;
+        case "redelegate":
+            w.u8(32);
+            w.str(a.from_validator);
+            w.str(a.to_validator);
+            w.u64(a.shares);
+            break;
+        case "withdraw_unbonded":
+            w.u8(33);
+            break;
+        case "update_validator":
+            w.u8(34);
+            w.int(a.commission_bps, "commission_bps");
+            w.str(a.p2p_addr);
+            w.str(a.http_addr);
+            break;
+        case "unjail":
+            w.u8(35);
+            w.str(a.validator);
+            break;
+        case "report_equivocation":
+            w.u8(36);
+            w.str(a.evidence);
+            break;
+        case "beacon_commit":
+            w.u8(37);
+            w.int(a.epoch, "epoch");
+            w.str(a.commitment);
+            break;
+        case "beacon_reveal":
+            w.u8(38);
+            w.int(a.epoch, "epoch");
+            w.str(a.secret);
+            break;
+        case "propose":
+            w.u8(39);
+            encodeProposalKind(w, a.kind);
+            w.u64(a.deposit);
+            w.str(a.title);
+            w.str(orDefault(a.url, ""));
+            break;
+        case "vote":
+            w.u8(40);
+            w.int(a.proposal_id, "proposal_id");
+            w.bool(a.aye, "aye");
+            w.u64(a.amount);
+            w.u8(a.conviction, "conviction");
+            w.str(a.proposal_digest);
+            break;
+        case "unlock":
+            w.u8(41);
+            break;
+        case "multisig_create":
+            w.u8(42);
+            w.strs(a.owners);
+            w.u8(a.threshold, "threshold");
+            break;
+        case "multisig_propose":
+            if (a.action.type === "multisig_propose")
+                throw new Error("a multisig proposal can't contain another");
+            // The node won't decode one (docs/PROGRAMS-V0.md §2.1, "No nesting").
+            if (isProgramAction(a.action))
+                throw new Error("a multisig proposal can't hold a program action");
+            w.u8(43);
+            encodeAction(w, a.action);
+            break;
+        case "multisig_approve":
+            w.u8(44);
+            w.int(a.id, "id");
+            w.str(a.action_digest);
+            break;
+        case "renew_name":
+            w.u8(45);
+            w.str(a.name);
+            w.u8(a.years, "years");
+            break;
+        case "transfer_name":
+            w.u8(46);
+            w.str(a.name);
+            w.str(a.to);
+            break;
+        case "release_name":
+            w.u8(47);
+            w.str(a.name);
+            break;
+        case "claim_distribution":
+            w.u8(48);
+            w.int(a.distribution_id, "distribution_id");
+            w.u64(a.amount);
+            w.strs(a.proof);
+            break;
+        case "attest_revert":
+            w.u8(49);
+            w.int(a.claim_id, "claim_id");
+            w.str(a.revert_sha);
+            break;
+        case "shield":
+            w.u8(50);
+            w.u64(a.amount);
+            encodeBundle(w, a.bundle);
+            break;
+        case "private_transfer":
+            w.u8(51);
+            encodeBundle(w, a.bundle);
+            break;
+        case "unshield":
+            w.u8(52);
+            w.str(a.to);
+            w.u64(a.amount);
+            encodeBundle(w, a.bundle);
+            break;
+        case "set_ghost_address":
+            w.u8(53);
+            w.fixed(a.address, GHOST_ADDRESS_BYTES);
+            break;
+        case "ghost_pause":
+            w.u8(54);
+            break;
+        case "validator_ready":
+            w.u8(60);
+            w.int(a.epoch, "epoch");
+            break;
+        case "admit_validator":
+            w.u8(61);
+            w.str(a.validator);
+            w.int(a.epoch, "epoch");
+            break;
+        // Programs (docs/PROGRAMS-V0.md §2.2–2.5). Counts are a u8; byte fields a u32 length (`putBytes`).
+        case "upload_code":
+            w.u8(62);
+            w.putBytes(a.wasm, "wasm");
+            w.putBytes(a.interface, "interface");
+            w.u64(a.storage_limit, "storage_limit");
+            break;
+        case "create_program": {
+            w.u8(63);
+            w.str(a.wasm_hash, "wasm_hash");
+            w.str(a.interface_hash, "interface_hash");
+            w.str(authorityField(a.authority), "authority");
+            w.int(a.upgrade_delay_blocks, "upgrade_delay_blocks");
+            w.u8(policyByte(a.policy));
+            w.bool(a.accepts_transfers, "accepts_transfers");
+            // `init`: a presence byte, then the method, its input and value (absent or null: none, as the node reads the JSON).
+            if (a.init === undefined || a.init === null)
+                w.u8(0);
+            else {
+                const init = fields(a.init, "init");
+                w.u8(1);
+                w.str(init.method, "init.method");
+                w.putBytes(init.input, "init.input");
+                w.u64(init.value, "init.value");
+            }
+            w.int(a.fuel_limit, "fuel_limit");
+            w.u64(a.storage_limit, "storage_limit");
+            encodeBindings(w, a.bindings);
+            break;
+        }
+        case "call_program":
+            w.u8(64);
+            w.entries(a.calls, "calls", (c) => { w.str(c.program, "calls.program"); w.str(c.version_digest, "calls.version_digest"); w.str(c.method, "calls.method"); w.putBytes(c.input, "calls.input"); w.u64(c.value, "calls.value"); });
+            w.int(a.fuel_limit, "fuel_limit");
+            w.u64(a.storage_limit, "storage_limit");
+            encodeBindings(w, a.bindings);
+            break;
+        case "programs_pause":
+            w.u8(69);
+            break;
+        default:
+            throw new Error(`unknown action type ${a.type}`);
+    }
+}
+/** A program action's bindings (node/src/types.rs `put_bindings`): a u8 count, then each program and version digest. */
+function encodeBindings(w, bindings) {
+    w.entries(bindings, "bindings", (b) => { w.str(b.program, "bindings.program"); w.str(b.version_digest, "bindings.version_digest"); });
+}
+/**
+ * A create's `authority` as the codec writes it (an optional string: `""` for none). The node
+ * reads JSON `""` as an authority that isn't an address, and refuses it, but its bytes would be
+ * an immutable program's: so `""` is refused here, never signed as the other.
+ */
+function authorityField(authority) {
+    if (authority === undefined || authority === null)
+        return "";
+    if (authority === "")
+        throw new Error('authority must be an address, or null for an immutable program (not "")');
+    if (typeof authority !== "string")
+        throw new TypeError("authority must be a string (an address) or null");
+    return authority;
+}
+/** A program policy's byte (node/src/types.rs `ProgramPolicy::byte`). */
+function policyByte(policy) {
+    if (policy === "open")
+        return 0;
+    if (policy === "additive")
+        return 1;
+    throw new Error(`policy must be "open" or "additive", not ${typeof policy === "string" ? JSON.stringify(policy) : typeof policy}`);
+}
+/** A bundle without its proof, raw and in wire order: what the sighash covers. */
+function encodeBundlePublic(w, b) {
+    w.fixed(b.instance, 32);
+    w.fixed(b.anchor, 32);
+    for (const x of [...b.nullifiers, ...b.commitments])
+        w.fixed(x, 32);
+    for (const x of b.enc)
+        w.fixed(x, GHOST_ENC_BYTES);
+    for (const x of b.out)
+        w.fixed(x, GHOST_OUT_BYTES);
+}
+/** node/src/types.rs `GhostBundle::encode`: the fixed fields, then the proof with a u32 length. */
+function encodeBundle(w, b) {
+    encodeBundlePublic(w, b);
+    const proof = hexToBytes(b.proof);
+    w.u32(proof.length);
+    w.bytes(proof);
+}
+/**
+ * What a ghost tx's Action proof is bound to (node/src/types.rs `Tx::ghost_sighash`):
+ * BLAKE3-KDF("blockula ghost v1 tx sighash", chain_id ‖ genesis hash ‖ tag ‖ valid_until ‖ fee ‖
+ * tip ‖ the tag's own fields (shield: from, nonce, amount; unshield: to, amount) ‖ the bundle
+ * without its proof ‖ circuit id). A wallet proves with this as the witness's sighash, then fills
+ * in the proof.
+ */
+export function ghostSighash(tx) {
+    const a = tx.action;
+    if (a.type !== "shield" && a.type !== "private_transfer" && a.type !== "unshield")
+        throw new Error("not a ghost transfer");
+    const w = new Writer();
+    w.str(tx.chain_id);
+    w.bytes(genesisHashBytes(tx.genesis_hash));
+    w.u8(a.type === "shield" ? 50 : a.type === "private_transfer" ? 51 : 52);
+    w.int(tx.valid_until, "valid_until");
+    w.u64(tx.fee, "fee");
+    w.u64(orDefault(tx.tip, "0"), "tip");
+    if (a.type === "shield") {
+        w.str(tx.from);
+        w.int(tx.nonce, "nonce");
+        w.u64(a.amount);
+    }
+    if (a.type === "unshield") {
+        w.str(a.to);
+        w.u64(a.amount);
+    }
+    encodeBundlePublic(w, a.bundle);
+    w.u32(GHOST_CIRCUIT_ID);
+    return blake3(w.done(), { context: utf8.encode("blockula ghost v1 tx sighash") });
+}
+/** A proposal kind's own tag and fields (node/src/types.rs `ProposalKind::encode`). */
+function encodeProposalKind(w, k) {
+    switch (k.type) {
+        case "param_change":
+            w.u8(0);
+            w.str(k.key);
+            w.u64(k.value);
+            break;
+        case "treasury_spend":
+            w.u8(1);
+            w.str(k.to);
+            w.u64(k.amount);
+            break;
+        case "distribution":
+            w.u8(2);
+            w.int(k.distribution_id, "distribution_id");
+            w.str(k.merkle_root);
+            w.u64(k.total);
+            w.int(k.claim_until, "claim_until");
+            break;
+        case "set_repo":
+            w.u8(3);
+            w.str(k.repo);
+            w.int(k.weight, "weight");
+            break;
+        case "grant_soul":
+            w.u8(4);
+            w.str(k.to);
+            w.int(k.amount, "amount");
+            w.str(k.reason);
+            break;
+        case "flag_sybil":
+            w.u8(5);
+            w.str(k.account);
+            w.str(k.reason);
+            break;
+        case "reject_claim":
+            w.u8(6);
+            w.int(k.claim_id, "claim_id");
+            w.str(k.reason);
+            break;
+        case "clawback":
+            w.u8(7);
+            w.str(k.account);
+            w.str(k.reason);
+            break;
+        case "unlink_github":
+            w.u8(8);
+            w.str(k.handle);
+            break;
+        case "refund_hunt":
+            w.u8(9);
+            w.int(k.hunt_id, "hunt_id");
+            break;
+        case "schedule_upgrade":
+            w.u8(10);
+            w.u32(k.version, "version");
+            w.int(k.activation_height, "activation_height");
+            break;
+        case "activate_feature":
+            w.u8(11);
+            w.str(k.feature);
+            break;
+        case "deactivate_feature":
+            w.u8(12);
+            w.str(k.feature);
+            break;
+        case "text":
+            w.u8(13);
+            break;
+        case "unflag_sybil":
+            w.u8(14);
+            w.str(k.account);
+            w.str(k.reason);
+            break;
+        case "cancel_upgrade":
+            w.u8(15);
+            w.u32(k.version, "version");
+            w.int(k.activation_height, "activation_height");
+            break;
+        default:
+            throw new Error(`unknown proposal kind ${k.type}`);
     }
-    w.str(tx.memo);
+}
+/**
+ * What a Séance juror seals before revealing (node/src/types.rs `seance_commitment`): hex
+ * BLAKE3 of the Séance id, the juror's account, the votes, spam flags and a secret salt.
+ */
+export function seanceCommitment(seanceId, juror, votes, spam, salt) {
+    const w = new Writer();
+    w.bytes(utf8.encode("BLOCKULA_SEANCE_V1"));
+    w.int(seanceId, "seance_id");
+    w.str(juror);
+    w.str(votes);
+    w.ids(spam, "spam");
+    w.str(salt);
+    return bytesToHex(blake3(w.done()));
+}
+/**
+ * A validator's randomness-beacon commitment (node/src/beacon.rs `commitment`): hex BLAKE3 in
+ * derive-key mode ("blockula beacon commitment v1") over the chain id, the target epoch, the
+ * validator's address and its 32-byte hex secret. Strings are u64-length-prefixed, integers
+ * u64 little-endian.
+ */
+export function beaconCommitment(chainId, epoch, validator, secret) {
+    const u64 = (n) => {
+        const b = new Uint8Array(8);
+        // setBigUint64 would wrap a negative or oversized value: check it first.
+        new DataView(b.buffer).setBigUint64(0, u64Field(n, "epoch"), true);
+        return b;
+    };
+    const str = (s) => {
+        const b = utf8.encode(s);
+        return concatBytes(u64(b.length), b);
+    };
+    const key = hexToBytes(secret);
+    if (key.length !== 32)
+        throw new Error("a beacon secret is 32 bytes");
+    return bytesToHex(blake3(concatBytes(str(chainId), u64(epoch), str(validator), key), { context: utf8.encode("blockula beacon commitment v1") }));
+}
+/** "2.5" Soul → 2500 milli-Soul. */
+export function parseSoul(soul) {
+    const s = String(soul).trim();
+    if (!/^\d+(\.\d{1,3})?$/.test(s))
+        throw new Error(`invalid Soul amount: ${s}`);
+    const [whole, frac = ""] = s.split(".");
+    return Number(whole) * 1000 + Number(frac.padEnd(3, "0"));
+}
+/**
+ * What a `multisig_approve` binds (node/src/types.rs `action_digest`): BLAKE3 (derive-key mode,
+ * context "blockula multisig action v1") of the action's encoding, as inside the signing bytes.
+ * Compute it from the action you show the approver (`client.multisig(account)` `pending[].action`).
+ */
+export function actionDigest(action) {
+    return digestOf("multisig action", "blockula multisig action v1", (w) => encodeAction(w, action));
+}
+/**
+ * What a `vote` binds (node/src/types.rs `proposal_digest`): the proposal's kind (accounts as
+ * stored, resolved), title and link. Compute it from the proposal you show the voter.
+ */
+export function proposalDigest(kind, title, url = "") {
+    return digestOf("proposal", "blockula proposal v1", (w) => {
+        encodeProposalKind(w, kind);
+        w.str(title);
+        w.str(url);
+    });
+}
+/**
+ * BLAKE3 (derive-key mode, `context`) of what `encode` writes. A field out of range (a JSON
+ * number past 2^53 − 1 arrives rounded, and can't be the value the chain stored) fails with
+ * what's wrong and where it likely came from, not a bare encoder error (review-r2-clients-1).
+ */
+function digestOf(what, context, encode) {
+    const w = new Writer();
+    try {
+        encode(w);
+    }
+    catch (e) {
+        if (e instanceof RangeError)
+            throw new RangeError(`can't compute this ${what}'s digest: ${e.message}. The chain stores no ${what} with a whole number past 2^53 − 1 (the most a JSON number carries exactly), so the node it was read from may be misreporting it: read it from another node`);
+        throw e;
+    }
+    return bytesToHex(blake3(w.done(), { context: utf8.encode(context) }));
+}
+// ---- Programs' digests (node/src/programs/digest.rs, docs/PROGRAMS-V0.md §2.1), checked offline
+// against test/program-vectors.json, which the node writes. Frozen with protocol v2. ----
+/**
+ * The contexts of programs' five digests, each BLAKE3 in derive-key mode: node/src/programs/digest.rs
+ * `CODE_CONTEXT`, `INTERFACE_CONTEXT`, `VERSION_CONTEXT` and `ADDRESS_CONTEXT`, and the VM's
+ * `SELECTOR_CONTEXT` (node/vm/src/interface.rs), the selector's only home on the node.
+ */
+export const PROGRAM_DIGEST_CONTEXTS = Object.freeze({
+    code: "blockula program code v1",
+    interface: "blockula program interface v1",
+    version: "blockula program version v1",
+    address: "blockula program address v1",
+    method: "blockula program method v1",
+});
+/** Every v0 program's version (node/src/programs/digest.rs `FIRST_VERSION`): only a program upgrade, in a later protocol version, raises it. */
+export const FIRST_PROGRAM_VERSION = 1;
+/** Address prefixes (index.ts `KNOWN_PREFIXES`, node/src/crypto.rs `KNOWN_PREFIXES`), kept here so this module imports nothing of the SDK's. */
+const ADDRESS_PREFIXES = ["boo", "tboo"];
+/**
+ * A canonical address's prefix and 32 bytes (node/src/crypto.rs `parse_address`): a known prefix,
+ * and only the exact rendering, so neither uppercase nor another checksum aliases the account.
+ * Programs are named by address, never by name.
+ */
+function parseAddress(s, what) {
+    if (typeof s === "string" && s.length <= 90) {
+        try {
+            const { prefix, words } = bech32m.decode(s);
+            const bytes = bech32m.fromWords(words);
+            if (ADDRESS_PREFIXES.includes(prefix) && bytes.length === 32 && bech32m.encode(prefix, words) === s)
+                return { prefix, bytes };
+        }
+        catch {
+            // Not bech32m: refused below.
+        }
+    }
+    throw new Error(`${what} must be an address (boo1… or tboo1…), not ${typeof s === "string" ? JSON.stringify(s) : typeof s}`);
+}
+/** A 32-byte digest as a program action's JSON carries it: 64 lowercase hex (node/src/types.rs `check_hex_32`). */
+function hex32(v, what) {
+    if (typeof v !== "string" || !/^[0-9a-f]{64}$/.test(v))
+        throw new Error(`${what} must be 32 bytes of lowercase hex`);
+    return hexToBytes(v);
+}
+/** BLAKE3 in derive-key mode (the node's `blake3::derive_key`). */
+const deriveKey = (context, input) => blake3(input, { context: utf8.encode(context) });
+/** Bytes, or lowercase hex as `upload_code` carries them. */
+const bytesOf = (v, what) => (v instanceof Uint8Array ? v : lowerHexBytes(v, what));
+/**
+ * The hash that names a program's code (node/src/programs/digest.rs `wasm_hash`): BLAKE3-KDF("blockula
+ * program code v1", wasm), as 64 lowercase hex. A `create_program` names its code by it, once an
+ * `upload_code` of the same bytes (as bytes, or lowercase hex) has applied.
+ */
+export function wasmHash(wasm) {
+    return bytesToHex(deriveKey(PROGRAM_DIGEST_CONTEXTS.code, bytesOf(wasm, "wasm")));
+}
+/** The hash that names an interface, its format-1 bytes (node/src/programs/digest.rs `interface_hash`): as `wasmHash`, under "blockula program interface v1". */
+export function interfaceHash(iface) {
+    return bytesToHex(deriveKey(PROGRAM_DIGEST_CONTEXTS.interface, bytesOf(iface, "interface")));
+}
+/**
+ * What a call to `program` binds (node/src/programs/digest.rs `version_digest`): BLAKE3-KDF("blockula
+ * program version v1", the program's address as a string field (u16 LE length, its bytes) ‖ its
+ * code's hash ‖ its interface's hash ‖ its version, u32 LE), as 64 lowercase hex. A call runs only
+ * while this is the program's digest in force, so it runs the code its signer was shown: compute it
+ * from the record you show (its hashes and version), rather than sign a digest a node reported.
+ */
+export function versionDigest(program, wasmHashHex, interfaceHashHex, version = FIRST_PROGRAM_VERSION) {
+    parseAddress(program, "program");
+    const w = new Writer();
+    w.str(program, "program");
+    w.bytes(hex32(wasmHashHex, "wasm_hash"));
+    w.bytes(hex32(interfaceHashHex, "interface_hash"));
+    w.u32(version, "version");
+    return bytesToHex(deriveKey(PROGRAM_DIGEST_CONTEXTS.version, w.done()));
+}
+/**
+ * The address of the program `creator` creates with its transaction of `nonce` (node/src/programs/digest.rs
+ * `program_address`): bech32m(prefix, BLAKE3-KDF("blockula program address v1", the creator's 32
+ * address bytes ‖ nonce u64 LE)). `prefix` defaults to the creator's own (a chain admits only its
+ * prefix, so for any create it runs the two are the same).
+ *
+ * Don't send FANG to it before the create has applied: a create that fails spends its nonce, no
+ * later create reaches the address, and what was sent there is stranded for good (docs/PROGRAMS-V0.md
+ * §2.3). Fund a program through its initializer's value, or by transfer once it exists.
+ */
+export function programAddress(creator, nonce, prefix) {
+    const c = parseAddress(creator, "creator");
+    const p = prefix ?? c.prefix;
+    if (!ADDRESS_PREFIXES.includes(p))
+        throw new Error(`unknown address prefix ${p}`);
+    const w = new Writer();
+    w.bytes(c.bytes);
+    w.u64(nonce, "nonce");
+    return bech32m.encode(p, bech32m.toWords(deriveKey(PROGRAM_DIGEST_CONTEXTS.address, w.done())));
+}
+/** A method name: an identifier, `[a-z][a-z0-9_]{0,31}` (node/vm `abi::is_ident`). */
+const METHOD_NAME = /^[a-z][a-z0-9_]{0,31}$/;
+/**
+ * A method's selector (node/vm/src/interface.rs `selector`): the first 8 bytes of
+ * BLAKE3-KDF("blockula program method v1", its name), as 16 lowercase hex. An interface's methods
+ * have distinct selectors. Only identifiers are method names, so anything else is refused.
+ */
+export function methodSelector(name) {
+    if (typeof name !== "string" || !METHOD_NAME.test(name))
+        throw new Error(`a method name is an identifier ([a-z][a-z0-9_]{0,31}), not ${typeof name === "string" ? JSON.stringify(name) : typeof name}`);
+    return bytesToHex(deriveKey(PROGRAM_DIGEST_CONTEXTS.method, utf8.encode(name)).subarray(0, 8));
+}
+/**
+ * What a `commit_votes` binds (node/src/types.rs `seance_pairs_digest`): the Séance, the juror and,
+ * per assigned pair in order, both claims' ids, repos and PR numbers.
+ */
+export function seancePairsDigest(seanceId, juror, pairs) {
+    const w = new Writer();
+    w.int(seanceId, "seance_id");
+    w.str(juror);
+    w.u16(pairs.length);
+    for (const pair of pairs)
+        for (const c of pair) {
+            w.int(c.id, "claim id");
+            w.str(c.repo);
+            w.int(c.pr, "pr");
+        }
+    return bytesToHex(blake3(w.done(), { context: utf8.encode("blockula seance pairs v1") }));
+}
+/** FIPS 204 context string for a key's proof of possession in `add_key` (node/src/types.rs `KEY_POP_CONTEXT`). */
+export const KEY_POP_CONTEXT = utf8.encode("blockula/key-pop/v1");
+/**
+ * What a key signs to consent to being added to `account` (node/src/types.rs `key_pop_message`):
+ * the chain instance, the account and the key's own id (audit gap-7-2).
+ */
+export function keyPopMessage(chainId, genesisHash, account, keyId) {
+    const w = new Writer();
+    w.bytes(utf8.encode("BLOCKULA_KEY_POP_V1"));
+    for (const s of [chainId, genesisHash, account, keyId])
+        w.str(s);
     return w.done();
 }
 /** FIPS 204 context string for validator proofs of possession (node/src/types.rs `POP_CONTEXT`). */
@@ -121,10 +914,57 @@ export function popMessage(chainId, owner, p2pAddr, httpAddr) {
         w.str(s);
     return w.done();
 }
-/** Mirrors `min_fee` in node/src/types.rs: base fee is priced per byte and burned. */
+/** Wire size in bytes (node/src/types.rs `Tx::size`): signing bytes plus the key and signature (none for an unsigned ghost tx). Fees are priced on it. */
+export function txSize(tx) {
+    return signingBytes(tx).length + (isUnsignedAction(tx.action) ? 0 : PUBLIC_KEY_LEN + SIGNATURE_LEN);
+}
+/** The base fee at its genesis floor: 10,000 drops + 10 per byte (`min_fee`). */
+export const FLOOR_BASE_FEE = { flat: 10000n, rate: 10000n };
+/** Mirrors `FeeSlot::fee` in node/src/econ.rs: `flat + rate × size / 1000`, rounded down. Burned. */
+export function baseFee(tx, fee = FLOOR_BASE_FEE) {
+    return BigInt(fee.flat) + (BigInt(fee.rate) * BigInt(txSize(tx))) / 1000n;
+}
+/** Mirrors `min_fee` in node/src/types.rs: the base fee at its floor (an idle chain's). */
 export function minFee(tx) {
-    const size = signingBytes(tx).length + PUBLIC_KEY_LEN + SIGNATURE_LEN;
-    return 10000n + BigInt(size) * 10n;
+    return baseFee(tx, FLOOR_BASE_FEE);
+}
+/** The chain's default `tip_cap_multiple` (node/src/params.rs): a tip may be at most this many times the base fee of the block that includes it. */
+export const DEFAULT_TIP_CAP_MULTIPLE = 20;
+/**
+ * The most this tx may tip in a block with this base fee (node/src/econ.rs `max_tip`): `multiple` × its base fee. Nodes refuse
+ * a bigger tip. `/api/fees` serves the chain's `tip_cap_multiple` and `lowest`, the base fee a tip fits under in any upcoming block.
+ * Tips are also paid only from transferable FANG (locks hold them), and a multisig's owner keys or a validator's consensus key
+ * acting for its owner can't tip at all.
+ */
+export function maxTip(tx, fee = FLOOR_BASE_FEE, multiple = DEFAULT_TIP_CAP_MULTIPLE) {
+    return BigInt(multiple) * baseFee(tx, fee);
+}
+/** What the tx is charged in a block with this base fee (node/src/econ.rs `charge`): base fee + tip. Its `fee` must cover it; nothing more is debited. */
+export function txCharge(tx, fee = FLOOR_BASE_FEE) {
+    return baseFee(tx, fee) + u64Field(orDefault(tx.tip, "0"), "tip");
+}
+/**
+ * Wire form (node/src/types.rs `Tx::to_bytes`): signing bytes ‖ public key (1,952 B) ‖ signature (3,309 B), or just the
+ * unsigned form for an unsigned ghost tx. Blocks and gossip carry this; `POST /api/tx` takes it as `application/octet-stream`.
+ */
+export function txBytes(tx) {
+    const sb = signingBytes(tx);
+    if (isUnsignedAction(tx.action))
+        return sb;
+    const out = new Uint8Array(sb.length + PUBLIC_KEY_LEN + SIGNATURE_LEN);
+    out.set(sb);
+    out.set(hexToBytes(tx.public_key), sb.length);
+    out.set(hexToBytes(tx.signature), sb.length + PUBLIC_KEY_LEN);
+    return out;
+}
+/** A tx's id (node/src/types.rs `Tx::id`): hex BLAKE3 of the signing bytes and the signature. Known before submitting. */
+export function txId(tx) {
+    const sb = signingBytes(tx);
+    const sig = hexToBytes(tx.signature);
+    const buf = new Uint8Array(sb.length + sig.length);
+    buf.set(sb);
+    buf.set(sig, sb.length);
+    return bytesToHex(blake3(buf));
 }
 /** "1.5" → 1500000000n drops. Accepts numbers, decimal strings or bigint drops. */
 export function parseFang(amount) {