@blockula/sdk 0.3.0 → 0.5.1

package/README.md

@@ -7,17 +7,25 @@ npm install @blockula/sdk
 ```
 
 ```ts
-import { Client, Wallet } from "@blockula/sdk";
+import { Client, Wallet, encodeKeyGrant } from "@blockula/sdk";
 
 const wallet = Wallet.generate(new Client("http://localhost:7070"));
 await wallet.faucet();                        // test chains: 100 FANG
 await wallet.registerName("vlad");            // vlad.boo
 await wallet.send("alice.boo", "1.5", { memo: "trick or treat" });
 
-// Let an agent spend up to 10 FANG/day from this account (enforced on-chain)
-await wallet.addSessionKey(agentKeyId, "claude", { limit: "10", periodBlocks: 86_400, expiresInBlocks: 30 * 86_400 });
+// Let an agent spend up to 10 FANG/day from this account (enforced on-chain). The agent's key
+// consents to joining this account first: its grant code (the MCP's use_account answers with one).
+const agentGrantCode = encodeKeyGrant(await agent.keyGrant(wallet.account));
+await wallet.addSessionKey(agentGrantCode, "claude", { limit: "10", periodBlocks: 86_400, expiresInBlocks: 30 * 86_400 });
 ```
 
+Adding a key needs the key's consent (audit gap-7-2): `AddKey` carries the key's public key and its signature over the chain, the account and its key id, so nobody can put your key on their account (and pad `client.keyAccounts(keyId)`, which pages with `{ after }`). The key's holder makes it with `keyGrant(account)`; `encodeKeyGrant`/`decodeKeyGrant` turn it into a pasteable `bkgrant1.…` code, `verifyKeyGrant` checks one, and `addOwnerKey`/`addSessionKey` take either and refuse a grant made for another account or chain.
+
+Votes, multisig approvals and sealed Séance judgments bind what they approve (audit gap-7-6): `vote(id, aye, amount, conviction, { proposal })` signs `proposalDigest(kind, title, url)` of the proposal you showed, `multisigApprove(id, { action })` signs `actionDigest(action)`, and `sealVotes(…, { pairs })` signs `seancePairsDigest` of the pairs and PRs the juror compared (each read from the client when not given). The chain refuses a digest that doesn't match what's stored, so a node that misreports what's being approved makes it fail instead of landing elsewhere.
+
+Show the voter or co-signer what the digest covers, rendered by the client, never the node's `summary` text (no digest covers it, so a node can make it say anything): `describeKind(kind)` and `describeAction(action)` say what a proposal or a multisig action does in plain English, every amount spelled out (`"Pay 10,000,000 FANG from the treasury to boo1…"`) and every recipient in full, and `proposalSummary(raw)` adds `does` (that description) and `digest` (what a vote binds; `null`, with `digest_error`, when the client can't read the proposal exactly, e.g. a number past 2^53: don't vote on it from JS). They never throw on content they can't read; they say so. Pass `{ freeText: false }` to leave reasons and labels out (to show them apart, marked as the proposer's words). If you show a digest and vote later, compare it with the one you sign. A multisig's pending `vote` binds its proposal by digest, not by id: `reviewAction(action, { proposal: await client.proposal(action.proposal_id) })` describes the proposal only when its content has the digest the vote binds, and says otherwise (`readable: false`, as for anything it describes as unreadable): don't offer to approve such an action. `multisigApprove(id, { action, proposal })` checks the same before signing: a vote is approved only if the proposal shown (else one read then) has exactly the content it binds.
+
 In the browser, a passkey unlocks the wallet. There's no seed phrase, and the passkey's (non-quantum-safe) signature is never used on-chain. Its PRF output derives the ML-DSA key:
 
 ```ts
@@ -25,12 +33,104 @@ import { createPasskeyWallet, unlockPasskeyWallet } from "@blockula/sdk/passkey"
 const wallet = await createPasskeyWallet({ username: "vlad" });
 ```
 
+Contribution pool (Proof of Contribution):
+
+```ts
+await wallet.submitClaim("jackdishman/blockula", 34);       // a merged PR by your linked GitHub handle
+const s = await client.seance((await client.contributions()).open_seance.id);   // jurors: your pairs
+const sealed = await juror.sealVotes(s.id, "ab=", [17]);  // a/b/= per pair, spam flags; keep sealed.salt
+await juror.revealVotes(s.id, sealed.votes, sealed.spam, sealed.salt);  // after the sealing phase
+await wallet.withdrawVested();
+```
+
 Amounts are FANG strings (`"1.5"`) or bigint drops (1 FANG = 10⁹ drops). Every transaction result includes a plain-English `summary`.
 
-- `send("alice.boo", …)` resolves the name first and signs the **address**, so whoever you checked is exactly who gets paid.
-- Node errors throw `ApiError` (`.status`: 429 means rate limited). A transaction that fails at execution throws `TxFailedError` from `waitForTx`.
+Fees, tips and expiry (protocol v1):
+
+```ts
+await wallet.send("alice.boo", "1.5", { tip: "0.001", validForBlocks: 120 });
+wallet.tip = 0n;                 // defaults for every tx this wallet builds
+wallet.validForBlocks = 600;
+```
+
+- A transaction is charged its block's base fee (`baseFee(tx, slot)`: priced per byte, burned; it rises while blocks are full and is fixed 17 blocks ahead) plus its `tip` (paid to the block's proposer; blocks take the highest tip per byte first). The wallet sets `fee` to the base fee at `client.fees()`'s `suggested` plus the tip; only the actual charge (`txCharge(tx, slot)`) is debited. On an idle chain the base fee is `minFee(tx)`.
+- A tip is at most `tip_cap_multiple` (20) × the base fee of the block that includes it (`maxTip(tx, slot, multiple)`); `wallet.build` refuses a bigger one, priced at `client.fees()`'s `lowest`. It's paid only from FANG the account could transfer (vesting and vote locks hold it), and a multisig's owner keys and a validator's consensus key acting for its owner can't tip at all.
+- Every transaction carries `valid_until`, the last block it may execute in. The wallet sets it to the current height plus `validForBlocks` (default 600 blocks, at most the chain's `max_tx_validity_blocks`, an hour of blocks). A transaction past `valid_until` can never execute, so it's safe to report it as expired.
+- `txBytes(tx)` is the binary wire form nodes gossip and put in blocks, and `txId(tx)` its id, known before you submit.
+- Every transaction names the chain it's for by `chain_id` and `genesis_hash` (the chain instance, from `/api/status`), so it can't replay on a relaunched chain that reuses the id. `wallet.build` fills both in; to sign offline, put the chain's `genesis_hash` in the `UnsignedTx` you pass to `wallet.sign`.
+
+Addresses are bech32m with the chain's prefix: `boo1…` on mainnet, `tboo1…` on public testnets. `isAddress(s)` accepts any known prefix and `isAddress(s, "tboo")` exactly one; `addressFromPublicKey(pk, prefix)` renders one. A `Client` learns its chain's prefix from `/api/status` (`await client.addressPrefix()`), and wallets using that client sign with it (`wallet.address`, `wallet.account`). Pin it with `new Client(rpc, { prefix: "boo" })` to refuse a node on another network (see "Which chain?" below). Nodes reject addresses of another network's prefix.
+
+- Names in a signature (audit gap-7-1). Where the chain resolves a name itself (`send`, `awardHunt`, `vouch`/`unvouch`, `grantSoul`, `flagSybil`, `clawback`, `transferName`, proposal targets), a client with `witnesses` (below) signs the name's proven owner, and one without signs the **name itself** (`alice.boo`): the chain pays whoever owns it when the tx runs, so a lying node can't point it at another account now. It could still hold the signed tx and release it later in its validity window, which counts from the height that node reported, by when the name may have lapsed and been registered again: pay a name that's about to expire by address. `Wallet.build` refuses a height more than `maxHeadLeadBlocks` (30) ahead of the lowest head the witnesses report (every witness must answer, so one honest witness is enough), or past what a `genesisClock: { createdAtMs, blockTimeMs }` pin allows by this machine's clock (`HeightAheadError`, nothing signed); without either the height is the node's word. `client.recipient(name)` says which (`signed`, `byChain`, and `how` to show before signing); the address it reports for an unproven name is the node's word, for display. Where an address is needed (`delegate`, `undelegate`, `redelegate`, `unjail`, `actAs`, `keyGrant`), a name is resolved (`client.resolution`: `proven` and `how`), and on mainnet nothing is signed with one only a single node vouched for: it throws `UnprovenNameError` (checked against the very status each tx is signed for). Pass the address once its owner has confirmed it, or give the client witnesses.
+- `wallet.address` uses the chain's prefix once the client knows it. Before the first request it shows the `boo` form, so `await client.addressPrefix()` first if you display it on a testnet.
+- Node errors throw `ApiError` (`.status`: 429 means rate limited). A transaction the node reports as failed throws `TxFailedError` from `waitForTx` (`dropped` says whether it ran: see "Timeouts and pending transactions").
 - Pass `rpId` to `createPasskeyWallet`/`unlockPasskeyWallet` to pin wallets to your production domain. Passkeys are bound to that hostname for good.
 
+### Staking, governance and names (protocol v1)
+
+```ts
+import { Client, Wallet, proposal, stakeSummary } from "@blockula/sdk";
+
+await wallet.delegate(validatorAddress, "100");               // stake in a validator's pool
+const stake = stakeSummary(await client.staking(wallet.account), (await client.status()).height);
+await wallet.undelegate(validatorAddress, { amount: "10" });  // the chain converts it to shares; or "all", or a share count
+await wallet.withdrawUnbonded();                              // once the unbonding period is over
+
+await wallet.propose(proposal.paramChange("max_validators", 40), { title: "More validators", url: "https://forum.example/p/1" });
+await wallet.vote(7, true, "10", 2);                          // aye, 10 FANG locked at 2× conviction
+await wallet.unlock();                                        // release vote locks that ended
+
+await wallet.renewName("vlad", 2);                            // names are registered a year at a time
+await wallet.transferName("vlad", "alice.boo");               // an offer: alice.boo accepts with acceptName("vlad")
+await wallet.multisigCreate([phoneKeyId, laptopKeyId, kitKeyId], 2);
+```
+
+- Every tag 30–49 has a helper: `delegate`, `undelegate`, `redelegate`, `withdrawUnbonded`, `updateValidator`, `unjail`, `propose`, `vote`, `unlock`, `multisigCreate` / `multisigPropose` / `multisigApprove`, `renewName`, `transferName` (an offer the recipient takes with `acceptName`; `withdrawNameOffer`), `releaseName`, `claimDistribution`, and the low-level validator ones (`reportEquivocation`, `beaconCommit`, `beaconReveal`, `attestRevert`); tags 60–61 are a set of one or two's `admitValidator` (a member's consensus key admits a candidate) and `validatorReady` (candidate nodes send it). They check their arguments before signing, resolve `.boo` names to the addresses they sign, and wait for the block.
+- `proposal.*` builds every `ProposalKind`: `paramChange`, `treasurySpend`, `distribution`, `setRepo`, `grantSoul`, `flagSybil`, `unflagSybil` (its appeal), `rejectClaim`, `clawback`, `unlinkGithub`, `refundHunt`, `scheduleUpgrade`, `cancelUpgrade`, `activateFeature`, `deactivateFeature`, `text`. `propose` bonds the chain's `proposal_deposit` unless you pass `deposit`.
+- `convictionWeight(amount, conviction)` is a vote's weight: 0.1× with no lock, then 1×–6× for 1, 2, 4, 8, 16 or 32 lock periods (`CONVICTION_PERIODS`).
+- Reads: `client.staking(account)`, `client.proposals()`, `client.proposal(id)`, `client.params()`, `client.fees()`, `client.upgrade()`, `client.distribution(id)`, `client.multisig(account)`. `stakeSummary`, `proposalSummary` and `paramsOf` turn them into stable shapes, tolerating renamed or missing fields.
+
+### Which chain? Pinning and proofs
+
+```ts
+const client = new Client("https://rpc.example", { chainId: "blockula-1", genesisHash: "…", prefix: "boo" });
+```
+
+A pinned client checks every `/api/status` it reads, including the one each signature is made against, and throws `ChainMismatchError` instead of signing for another chain.
+
+A node can still lie about the state of the right chain. Give a client witnesses and the names it resolves for signatures are proven (without them, see "Names in a signature" above) (`new Client(rpc, { …pins, witnesses: [new Client(rpc2, pins), …], requireProvenNames: true })`; `requireProvenNames` refuses any name it can't prove). `Wallet.propose`'s default deposit must be the same on the node and every witness, and at most `maxDeposit` (default `DEFAULT_MAX_PROPOSAL_DEPOSIT`, 1,000 FANG): a node can report any deposit, and all of it burns if the vote misses quorum (audit gap-7-5). Session-key and hunt expiries count from the same status read as `valid_until`, so a node lying about the height can stretch them by at most `max_tx_validity_blocks` (audit gap-7-3).
+
+Proven reads check the node's Merkle proof (`/api/proof`) against its state root, ask independent nodes (`witnesses`) for that block's root, and require the proof to be fresh:
+
+```ts
+const others = [new Client("https://rpc-2.example"), new Client("https://rpc-3.example")];
+const acct = await client.provenAccount("boo1…", { witnesses: others });  // { balance, nonce, keys, height, root, head } or null
+const name = await client.provenName("vlad.boo", { witnesses: others });  // { owner, registered_at, expires_at, active, … } or null
+```
+
+- **Fresh, not just genuine.** Witnesses confirm any root the chain ever had, so a lying node could answer with a real but old record: a name's previous owner, a balance before a spend, a key since removed. The proof's block may be at most `maxLagBlocks` (default 10) behind the newest head the node and its witnesses report, or it throws `StaleProofError`. Without witnesses only the node's own head is compared, which a lying node controls.
+- **Expired names don't resolve.** `provenName` returns `null` once a name's `expires_at` has passed (its grace period included), like `client.resolve`. `{ includeExpired: true }` returns the record with `active: false`; never pay its `owner`.
+
+`verifyProof(root, namespace, key, value, proof)` is the bare check (a port of `node/src/state/tree.rs`, tested against the node's own vectors), and `provenRecord(namespace, key)` works for any record (check its `height` against `head` if you call it with your own options).
+
+### Timeouts and pending transactions
+
+Every request has a timeout (`new Client(rpc, { timeoutMs })`, default 15 s, at most `MAX_TIMEOUT_MS` = 2^31 − 1 ms, since a longer timer fires at once): a node that never answers fails with `RequestTimeoutError` instead of hanging. `submit` (and every helper that sends) tells you what a failure means:
+
+- `ApiError`: the node refused the tx. It wasn't admitted, so nothing was spent.
+- `TxFailedError` with `dropped` false: it executed in a block and failed there (its fee was charged). It can't execute again.
+- `TxFailedError` with `dropped` true: this node dropped it from its mempool without running it (evicted by a higher tip, replaced, not included, or an earlier tx from the account was dropped). Nothing was charged, but another node may still hold it and include it until its `valid_until`: check `client.tx(id)` before sending again, or the payment can go out twice.
+- `TxPendingError`: it was admitted but isn't final yet, and it can still execute until its `valid_until`. Check `client.tx(err.id)` before sending again, or the payment can go out twice.
+- `RequestTimeoutError` or a network error while submitting: unknown, the tx may have arrived. Same advice.
+
+### Encoding
+
+`signingBytes` and `txBytes` encode a tx exactly as the node does (`node/src/types.rs`, checked offline against the node's vectors in `test/tx-vectors.json`). They take integers as the node's JSON parser does, as JSON numbers or strings of digits within the field's width, and refuse anything else (a negative or oversized amount, `"0x10"`, `" 1"`, a fraction) instead of wrapping it into a different tx.
+
+`verifyReleaseSignature(sig, checksumsFile, trustedKeyId)` checks a release's offline ML-DSA-65 signature (docs/OPERATIONS.md "Releases").
+
 The public testnet is `https://blockula-testnet.fly.dev`, and the wallet is https://blockula-wallet.vercel.app.
 
+Tests: `npm run test:vectors` (offline: passkey derivation, state-proof and tx-encoding vectors from the node, every protocol v1 helper against a fake node, pinning, proof freshness, timeouts, release signatures), `npm run test:kat` (ML-DSA known answers), `npm test` (end to end against `blockula dev`).
+
 ⚠️ Early and unaudited: test chains only.

package/dist/describe.d.ts

@@ -0,0 +1,50 @@
+/** Options of `describeKind` / `describeAction`. */
+export interface DescribeOptions {
+    /**
+     * Quote the text a stranger wrote (reasons, labels, titles, memos) inside the description.
+     * Default true. Pass false where it must be shown apart, marked untrusted (an agent's tools do).
+     */
+    freeText?: boolean;
+    /**
+     * For a `vote` action (a multisig's ballot): the node's read of the proposal it names
+     * (`client.proposal(id)`). A vote binds that proposal's content by digest, not by id (audit
+     * gap-7-6), so the proposal is described only if its kind, title and link hash to the digest
+     * the vote binds; otherwise the description says the node's proposal isn't what it backs.
+     * `reviewAction` says whether that makes the action fit to approve.
+     */
+    proposal?: unknown;
+}
+/** An amount of drops, spelled out in FANG with every digit: "10,000,000 FANG", "0.5 FANG". */
+export declare function fangText(drops: unknown): string;
+/**
+ * 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 declare function describeKind(kind: unknown, opts?: DescribeOptions): string;
+/**
+ * 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 declare function describeAction(action: unknown, opts?: DescribeOptions): string;
+/** Whether an approver can act on a description (`reviewAction`). */
+export interface ActionReview {
+    /** `describeAction(action, opts)`. */
+    does: string;
+    /**
+     * Whether this client could read all of it: false for anything it described as unreadable
+     * (an unknown type, a malformed field, a number JSON rounded, a key id the chain couldn't store)
+     * and for a `vote` whose proposal (`opts.proposal`) wasn't given or doesn't hash to the digest
+     * it binds. Don't offer to approve an action that isn't `readable`.
+     */
+    readable: boolean;
+}
+/**
+ * `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 declare function reviewAction(action: unknown, opts?: DescribeOptions): ActionReview;

package/dist/describe.js

@@ -0,0 +1,350 @@
+// 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, proposalDigest } 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")}`;
+}
+/**
+ * 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)`;
+        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;
+    return { does, readable: !unreadable && vote };
+}

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;