@blockula/sdk 0.3.0 → 1.0.0

package/dist/describe.js

@@ -0,0 +1,441 @@
+// What a proposal kind or a multisig action does, in plain English, rendered by the client from
+// the exact content a vote or an approval binds (audit gap-7-6). The node's own `summary` text
+// isn't covered by any digest, so a lying node can rewrite it at will: show these instead.
+//
+// They never throw. Content a client can't read exactly (an unknown type, a number past 2^53 that
+// JSON rounded, a malformed amount or account) is described as such, so a UI can say "don't vote
+// on this" instead of rendering something it guessed.
+import { blake3 } from "@noble/hashes/blake3.js";
+import { bytesToHex, hexToBytes } from "@noble/hashes/utils.js";
+import { bech32m } from "@scure/base";
+import { DROPS_PER_FANG, PUBLIC_KEY_LEN, interfaceHash, isProgramAction, proposalDigest, wasmHash } from "./tx.js";
+const obj = (v) => (v && typeof v === "object" && !Array.isArray(v) ? v : {});
+/** Whether `s` is a canonical address (any known prefix). Kept local so this module has no import cycle. */
+function address(s) {
+    if (typeof s !== "string" || s !== s.toLowerCase())
+        return false;
+    try {
+        const { prefix, words } = bech32m.decode(s);
+        return (prefix === "boo" || prefix === "tboo") && bech32m.fromWords(words).length === 32;
+    }
+    catch {
+        return false;
+    }
+}
+/** Groups a string of digits in thousands: 10000000 → 10,000,000. */
+const grouped = (digits) => digits.replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+/** A JSON number the client can read exactly, or a decimal string, as a bigint; `undefined` otherwise. */
+function whole(v) {
+    if (typeof v === "bigint")
+        return v >= 0n ? v : undefined;
+    if (typeof v === "number")
+        return Number.isSafeInteger(v) && v >= 0 ? BigInt(v) : undefined;
+    if (typeof v === "string" && /^\d{1,20}$/.test(v) && BigInt(v) < 1n << 64n)
+        return BigInt(v);
+    return undefined;
+}
+/** Why a number can't be shown exactly. */
+const unreadable = (v) => typeof v === "number" && Number.isFinite(v) && Number.isInteger(v) && v > Number.MAX_SAFE_INTEGER
+    ? "a number too large for this client to read exactly (it may have been rounded)"
+    : "an unreadable number";
+/** An amount of drops, spelled out in FANG with every digit: "10,000,000 FANG", "0.5 FANG". */
+export function fangText(drops) {
+    const d = whole(drops);
+    if (d === undefined)
+        return typeof drops === "string" || typeof drops === "number" ? `${unreadable(drops)} of FANG` : "an unreadable amount of FANG";
+    const frac = (d % DROPS_PER_FANG).toString().padStart(9, "0").replace(/0+$/, "");
+    return `${grouped((d / DROPS_PER_FANG).toString())}${frac ? "." + frac : ""} FANG`;
+}
+/** A whole number (ids, heights, counts), or what's wrong with it. */
+function n(v) {
+    const d = whole(v);
+    return d === undefined ? unreadable(v) : d.toString();
+}
+/** milli-Soul as Soul ("2.5 Soul"). */
+function soul(v) {
+    const d = whole(v);
+    if (d === undefined)
+        return `${unreadable(v)} of Soul`;
+    const frac = (d % 1000n).toString().padStart(3, "0").replace(/0+$/, "");
+    return `${grouped((d / 1000n).toString())}${frac ? "." + frac : ""} Soul`;
+}
+const NAME = /^[a-z0-9]([a-z0-9-]{1,30}[a-z0-9])$/;
+/**
+ * An account field: an address in full (check it), or a `.boo` name, which the chain resolves to
+ * its owner when the action runs.
+ */
+function account(v) {
+    if (address(v))
+        return v;
+    if (typeof v === "string") {
+        // Exactly as the chain reads it (node/src/types.rs `normalize_name`): ASCII, any case, no spaces.
+        const bare = v.toLowerCase().replace(/\.boo$/, "");
+        if (NAME.test(bare))
+            return `${bare}.boo (a name, not an address: the chain resolves it to whoever owns it when this runs)`;
+    }
+    return "an unreadable account";
+}
+/** A `.boo` name field (registered, renewed, offered, released). */
+function nameField(v) {
+    if (typeof v !== "string")
+        return "an unreadable name";
+    const bare = v.toLowerCase().replace(/\.boo$/, "");
+    return NAME.test(bare) ? `${bare}.boo` : "an unreadable name";
+}
+/** A plain token (parameter keys, feature names, repos, handles), or nothing it can show safely. */
+function token(v, re, what) {
+    return typeof v === "string" && re.test(v) ? v : `an unreadable ${what}`;
+}
+/** Hex of an exact length, shortened to its ends. */
+function hex(v, bytes, what) {
+    return typeof v === "string" && new RegExp(`^[0-9a-f]{${bytes * 2}}$`).test(v) ? `${v.slice(0, 12)}…${v.slice(-8)}` : `an unreadable ${what}`;
+}
+/** Text a stranger wrote, quoted (one line, at most 200 characters), or left out. */
+function quoted(v, label, opts) {
+    if (opts.freeText === false || typeof v !== "string" || !v.trim())
+        return "";
+    // One line, nothing invisible, and no curly quotes of its own, so it can't close the quote early.
+    const t = [...v.replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]+/gu, " ").replace(/[“”]/g, '"').replace(/ {2,}/g, " ").trim()];
+    return ` (${label}, as written: “${t.length > 200 ? t.slice(0, 200).join("") + "…" : t.join("")}”)`;
+}
+/** A network address field (host:port or a URL) as written, quoted on one line, or an unreadable one. */
+function netAddr(v) {
+    if (typeof v !== "string" || v.length > 256)
+        return "an unreadable address";
+    const t = [...v.replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}\s]+/gu, " ").replace(/[“”]/g, '"').trim()];
+    return `“${t.length > 120 ? t.slice(0, 120).join("") + "…" : t.join("")}”`;
+}
+/** A consensus key (hex ML-DSA-65 public key) by its key id, shortened like the other key ids. */
+function consensusKey(v) {
+    if (typeof v !== "string" || !new RegExp(`^[0-9a-f]{${PUBLIC_KEY_LEN * 2}}$`).test(v))
+        return "an unreadable consensus key";
+    return `consensus key ${hex(bytesToHex(blake3(hexToBytes(v))), 32, "key id")}`;
+}
+// ---- Program actions (tags 62–64 and 69, docs/PROGRAMS-V0.md §2), described from their structure
+// only, as node/src/programs/describe.rs does: programs and code by address and hash, the FANG
+// that goes in, what the program may become. A method's name, an interface's identifiers and a
+// call's input are the deployer's or the caller's words, and these never quote them (PRG 9.7). ----
+/** An address a program action names (a program, an authority): in full, or unreadable. Never a name: programs are named by address. */
+function addressOnly(v, what) {
+    return address(v) ? v : `an unreadable ${what}`;
+}
+/** Uploaded bytes (lowercase hex, as `upload_code` carries them) by the hash a create names them with, and their size. */
+function blob(v, hash, what) {
+    if (typeof v !== "string" || !/^(?:[0-9a-f]{2})*$/.test(v))
+        return `an unreadable ${what}`;
+    return `${what} ${hex(hash(v), 32, "hash")} (${grouped(String(v.length / 2))} bytes)`;
+}
+/** A binding's digest that admits any version of its program (node/vm `exec::ANY_VERSION`). */
+const ANY_VERSION = "0".repeat(64);
+/** The other programs a program action's code may reach (its bindings), or nothing when there are none. */
+function bindings(v) {
+    if (!Array.isArray(v))
+        return "; its code may also reach an unreadable list of programs";
+    if (v.length === 0)
+        return "";
+    const each = v.map((b) => {
+        const x = obj(b);
+        const version = x.version_digest === ANY_VERSION ? " (any version)" : typeof x.version_digest === "string" && /^[0-9a-f]{64}$/.test(x.version_digest) ? "" : " (an unreadable version)";
+        return `${addressOnly(x.program, "program")}${version}`;
+    });
+    return `; its code may also reach ${each.join(", ")}`;
+}
+/**
+ * What a create's authority may later do to the program, once program upgrades exist (inert in
+ * v0): the sentence's subject ("an immutable program" or "a program") and what follows the code.
+ */
+function upgrades(a) {
+    if (a.authority === undefined || a.authority === null) {
+        // The one encoding of an immutable program; the chain refuses any other.
+        if (whole(a.upgrade_delay_blocks) === 0n && a.policy === "open")
+            return ["an immutable program", ""];
+        return ["a program", ", with an unreadable upgrade setting (no authority, but an upgrade delay or policy)"];
+    }
+    const policy = a.policy === "open" ? "any code" : a.policy === "additive" ? "code that keeps every method" : "an unreadable policy";
+    return ["a program", `, upgradable by ${addressOnly(a.authority, "account")} to ${policy} with ${n(a.upgrade_delay_blocks)} blocks' notice once program upgrades exist`];
+}
+/** A create's initializer (the interface's `Init` method, never named here) and the FANG it's sent, or nothing when there's none. */
+function initializer(v) {
+    if (v === undefined || v === null)
+        return "";
+    if (typeof v !== "object" || Array.isArray(v))
+        return ", running an unreadable initializer";
+    const value = obj(v).value;
+    return whole(value) === 0n ? ", running its initializer" : `, running its initializer with ${fangText(value)} attached`;
+}
+/** The sum of the calls' values (drops), or `undefined` if one can't be read exactly. */
+function callValue(calls) {
+    let sum = 0n;
+    for (const c of calls) {
+        const v = whole(c.value);
+        if (v === undefined)
+            return undefined;
+        sum += v;
+    }
+    return sum;
+}
+/** The storage deposits a program action may bond, at most (`storage_limit`, and what for), or nothing when it's 0. */
+function storage(v, what = "") {
+    return whole(v) === 0n ? "" : `, bonding at most ${fangText(v)} in storage deposits${what}`;
+}
+/**
+ * What a `vote` action backs, given the node's read of the proposal it names (`opts.proposal`):
+ * `ok` only when that proposal's content hashes to the digest the vote binds (no node can make
+ * other content do that), and the text to append to the vote's description.
+ */
+function voteTarget(a, opts) {
+    const id = n(a.proposal_id);
+    if (opts.proposal === undefined)
+        return { ok: false, text: `: read proposal #${id} and check its digest before approving` };
+    const p = obj(opts.proposal);
+    let digest = null;
+    try {
+        digest = p.kind && typeof p.kind === "object" ? proposalDigest(p.kind, String(p.title ?? ""), typeof p.url === "string" ? p.url : "") : null;
+    }
+    catch {
+        digest = null;
+    }
+    if (digest === null)
+        return { ok: false, text: `; this client can't read the node's proposal #${id} exactly: don't approve it` };
+    if (digest !== a.proposal_digest)
+        return { ok: false, text: `; but that's NOT what the node shows as proposal #${id} (${describeKind(p.kind, { freeText: false })}, digest ${digest}): the node is showing another proposal, or the vote was made for content #${id} doesn't have. Don't approve it` };
+    return { ok: true, text: `: proposal #${id} (its content has exactly that digest), which does this: ${describeKind(p.kind, opts)}${quoted(p.title, "title", opts)}` };
+}
+const REPO = /^[A-Za-z0-9-]{1,39}\/[A-Za-z0-9._-]{1,100}$/;
+const HANDLE = /^[A-Za-z0-9-]{1,39}$/;
+const KEY = /^[a-z0-9_]{1,64}$/;
+const FEATURE = /^[a-z0-9_-]{1,64}$/;
+/**
+ * What a governance proposal's `kind` does, in plain English, from the kind itself (as stored on
+ * chain: accounts are addresses there). Every amount is spelled out in FANG and every recipient
+ * in full. Show this to a voter, not the node's `summary`: `proposalDigest(kind, title, url)` is
+ * what the vote binds, and this is rendered from the same `kind`.
+ */
+export function describeKind(kind, opts = {}) {
+    const k = obj(kind);
+    switch (k.type) {
+        case "param_change":
+            return `Set the chain parameter ${token(k.key, KEY, "parameter")} to ${n(k.value)} (in that parameter's own units: drops, blocks, basis points…)`;
+        case "treasury_spend":
+            return `Pay ${fangText(k.amount)} from the treasury to ${account(k.to)}`;
+        case "distribution":
+            return `Distribute ${fangText(k.total)} from the community account as distribution #${n(k.distribution_id)}, to the accounts in the Merkle tree with root ${hex(k.merkle_root, 32, "root")} (check it against the published tree), claimable until block #${n(k.claim_until)}`;
+        case "set_repo":
+            return whole(k.weight) === 0n ? `Remove the repo ${token(k.repo, REPO, "repo")} from the contribution pool` : `Put the repo ${token(k.repo, REPO, "repo")} in the contribution pool with weight ${n(k.weight)}`;
+        case "grant_soul":
+            return `Grant ${soul(k.amount)} to ${account(k.to)}${quoted(k.reason, "reason", opts)}`;
+        case "flag_sybil":
+            return `Flag ${account(k.account)} as a sybil (its voucher is slashed, its unvested rewards clawed back)${quoted(k.reason, "reason", opts)}`;
+        case "unflag_sybil":
+            return `Lift the sybil flag on ${account(k.account)} (nothing the flag took comes back)${quoted(k.reason, "reason", opts)}`;
+        case "reject_claim":
+            return `Reject contribution claim #${n(k.claim_id)}${quoted(k.reason, "reason", opts)}`;
+        case "clawback":
+            return `Claw back the unvested contribution rewards of ${account(k.account)}${quoted(k.reason, "reason", opts)}`;
+        case "unlink_github":
+            return `Unlink the GitHub handle @${token(k.handle, HANDLE, "handle")} and hold it for the proposer to link for one voting period`;
+        case "refund_hunt":
+            return `Refund every funder of hunt #${n(k.hunt_id)} what they put in`;
+        case "schedule_upgrade":
+            return `Switch the chain to protocol version ${n(k.version)} at block #${n(k.activation_height)} (nodes that can't run it stop there)`;
+        case "cancel_upgrade":
+            // The same sentence as the CLI's describe_kind and the node's static text (audit
+            // review-r3-clients-1): a cancellation also supersedes every upgrade proposal still open.
+            return `Cancel the upgrade to protocol v${n(k.version)} at block ${n(k.activation_height)} and any upgrade scheduled after it; upgrade proposals still open when it runs are superseded and can't take effect`;
+        case "activate_feature":
+            return `Turn on the feature ${token(k.feature, FEATURE, "feature")}`;
+        case "deactivate_feature":
+            return `Turn off the feature ${token(k.feature, FEATURE, "feature")}`;
+        case "text":
+            return "Nothing on chain: a text proposal (a signal; read its title and link)";
+        default:
+            return `Something this client can't read (a proposal of type ${typeof k.type === "string" ? token(k.type, /^[a-z_]{1,40}$/, "type") : "unknown"}): don't vote on it from here`;
+    }
+}
+/** A key role (`add_key`). */
+function role(r) {
+    const x = obj(r);
+    if (x.type === "owner")
+        return "an owner key (full control of the account)";
+    if (x.type === "session")
+        return `a session key that may send up to ${fangText(x.limit)} (fees included) every ${n(x.period_blocks)} blocks, until block #${n(x.expires_at)}, and nothing else`;
+    return "an unreadable role";
+}
+/**
+ * What a transaction action does (a multisig's pending action, before an owner approves it), in
+ * plain English, from the action itself. Show this, not the node's summary:
+ * `actionDigest(action)` is what the approval binds, and this is rendered from the same action.
+ */
+export function describeAction(action, opts = {}) {
+    const a = obj(action);
+    switch (a.type) {
+        case "transfer":
+            return `Send ${fangText(a.amount)} to ${account(a.to)}`;
+        case "register_name":
+            return `Register the name ${nameField(a.name)}`;
+        case "add_key":
+            return `Add key ${hex(a.key_id, 32, "key id")} to the account as ${role(a.role)}${quoted(a.label, "label", opts)}`;
+        case "remove_key":
+            return `Remove key ${hex(a.key_id, 32, "key id")} from the account`;
+        case "register_validator":
+            // The consensus key decides who signs for (and can be slashed with) the bonded pool: named
+            // by its key id, the 32 bytes the validator's address carries (review-r3-clients-5).
+            return `Register a validator with ${consensusKey(a.consensus_key)} (it signs for the validator; the validator's address carries the same key id), p2p address ${netAddr(a.p2p_addr)}, HTTP address ${netAddr(a.http_addr)}, bonding ${fangText(a.bond)} from the account`;
+        case "approve_validator":
+            return `Approve validator ${account(a.validator)} (admin chains only)`;
+        case "remove_validator":
+            return `Remove validator ${account(a.validator)} (admin chains only)`;
+        case "unbond":
+            return `Reclaim the bond of removed validator ${account(a.validator)}`;
+        case "link_github":
+            return `Link the GitHub handle @${token(a.handle, HANDLE, "handle")} to the account`;
+        case "unlink_github":
+            return `Unlink the GitHub handle @${token(a.handle, HANDLE, "handle")}`;
+        case "create_hunt":
+            return `Escrow ${fangText(a.amount)} as a bounty on ${token(a.repo, REPO, "repo")} issue #${n(a.issue)}, until block #${n(a.expires_at)}${quoted(a.title, "title", opts)}`;
+        case "fund_hunt":
+            return `Add ${fangText(a.amount)} to hunt #${n(a.hunt_id)}`;
+        case "award_hunt":
+            return `Pay hunt #${n(a.hunt_id)}'s bounty to ${account(a.to)} for PR #${n(a.pr)}`;
+        case "cancel_hunt":
+            return `Cancel hunt #${n(a.hunt_id)} and refund its funders`;
+        case "register_familiar":
+            return `Register key ${hex(a.key_id, 32, "key id")} as a Familiar${quoted(a.label, "label", opts)}`;
+        case "set_repo":
+            return `Set the repo ${token(a.repo, REPO, "repo")}'s weight in the contribution pool to ${n(a.weight)} (admin chains only)`;
+        case "grant_soul":
+            return `Grant ${soul(a.amount)} to ${account(a.to)} (admin chains only)${quoted(a.reason, "reason", opts)}`;
+        case "vouch":
+            return `Stake 10 FANG vouching for ${account(a.account)}`;
+        case "unvouch":
+            return `Withdraw the vouch for ${account(a.account)}`;
+        case "flag_sybil":
+            return `Flag ${account(a.account)} as a sybil (admin chains only)${quoted(a.reason, "reason", opts)}`;
+        case "submit_claim":
+            return `Claim PR ${token(a.repo, REPO, "repo")}#${n(a.pr)} for the contribution pool`;
+        case "attest_claim":
+            return `Attest contribution claim #${n(a.claim_id)} as ${a.ok === true ? "merged" : "not merged"}`;
+        case "reject_claim":
+            return `Reject contribution claim #${n(a.claim_id)} (admin chains only)${quoted(a.reason, "reason", opts)}`;
+        case "join_jury":
+            return `Join the Séance juror pool, bonding ${fangText(a.bond)}`;
+        case "leave_jury":
+            return "Leave the Séance juror pool";
+        case "commit_votes":
+            return `Seal a judgment in Séance #${n(a.seance_id)}`;
+        case "reveal_votes":
+            return `Reveal a judgment in Séance #${n(a.seance_id)}`;
+        case "fund_pool":
+            return `Add ${fangText(a.amount)} to the contribution pool`;
+        case "withdraw_vested":
+            return "Withdraw the contribution rewards that have vested";
+        case "clawback":
+            return `Claw back the unvested rewards of ${account(a.account)} (admin chains only)${quoted(a.reason, "reason", opts)}`;
+        case "delegate":
+            return `Stake ${fangText(a.amount)} with validator ${account(a.validator)}`;
+        case "undelegate": {
+            // Amount mode (audit gap-7-5): `shares` 0 and an amount the chain converts at its own price.
+            const amount = whole(a.amount);
+            if (amount !== undefined && amount > 0n)
+                return `Start unbonding ${fangText(a.amount)} of stake from validator ${account(a.validator)} (the chain converts it to pool shares at its own price when this runs)`;
+            if (a.amount !== undefined && amount === undefined)
+                return `Start unbonding ${fangText(a.amount)} of stake from validator ${account(a.validator)}`;
+            return `Start unbonding ${n(a.shares)} pool shares from validator ${account(a.validator)}`;
+        }
+        case "redelegate":
+            return `Move ${n(a.shares)} pool shares from validator ${account(a.from_validator)} to validator ${account(a.to_validator)}`;
+        case "withdraw_unbonded":
+            return "Withdraw the stake that has finished unbonding";
+        case "update_validator":
+            // Each address separately: on chain an empty one means "keep it" (review-r3-clients-5).
+            return `Set the account's validator commission to ${n(a.commission_bps)} basis points${a.p2p_addr === "" ? "" : `, its p2p address to ${netAddr(a.p2p_addr)}`}${a.http_addr === "" ? "" : `, its HTTP address to ${netAddr(a.http_addr)}`}`;
+        case "unjail":
+            return `Unjail validator ${account(a.validator)}`;
+        case "report_equivocation":
+            return "Report a validator's equivocation (two conflicting signed votes)";
+        case "beacon_commit":
+            return `Commit to a randomness-beacon secret for epoch ${n(a.epoch)}`;
+        case "beacon_reveal":
+            return `Reveal the randomness-beacon secret for epoch ${n(a.epoch)}`;
+        case "propose":
+            return `Propose, bonding ${fangText(a.deposit)}: ${describeKind(a.kind, opts)}${quoted(a.title, "title", opts)}`;
+        case "vote":
+            // What #id is comes from the digest the vote binds, never from the id (audit gap-7-6).
+            return `Vote ${a.aye === true ? "aye" : a.aye === false ? "nay" : "(unreadable side)"} on proposal #${n(a.proposal_id)} with ${fangText(a.amount)} at conviction ${n(a.conviction)}, binding the proposal whose content has digest ${typeof a.proposal_digest === "string" && /^[0-9a-f]{64}$/.test(a.proposal_digest) ? a.proposal_digest : "(unreadable)"}${voteTarget(a, opts).text}`;
+        case "unlock":
+            return "Release the account's expired vote locks";
+        case "multisig_create": {
+            const owners = Array.isArray(a.owners) ? a.owners : [];
+            return `Make the account a ${n(a.threshold)}-of-${owners.length} multisig of the owner keys ${owners.map((o) => hex(o, 32, "key id")).join(", ") || "(none)"}`;
+        }
+        case "multisig_propose":
+            return `Propose a multisig action: ${describeAction(a.action, opts)}`;
+        case "multisig_approve":
+            return `Approve multisig action #${n(a.id)}`;
+        case "renew_name":
+            return `Renew the name ${nameField(a.name)} for ${n(a.years)} year(s)`;
+        case "transfer_name":
+            return `Offer the name ${nameField(a.name)} to ${account(a.to)} (theirs once they accept it; offered to the account itself, it accepts or withdraws an offer)`;
+        case "release_name":
+            return `Release the name ${nameField(a.name)}: anyone can register it afterwards`;
+        case "claim_distribution":
+            return `Claim ${fangText(a.amount)} from community distribution #${n(a.distribution_id)}`;
+        case "attest_revert":
+            return `Attest that contribution claim #${n(a.claim_id)}'s PR was reverted`;
+        case "shield":
+            return `Move ${fangText(a.amount)} into the Ghost Mode pool`;
+        case "unshield":
+            return `Pay ${fangText(a.amount)} out of the Ghost Mode pool to ${account(a.to)}`;
+        case "private_transfer":
+            return "A private Ghost Mode transfer";
+        case "set_ghost_address":
+            return "Publish the account's Ghost Mode address";
+        case "ghost_pause":
+            return "Vote to pause Ghost Mode (validators)";
+        case "validator_ready":
+            return `Signal that the account's candidate validator node is running, to join a set of one or two at the end of epoch ${n(a.epoch)} (validators)`;
+        case "admit_validator":
+            return `Admit candidate validator ${account(a.validator)} into a set of one or two at the end of epoch ${n(a.epoch)} (validators)`;
+        case "upload_code":
+            return `Upload ${blob(a.wasm, wasmHash, "program code")} with ${blob(a.interface, interfaceHash, "interface")}${storage(a.storage_limit, " for whichever isn't stored yet")}`;
+        case "create_program": {
+            const [program, upgradable] = upgrades(a);
+            const transfers = a.accepts_transfers === true ? ", accepting transfers" : a.accepts_transfers === false ? "" : ", with an unreadable transfer setting";
+            return `Create ${program} from code ${hex(a.wasm_hash, 32, "code hash")} and interface ${hex(a.interface_hash, 32, "interface hash")}${upgradable}${transfers}${initializer(a.init)}${storage(a.storage_limit)}${bindings(a.bindings)}`;
+        }
+        case "call_program": {
+            if (!Array.isArray(a.calls) || a.calls.length === 0)
+                return `Call programs: an unreadable list of calls${bindings(a.bindings)}`;
+            const calls = a.calls.map(obj);
+            // The programs called, each once, in the order the calls first name them.
+            const programs = [...new Set(calls.map((c) => addressOnly(c.program, "program")))];
+            const what = calls.length === 1 ? `Call program ${programs[0]}`
+                : programs.length === 1 ? `Make ${calls.length} calls to program ${programs[0]} (all or nothing)`
+                    : `Call ${programs.length} programs (${programs.join(", ")}) in ${calls.length} calls (all or nothing)`;
+            const value = callValue(calls);
+            const attached = value === undefined ? " with an unreadable amount of FANG attached" : value > 0n ? ` with ${fangText(value)} attached` : "";
+            return `${what}${attached}${storage(a.storage_limit)}${bindings(a.bindings)}`;
+        }
+        case "programs_pause":
+            return "Vote to pause programs (validators: they pause once f + 1 of the epoch's validators have)";
+        default:
+            return `Something this client can't read (an action of type ${typeof a.type === "string" ? token(a.type, /^[a-z_]{1,40}$/, "type") : "unknown"}): don't approve it from here`;
+    }
+}
+/**
+ * `describeAction`, and whether the description is complete enough to approve on (a multisig
+ * co-signer's check). For a `vote`, pass the node's read of the proposal it names as
+ * `opts.proposal` (`client.proposal(action.proposal_id)`): it's described, and approvable, only
+ * when its content hashes to the digest the vote binds (audit gap-7-6).
+ */
+export function reviewAction(action, opts = {}) {
+    const does = describeAction(action, opts);
+    const a = obj(action);
+    // Strangers' quoted text is left out of the check: it can say "unreadable" too.
+    const ours = does.replace(/ \((?:reason|label|title), as written: “[^”]*”\)/g, "");
+    const unreadable = /\b(unreadable|can't read|too large for this client)\b/.test(ours);
+    const vote = a.type !== "vote" || voteTarget(a, opts).ok;
+    // A multisig holds no program action: the node never decodes one inside a multisig proposal.
+    const multisigCanHold = !isProgramAction(a);
+    return { does, readable: !unreadable && vote && multisigCanHold };
+}

package/dist/distribution.d.ts

@@ -0,0 +1,26 @@
+/** Most hashes a claim's proof may carry (the node's `MAX_PROOF`). */
+export declare const MAX_DISTRIBUTION_PROOF = 64;
+/**
+ * The leaf of `address`'s `amount` (drops) in distribution `id`:
+ * BLAKE3("BLOCKULA_DISTRIBUTION_LEAF_V1" ‖ id u64 LE ‖ len(address) u16 LE ‖ address ‖ amount u64 LE).
+ * `address` is the bech32m string exactly as the claimant's tx spells it.
+ */
+export declare function distributionLeaf(id: bigint | number, address: string, amount: bigint): Uint8Array;
+/** Sorted-pair inner node: BLAKE3("BLOCKULA_DISTRIBUTION_NODE_V1" ‖ min(a, b) ‖ max(a, b)). */
+export declare function distributionNode(a: Uint8Array, b: Uint8Array): Uint8Array;
+/**
+ * Root and per-entry proofs (hex sibling hashes from the leaf up), entries in input order, in
+ * the reference shape: leaves sorted, paired left to right level by level, an odd last node
+ * carried up unchanged. Addresses must be distinct and amounts non-zero.
+ */
+export declare function buildDistribution(id: bigint | number, entries: {
+    address: string;
+    amount: bigint;
+}[]): {
+    root: string;
+    proofs: string[][];
+};
+/** The root a leaf and its proof (hex sibling hashes from the leaf up) lead to (hex). */
+export declare function distributionRoot(id: bigint | number, address: string, amount: bigint, proof: string[]): string;
+/** Whether `proof` leads from `address`'s leaf for `amount` (drops) in distribution `id` to `root` (hex). */
+export declare function verifyDistributionProof(root: string, id: bigint | number, address: string, amount: bigint, proof: string[]): boolean;

package/dist/distribution.js

@@ -0,0 +1,110 @@
+// Community distribution Merkle trees (docs/GOVERNANCE.md "Merkle tree format"): a port of
+// node/src/governance.rs `distribution_leaf`, `merkle_parent`, `build_distribution` and
+// `root_from_proof`. Claims are checked on chain against the proposal's root, so these must match
+// the node byte for byte; test/unit.ts checks the shared vectors (distribution 7).
+import { blake3 } from "@noble/hashes/blake3.js";
+import { bytesToHex, hexToBytes } from "@noble/hashes/utils.js";
+const LEAF_DOMAIN = new TextEncoder().encode("BLOCKULA_DISTRIBUTION_LEAF_V1");
+const NODE_DOMAIN = new TextEncoder().encode("BLOCKULA_DISTRIBUTION_NODE_V1");
+/** Most hashes a claim's proof may carry (the node's `MAX_PROOF`). */
+export const MAX_DISTRIBUTION_PROOF = 64;
+const U64_MAX = (1n << 64n) - 1n;
+function u64le(v, what) {
+    const n = BigInt(v);
+    if (n < 0n || n > U64_MAX)
+        throw new Error(`${what} must fit in a u64`);
+    const out = new Uint8Array(8);
+    new DataView(out.buffer).setBigUint64(0, n, true);
+    return out;
+}
+function concat(...parts) {
+    const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let at = 0;
+    for (const p of parts) {
+        out.set(p, at);
+        at += p.length;
+    }
+    return out;
+}
+function compare(a, b) {
+    for (let i = 0; i < Math.min(a.length, b.length); i++)
+        if (a[i] !== b[i])
+            return a[i] - b[i];
+    return a.length - b.length;
+}
+/**
+ * The leaf of `address`'s `amount` (drops) in distribution `id`:
+ * BLAKE3("BLOCKULA_DISTRIBUTION_LEAF_V1" ‖ id u64 LE ‖ len(address) u16 LE ‖ address ‖ amount u64 LE).
+ * `address` is the bech32m string exactly as the claimant's tx spells it.
+ */
+export function distributionLeaf(id, address, amount) {
+    const addr = new TextEncoder().encode(address);
+    if (addr.length > 0xffff)
+        throw new Error("address too long");
+    const len = new Uint8Array([addr.length & 0xff, addr.length >> 8]);
+    return blake3(concat(LEAF_DOMAIN, u64le(id, "distribution id"), len, addr, u64le(amount, "amount")));
+}
+/** Sorted-pair inner node: BLAKE3("BLOCKULA_DISTRIBUTION_NODE_V1" ‖ min(a, b) ‖ max(a, b)). */
+export function distributionNode(a, b) {
+    const [lo, hi] = compare(a, b) <= 0 ? [a, b] : [b, a];
+    return blake3(concat(NODE_DOMAIN, lo, hi));
+}
+/**
+ * Root and per-entry proofs (hex sibling hashes from the leaf up), entries in input order, in
+ * the reference shape: leaves sorted, paired left to right level by level, an odd last node
+ * carried up unchanged. Addresses must be distinct and amounts non-zero.
+ */
+export function buildDistribution(id, entries) {
+    if (entries.length === 0)
+        throw new Error("a distribution needs at least one entry");
+    const seen = new Set();
+    for (const e of entries) {
+        if (seen.has(e.address))
+            throw new Error(`${e.address} is listed twice`);
+        seen.add(e.address);
+        if (e.amount <= 0n)
+            throw new Error(`${e.address} gets 0`);
+    }
+    const leaves = entries.map((e, i) => ({ hash: distributionLeaf(id, e.address, e.amount), i }));
+    // Like the node's sort of (hash, index) pairs: by hash, then input order.
+    leaves.sort((x, y) => compare(x.hash, y.hash) || x.i - y.i);
+    let level = leaves.map((l) => l.hash);
+    const pos = new Array(entries.length);
+    leaves.forEach((l, p) => (pos[l.i] = p));
+    const proofs = entries.map(() => []);
+    while (level.length > 1) {
+        for (let i = 0; i < pos.length; i++) {
+            const sibling = pos[i] ^ 1;
+            if (sibling < level.length)
+                proofs[i].push(level[sibling]);
+            pos[i] = Math.floor(pos[i] / 2);
+        }
+        const next = [];
+        for (let k = 0; k < level.length; k += 2)
+            next.push(k + 1 < level.length ? distributionNode(level[k], level[k + 1]) : level[k]);
+        level = next;
+    }
+    return { root: bytesToHex(level[0]), proofs: proofs.map((p) => p.map(bytesToHex)) };
+}
+/** The root a leaf and its proof (hex sibling hashes from the leaf up) lead to (hex). */
+export function distributionRoot(id, address, amount, proof) {
+    if (proof.length > MAX_DISTRIBUTION_PROOF)
+        throw new Error(`a proof has at most ${MAX_DISTRIBUTION_PROOF} hashes`);
+    let h = distributionLeaf(id, address, amount);
+    for (const s of proof) {
+        const sibling = hexToBytes(s);
+        if (sibling.length !== 32)
+            throw new Error("proof hashes are 32 bytes of hex");
+        h = distributionNode(h, sibling);
+    }
+    return bytesToHex(h);
+}
+/** Whether `proof` leads from `address`'s leaf for `amount` (drops) in distribution `id` to `root` (hex). */
+export function verifyDistributionProof(root, id, address, amount, proof) {
+    try {
+        return distributionRoot(id, address, amount, proof) === root.toLowerCase();
+    }
+    catch {
+        return false;
+    }
+}