@blockula/sdk 0.3.0 → 0.5.1

package/dist/tx.js

@@ -1,32 +1,159 @@
 // 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";
 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);
 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);
+    }
     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";
+}
+/**
+ * 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 +167,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 +183,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 +210,485 @@ 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");
+            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;
+        default:
+            throw new Error(`unknown action type ${a.type}`);
+    }
+}
+/** 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);
     }
-    w.str(tx.memo);
+    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}`);
+    }
+}
+/**
+ * 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) }));
+}
+/**
+ * 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 +701,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) {