@blockula/sdk 0.3.0 → 1.0.0

package/dist/index.js

@@ -1,24 +1,351 @@
 import { ml_dsa65 } from "@noble/post-quantum/ml-dsa.js";
 import { blake3 } from "@noble/hashes/blake3.js";
 import { bytesToHex, hexToBytes, randomBytes, utf8ToBytes } from "@noble/hashes/utils.js";
-import { bech32m } from "@scure/base";
-import { minFee, parseFang, signingBytes } from "./tx.js";
+import { base64urlnopad, bech32m } from "@scure/base";
+import { DEFAULT_TIP_CAP_MULTIPLE, KEY_POP_CONTEXT, PUBLIC_KEY_LEN, SIGNATURE_LEN, actionDigest, baseFee, formatFang, interfaceHash, keyPopMessage, maxTip, parseFang, parseSoul, programAddress, proposalDigest, seanceCommitment, seancePairsDigest, signingBytes, txBytes, txId, versionDigest, wasmHash } from "./tx.js";
+import { NAMESPACES, checkProofResponse, decodeAccount, decodeName, decodeProgram } from "./proof.js";
+import { ANY_PROGRAM_VERSION, MAX_PROGRAM_BINDINGS, MAX_PROGRAM_CALLS, MAX_PROGRAM_CODE_BYTES, MAX_PROGRAM_INTERFACE_BYTES, ProgramAnswerError, ProgramsOffError, defaultFuelLimit, depositWithMargin, plainText, positiveFuel, programAddressArg, programBytesArg, programHashArg, programInputArg, programMethodArg, checkCode, checkFuel, checkInterface, checkParams, checkProgram, checkProgramsStatus, checkReceipt, checkView, outcomeWords, priceFuel, programCost, programRecordDeposit, programUploadDeposit, reserveFuel, uploadFuel } from "./programs.js";
+import { describeKind, reviewAction } from "./describe.js";
+import { NETWORKS, isNetworkName } from "./networks.js";
 export * from "./tx.js";
+export * from "./proof.js";
+export * from "./distribution.js";
+export * from "./release.js";
+export * from "./describe.js";
+export * from "./networks.js";
+export * from "./payments.js";
+export * from "./programs.js";
 export const DEFAULT_RPC = "http://localhost:7070";
-export function addressFromPublicKey(publicKey) {
-    return bech32m.encode("boo", bech32m.toWords(blake3(publicKey)));
+/** Address prefixes: `boo` on mainnet (and dev chains), `tboo` on public testnets. */
+export const KNOWN_PREFIXES = ["boo", "tboo"];
+export const DEFAULT_PREFIX = "boo";
+/** Mainnet's chain id (node/src/chain.rs `MAINNET_CHAIN_ID`). */
+export const MAINNET_CHAIN_ID = "blockula-1";
+/** How long a transaction stays valid by default: 600 blocks (10 minutes at 1 s blocks). */
+export const DEFAULT_VALID_FOR_BLOCKS = 600;
+/** The address of a public key: bech32m(prefix, BLAKE3(public key)). */
+export function addressFromPublicKey(publicKey, prefix = DEFAULT_PREFIX) {
+    if (!KNOWN_PREFIXES.includes(prefix))
+        throw new Error(`unknown address prefix ${prefix}`);
+    return bech32m.encode(prefix, bech32m.toWords(blake3(publicKey)));
 }
 /** A key's id: BLAKE3(public key) as hex. Same 32 bytes as inside the `boo1…` address it derives. */
 export function keyId(publicKey) {
     return bytesToHex(blake3(publicKey));
 }
-export function isAddress(s) {
+/** The prefix of a canonical address (`boo`, `tboo`), or `undefined` if `s` isn't one. */
+export function addressPrefix(s) {
     // Addresses are canonical lowercase; the node rejects any other casing.
     if (s !== s.toLowerCase())
-        return false;
+        return undefined;
     try {
         const { prefix, words } = bech32m.decode(s);
-        return prefix === "boo" && bech32m.fromWords(words).length === 32;
+        return KNOWN_PREFIXES.includes(prefix) && bech32m.fromWords(words).length === 32 ? prefix : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Whether `s` is an address: with any known prefix, or exactly `prefix` when given. */
+export function isAddress(s, prefix) {
+    const p = addressPrefix(s);
+    return p !== undefined && (prefix === undefined || p === prefix);
+}
+const positive = (drops, what) => {
+    if (drops <= 0n)
+        throw new Error(`${what} more than 0`);
+    if (drops >= 1n << 64n)
+        throw new Error(`${what}: amount too large`);
+    return drops;
+};
+const wholeNumber = (n, what) => {
+    if (!Number.isSafeInteger(n) || n < 0)
+        throw new Error(`${what} must be a whole number`);
+    return n;
+};
+/** `n` as drops a transaction can carry: 0 to 2^64 − 1. */
+const checkedDrops = (n, what) => {
+    if (n < 0n || n >= 1n << 64n)
+        throw new Error(`${what}: amount too large`);
+    return n;
+};
+/** How long a program helper waits by default for what it needs to be usable: a minute of blocks. */
+const DEFAULT_PROGRAM_WAIT_MS = 60_000;
+/** The program actions that reserve fuel (tags 62–64) and the helper that prices it: `build()` and the generic paths refuse them, naming it. */
+const PROGRAM_HELPERS = new Map([["upload_code", "wallet.uploadCode"], ["create_program", "wallet.createProgram"], ["call_program", "wallet.callProgram (or wallet.call)"]]);
+const programWaitMs = (ms) => (ms === undefined ? DEFAULT_PROGRAM_WAIT_MS : checkTimeoutMs(ms, "waitMs"));
+const hexArg = (s, what) => {
+    const h = s.trim().toLowerCase();
+    if (!/^[0-9a-f]{64}$/.test(h))
+        throw new Error(`${what} must be 32 bytes of hex`);
+    return h;
+};
+/** A `.boo` name as the chain stores it (node/src/types.rs `normalize_name`): lowercase, without the suffix. */
+export function bareName(name) {
+    const n = name.trim().toLowerCase().replace(/\.boo$/, "");
+    if (n.length < 3 || n.length > 32)
+        throw new Error("names must be 3–32 characters");
+    if (!/^[a-z0-9-]+$/.test(n))
+        throw new Error("names may only use a-z, 0-9 and '-'");
+    if (n.startsWith("-") || n.endsWith("-"))
+        throw new Error("names can't start or end with '-'");
+    return n;
+}
+/**
+ * The most `Wallet.propose` bonds by default without being told (audit gap-7-5): mainnet's genesis
+ * `proposal_deposit` (node/src/params.rs). A node reporting more is refused; pass `deposit`.
+ */
+export const DEFAULT_MAX_PROPOSAL_DEPOSIT = 1000n * 1000000000n;
+/** Highest vote conviction (node/src/params.rs `MAX_CONVICTION`). */
+export const MAX_CONVICTION = 6;
+/** Lock periods a vote at each conviction locks its amount for (params.rs `CONVICTION_PERIODS`) … */
+export const CONVICTION_PERIODS = [0, 1, 2, 4, 8, 16, 32];
+/** … and its weight in tenths of the amount (`CONVICTION_TENTHS`): 0.1× with no lock, then 1×–6×. */
+export const CONVICTION_TENTHS = [1, 10, 20, 30, 40, 50, 60];
+/** A vote's weight in drops: `amount` × the conviction multiplier (params.rs `vote_weight`). */
+export function convictionWeight(amount, conviction) {
+    const t = CONVICTION_TENTHS[conviction];
+    if (t === undefined)
+        throw new Error(`conviction must be 0–${MAX_CONVICTION}`);
+    return (parseFang(amount) * BigInt(t)) / 10n;
+}
+/**
+ * Builders for `Wallet.propose` kinds (node/src/types.rs `ProposalKind`). Amounts are FANG (or
+ * bigint drops), Soul is in Soul ("2.5"); names in `to`/`account` are resolved when proposing.
+ */
+export const proposal = {
+    /** Set a governance parameter (a key of `/api/params`, e.g. "max_validators") to a raw value (drops, blocks, bps …), within its bounds. */
+    paramChange(key, value) {
+        const v = BigInt(value);
+        if (!/^[a-z0-9_]{1,64}$/.test(key))
+            throw new Error("parameter keys are 1–64 characters of a-z, 0-9 and _");
+        if (v < 0n || v >= 1n << 64n)
+            throw new Error("parameter values are 0 to 2^64 - 1");
+        return { type: "param_change", key, value: v.toString() };
+    },
+    /** Pay from the treasury (spends above a share of the treasury need a supermajority). */
+    treasurySpend(to, amount) {
+        return { type: "treasury_spend", to, amount: positive(parseFang(amount), "spend").toString() };
+    },
+    /**
+     * Open a community distribution of `total`, claimable with Merkle proofs against `merkleRoot` until block `claimUntil`.
+     * `distributionId` is the id the tree was built for (`buildDistribution(id, …)`): one no distribution has yet,
+     * at most 1,000 past the next proposal id (`client.proposals()`'s `next_distribution_id` is free, and
+     * `max_distribution_id` is the largest allowed; the range only grows). Other proposals landing first don't change
+     * it, so a multisig can take its time approving; if a distribution with that id opens first, the node refuses this
+     * one (nothing is escrowed), or it fails when it runs. Claims close at most 730 days after the proposal's vote ends.
+     */
+    distribution(distributionId, merkleRoot, total, claimUntil) {
+        return { type: "distribution", distribution_id: wholeNumber(distributionId, "distributionId"), merkle_root: hexArg(merkleRoot, "merkleRoot"), total: positive(parseFang(total), "distribute").toString(), claim_until: wholeNumber(claimUntil, "claimUntil") };
+    },
+    /** Put a repo in the contribution pool (weight 1–100; 0 removes it). */
+    setRepo(repo, weight) {
+        if (!/^[A-Za-z0-9-]{1,39}\/[A-Za-z0-9._-]{1,100}$/.test(repo))
+            throw new Error("repo must be owner/name");
+        if (!Number.isInteger(weight) || weight < 0 || weight > 100)
+            throw new Error("weight must be 0–100");
+        return { type: "set_repo", repo, weight };
+    },
+    /** Grant Soul (in Soul, "2.5"; at most 100 per grant). */
+    grantSoul(to, soul, reason) {
+        return { type: "grant_soul", to, amount: parseSoul(soul), reason };
+    },
+    flagSybil(account, reason) {
+        return { type: "flag_sybil", account, reason };
+    },
+    /** Lift a sybil flag: the appeal path for `flagSybil` (nothing the flag took comes back). */
+    unflagSybil(account, reason) {
+        return { type: "unflag_sybil", account, reason };
+    },
+    rejectClaim(claimId, reason) {
+        return { type: "reject_claim", claim_id: wholeNumber(claimId, "claimId"), reason };
+    },
+    clawback(account, reason) {
+        return { type: "clawback", account, reason };
+    },
+    unlinkGithub(handle) {
+        return { type: "unlink_github", handle };
+    },
+    /** Refund every funder of a hunt (escrow can be refunded, never redirected). */
+    refundHunt(huntId) {
+        return { type: "refund_hunt", hunt_id: wholeNumber(huntId, "huntId") };
+    },
+    /**
+     * Switch to protocol `version` at block `activationHeight` (needs a supermajority). The version is newer than
+     * every one scheduled or withdrawn (`client.upgrade()`'s `withdrawn.highest_version`) and at most 16 past the
+     * newest scheduled, withdrawn or superseded (`next_version` is the number to use); the activation is at most
+     * 365 days after the proposal's vote ends.
+     */
+    scheduleUpgrade(version, activationHeight) {
+        if (!Number.isInteger(version) || version < 1 || version > 0xffffffff)
+            throw new Error("version must be a positive 32-bit number");
+        return { type: "schedule_upgrade", version, activation_height: wholeNumber(activationHeight, "activationHeight") };
+    },
+    /**
+     * Withdraw the upgrade to protocol `version` scheduled at block `activationHeight` (see
+     * `client.upgrade()`), and any scheduled after it, before it activates. Needs a supermajority;
+     * there's no timelock (it runs the block after its vote), and it must run at least 64 blocks
+     * before the activation height, so propose it at least `voting_blocks + 65` blocks ahead.
+     */
+    cancelUpgrade(version, activationHeight) {
+        if (!Number.isInteger(version) || version < 1 || version > 0xffffffff)
+            throw new Error("version must be a positive 32-bit number");
+        if (wholeNumber(activationHeight, "activationHeight") < 1)
+            throw new Error("activationHeight is the block the upgrade is scheduled at");
+        return { type: "cancel_upgrade", version, activation_height: activationHeight };
+    },
+    /** Turn on a feature flag (e.g. "ghost"). */
+    activateFeature(feature) {
+        return { type: "activate_feature", feature };
+    },
+    deactivateFeature(feature) {
+        return { type: "deactivate_feature", feature };
+    },
+    /** A signal with no on-chain effect. */
+    text() {
+        return { type: "text" };
+    },
+};
+// ---- Readers for the protocol v1 endpoints: they take what the node serves (node/src/api.rs)
+// and return plain shapes with amounts as decimal strings of drops. They don't throw on a
+// missing field (an older node, or a page that hasn't loaded): it reads as empty or zero. ----
+/** A JSON object, or an empty one. */
+const obj = (v) => (v && typeof v === "object" && !Array.isArray(v) ? v : {});
+const arr = (v) => (Array.isArray(v) ? v : []);
+/** Drops as a decimal string: from a string or number of drops, or "0". */
+const drops = (v) => {
+    if (typeof v === "bigint")
+        return v.toString();
+    if (typeof v === "number" && Number.isSafeInteger(v) && v >= 0)
+        return String(v);
+    if (typeof v === "string" && /^\d+$/.test(v))
+        return v;
+    return "0";
+};
+/** An address from a label (`{address, name}`) or a plain string. */
+const addressOf = (v) => (typeof v === "string" ? v : String(obj(v).address ?? ""));
+const nameOf = (v) => (typeof v === "object" && v ? (obj(v).name ?? null) : null);
+const num = (v) => (typeof v === "number" ? v : typeof v === "string" && /^\d+$/.test(v) ? Number(v) : undefined);
+export function stakeSummary(raw) {
+    const r = obj(raw);
+    const delegations = arr(r.delegations).map((d0) => {
+        const d = obj(d0);
+        return { validator: addressOf(d.validator), validator_name: nameOf(d.validator), shares: drops(d.shares), value: drops(d.value), principal: drops(d.principal), self_bond: d.self_bond === true };
+    });
+    const entries = arr(r.entries).map(obj);
+    const unbonding = entries.filter((e) => e.type === "unbonding").map((e) => ({ id: num(e.id) ?? 0, validator: addressOf(e.validator), amount: drops(e.amount), started_at: num(e.started_at) ?? 0, completes_at: num(e.release_at) ?? 0, ready: e.ready === true }));
+    const redelegations = entries.filter((e) => e.type === "redelegation").map((e) => ({ id: num(e.id) ?? 0, from: addressOf(e.from), to: addressOf(e.to), amount: drops(e.amount), completes_at: num(e.release_at) ?? 0 }));
+    return { delegations, unbonding, redelegations, bonded: drops(r.bonded), unbonding_total: drops(r.unbonding), withdrawable: drops(r.withdrawable), summary: String(r.summary ?? "") };
+}
+/**
+ * Shares worth about `value` drops in a delegation (rounded down, at most all of them), at the
+ * value the delegation reports. That's a node's word: to unbond an amount, pass
+ * `wallet.undelegate(validator, { amount })`, which the chain converts itself (audit gap-7-5).
+ */
+export function sharesFor(d, value) {
+    const want = parseFang(value);
+    const [shares, worth] = [BigInt(d.shares), BigInt(d.value)];
+    if (worth === 0n || want >= worth)
+        return shares;
+    return (want * shares) / worth;
+}
+/** `/api/params`' governance parameters as a key → value map (values as strings: amounts can exceed 2^53). */
+export function paramsOf(raw) {
+    const out = {};
+    for (const [k, v] of Object.entries(obj(obj(raw).params))) {
+        if ((typeof v === "number" && Number.isSafeInteger(v)) || (typeof v === "string" && /^\d+$/.test(v)))
+            out[k] = String(v);
+    }
+    return out;
+}
+/** `proposalDigest` of a proposal's content as the node served it, or why it can't be computed. */
+function digestOf(kind, title, url) {
+    if (!kind || typeof kind !== "object")
+        return { digest: null, digest_error: "the node didn't say what this proposal does" };
+    try {
+        return { digest: proposalDigest(kind, String(title ?? ""), typeof url === "string" ? url : "") };
+    }
+    catch (e) {
+        return { digest: null, digest_error: `this client can't read the proposal exactly (${e.message})` };
+    }
+}
+export function proposalSummary(raw, rules) {
+    const p = obj(raw);
+    const weight = (side) => drops(obj(obj(side).weight).drops);
+    const amount = (side) => drops(obj(obj(side).amount).drops);
+    const tally = p.tally ? obj(p.tally) : null;
+    const council = arr(p.council).map(obj);
+    const [ayeAmount, nayAmount] = [amount(p.ayes), amount(p.nays)];
+    const supermajority = p.supermajority === true;
+    return {
+        id: num(p.id) ?? -1,
+        title: String(p.title ?? ""),
+        url: typeof p.url === "string" ? p.url : "",
+        summary: String(p.summary ?? ""),
+        does: describeKind(p.kind),
+        kind: p.kind && typeof p.kind === "object" ? p.kind : null,
+        ...digestOf(p.kind, p.title, p.url),
+        proposer: p.proposer === undefined ? null : addressOf(p.proposer),
+        proposer_name: nameOf(p.proposer),
+        status: String(p.status ?? "unknown"),
+        deposit: drops(p.deposit),
+        aye: weight(p.ayes),
+        nay: weight(p.nays),
+        aye_amount: ayeAmount,
+        nay_amount: nayAmount,
+        turnout: (BigInt(ayeAmount) + BigInt(nayAmount)).toString(),
+        voters: num(p.voters) ?? 0,
+        quorum: tally ? drops(obj(tally.quorum).drops) : undefined,
+        quorum_reached: tally ? tally.quorum_reached === true : undefined,
+        council: { ayes: council.filter((c) => c.aye === true).length, nays: council.filter((c) => c.aye === false).length, of: tally ? num(tally.council_size) : undefined },
+        supermajority,
+        voting_ends_at: num(p.voting_end) ?? 0,
+        executes_at: num(p.execute_at),
+        outcome: String(p.outcome ?? ""),
+        threshold_bps: supermajority ? rules?.supermajority_bps : undefined,
+    };
+}
+/** The most `feeHeadroom` a tx may ask for: 100 × the base fee. */
+export const MAX_FEE_HEADROOM = 100;
+/** The least a payment that opens an account must carry: 0.01 FANG (node/src/types.rs `MIN_NEW_ACCOUNT`). */
+export const MIN_NEW_ACCOUNT = 10000000n;
+const GRANT_PREFIX = "bkgrant1";
+/** A grant as one pasteable string: `bkgrant1.<account>.<base64url(public key ‖ pop)>`. */
+export function encodeKeyGrant(g) {
+    const body = new Uint8Array(PUBLIC_KEY_LEN + SIGNATURE_LEN);
+    body.set(hexToBytes(g.public_key));
+    body.set(hexToBytes(g.pop), PUBLIC_KEY_LEN);
+    return `${GRANT_PREFIX}.${g.account}.${base64urlnopad.encode(body)}`;
+}
+/** Parses a grant code (`encodeKeyGrant`). Whitespace is ignored, so a wrapped paste works. */
+export function decodeKeyGrant(code) {
+    const c = code.replace(/\s+/g, "");
+    if (/^[0-9a-f]{64}$/i.test(c))
+        throw new Error("that's a key id: adding a key needs its grant code now, which the key's holder makes for your account (Wallet.keyGrant, the MCP's use_account, or a new device's link screen)");
+    const [prefix, account, body, ...rest] = c.split(".");
+    if (prefix !== GRANT_PREFIX || !account || !body || rest.length)
+        throw new Error("that isn't a key grant code (it starts with bkgrant1.)");
+    if (!isAddress(account))
+        throw new Error("the grant code's account isn't an address");
+    let bytes;
+    try {
+        bytes = base64urlnopad.decode(body);
+    }
+    catch {
+        throw new Error("the grant code is damaged (copy all of it)");
+    }
+    if (bytes.length !== PUBLIC_KEY_LEN + SIGNATURE_LEN)
+        throw new Error("the grant code is damaged or cut short (copy all of it)");
+    const pk = bytes.slice(0, PUBLIC_KEY_LEN);
+    return { account, key_id: keyId(pk), public_key: bytesToHex(pk), pop: bytesToHex(bytes.slice(PUBLIC_KEY_LEN)) };
+}
+/** Whether `g` is a valid consent by its key to join `g.account` on the chain `(chainId, genesisHash)`. */
+export function verifyKeyGrant(g, chainId, genesisHash) {
+    try {
+        const pk = hexToBytes(g.public_key);
+        if (pk.length !== PUBLIC_KEY_LEN || keyId(pk) !== g.key_id)
+            return false;
+        return ml_dsa65.verify(hexToBytes(g.pop), keyPopMessage(chainId, genesisHash, g.account, g.key_id), pk, { context: KEY_POP_CONTEXT });
     }
     catch {
         return false;
@@ -33,28 +360,63 @@ export class Wallet {
     seed;
     client;
     publicKey;
-    /** This key's own address. */
-    address;
-    /** The account this wallet acts for (defaults to `address`). */
-    account;
     /** WebAuthn credential id, when the wallet was unlocked by a passkey. Not secret. */
     credentialId;
+    /** Default tip (drops) for this wallet's transactions. */
+    tip = 0n;
+    /** Default validity (blocks from now) for this wallet's transactions. */
+    validForBlocks = DEFAULT_VALID_FOR_BLOCKS;
+    /** Default `feeHeadroom` for this wallet's transactions (1: none). See `TxOptions.feeHeadroom`. */
+    feeHeadroom = 1;
     secretKey;
+    /**
+     * This wallet's txs are signed and submitted one at a time, in nonce order (DEV-3): parallel
+     * `send`s from one wallet would otherwise read the same next nonce and all but one be refused.
+     */
+    queue = Promise.resolve();
+    /** The nonce after the last tx this wallet submitted, for one chain and account, and that tx. */
+    cursor;
+    acting;
+    /** How `actAs` found the account, when that was one node's unproven word (checked when signing on mainnet). */
+    actingUnproven;
     constructor(seed, client = new Client()) {
         this.seed = seed;
         this.client = client;
         const keys = ml_dsa65.keygen(seed);
         this.publicKey = keys.publicKey;
         this.secretKey = keys.secretKey;
-        this.address = addressFromPublicKey(keys.publicKey);
-        this.account = this.address;
+    }
+    /** This key's own address, with the chain's prefix once the client knows it (`await client.addressPrefix()`). */
+    get address() {
+        return addressFromPublicKey(this.publicKey, this.client.prefix);
+    }
+    /** The account this wallet acts for (defaults to `address`). */
+    get account() {
+        return this.acting ?? this.address;
+    }
+    set account(account) {
+        this.acting = account;
+        this.actingUnproven = undefined;
     }
     get keyId() {
         return keyId(this.publicKey);
     }
-    /** Act for another account this key has been authorized on. Accepts a name or address. */
+    /**
+     * Act for another account this key has been authorized on. Accepts a name or address. A name
+     * needs an address here (every tx names the account it acts for), so it's resolved: proven with
+     * the client's witnesses. Without them it's one node's word, and on mainnet nothing is signed
+     * for an account found that way (`UnprovenNameError`): check the address and pass it instead
+     * (audit gap-7-1).
+     */
     async actAs(account) {
-        this.account = await this.client.resolve(account);
+        const r = await this.addressNeeded(await this.client.resolution(account));
+        // An address with another chain's prefix (a relaunched testnet's `boo1…` on a `tboo1…` chain)
+        // isn't an account here: every tx from it, and a faucet drip to it, would be refused.
+        const prefix = await this.client.addressPrefix();
+        if (!isAddress(r.address, prefix))
+            throw new Error(`${r.address} is an address on another chain: this chain's addresses start with ${prefix}1`);
+        this.acting = r.address;
+        this.actingUnproven = r.proven ? undefined : r;
         return this;
     }
     static generate(client) {
@@ -80,183 +442,2107 @@ export class Wallet {
         const signature = ml_dsa65.sign(signingBytes(tx), this.secretKey);
         return { ...tx, public_key: bytesToHex(this.publicKey), signature: bytesToHex(signature) };
     }
-    async build(action, memo = "") {
-        const [status, account] = await Promise.all([this.client.status(), this.client.account(this.account).catch(() => null)]);
-        const unsigned = { chain_id: status.chain_id, from: this.account, nonce: account?.next_nonce ?? 0, fee: "0", action, memo };
-        unsigned.fee = minFee(unsigned).toString();
+    /**
+     * This key's consent to being added to `account` (an address, or a name resolved by the
+     * client: proven when it has witnesses; on mainnet an unproven name is refused, pass the address)
+     * on the client's chain: hand `encodeKeyGrant(grant)` to the account's owner, who adds the key
+     * with it. Pass `chain` to sign offline.
+     */
+    async keyGrant(account, chain) {
+        // A resolution already made (and shown) is used as is: resolving the name again could get another answer.
+        const res = typeof account !== "string" ? (account.name === null ? null : account) : isAddress(account) ? null : await this.client.resolution(account);
+        const address = typeof account !== "string" ? account.address : (res?.address ?? account);
+        let c = chain;
+        if (!c) {
+            const status = await this.client.status();
+            if (typeof status.genesis_hash !== "string")
+                throw new Error(`${this.client.rpc} doesn't report a genesis_hash; it's too old for this SDK`);
+            // A `chain` given by the caller names the chain itself; one read from the node is checked like a signing status.
+            this.client.checkMainnetPin(status.chain_id);
+            c = { chainId: status.chain_id, genesisHash: status.genesis_hash };
+        }
+        if (res && !res.proven && c.chainId === MAINNET_CHAIN_ID)
+            throw new UnprovenNameError(res, this.client.rpc);
+        const pop = ml_dsa65.sign(keyPopMessage(c.chainId, c.genesisHash, address, this.keyId), this.secretKey, { context: KEY_POP_CONTEXT });
+        return { account: address, key_id: this.keyId, public_key: bytesToHex(this.publicKey), pop: bytesToHex(pop) };
+    }
+    /**
+     * The `add_key` action for a grant (an object or its code): it must be for this account and
+     * verify on the client's chain, so a wrong or damaged code fails here, before anything is signed.
+     */
+    async grantAction(grant, label, role) {
+        const g = typeof grant === "string" ? decodeKeyGrant(grant) : grant;
+        if (g.account !== this.account)
+            throw new Error(`that grant is for ${g.account}, not this account (${this.account}): the key's holder must make it for ${this.account}`);
+        const status = await this.client.status();
+        if (!verifyKeyGrant(g, status.chain_id, status.genesis_hash))
+            throw new Error("that grant doesn't verify: it's damaged, or it was made for another chain");
+        return { type: "add_key", key_id: g.key_id, label, role, public_key: g.public_key, pop: g.pop };
+    }
+    /**
+     * Builds and signs a tx: `fee` = the highest base fee already fixed for the next blocks
+     * (`/api/fees` `suggested`) + `tip`, `valid_until` = the current height + `validForBlocks`, and
+     * the chain's id and genesis hash from `/api/status`. Only the base fee of the block that
+     * includes it (+ the tip) is charged. A tip above `tip_cap_multiple` × the lowest upcoming base
+     * fee (`/api/fees` `lowest`, see `maxTip`) is refused here, as nodes would refuse it. To sign
+     * offline, build an `UnsignedTx` yourself (with the chain's `genesis_hash`) and `sign` it.
+     *
+     * `action` may be a function of the height `valid_until` is counted from, for actions that
+     * carry an absolute block height of their own (a session key's or a hunt's expiry): computed
+     * from the same status read, a node that lies about the height can stretch them by at most
+     * `max_tx_validity_blocks`, since validators refuse a `valid_until` further ahead than that
+     * (audit gap-7-3).
+     *
+     * That height is checked first (`Client.checkSigningHeight`: against the witnesses' heads and,
+     * when the client knows its genesis clock, the clock), since a node reporting one the chain
+     * hasn't reached gets a tx it can hold and release later.
+     *
+     * `opts.resolutions`: how names in fields that need an address got into `action` (their
+     * `Client.resolution`s). On mainnet a tx carrying one that only one node vouched for isn't
+     * signed (`UnprovenNameError`), checked against the very status the tx is signed for, as the
+     * helpers do (audit gap-7-1). Fields the chain resolves itself take `Client.recipient(x).signed`.
+     */
+    async build(action, memo = "", opts = {}) {
+        return this.buildChecked(action, memo, opts, opts.resolutions ?? []);
+    }
+    /**
+     * `build`, refusing on mainnet a tx that carries an address only one node vouched for: `unproven`
+     * (the helpers' resolutions of names in fields that need an address) or the account `actAs`
+     * found that way (audit gap-7-1). Checked against the very status the tx is signed for.
+     */
+    async buildChecked(action, memo, opts, unproven) {
+        await this.client.addressPrefix(); // so `this.account` uses the chain's prefix
+        const [status, account, fees] = await Promise.all([this.client.status(), this.client.account(this.account).catch(() => null), this.client.fees()]);
+        if (!Number.isSafeInteger(status.height) || status.height < 0)
+            throw new Error(`${this.client.rpc} doesn't report its height`);
+        // blockula-1 only through a client pinned to it (DEV-1), checked against the very status the tx is signed for.
+        this.client.checkMainnetPin(status.chain_id);
+        await this.client.checkSigningHeight(status.height);
+        const max = status.max_tx_validity_blocks ?? Number.MAX_SAFE_INTEGER;
+        const validFor = opts.validForBlocks ?? Math.min(this.validForBlocks, max);
+        if (!Number.isSafeInteger(validFor) || validFor < 1)
+            throw new Error("validForBlocks must be a positive whole number of blocks");
+        if (validFor > max)
+            throw new Error(`validForBlocks can be at most ${max} (an hour of blocks)`);
+        const tip = opts.tip === undefined ? this.tip : parseFang(opts.tip);
+        if (typeof status.genesis_hash !== "string")
+            throw new Error(`${this.client.rpc} doesn't report a genesis_hash; it's too old for this SDK`);
+        const guess = [...unproven, ...(this.actingUnproven ? [this.actingUnproven] : [])].find((r) => !r.proven);
+        if (guess && status.chain_id === MAINNET_CHAIN_ID)
+            throw new UnprovenNameError(guess, this.client.rpc);
+        // Binds the tx to this chain instance (not just its id), so it can't replay on a relaunch.
+        const act = typeof action === "function" ? action(status.height) : action;
+        // A program action reserves fuel and pays for it (§5.1): only the helpers below price that, so this generic path refuses it.
+        const helper = PROGRAM_HELPERS.get(act.type);
+        if (helper && !opts.reserved)
+            throw new Error(`a ${act.type} reserves fuel, which this generic builder doesn't price (its fee would be too low and the chain would refuse it): use ${helper}. Nothing was signed`);
+        const nonce = await this.nonceFor(cursorKey(status.chain_id, status.genesis_hash, this.account), Number(account?.next_nonce ?? 0), status.height);
+        const unsigned = { chain_id: status.chain_id, genesis_hash: status.genesis_hash, from: this.account, nonce, fee: "0", tip: tip.toString(), valid_until: status.height + validFor, action: act, memo };
+        // A program transaction also pays for the fuel it reserves (§5.1): at the rate the next blocks can reach, from this very read
+        // of the node's prices, which also refuses a reservation no block could carry (programs.ts `priceFuel`).
+        const fuel = opts.reserved ? priceFuel(checkFuel(this.client.rpc, fees.fuel), opts.reserved) : { suggested: 0n, floor: 0n };
+        unsigned.fee = this.feeFor(unsigned, fees.suggested, tip, opts, fuel.suggested).toString();
+        if (tip > 0n) {
+            // The cap is a multiple of the base fee of the block that includes the tx (its bytes' and its fuel's): price it at the lowest upcoming
+            // one, and a program's fuel at the floor rate, which no block undercuts.
+            const multiple = fees.tip_cap_multiple ?? DEFAULT_TIP_CAP_MULTIPLE;
+            const cap = maxTip(unsigned, fees.lowest ?? fees.suggested, multiple) + BigInt(multiple) * fuel.floor;
+            if (tip > cap)
+                throw new Error(`tip too high: at most ${multiple}× the base fee, ${cap} drops for this transaction now`);
+        }
         return this.sign(unsigned);
     }
-    /** Send FANG to a `.boo` name or `boo1…` address. `amount` is in FANG ("1.5") or bigint drops. */
+    /**
+     * A tx's `fee`: the base fee at `suggested` for its size (and, for a program transaction, its
+     * fuel fee at the suggested rate: `fuelFee`), times the headroom, plus the tip; or `maxFee`
+     * outright, which must cover at least that base fee plus the tip.
+     */
+    feeFor(unsigned, suggested, tip, opts, fuelFee = 0n) {
+        const base = baseFee(unsigned, suggested) + fuelFee;
+        if (opts.maxFee !== undefined) {
+            const fee = parseFang(opts.maxFee);
+            if (fee < base + tip)
+                throw new Error(`maxFee ${formatFang(fee)} is below what this transaction costs now: ${formatFang(base + tip)} (base fee ${formatFang(base)} + tip ${formatFang(tip)})`);
+            if (fee >= 1n << 64n)
+                throw new Error("maxFee: amount too large");
+            return fee;
+        }
+        const headroom = opts.feeHeadroom ?? this.feeHeadroom;
+        if (typeof headroom !== "number" || !Number.isFinite(headroom) || headroom < 1 || headroom > MAX_FEE_HEADROOM)
+            throw new Error(`feeHeadroom must be a number from 1 to ${MAX_FEE_HEADROOM} (times the base fee)`);
+        // In thousandths, rounded up, so 1.5 is exactly 1.5× and nothing rounds below the base fee.
+        const milli = BigInt(Math.ceil(headroom * 1000));
+        return (base * milli + 999n) / 1000n + tip;
+    }
+    /**
+     * The nonce for this wallet's next tx on chain/account `key`: the node's `next_nonce` (which
+     * counts the txs it holds), or one past the last tx this wallet submitted when that's higher
+     * and the tx may still run: still pending on its way through the network, or not yet counted
+     * by a node writing a block (DEV-3). A tx that was dropped, or can't run any more
+     * (`valid_until` passed), gives its nonce back: the node's word is used again. A nonce handed to
+     * a tx a node admitted is never handed out again while that tx may run.
+     */
+    async nonceFor(key, nodeNext, height) {
+        const c = this.cursor;
+        if (!c || c.key !== key || c.next <= nodeNext)
+            return nodeNext;
+        if (height <= c.validUntil) {
+            const last = await this.client.tx(c.lastId).catch(() => null);
+            // Unknown here (another node holds it, or it never arrived): kept, so a tx that may run isn't doubled.
+            if (!last || last.status === "pending" || last.status === "finalized" || (last.status === "failed" && !txDropped(last)))
+                return c.next;
+        }
+        if (this.cursor === c)
+            this.cursor = undefined;
+        return nodeNext;
+    }
+    /** Runs `job` after every job queued before it (its outcome doesn't stop the next one). */
+    enqueue(job) {
+        const run = this.queue.then(job, job);
+        this.queue = run.catch(() => undefined);
+        return run;
+    }
+    /**
+     * Builds, signs and submits one tx in this wallet's queue (`enqueue`): one at a time, so each
+     * is admitted before the next is signed, in nonce order (DEV-3). Waits for it after leaving the
+     * queue, so parallel calls are only serialized for the moment it takes to sign and submit.
+     *
+     * What a failure does to the next nonce: refused by the node (a 4xx answer: it wasn't admitted),
+     * the nonce is used for the next tx, which can't be paid twice since only one tx per nonce ever
+     * runs; on "bad nonce" the same signed bytes are tried again once (a node writing a block can
+     * misjudge a correct nonce for a moment), then the node's next nonce is used. Anything else
+     * (a timeout, a 5xx, a broken connection) may have been admitted, so its nonce isn't reused.
+     */
+    async submitQueued(action, memo, opts, unproven, retry = NO_RETRY) {
+        const { tx, id } = await this.enqueue(async () => {
+            const tx = await this.buildChecked(action, memo, opts, unproven);
+            // Stored before it leaves (store first, then send); a store that fails submits nothing.
+            if (opts.onSigned)
+                await opts.onSigned(tx, txId(tx));
+            const key = cursorKey(tx.chain_id, tx.genesis_hash, tx.from);
+            try {
+                const { id } = await postPatiently(this.client, tx, retry);
+                this.cursor = { key, next: tx.nonce + 1, lastId: id, validUntil: tx.valid_until };
+                return { tx, id };
+            }
+            catch (e) {
+                if (!refused(e))
+                    this.cursor = { key, next: tx.nonce + 1, lastId: txId(tx), validUntil: tx.valid_until };
+                else if (/bad nonce/i.test(e.message) && this.cursor?.key === key)
+                    this.cursor = undefined;
+                throw e;
+            }
+        });
+        if (opts.wait ?? true)
+            return this.client.waitForTx(id, undefined, tx.valid_until);
+        try {
+            return await this.client.tx(id);
+        }
+        catch (e) {
+            throw new TxPendingError(id, 0, e);
+        }
+    }
+    /**
+     * Send FANG to a `.boo` name or an address. `amount` is in FANG ("1.5") or bigint drops. A name
+     * is signed as its proven owner's address when the client has witnesses (who you checked is who
+     * gets paid, even if the name changes hands before the tx runs), and as the name itself when it
+     * doesn't: the chain then pays whoever owns it when the tx runs. A lying node can't point it at
+     * another account now, but it can hold the signed tx until its validity window, which counts
+     * from the height the node reported, and release it later, by when the name may have lapsed
+     * and been registered again (audit gap-7-1, review-r3-clients-2). See `Client.recipient`.
+     */
     async send(to, amount, opts = {}) {
-        // Sign the resolved address, not the name: what you checked is exactly who gets paid,
-        // even if the name changes hands before the block is sealed.
-        const recipient = await this.client.resolve(to);
-        const tx = await this.build({ type: "transfer", to: recipient, amount: parseFang(amount).toString() }, opts.memo);
-        return this.client.submit(tx, opts.wait ?? true);
+        return this.pay(to, amount, opts);
+    }
+    /**
+     * `send`, with the batch's retry policy. An amount of 0 is refused before anything is signed
+     * (DEV-14): it moves nothing and only pays a fee. A payment that opens an account must carry at
+     * least 0.01 FANG and burns `creation_fee` (0.1 FANG) from this account on top; the result of a
+     * finalized payment that did says so (`opened_account`, `creation_fee`), since its `summary` and
+     * `fee` don't (DEV-7).
+     */
+    async pay(to, amount, opts, retry = NO_RETRY) {
+        const drops = positive(parseFang(amount), "send");
+        const recipient = await this.client.recipient(to);
+        const opening = await this.openingCost(recipient.address);
+        if (opening?.opens && drops < MIN_NEW_ACCOUNT)
+            throw new Error(`sending to a new account needs at least ${formatFang(MIN_NEW_ACCOUNT)}: ${recipient.input} has no account yet. Nothing was signed`);
+        const tx = await this.submitQueued({ type: "transfer", to: recipient.signed, amount: drops.toString() }, opts.memo ?? "", opts, [], retry);
+        if (opening?.opens && opening.fee > 0n && tx?.status === "finalized" && (await this.opened(recipient.address, tx))) {
+            return { ...tx, opened_account: true, creation_fee: opening.fee.toString(), creation_fee_display: formatFang(opening.fee) };
+        }
+        return tx;
+    }
+    /**
+     * Whether a payment to `address` would open its account, and what that burns from the payer
+     * (`/api/account`'s `exists` and `creation_fee`; on nodes without them, an account with no
+     * balance and no nonce counts as new). `undefined` when the node didn't say.
+     */
+    async openingCost(address) {
+        const a = await this.client.account(address).catch(() => null);
+        if (!a || typeof a !== "object")
+            return undefined;
+        const opens = typeof a.exists === "boolean" ? !a.exists : BigInt(drops(a.balance)) === 0n && !Number(a.nonce ?? 0);
+        if (!opens)
+            return { opens, fee: 0n };
+        const fee = /^\d+$/.test(String(a.creation_fee ?? "")) ? BigInt(a.creation_fee) : BigInt(drops((await this.client.fees().catch(() => ({}))).account_creation_fee));
+        return { opens, fee };
+    }
+    /**
+     * Whether finalized payment `tx` opened `address`'s account (it had none when the payment was
+     * signed): no other finalized tx naming it ran before this one. From its newest history, so a
+     * flood of more than 25 txs to a brand-new account within seconds can hide an earlier one.
+     */
+    async opened(address, tx) {
+        const a = await this.client.account(address).catch(() => null);
+        const height = tx.height;
+        if (!a || typeof height !== "number")
+            return true;
+        const before = arr(a.recent_txs).filter((t) => t?.id !== tx.id && t?.status === "finalized" && typeof t.height === "number" && t.height <= height && addressOf(t.to) === address);
+        if (before.some((t) => t.height < height))
+            return false;
+        if (!before.length)
+            return true;
+        // Same block: whichever ran first opened it.
+        const block = await this.client.block(height).catch(() => null);
+        const ids = arr(block?.txs).map((t) => String(t?.id));
+        const mine = ids.indexOf(String(tx.id));
+        return mine >= 0 && !before.some((t) => ids.indexOf(String(t.id)) >= 0 && ids.indexOf(String(t.id)) < mine);
+    }
+    /**
+     * What paying `amount` to `to` would cost this account, before anything is signed (DEV-7):
+     * - `fee`: the base fee for this payment's size at what `/api/fees` fixes for the next 17 blocks
+     *   (`suggested`), plus the tip. On a chain that isn't busy, what it's charged;
+     * - `maxFee`: the most it can be charged (`fee`, or more with `feeHeadroom` / `maxFee`);
+     * - `creationFee`: burned from this account when the payment opens the recipient's account
+     *   (0.1 FANG on chains with genesis defaults), on top of `amount`;
+     * - `total`: `amount + fee + creationFee`;
+     * - `transferableAfter`: what this account could still move afterwards, counting `maxFee`
+     *   (negative: it can't pay this). Amounts are bigint drops; `display` has them as FANG text.
+     * `recipient` is how `to` gets signed (`Client.recipient`): show `recipient.how` before paying.
+     * Refuses (throws) a 0 amount, and less than 0.01 FANG to an account that doesn't exist yet.
+     */
+    async quote(to, amount, opts = {}) {
+        const value = positive(parseFang(amount), "send");
+        await this.client.addressPrefix();
+        const recipient = await this.client.recipient(to);
+        const [status, fees, from, opening] = await Promise.all([this.client.status(), this.client.fees(), this.client.account(this.account), this.openingCost(recipient.address)]);
+        if (!opening)
+            throw new Error(`${this.client.rpc} didn't say whether ${recipient.address} has an account, so the cost of paying it can't be quoted`);
+        if (opening.opens && value < MIN_NEW_ACCOUNT)
+            throw new Error(`sending to a new account needs at least ${formatFang(MIN_NEW_ACCOUNT)}: ${recipient.input} has no account yet`);
+        const tip = opts.tip === undefined ? this.tip : parseFang(opts.tip);
+        const unsigned = { chain_id: String(status.chain_id), genesis_hash: String(status.genesis_hash), from: this.account, nonce: Number(from?.next_nonce ?? 0), fee: "0", tip: tip.toString(), valid_until: Number(status.height) + (opts.validForBlocks ?? this.validForBlocks), action: { type: "transfer", to: recipient.signed, amount: value.toString() }, memo: opts.memo ?? "" };
+        const fee = baseFee(unsigned, fees.suggested) + tip;
+        const maxFee = this.feeFor(unsigned, fees.suggested, tip, opts);
+        const transferable = BigInt(drops(from?.transferable ?? from?.balance));
+        const total = value + fee + opening.fee;
+        const transferableAfter = transferable - (value + maxFee + opening.fee);
+        return {
+            amount: value,
+            fee,
+            maxFee,
+            creationFee: opening.fee,
+            total,
+            transferableAfter,
+            enough: transferableAfter >= 0n,
+            opensAccount: opening.opens,
+            recipient,
+            display: { amount: formatFang(value), fee: formatFang(fee), maxFee: formatFang(maxFee), creationFee: formatFang(opening.fee), total: formatFang(total), transferableAfter: transferableAfter < 0n ? `-${formatFang(-transferableAfter)}` : formatFang(transferableAfter) },
+        };
+    }
+    /**
+     * Many payments from this account (TR-5), with at most `concurrency` (default 16, at most 64,
+     * the chain's limit of pending txs per sender) waiting to finalize at once. They're signed in
+     * turn, one nonce after the other. A node that answers 429 (rate limited) or "too many pending
+     * transactions" gets the same signed bytes again once it says to retry (`Retry-After`), for up
+     * to `patienceMs` (default 2 minutes); resubmitting the same bytes can't pay twice.
+     *
+     * Every payment gets a result, in order: `{ ok: true, tx }` or `{ ok: false, error }`. A refused
+     * payment (the node said no: insufficient balance, a bad name) used no nonce, and the rest go on.
+     * A payment that failed for another reason (`TxPendingError`, `TxFailedError` with `dropped`, a
+     * timeout) may still run: check it (`client.tx`) before paying it again, and note that when the
+     * chain drops a tx it drops every later one from the account too. `onSigned` is called with
+     * each signed tx before it's submitted, as with `send`.
+     */
+    async sendMany(payments, opts = {}) {
+        const concurrency = opts.concurrency ?? 16;
+        if (!Number.isSafeInteger(concurrency) || concurrency < 1 || concurrency > MAX_PENDING_PER_SENDER)
+            throw new Error(`concurrency must be a whole number from 1 to ${MAX_PENDING_PER_SENDER}`);
+        const patienceMs = opts.patienceMs ?? 120_000;
+        if (!Number.isSafeInteger(patienceMs) || patienceMs < 0)
+            throw new Error("patienceMs must be a whole number of milliseconds");
+        // Every amount is checked before the first is signed.
+        for (const [i, p] of payments.entries())
+            positive(parseFang(p.amount), `payment ${i + 1}: send`);
+        const results = new Array(payments.length);
+        let next = 0;
+        const worker = async () => {
+            while (next < payments.length) {
+                const i = next++;
+                const p = payments[i];
+                const { to, amount, ...txOpts } = p;
+                try {
+                    results[i] = { ok: true, to, amount, tx: await this.pay(to, amount, { ...opts, ...txOpts }, { untilMs: patienceMs }) };
+                }
+                catch (error) {
+                    results[i] = { ok: false, to, amount, error };
+                }
+            }
+        };
+        await Promise.all(Array.from({ length: Math.min(concurrency, payments.length) }, worker));
+        return results;
     }
     async registerName(name, opts = {}) {
-        const tx = await this.build({ type: "register_name", name });
-        return this.client.submit(tx, opts.wait ?? true);
+        return this.submitQueued({ type: "register_name", name }, "", opts, []);
     }
-    /** Authorize another device's key (e.g. a second passkey) with full control. */
-    async addOwnerKey(keyIdHex, label) {
-        return this.client.submit(await this.build({ type: "add_key", key_id: keyIdHex, label, role: { type: "owner" } }));
+    /**
+     * Authorize another device's key (e.g. a second passkey) with full control. `grant` is the
+     * key's consent to this account (`keyGrant` on that device, or its grant code).
+     */
+    async addOwnerKey(grant, label) {
+        return this.submitQueued(await this.grantAction(grant, label, { type: "owner" }), "", {}, []);
     }
     /**
-     * Let an agent/app key spend from this account, transfers only, within a limit.
-     * Example: `addSessionKey(agentKeyId, "claude", { limit: "10", periodBlocks: 86_400, expiresInBlocks: 30 * 86_400 })`.
+     * Let an agent/app key spend from this account, transfers only, within a limit. `grant` is the
+     * key's consent to this account (the agent's grant code).
+     * Example: `addSessionKey(grantCode, "claude", { limit: "10", periodBlocks: 86_400, expiresInBlocks: 30 * 86_400 })`.
      */
-    async addSessionKey(keyIdHex, label, opts) {
+    async addSessionKey(grant, label, opts) {
         if (!Number.isSafeInteger(opts.periodBlocks) || opts.periodBlocks < 1)
             throw new Error("periodBlocks must be a positive whole number of blocks");
         if (!Number.isSafeInteger(opts.expiresInBlocks) || opts.expiresInBlocks < 1)
             throw new Error("expiresInBlocks must be a positive whole number of blocks");
-        const { height } = await this.client.status();
-        const role = { type: "session", limit: parseFang(opts.limit).toString(), period_blocks: opts.periodBlocks, expires_at: height + opts.expiresInBlocks };
-        return this.client.submit(await this.build({ type: "add_key", key_id: keyIdHex, label, role }));
+        const limit = parseFang(opts.limit).toString();
+        const base = await this.grantAction(grant, label, { type: "owner" });
+        // The expiry counts from the height valid_until does (one status read): see `build`.
+        return this.submitQueued((height) => ({ ...base, role: { type: "session", limit, period_blocks: opts.periodBlocks, expires_at: height + opts.expiresInBlocks } }), "", {}, []);
     }
     async removeKey(keyIdHex) {
-        return this.client.submit(await this.build({ type: "remove_key", key_id: keyIdHex }));
+        return this.submitQueued({ type: "remove_key", key_id: keyIdHex }, "", {}, []);
     }
     /**
-     * Offer a validator: bonds `bond` FANG from this account. `consensusKeyHex` is the validator
-     * node's ML-DSA-65 public key (see `blockula validator init`). Pending until an admin approves.
+     * Register a validator owned by this account, self-bonding `bond` FANG into its stake pool (at
+     * least the chain's `min_self_bond`). `consensusKey` is the validator node's ML-DSA-65 public
+     * key and `pop` its proof of possession (see `blockula validator init`). It's a candidate: at
+     * each epoch boundary the top `max_validators` pools by stake form the next active set.
      */
     async registerValidator(opts) {
-        return this.client.submit(await this.build({ type: "register_validator", consensus_key: opts.consensusKey, p2p_addr: opts.p2pAddr, http_addr: opts.httpAddr, bond: parseFang(opts.bond).toString(), pop: opts.pop }));
+        return this.submitQueued({ type: "register_validator", consensus_key: opts.consensusKey, p2p_addr: opts.p2pAddr, http_addr: opts.httpAddr, bond: parseFang(opts.bond).toString(), pop: opts.pop }, "", {}, []);
     }
-    /** Season 0 admins only. */
+    /** Dev and test chains with admins only: pin a validator into the set ahead of stake. */
     async approveValidator(validator) {
-        return this.client.submit(await this.build({ type: "approve_validator", validator }));
+        return this.submitQueued({ type: "approve_validator", validator }, "", {}, []);
     }
-    /** Season 0 admins only. */
+    /** Dev and test chains with admins only: take a validator out of the set for good. */
     async removeValidator(validator) {
-        return this.client.submit(await this.build({ type: "remove_validator", validator }));
+        return this.submitQueued({ type: "remove_validator", validator }, "", {}, []);
     }
     /** Claim a GitHub handle. Verify it by creating a public gist (as that user) containing this account's address. */
     async linkGithub(handle, gistId) {
-        return this.client.submit(await this.build({ type: "link_github", handle, gist_id: gistId }));
+        return this.submitQueued({ type: "link_github", handle, gist_id: gistId }, "", {}, []);
     }
     async unlinkGithub(handle) {
-        return this.client.submit(await this.build({ type: "unlink_github", handle }));
+        return this.submitQueued({ type: "unlink_github", handle }, "", {}, []);
     }
     /** Put a bounty on a GitHub issue. `expiresInBlocks` from now (max ~1 year). */
     async createHunt(opts) {
-        const { height } = await this.client.status();
-        return this.client.submit(await this.build({ type: "create_hunt", repo: opts.repo, issue: opts.issue, amount: parseFang(opts.amount).toString(), expires_at: height + opts.expiresInBlocks, title: opts.title }));
+        if (!Number.isSafeInteger(opts.expiresInBlocks) || opts.expiresInBlocks < 1)
+            throw new Error("expiresInBlocks must be a positive whole number of blocks");
+        const amount = parseFang(opts.amount).toString();
+        // The expiry counts from the height valid_until does (one status read): see `build`.
+        return this.submitQueued((height) => ({ type: "create_hunt", repo: opts.repo, issue: opts.issue, amount, expires_at: height + opts.expiresInBlocks, title: opts.title }), "", {}, []);
     }
     async fundHunt(huntId, amount) {
-        return this.client.submit(await this.build({ type: "fund_hunt", hunt_id: huntId, amount: parseFang(amount).toString() }));
+        return this.submitQueued({ type: "fund_hunt", hunt_id: huntId, amount: parseFang(amount).toString() }, "", {}, []);
     }
-    /** Pay a hunt's bounty (creator or admin). `to` may be a .boo name; it's resolved and the address is signed. */
+    /** Pay a hunt's bounty (creator or admin). `to` may be a .boo name: signed as `Client.recipient` says (the proven address, or the name for the chain to resolve). */
     async awardHunt(huntId, to, pr, familiarKey) {
-        const addr = await this.client.resolve(to);
-        return this.client.submit(await this.build({ type: "award_hunt", hunt_id: huntId, to: addr, pr, ...(familiarKey ? { familiar_key: familiarKey } : {}) }));
+        const addr = (await this.client.recipient(to)).signed;
+        return this.submitQueued({ type: "award_hunt", hunt_id: huntId, to: addr, pr, ...(familiarKey ? { familiar_key: familiarKey } : {}) }, "", {}, []);
     }
     async cancelHunt(huntId) {
-        return this.client.submit(await this.build({ type: "cancel_hunt", hunt_id: huntId }));
+        return this.submitQueued({ type: "cancel_hunt", hunt_id: huntId }, "", {}, []);
     }
     /** Mark one of this account's session keys (an agent) as a Familiar. */
     async registerFamiliar(keyIdHex, label) {
-        return this.client.submit(await this.build({ type: "register_familiar", key_id: keyIdHex, label }));
+        return this.submitQueued({ type: "register_familiar", key_id: keyIdHex, label }, "", {}, []);
+    }
+    // ---- 🪦 Proof of Contribution ----
+    /** Claim a merged PR (authored by this account's linked GitHub handle) for the contribution pool. Bonded; validators check it on GitHub. */
+    async submitClaim(repo, pr, familiarKey) {
+        return this.submitQueued({ type: "submit_claim", repo, pr, ...(familiarKey ? { familiar_key: familiarKey } : {}) }, "", {}, []);
+    }
+    /** Stake 10 FANG on a newcomer being a real, distinct person (needs 10 Soul). */
+    async vouch(account) {
+        return this.submitQueued({ type: "vouch", account: (await this.client.recipient(account)).signed }, "", {}, []);
+    }
+    /** Withdraw your vouch for `account` (after the lock), or pass your own account to decline one. */
+    async unvouch(account) {
+        return this.submitQueued({ type: "unvouch", account: (await this.client.recipient(account)).signed }, "", {}, []);
+    }
+    /** Join (or top up) the Séance juror pool. Needs 5 Soul; owner keys only. */
+    async joinJury(bond = "10") {
+        return this.submitQueued({ type: "join_jury", bond: parseFang(bond).toString() }, "", {}, []);
+    }
+    async leaveJury() {
+        return this.submitQueued({ type: "leave_jury" }, "", {}, []);
+    }
+    /**
+     * Seal a Séance judgment: one of "a", "b" or "=" per assigned pair (see `client.seance(id)`),
+     * plus claim ids you think are spam. Keep the returned `salt`: `revealVotes` needs it.
+     *
+     * The judgment binds the pairs it was made on (audit gap-7-6): pass `pairs`, the claims (id,
+     * repo, PR) you showed the juror in order, or they're read from the client (`seancePairs`). A
+     * node that showed other pairs or PRs makes the commitment fail instead of misdirecting it.
+     */
+    async sealVotes(seanceId, votes, spam = [], salt = bytesToHex(randomBytes(16)), opts = {}) {
+        await this.client.addressPrefix(); // the commitment names this account
+        const pairs = opts.pairs ?? (await this.client.seancePairs(seanceId, this.account));
+        if (votes.length !== pairs.length)
+            throw new Error(`you have ${pairs.length} assigned pairs: give one of a, b or = for each`);
+        const commitment = seanceCommitment(seanceId, this.account, votes, spam, salt);
+        const pairs_digest = seancePairsDigest(seanceId, this.account, pairs);
+        const tx = await this.submitQueued({ type: "commit_votes", seance_id: seanceId, commitment, pairs_digest }, "", {}, []);
+        return { tx, salt, votes, spam };
+    }
+    async revealVotes(seanceId, votes, spam, salt) {
+        return this.submitQueued({ type: "reveal_votes", seance_id: seanceId, votes, spam, salt }, "", {}, []);
+    }
+    async fundPool(amount) {
+        return this.submitQueued({ type: "fund_pool", amount: parseFang(amount).toString() }, "", {}, []);
+    }
+    /** Withdraw every contribution reward that has vested so far. */
+    async withdrawVested() {
+        return this.submitQueued({ type: "withdraw_vested" }, "", {}, []);
+    }
+    /** Admins of dev and test chains only (elsewhere: a governance proposal). Weight 1–100; 0 removes the repo. */
+    async setRepo(repo, weight) {
+        return this.submitQueued({ type: "set_repo", repo, weight }, "", {}, []);
+    }
+    /** Admins of dev and test chains only (elsewhere: a governance proposal). `soul` in Soul ("2.5"), up to 100 per grant. */
+    async grantSoul(to, soul, reason) {
+        return this.submitQueued({ type: "grant_soul", to: (await this.client.recipient(to)).signed, amount: parseSoul(soul), reason }, "", {}, []);
+    }
+    /** Admins of dev and test chains only (elsewhere: a governance proposal). */
+    async rejectClaim(claimId, reason) {
+        return this.submitQueued({ type: "reject_claim", claim_id: claimId, reason }, "", {}, []);
+    }
+    /** Admins of dev and test chains only (elsewhere: a governance proposal). */
+    async flagSybil(account, reason) {
+        return this.submitQueued({ type: "flag_sybil", account: (await this.client.recipient(account)).signed, reason }, "", {}, []);
+    }
+    /** Admins of dev and test chains only (elsewhere: a governance proposal). */
+    async clawback(account, reason) {
+        return this.submitQueued({ type: "clawback", account: (await this.client.recipient(account)).signed, reason }, "", {}, []);
     }
     /** Reclaim the bond of a removed validator this account owns. */
     async unbond(validator) {
-        return this.client.submit(await this.build({ type: "unbond", validator }));
+        return this.submitQueued({ type: "unbond", validator }, "", {}, []);
+    }
+    // ---- protocol v1 (tags 30–49). Each builds, signs and submits one tx and waits for it. ----
+    /** Submits one action (the shared tail of the helpers below); `unproven`: see `buildChecked`. */
+    async act(action, opts = {}, unproven = []) {
+        return this.submitQueued(action, opts.memo ?? "", opts, unproven);
+    }
+    /**
+     * A validator by address, or by a `.boo` name its account holds. Staking needs the address, so
+     * a name is resolved (proven with the client's witnesses); on mainnet a tx with an unproven one
+     * isn't signed (audit gap-7-1): pass the validator's address.
+     */
+    async validatorAddress(validator) {
+        return this.addressNeeded(await this.client.resolution(validator));
+    }
+    /** `r`, unless it's an unproven name on mainnet (`UnprovenNameError`); `buildChecked` checks again against the signing status. */
+    async addressNeeded(r) {
+        if (!r.proven && (await this.client.status()).chain_id === MAINNET_CHAIN_ID)
+            throw new UnprovenNameError(r, this.client.rpc);
+        return r;
+    }
+    /** Stake `amount` (FANG, or bigint drops) in a validator's pool. Your stake earns its share of issuance and is slashed with the pool. */
+    async delegate(validator, amount, opts = {}) {
+        const v = await this.validatorAddress(validator);
+        return this.act({ type: "delegate", validator: v.address, amount: positive(parseFang(amount), "delegate").toString() }, opts, [v]);
+    }
+    /**
+     * Start unbonding stake in a validator's pool: `{ amount }` (FANG, or bigint drops), `shares`,
+     * or `"all"` (every share you hold there, read from `/api/staking`). An amount is signed as an
+     * amount and the chain converts it at the pool's price when the tx runs, so no node's report of
+     * the stake decides how much unbonds (audit gap-7-5); prefer it to `sharesFor`. It stops
+     * earning now and can be withdrawn with `withdrawUnbonded` once the unbonding period (21 days
+     * on mainnet) is over.
+     */
+    async undelegate(validator, shares, opts = {}) {
+        const v = await this.validatorAddress(validator);
+        if (typeof shares === "object" && shares !== null)
+            return this.act({ type: "undelegate", validator: v.address, shares: "0", amount: positive(parseFang(shares.amount), "undelegate").toString() }, opts, [v]);
+        return this.act({ type: "undelegate", validator: v.address, shares: (await this.sharesOf(v.address, shares)).toString() }, opts, [v]);
+    }
+    /** Move `shares` (or `"all"`) from one pool to another without waiting out the unbonding period. */
+    async redelegate(fromValidator, toValidator, shares, opts = {}) {
+        const [from, to] = await Promise.all([this.validatorAddress(fromValidator), this.validatorAddress(toValidator)]);
+        if (from.address === to.address)
+            throw new Error("redelegate to a different validator");
+        return this.act({ type: "redelegate", from_validator: from.address, to_validator: to.address, shares: (await this.sharesOf(from.address, shares)).toString() }, opts, [from, to]);
+    }
+    /** Pay out every unbonding entry that has finished unbonding. */
+    async withdrawUnbonded(opts = {}) {
+        return this.act({ type: "withdraw_unbonded" }, opts);
+    }
+    /** A validator's owner: set the pool's commission (basis points, 0–10000; it moves a little per epoch at most) and, optionally, new addresses. */
+    async updateValidator(opts) {
+        if (!Number.isInteger(opts.commissionBps) || opts.commissionBps < 0 || opts.commissionBps > 10_000)
+            throw new Error("commissionBps must be a whole number from 0 to 10000");
+        return this.act({ type: "update_validator", commission_bps: opts.commissionBps, p2p_addr: opts.p2pAddr ?? "", http_addr: opts.httpAddr ?? "" }, opts);
+    }
+    /** Bring a jailed validator back (its owner, after the jail period). */
+    async unjail(validator, opts = {}) {
+        const v = await this.validatorAddress(validator);
+        return this.act({ type: "unjail", validator: v.address }, opts, [v]);
+    }
+    /** Low-level (nodes do this automatically): two conflicting signed votes, hex-encoded as the node's evidence reporter emits them. */
+    async reportEquivocation(evidenceHex, opts = {}) {
+        if (!/^([0-9a-f]{2})+$/.test(evidenceHex) || evidenceHex.length > 2 * 16 * 1024)
+            throw new Error("evidence must be 1–16384 bytes of lowercase hex");
+        return this.act({ type: "report_equivocation", evidence: evidenceHex }, opts);
+    }
+    /** Low-level (validator nodes do this automatically): commit to a beacon secret for `epoch`. */
+    async beaconCommit(epoch, commitmentHex, opts = {}) {
+        return this.act({ type: "beacon_commit", epoch: wholeNumber(epoch, "epoch"), commitment: hexArg(commitmentHex, "commitment") }, opts);
+    }
+    /** Low-level (validator nodes do this automatically): reveal the beacon secret committed for `epoch`. */
+    async beaconReveal(epoch, secretHex, opts = {}) {
+        return this.act({ type: "beacon_reveal", epoch: wholeNumber(epoch, "epoch"), secret: hexArg(secretHex, "secret") }, opts);
+    }
+    /**
+     * A member of a set of one or two, signing with its consensus key: admit candidate `validator`
+     * into the set at the end of `epoch` (default: the epoch the next block is in; the tx fails in
+     * any other). The newcomer will be needed for every quorum, so this is the operator's decision,
+     * once an epoch per member; it joins once a quorum of the members admitted it and its node
+     * showed up (`validatorReady`).
+     */
+    async admitValidator(validator, opts = {}) {
+        const [v, epoch] = await Promise.all([this.validatorAddress(validator), opts.epoch ?? this.client.status().then((s) => s.epoch)]);
+        return this.act({ type: "admit_validator", validator: v.address, epoch: wholeNumber(epoch, "epoch") }, opts, [v]);
+    }
+    /** Low-level (candidate nodes do this automatically, in the epoch's last tenth, once a set of one or two admitted them): a candidate's consensus key signals its node is running in `epoch`. */
+    async validatorReady(epoch, opts = {}) {
+        return this.act({ type: "validator_ready", epoch: wholeNumber(epoch, "epoch") }, opts);
+    }
+    /**
+     * Put a proposal to a vote (build `kind` with `proposal.*`). Bonds `deposit` (default: the
+     * chain's `proposal_deposit`), refunded once the proposal reaches quorum and burned if it
+     * doesn't. Names in the kind (`to`, `account`) are signed as `Client.recipient` says: the proven
+     * address with witnesses, else the name, which the chain resolves when the proposal is made
+     * (it stores the address, which voters then see and bind).
+     *
+     * The default deposit is what the node reports, and a node can report anything, so it's
+     * bounded (audit gap-7-5): every witness of the client must report the same value, and it may
+     * be at most `maxDeposit` (default `DEFAULT_MAX_PROPOSAL_DEPOSIT`, mainnet's 1,000 FANG).
+     * Pass `deposit` to bond an amount you checked yourself.
+     */
+    async propose(kind, opts) {
+        const title = opts.title.trim();
+        if (!title || new TextEncoder().encode(title).length > 96 || /\p{Cc}/u.test(title))
+            throw new Error("title must be 1–96 bytes with no control characters");
+        const url = opts.url ?? "";
+        if (url && (!url.startsWith("https://") || url.length > 200 || /\s|\p{Cc}/u.test(url)))
+            throw new Error("url must be an https:// link of at most 200 bytes");
+        let deposit;
+        if (opts.deposit !== undefined)
+            deposit = parseFang(opts.deposit);
+        else {
+            const reported = await Promise.all([this.client, ...this.client.witnesses].map(async (c) => paramsOf(await c.params()).proposal_deposit));
+            const d = reported[0];
+            if (d === undefined)
+                throw new Error("this node doesn't report proposal_deposit; pass deposit");
+            if (reported.some((x) => x !== d))
+                throw new Error(`the node and its witnesses disagree about proposal_deposit (${reported.map((x) => (x === undefined ? "none" : formatFang(x))).join(", ")}); pass deposit`);
+            deposit = BigInt(d);
+            const max = opts.maxDeposit !== undefined ? parseFang(opts.maxDeposit) : DEFAULT_MAX_PROPOSAL_DEPOSIT;
+            if (deposit > max)
+                throw new Error(`${this.client.rpc} reports a proposal_deposit of ${formatFang(deposit)}, more than maxDeposit (${formatFang(max)}): a node can report any deposit, and all of it is burned if the vote misses quorum. Check it on another node, then pass deposit (or a higher maxDeposit)`);
+        }
+        return this.act({ type: "propose", kind: await this.resolveKind(kind), deposit: positive(deposit, "deposit").toString(), title, url }, opts);
+    }
+    /**
+     * Vote on a proposal with `amount` of your unlocked holdings (liquid, staked or unbonding;
+     * unvested tokens can't vote). `conviction` 0–6 locks `amount` for 0, 1, 2, 4, 8, 16 or 32 lock
+     * periods after the vote ends, for 0.1×, 1×, 2× … 6× the weight (see `convictionWeight`).
+     * Voting again replaces your vote. A validator's consensus key or owner voting before the
+     * bootstrap council ends also casts that validator's council vote.
+     *
+     * The vote binds the proposal's content (audit gap-7-6): pass `proposal`, the kind, title and
+     * link you showed the voter (e.g. the `client.proposal(id)` object you rendered, described with
+     * `describeKind`), or it's read from the client. A node that showed another proposal's content
+     * makes the vote fail. If you showed it earlier and only kept its digest
+     * (`proposalSummary(raw).digest`), pass `digest`: a proposal that reads differently now is
+     * refused before anything is signed.
+     */
+    async vote(proposalId, aye, amount, conviction = 1, opts = {}) {
+        if (!Number.isInteger(conviction) || conviction < 0 || conviction > MAX_CONVICTION)
+            throw new Error(`conviction must be 0–${MAX_CONVICTION}`);
+        const id = wholeNumber(proposalId, "proposalId");
+        const drops = positive(parseFang(amount), "vote").toString();
+        const p = opts.proposal ?? (await this.client.proposal(id));
+        const proposal_digest = proposalDigest(p.kind, p.title, p.url ?? "");
+        shownDigest(opts.digest, proposal_digest, `proposal #${id}`);
+        return this.act({ type: "vote", proposal_id: id, aye, amount: drops, conviction, proposal_digest }, opts);
+    }
+    /** Release every vote lock that has expired. */
+    async unlock(opts = {}) {
+        return this.act({ type: "unlock" }, opts);
+    }
+    /**
+     * Make this account an M-of-N multisig of its owner keys (`ownerKeyIds`): owner-only actions
+     * then need `multisigPropose` plus approvals up to `threshold`. Session keys keep working
+     * within their limits.
+     */
+    async multisigCreate(ownerKeyIds, threshold, opts = {}) {
+        const owners = ownerKeyIds.map((k) => k.trim().toLowerCase());
+        if (owners.length === 0 || owners.length > 16 || owners.some((k) => !/^[0-9a-f]{64}$/.test(k)))
+            throw new Error("owners must be 1–16 key ids (64 hex characters)");
+        if (new Set(owners).size !== owners.length)
+            throw new Error("owners must be distinct");
+        if (!Number.isInteger(threshold) || threshold < 1 || threshold > owners.length)
+            throw new Error(`threshold must be 1–${owners.length} (the number of owners)`);
+        return this.act({ type: "multisig_create", owners, threshold }, opts);
+    }
+    /** Propose an action for this multisig account; it runs once enough owners approve. */
+    async multisigPropose(action, opts = {}) {
+        if (action.type === "multisig_propose" || action.type === "multisig_approve")
+            throw new Error("a multisig proposal can't hold another multisig proposal or approval");
+        return this.act({ type: "multisig_propose", action }, opts);
+    }
+    /**
+     * Approve open multisig proposal `id`. The approval binds the action (audit gap-7-6): pass
+     * `action`, the one you showed the approver (decode it and describe it with `describeAction`,
+     * don't trust a summary), or it's read from `client.multisig(account)`. A node that showed
+     * another action makes the approval fail. `digest`: the `actionDigest` of what you showed, if
+     * that's all you kept; an action that reads differently now is refused before anything is signed.
+     * A `vote` binds its proposal by digest, not by id: show it with `reviewAction(action, {
+     * proposal: await client.proposal(action.proposal_id) })`, which describes the proposal only if
+     * its content has that digest, and don't offer the approval unless it's `readable` (gap-7-6).
+     * Pass that proposal read as `proposal` here: approving a vote is refused, before anything is
+     * signed, unless the proposal shown (else one read now) has exactly the content the vote binds.
+     * The approval counts on this wallet's account (`actAs`), which the digest doesn't bind: on
+     * mainnet act for an address you checked, not a name one node resolved.
+     */
+    async multisigApprove(id, opts = {}) {
+        const n = wholeNumber(id, "id");
+        let action = opts.action;
+        if (!action) {
+            const m = await this.client.multisig(this.account);
+            action = (Array.isArray(m?.pending) ? m.pending : []).find((p) => p.id === n)?.action;
+            if (!action)
+                throw new Error(`${this.account} has no open multisig action #${n}`);
+        }
+        const action_digest = actionDigest(action);
+        shownDigest(opts.digest, action_digest, `multisig action #${n}`);
+        if (action.type === "vote") {
+            // What the ballot backs is the proposal whose content has its digest, whatever the node
+            // calls #id (audit gap-7-6): a node can't make other content hash to it.
+            const proposal = opts.proposal ?? (await this.client.proposal(action.proposal_id).catch(() => undefined));
+            const review = reviewAction(action, { proposal, freeText: false });
+            if (!review.readable)
+                throw new Error(`multisig action #${n} can't be approved from here: ${review.does}. Nothing was signed`);
+        }
+        return this.act({ type: "multisig_approve", id: n, action_digest }, opts);
+    }
+    /** Extend a name you own by `years` (1–10), at the chain's renewal price per year. */
+    async renewName(name, years = 1, opts = {}) {
+        if (!Number.isInteger(years) || years < 1 || years > 10)
+            throw new Error("renew for 1–10 years");
+        return this.act({ type: "renew_name", name: bareName(name), years }, opts);
+    }
+    /**
+     * Offer a name you own to another account (a `.boo` name or address, signed as `Client.recipient` says). It
+     * stays yours until they accept it (`acceptName`); offering it again replaces the offer, and
+     * `withdrawNameOffer` withdraws it. Nobody can be given a name without saying yes.
+     */
+    async transferName(name, to, opts = {}) {
+        return this.act({ type: "transfer_name", name: bareName(name), to: (await this.client.recipient(to)).signed }, opts);
+    }
+    /** Accept a name offered to the account you act for (`client.name(n).offered_to`): it becomes yours. */
+    async acceptName(name, opts = {}) {
+        return this.act({ type: "transfer_name", name: bareName(name), to: this.account }, opts);
+    }
+    /** Withdraw your offer of a name you own (the same tx as `acceptName`: the chain tells them apart by who owns the name). */
+    async withdrawNameOffer(name, opts = {}) {
+        return this.acceptName(name, opts);
+    }
+    /** Give up a name you own; anyone can register it afterwards. */
+    async releaseName(name, opts = {}) {
+        return this.act({ type: "release_name", name: bareName(name) }, opts);
+    }
+    /** Claim your share of a community distribution with the Merkle proof published alongside it (hex hashes). */
+    async claimDistribution(distributionId, amount, proof, opts = {}) {
+        if (proof.length > 64)
+            throw new Error("proof too long (max 64 hashes)");
+        return this.act({ type: "claim_distribution", distribution_id: wholeNumber(distributionId, "distributionId"), amount: positive(parseFang(amount), "claim").toString(), proof: proof.map((h) => hexArg(h, "proof")) }, opts);
+    }
+    /** Low-level (validator nodes do this automatically): a matured claim's PR was reverted by commit `revertSha`. */
+    async attestRevert(claimId, revertSha, opts = {}) {
+        if (!/^[0-9a-f]{40}$/.test(revertSha))
+            throw new Error("revertSha must be the 40-hex revert commit");
+        return this.act({ type: "attest_revert", claim_id: wholeNumber(claimId, "claimId"), revert_sha: revertSha }, opts);
+    }
+    // ---- programs (protocol v2: tags 62, 63, 64 and 69; docs/PROGRAMS-V0.md §8.4). Third-party WebAssembly: every node answer is
+    // checked before it's used (programs.ts), fuel is priced at the node's suggested rate and refused when no block could carry it,
+    // and nothing is signed that the user wasn't shown the digest of. Upload, create and call are one step per block (§2.1): each
+    // waits for what it needs to be usable instead of being refused by the mempool. ----
+    /** The chain's fuel prices, with programs required to be on (`ProgramsOffError`) and to admit this kind of transaction now. */
+    async programsFor(kind, sendsValue) {
+        const fuel = await this.client.programFuel();
+        checkProgramsStatus(fuel, kind, sendsValue);
+        return fuel;
+    }
+    /** Waits (up to `waitMs`) for the node's head to pass `height`: what block `height` stored is usable from the next one (§2.1). */
+    async waitPast(height, waitMs, what) {
+        const until = Date.now() + waitMs;
+        for (;;) {
+            const head = (await this.client.status()).height;
+            if (!Number.isSafeInteger(head) || head < 0)
+                throw new Error(`${this.client.rpc} doesn't report its height`);
+            this.client.checkHeightClock(head);
+            if (head > height)
+                return;
+            if (Date.now() > until)
+                throw new Error(`${what} is final in block ${height}, but ${this.client.rpc} hasn't sealed the block after it in ${waitMs} ms, so it can't be used yet: check again shortly`);
+            await sleep(250);
+        }
+    }
+    /**
+     * Runs what follows a transaction that was submitted and is final, saying so if it fails: `what` names
+     * the transaction (its id, and what it made), which was sent and ran, so the failure is of the receipt,
+     * the wait or the read after it, and the transaction must not be sent again. The typed error stays
+     * as `cause`; its reason is quoted stripped of hidden characters (it may hold a node's text). `what` may be a function
+     * so the name can grow as `run` learns more (the address a create made).
+     */
+    async finalThen(what, run) {
+        try {
+            return await run();
+        }
+        catch (e) {
+            const reason = plainText(String(e?.message ?? e)).slice(0, 600);
+            throw new Error(`${typeof what === "string" ? what : what()} was sent and is final: it already ran, so don't send it again. What came after it failed: ${reason}`, { cause: e });
+        }
+    }
+    /**
+     * Waits (up to `waitMs`) until `read` finds what it names (`null`: not there yet) stored in a block
+     * before the node's head, which is when it's usable (§2.1: a create, or a call, signed earlier is
+     * refused by the mempool). Says what was waited for if it never is.
+     */
+    async waitUsable(what, waitMs, read) {
+        const until = Date.now() + waitMs;
+        let seen = null;
+        for (;;) {
+            const r = await read();
+            if (r && r.stored !== null) {
+                seen = r.stored;
+                const head = (await this.client.status()).height;
+                if (!Number.isSafeInteger(head) || head < 0)
+                    throw new Error(`${this.client.rpc} doesn't report its height`);
+                this.client.checkHeightClock(head);
+                if (r.stored < head)
+                    return r.found;
+            }
+            if (Date.now() > until)
+                throw new Error(`${what} isn't usable after ${waitMs} ms: ${seen === null ? "it isn't stored (upload or create it first)" : `it was stored in block ${seen}, and is usable from the block after it`}. Nothing was signed`);
+            await sleep(250);
+        }
+    }
+    /** A program as a call needs it: usable (stored in an earlier block), its digest recomputed from its own record, and proven against the client's witnesses when it has some. */
+    async programForCall(address, waitMs) {
+        const info = await this.waitUsable(`the program ${address}`, waitMs, async () => {
+            try {
+                const p = await this.client.program(address);
+                return { stored: p.created_at, found: p };
+            }
+            catch (e) {
+                if (e instanceof ApiError && e.status === 404)
+                    return null;
+                throw e;
+            }
+        });
+        if (info.code.size === null)
+            throw new ProgramAnswerError(this.client.rpc, `GET /api/program/${address}`, "code.size", "is missing: the code's load can't be priced");
+        if (this.client.witnesses.length) {
+            const proven = await this.client.provenProgram(address, { witnesses: this.client.witnesses });
+            if (!proven)
+                throw new Error(`${address} isn't a program: its record is provably absent (proven against ${this.client.witnesses.length} witness${this.client.witnesses.length === 1 ? "" : "es"}), whatever ${this.client.rpc} says. Nothing was signed`);
+            if (proven.version_digest !== info.version_digest || proven.wasm_hash !== info.code.wasm_hash || proven.interface_hash !== info.code.interface_hash)
+                throw new Error(`${this.client.rpc} and its witnesses disagree about the code at ${address}: the proven record's digest is ${proven.version_digest.slice(0, 16)}…, the node says ${info.version_digest.slice(0, 16)}…. Nothing was signed`);
+        }
+        return { info, digest: info.version_digest };
+    }
+    /**
+     * The bindings of a transaction (`ProgramBindingInput`s): each program read (usable, checked, proven
+     * with witnesses), its version digest filled with the version in force now when none is given (never
+     * "any version", 64 zeros, unless asked: `ANY_PROGRAM_VERSION`), and its code added to `declared`,
+     * which load fuel is counted on.
+     */
+    async resolveBindings(bindings, declared, waitMs) {
+        if (!Array.isArray(bindings) || bindings.length > MAX_PROGRAM_BINDINGS)
+            throw new Error(`a transaction binds at most ${MAX_PROGRAM_BINDINGS} programs`);
+        const out = [];
+        for (const b of bindings) {
+            const program = programAddressArg(b.program, "a binding");
+            if (out.some((o) => o.program === program))
+                throw new Error(`${program} is bound twice`);
+            const { info, digest } = await this.programForCall(program, waitMs);
+            const given = b.versionDigest === undefined ? undefined : programHashArg(b.versionDigest, "a binding's version digest");
+            if (given !== undefined && given !== ANY_PROGRAM_VERSION)
+                shownDigest(given, digest, `the program ${program}`);
+            declared.set(info.code.wasm_hash, info.code.size);
+            out.push({ program, version_digest: given ?? digest });
+        }
+        return out;
+    }
+    /**
+     * Signs and submits a program transaction (reserving `reservation` fuel: its fee is priced with it),
+     * waits for it, checks its receipt (programs.ts `checkReceipt`) and returns it with what it cost.
+     * One that ran and failed throws `ProgramFailedError` (its fee was charged; `storageLimit` names
+     * the limit it signed, for the hint a `storage_limit` trap needs).
+     *
+     * Once the transaction is submitted and the node reports it final, **every failure says so**
+     * (`finalThen`): a receipt or answer that doesn't check isn't "nothing happened, ask another node",
+     * since the transaction ran, and a payable call sent again pays twice. The typed error is the `cause`.
+     */
+    async sendProgram(kind, action, reservation, opts, storageLimit) {
+        let signed;
+        let done;
+        try {
+            done = await this.submitQueued(action, "", { ...opts, wait: true, reserved: reservation, onSigned: async (tx, id) => { signed = tx; await opts.onSigned?.(tx, id); } }, []);
+        }
+        catch (e) {
+            if (e instanceof TxFailedError && !e.dropped)
+                throw programFailure(this.client.rpc, e, storageLimit);
+            throw e;
+        }
+        const tx = signed;
+        const id = tx ? txId(tx) : "(its id wasn't seen here)";
+        return this.finalThen(`the ${kind} (tx ${id})`, async () => {
+            if (!tx)
+                throw new Error("a program transaction was submitted without being signed here");
+            if (done?.id !== id)
+                throw new ProgramAnswerError(this.client.rpc, `GET /api/tx/${id}`, "id", `isn't the transaction that was submitted (${plainText(String(done?.id)).slice(0, 16)})`);
+            const receipt = checkReceipt(this.client.rpc, done);
+            if (!receipt)
+                throw new ProgramAnswerError(this.client.rpc, `GET /api/tx/${id}`, "program", "is null for a transaction that is final: it should hold its receipt");
+            if (receipt.kind !== kind)
+                throw new ProgramAnswerError(this.client.rpc, `GET /api/tx/${id}`, "program.kind", `is ${receipt.kind}, not ${kind}`);
+            if (!receipt.outcome.ok)
+                throw new ProgramAnswerError(this.client.rpc, `GET /api/tx/${id}`, "program.outcome", "says it failed for a transaction that is final");
+            if (!Number.isSafeInteger(done.height) || done.height < 0)
+                throw new ProgramAnswerError(this.client.rpc, `GET /api/tx/${id}`, "height", "isn't a block height");
+            this.client.checkHeightClock(done.height);
+            return { tx: done, receipt, cost: programCost(receipt, tx.from), signed: tx };
+        });
+    }
+    /**
+     * Uploads a program's code (WebAssembly 1.0) and its interface (format 1: `blockula program interface
+     * encode`, or the `.iface` files beside the guests), bonding a storage deposit for each that isn't
+     * stored yet: the deposit at today's price (`programUploadDeposit`), which v0 never gives back. `storageLimit`
+     * (FANG, default that deposit plus 10%) is the most the upload may bond; below the deposit it's
+     * refused before signing, as the upload would fail and still be charged. Fuel is priced at the
+     * node's suggested rate. Resolves once the upload is final **and the block after it has been sealed**,
+     * when the code is usable (a create signed sooner is refused, §2.1), with its receipt and what it
+     * cost: the fee, and the deposit, which `receipt.facts.outside_vm` holds apart from the VM's diff.
+     */
+    async uploadCode(wasm, iface, opts = {}) {
+        const code = programBytesArg(wasm, "the code", MAX_PROGRAM_CODE_BYTES);
+        const interfaceBytes = programBytesArg(iface, "the interface", MAX_PROGRAM_INTERFACE_BYTES);
+        const waitMs = programWaitMs(opts.waitMs);
+        const [wasm_hash, interface_hash] = [wasmHash(code), interfaceHash(interfaceBytes)];
+        const fuel = await this.programsFor("upload", false);
+        const params = await this.client.programParams();
+        // What's stored already bonds nothing again (an upload of stored blobs only refreshes them). That's one node's word, so it only
+        // says what deposit to expect: the limit defaults to the deposit as if both blobs were new, a ceiling the chain bonds only
+        // what's new against, which a node that says "already stored" can't lower (it'd make the upload fail, and charge its fee).
+        const stored = async (read) => read().then(() => true, (e) => (e instanceof ApiError && e.status === 404 ? false : Promise.reject(e)));
+        const [codeStored, interfaceStored] = await Promise.all([stored(() => this.client.code(wasm_hash)), stored(() => this.client.interface(interface_hash))]);
+        const deposit = programUploadDeposit(fuel, params, [{ size: code.length, isNew: !codeStored }, { size: interfaceBytes.length, isNew: !interfaceStored }]);
+        if (deposit === null)
+            throw new Error("program state is full: nothing more can be stored at any price. Nothing was signed");
+        const ceiling = programUploadDeposit(fuel, params, [{ size: code.length, isNew: true }, { size: interfaceBytes.length, isNew: true }]) ?? deposit;
+        const storageLimit = opts.storageLimit === undefined ? depositWithMargin(ceiling) : checkedDrops(parseFang(opts.storageLimit), "storageLimit");
+        if (storageLimit < deposit)
+            throw new Error(`storageLimit ${formatFang(storageLimit)} is below the deposit ${formatFang(deposit)} at today's price: the upload would fail and still be charged its fee. Nothing was signed`);
+        // An upload reserves its own validation, test translation and hashing (§5.1), priced by its size.
+        const reservation = reserveFuel(fuel, uploadFuel(code.length, interfaceBytes.length), new Map(), false);
+        const action = { type: "upload_code", wasm: bytesToHex(code), interface: bytesToHex(interfaceBytes), storage_limit: storageLimit.toString() };
+        const { tx, receipt, cost } = await this.sendProgram("upload", action, reservation, opts, storageLimit);
+        return this.finalThen(`the upload (tx ${tx.id})`, async () => {
+            const upload = receipt.facts.upload;
+            if (!upload || upload.wasm_hash !== wasm_hash || upload.interface_hash !== interface_hash)
+                throw new ProgramAnswerError(this.client.rpc, `GET /api/tx/${tx.id}`, "program.facts.upload", "isn't the code and interface that were uploaded");
+            await this.waitPast(tx.height, waitMs, "the upload");
+            return { wasmHash: wasm_hash, interfaceHash: interface_hash, deposit: upload.deposit, tx, receipt, cost };
+        });
     }
-    balance() {
-        return this.client.account(this.account).then((a) => a.balance_display, () => "0 FANG");
+    /**
+     * Creates a program from stored code and interface (`uploadCode`'s hashes), at the address made from
+     * this account and the transaction's nonce, which is returned **only once the create has applied**
+     * and the block after it has been sealed (the program is then usable), never predicted ahead of it:
+     * FANG sent to a program's address before its create is final is stranded for good if the create
+     * fails (§2.3). It first waits for the code and interface to be usable (an upload a block ago).
+     *
+     * `init` runs the interface's `Init` method with its `input` and `value`, present exactly when the
+     * interface declares one; it runs under `fuelLimit` (default `program_max_tx_fuel`, 0 without `init`).
+     * `storageLimit` (FANG) is the most the record's deposit and what the initializer's writes bond may
+     * be: default the record's deposit plus 10%, which a program whose initializer writes needs more than.
+     * `authority` (an address, never a name) may upgrade it once a protocol version adds upgrades, with
+     * `delayBlocks` of notice (default and least: `program_min_upgrade_delay_blocks`) and an upgrade
+     * `policy`; without one the program is immutable. `bindings` are programs the initializer may reach.
+     * The receipt's `outside_vm` holds the record deposit and the account creation fee the create burns
+     * when the program's address held no account yet.
+     */
+    async createProgram(opts) {
+        const wasm_hash = programHashArg(opts.wasmHash, "wasmHash");
+        const interface_hash = programHashArg(opts.interfaceHash, "interfaceHash");
+        const waitMs = programWaitMs(opts.waitMs);
+        const init = opts.init;
+        const initMethod = init === undefined ? undefined : programMethodArg(init.method);
+        const initValue = checkedDrops(parseFang(init?.value ?? 0n), "init.value");
+        if (init === undefined && (opts.fuelLimit !== undefined || opts.bindings?.length))
+            throw new Error("fuelLimit and bindings are an initializer's: pass `init`, or leave them out");
+        if (opts.authority === undefined && (opts.delayBlocks !== undefined || opts.policy !== undefined))
+            throw new Error("delayBlocks and policy are an upgrade authority's: pass `authority` (an immutable program has neither)");
+        const authority = opts.authority === undefined ? null : programAddressArg(opts.authority, "an upgrade authority");
+        const fuel = await this.programsFor("create", initValue > 0n);
+        const params = await this.client.programParams();
+        const stored = (read) => async () => {
+            try {
+                const r = await read();
+                return { stored: r.uploaded_at, found: r };
+            }
+            catch (e) {
+                if (e instanceof ApiError && e.status === 404)
+                    return null;
+                throw e;
+            }
+        };
+        // Both blobs usable: stored in an earlier block (the upload may be a block away).
+        const code = await this.waitUsable("the code", waitMs, stored(() => this.client.code(wasm_hash)));
+        const iface = await this.waitUsable("the interface", waitMs, stored(() => this.client.interface(interface_hash)));
+        // The interface says whether it has an initializer (the node's reading of its bytes; the chain enforces it either way).
+        const methods = iface.untrusted_interface?.methods;
+        if (Array.isArray(methods)) {
+            const declares = methods.some((m) => m?.kind === "init");
+            if (declares && init === undefined)
+                throw new Error("this interface declares an initializer, so the create must run it: pass `init`. Nothing was signed");
+            if (!declares && init !== undefined)
+                throw new Error("this interface declares no initializer, so `init` has none to run. Nothing was signed");
+        }
+        const declared = new Map();
+        if (init !== undefined)
+            declared.set(wasm_hash, code.size);
+        const bindings = await this.resolveBindings(opts.bindings ?? [], declared, waitMs);
+        const fuelLimit = init === undefined ? 0n : opts.fuelLimit === undefined ? defaultFuelLimit(fuel, declared) : BigInt(positiveFuel(opts.fuelLimit));
+        const reservation = reserveFuel(fuel, fuelLimit, declared);
+        const delay = authority === null ? 0 : opts.delayBlocks ?? params.min_upgrade_delay_blocks;
+        if (authority !== null && (!Number.isSafeInteger(delay) || delay < params.min_upgrade_delay_blocks))
+            throw new Error(`delayBlocks ${delay} is below program_min_upgrade_delay_blocks (${params.min_upgrade_delay_blocks}): an upgradable program gives at least that much notice. Nothing was signed`);
+        const policy = authority === null ? "open" : opts.policy ?? "open";
+        if (policy !== "open" && policy !== "additive")
+            throw new Error(`policy is "open" or "additive", not ${JSON.stringify(policy)}`);
+        const record = programRecordDeposit(fuel, params);
+        if (record === null)
+            throw new Error("program state is full: nothing more can be stored at any price. Nothing was signed");
+        const storageLimit = opts.storageLimit === undefined ? depositWithMargin(record) : checkedDrops(parseFang(opts.storageLimit), "storageLimit");
+        if (storageLimit < record)
+            throw new Error(`storageLimit ${formatFang(storageLimit)} is below the record deposit ${formatFang(record)} at today's price: the create would fail and still be charged its fee. Nothing was signed`);
+        const action = {
+            type: "create_program",
+            wasm_hash,
+            interface_hash,
+            authority,
+            upgrade_delay_blocks: delay,
+            policy,
+            accepts_transfers: opts.acceptsTransfers === true,
+            init: init === undefined ? null : { method: initMethod, input: programInputArg(init.input ?? ""), value: initValue.toString() },
+            fuel_limit: Number(fuelLimit),
+            storage_limit: storageLimit.toString(),
+            bindings,
+        };
+        const { tx, receipt, cost, signed } = await this.sendProgram("create", action, reservation, opts, storageLimit);
+        // The address this transaction makes is its sender's and its nonce's: what the receipt names must be that one.
+        let what = `the create (tx ${tx.id})`;
+        return this.finalThen(() => what, async () => {
+            const address = programAddress(signed.from, signed.nonce, await this.client.addressPrefix());
+            what = `the create (tx ${tx.id}), which made ${address},`;
+            if (receipt.facts.created !== address)
+                throw new ProgramAnswerError(this.client.rpc, `GET /api/tx/${tx.id}`, "program.facts.created", `names ${String(receipt.facts.created)}, not ${address}, the program this create makes`);
+            await this.waitPast(tx.height, waitMs, "the create");
+            const program = await this.client.program(address);
+            if (program.code.wasm_hash !== wasm_hash || program.code.interface_hash !== interface_hash)
+                throw new ProgramAnswerError(this.client.rpc, `GET /api/program/${address}`, "code", "isn't the code and interface this create named");
+            return { address, program, tx, receipt, cost };
+        });
+    }
+    /**
+     * Calls programs: 1 to 8 calls run in order, all or nothing, sharing `fuelLimit` (default
+     * `program_max_tx_fuel`) and `storageLimit` (FANG): **the default is 0, which consents to no new
+     * storage**, so a call whose writes bond a deposit traps `storage_limit` and still pays its fee
+     * (`ProgramFailedError` says so): pass a limit for any method that writes.
+     *
+     * Each call binds the `versionDigest` of the program it's calling: when you pass the digest you
+     * showed the user (`ProgramCallInput.versionDigest`) the call is refused if the program's code,
+     * interface or version isn't the one that digest names; without it, it's recomputed from the
+     * program's record (proven against the client's witnesses when it has any), never taken from the
+     * node's `version_digest`. Fuel is priced at the node's suggested rate on what's reserved (fuel to
+     * run, plus the load of the code the calls and `bindings` declare) and refused when no block
+     * could carry it (`FuelReservationError`). Waits for each program to be usable (created a block ago).
+     * The receipt's `claims` are what the programs say happened: the chain checks none of it.
+     */
+    async callProgram(calls, opts = {}) {
+        if (!Array.isArray(calls) || calls.length < 1 || calls.length > MAX_PROGRAM_CALLS)
+            throw new Error(`a call_program runs 1 to ${MAX_PROGRAM_CALLS} calls`);
+        const waitMs = programWaitMs(opts.waitMs);
+        const parsed = calls.map((c, i) => ({
+            program: programAddressArg(c.program, `call ${i + 1}'s program`),
+            method: programMethodArg(c.method),
+            input: programInputArg(c.input ?? ""),
+            value: checkedDrops(parseFang(c.value ?? 0n), `call ${i + 1}'s value`),
+            shown: c.versionDigest === undefined ? undefined : programHashArg(c.versionDigest, `call ${i + 1}'s versionDigest`),
+        }));
+        const fuel = await this.programsFor("call", parsed.some((c) => c.value > 0n));
+        const declared = new Map();
+        const read = new Map();
+        const signed = [];
+        for (const c of parsed) {
+            let p = read.get(c.program);
+            if (!p)
+                read.set(c.program, (p = await this.programForCall(c.program, waitMs)));
+            if (c.shown !== undefined)
+                shownDigest(c.shown, p.digest, `the program ${c.program}`);
+            declared.set(p.info.code.wasm_hash, p.info.code.size);
+            signed.push({ program: c.program, version_digest: p.digest, method: c.method, input: c.input, value: c.value.toString() });
+        }
+        const bindings = await this.resolveBindings(opts.bindings ?? [], declared, waitMs);
+        const fuelLimit = opts.fuelLimit === undefined ? defaultFuelLimit(fuel, declared) : BigInt(positiveFuel(opts.fuelLimit));
+        const reservation = reserveFuel(fuel, fuelLimit, declared);
+        const storageLimit = opts.storageLimit === undefined ? 0n : checkedDrops(parseFang(opts.storageLimit), "storageLimit");
+        const action = { type: "call_program", calls: signed, fuel_limit: Number(fuelLimit), storage_limit: storageLimit.toString(), bindings };
+        const { tx, receipt, cost } = await this.sendProgram("call", action, reservation, opts, storageLimit);
+        return { tx, receipt, cost };
+    }
+    /**
+     * One call: `program`'s `method` (a `call` method of its interface; read a `view` with
+     * `client.view`) with `input` (bytes, or lowercase hex) and `value` FANG attached (only to a
+     * payable method). It reads the program first, so a method its interface doesn't have, a view,
+     * an initializer, or FANG sent to a method that isn't payable is refused before anything is signed
+     * (the chain refuses them too, and charges the fee), and signs its `version_digest`: see `callProgram`,
+     * whose options it takes, including the 0 default of `storageLimit`.
+     */
+    async call(program, method, input = "", opts = {}) {
+        const address = programAddressArg(program);
+        const name = programMethodArg(method);
+        const { info } = await this.programForCall(address, programWaitMs(opts.waitMs));
+        const m = info.methods?.find((x) => x.untrusted_name === name);
+        if (info.methods && !m)
+            throw new Error(`the program's interface has no method ${JSON.stringify(name)}: client.program(${JSON.stringify(address)}) lists them. Nothing was signed`);
+        if (m && m.kind === "view")
+            throw new Error(`${JSON.stringify(name)} is a view: read it with client.view (a transaction can't call it). Nothing was signed`);
+        if (m && m.kind === "init")
+            throw new Error(`${JSON.stringify(name)} is the program's initializer, which runs only when it's created. Nothing was signed`);
+        if (m && !m.payable && checkedDrops(parseFang(opts.value ?? 0n), "value") > 0n)
+            throw new Error(`${JSON.stringify(name)} isn't payable, so the call can't send it FANG. Nothing was signed`);
+        return this.callProgram([{ program: address, method: name, input, value: opts.value, versionDigest: opts.versionDigest }], opts);
+    }
+    /**
+     * For a validator: signs a vote to pause programs (tag 69), from the validator's own account with
+     * its key (build the wallet from `validator.key`'s seed and `actAs` nothing: it signs as itself).
+     * Programs pause from the block after f + 1 of the epoch's validators have signed, for days, with
+     * no undo, so check `client.params()`' `programs` section (the live `votes`, `pause_signed` and
+     * `fix_pending`) first, or use `blockula program pause`, which does.
+     *
+     * It signs and lets the chain's admission decide: a signature the chain refuses (this validator
+     * signed one recently, or has a live vote of its own, or isn't in the active set) is an `ApiError`
+     * 400 and is never charged. It reserves no fuel and prices none, so its fee is a plain
+     * transaction's; it only needs programs to have been switched on (`/api/fees` has a `fuel` section:
+     * `ProgramsOffError` otherwise), not any fuel schedule this SDK knows, since a pause must not depend on one.
+     */
+    async programsPause(opts = {}) {
+        const fees = await this.client.fees();
+        if (fees.fuel === undefined || fees.fuel === null)
+            throw new ProgramsOffError(this.client.rpc);
+        return this.submitQueued({ type: "programs_pause" }, "", { ...opts, wait: true }, []);
+    }
+    /** This account's shares in a validator's pool, for `"all"`; anything else is parsed and checked. */
+    async sharesOf(validator, shares) {
+        if (shares !== "all") {
+            const s = typeof shares === "bigint" ? shares : /^\d+$/.test(shares.trim()) ? BigInt(shares.trim()) : -1n;
+            if (s <= 0n || s >= 1n << 64n)
+                throw new Error("shares must be a positive whole number (see client.staking(account))");
+            return s;
+        }
+        const d = stakeSummary(await this.client.staking(this.account)).delegations.find((x) => x.validator === validator);
+        if (!d || BigInt(d.shares) === 0n)
+            throw new Error(`${this.account} has no stake with validator ${validator}`);
+        return BigInt(d.shares);
+    }
+    /** A proposal kind with its accounts as `Client.recipient` signs them (the chain resolves names when the proposal is made). */
+    async resolveKind(kind) {
+        switch (kind.type) {
+            case "treasury_spend":
+            case "grant_soul":
+                return { ...kind, to: (await this.client.recipient(kind.to)).signed };
+            case "flag_sybil":
+            case "unflag_sybil":
+            case "clawback":
+                return { ...kind, account: (await this.client.recipient(kind.account)).signed };
+            default:
+                return kind;
+        }
+    }
+    /**
+     * Everything this account holds, as FANG text ("12.5 FANG"), locked or not: `balances()` says
+     * what it can pay. "0 FANG" only for an account that doesn't exist yet; anything else that goes
+     * wrong (the node is down or rate limited, a timeout, another chain) throws (DEV-2), so a
+     * failure never reads as an empty account.
+     */
+    async balance() {
+        return (await this.balances()).display.balance;
+    }
+    /**
+     * This account's balances, in bigint drops (DEV-2):
+     * - `balance`: everything it holds;
+     * - `transferable`: what it can pay or send now, fees and tips included: the "can pay" number;
+     * - `locked`: what vesting and vote locks hold (their `until` is in `client.account(…).locks`).
+     * Staked FANG isn't in `balance` (see `client.staking`). `exists` is false for an account the
+     * chain hasn't opened yet (all zeros). Errors propagate, like `balance()`.
+     */
+    async balances() {
+        await this.client.addressPrefix();
+        let a;
+        try {
+            a = await this.client.account(this.account);
+        }
+        catch (e) {
+            if (e instanceof ApiError && e.status === 404)
+                a = { balance: "0", transferable: "0", locked: "0", exists: false };
+            else
+                throw e;
+        }
+        const amount = (v, what) => {
+            if (typeof v === "string" && /^\d+$/.test(v))
+                return BigInt(v);
+            if (typeof v === "number" && Number.isSafeInteger(v) && v >= 0)
+                return BigInt(v);
+            throw new Error(`${this.client.rpc} didn't report ${this.account}'s ${what}`);
+        };
+        const balance = amount(a?.balance, "balance");
+        // Nodes before protocol v1 don't report locks: everything is transferable there.
+        const transferable = a?.transferable === undefined ? balance : amount(a.transferable, "transferable balance");
+        const locked = a?.locked === undefined ? 0n : amount(a.locked, "locked balance");
+        const exists = typeof a?.exists === "boolean" ? a.exists : balance > 0n || Number(a?.nonce ?? 0) > 0;
+        return { balance, transferable, locked, exists, display: { balance: formatFang(balance), transferable: formatFang(transferable), locked: formatFang(locked) } };
     }
     /** Dev/test chains only: drip 100 FANG to this wallet. */
-    faucet(wait = true) {
+    async faucet(wait = true) {
+        await this.client.addressPrefix();
         return this.client.faucet(this.account, wait);
     }
 }
-/** An error response from a Blockula node. `status` is the HTTP status (429 = rate limited). */
+/** Throws unless `shown` (a digest the caller displayed, if any) is `now`, the digest about to be signed. */
+function shownDigest(shown, now, what) {
+    if (shown === undefined)
+        return;
+    if (shown.trim().toLowerCase() !== now)
+        throw new Error(`${what} doesn't read the way it did when it was shown: its digest is now ${now}, not ${shown}. Nothing was signed: the node may be showing different content to different reads.`);
+}
+/**
+ * An error response from a Blockula node. `status` is the HTTP status (429 = rate limited);
+ * `retryAfterMs`, when the node said how long to wait (`Retry-After`, or "try again in N minutes").
+ */
 export class ApiError extends Error {
     status;
-    constructor(status, message) {
+    retryAfterMs;
+    constructor(status, message, retryAfterMs) {
         super(message);
         this.status = status;
+        this.retryAfterMs = retryAfterMs;
         this.name = "ApiError";
     }
 }
-/** A transaction that was rejected at execution (fee charged) or dropped from the mempool. */
+/**
+ * The node says it's on blockula-1, and this client isn't pinned to that chain (DEV-1). Nothing
+ * was signed. A client signs there only with a `chainId: "blockula-1"` pin.
+ */
+export class MainnetNotAllowedError extends Error {
+    rpc;
+    constructor(rpc) {
+        super(`${rpc} says it's on ${MAINNET_CHAIN_ID}, and this client isn't pinned to that chain, so nothing was signed. If that's the chain you mean, pin it where the client is created: { chainId: "${MAINNET_CHAIN_ID}" }`);
+        this.rpc = rpc;
+        this.name = "MainnetNotAllowedError";
+    }
+}
+/** The most txs a node holds pending from one sender (node/src/chain.rs `MAX_PENDING_PER_SENDER`). */
+export const MAX_PENDING_PER_SENDER = 64;
+const cursorKey = (chainId, genesisHash, account) => `${chainId} ${genesisHash} ${account}`;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Whether the node said it refused a request: a 4xx answer, except 408 (a request that timed out
+ * may still have been handled). A refused tx wasn't admitted, so it can't run from there.
+ */
+function refused(e) {
+    return e instanceof ApiError && e.status >= 400 && e.status < 500 && e.status !== 408;
+}
+const NO_RETRY = { untilMs: 0 };
+/**
+ * Posts a signed tx. The same bytes go again (never a re-signed tx, so it can't be paid twice):
+ * once after a "bad nonce" refusal, since a node writing a block can misjudge a correct nonce for a
+ * moment (TR-1), and, within `retry`, after a 429 or "too many pending" (the 64-per-sender cap),
+ * as soon as the node says to try again.
+ */
+async function postPatiently(client, tx, retry) {
+    const start = Date.now();
+    let nonceRetried = false;
+    for (;;) {
+        try {
+            return await client.post(tx);
+        }
+        catch (e) {
+            if (!(e instanceof ApiError))
+                throw e;
+            if (/bad nonce/i.test(e.message) && !nonceRetried) {
+                nonceRetried = true;
+                await sleep(300);
+                continue;
+            }
+            const busy = e.status === 429 ? (e.retryAfterMs ?? 1_000) : /too many pending/i.test(e.message) ? 1_000 : undefined;
+            if (busy === undefined || Date.now() + busy - start > retry.untilMs)
+                throw e;
+            await sleep(busy);
+        }
+    }
+}
+/**
+ * The node reports a transaction as failed. Two different things (audit review-fix-clients-2):
+ * - `dropped` false: it executed in block `tx.height` and failed there. Its fee was charged; it
+ *   can't execute again.
+ * - `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 other nodes may still hold it and include it until its `valid_until`
+ *   (`validUntil`, when known): check `client.tx(id)` before sending it again, or a retry can pay twice.
+ */
+/**
+ * Whether a `/api/tx` answer of status "failed" is a tx the node dropped from its mempool without
+ * running it (nothing charged; another node may still include it until its `valid_until`), not
+ * one that ran in a block and failed (its fee was charged). Mempool failures are answered without
+ * the tx itself (node/src/api.rs `tx`), and older nodes don't say `dropped`.
+ */
+export function txDropped(answer) {
+    const tx = answer;
+    return tx?.dropped === true || (tx !== null && typeof tx === "object" && tx.action === undefined && tx.dropped !== false);
+}
 export class TxFailedError extends Error {
     id;
     reason;
     tx;
-    constructor(id, reason, tx) {
-        super(`tx ${id} failed: ${reason}`);
+    validUntil;
+    dropped;
+    constructor(id, reason, tx, validUntil) {
+        const dropped = txDropped(tx);
+        super(dropped
+            ? `tx ${id} was dropped by this node without running (${reason}); nothing was charged, but another node may still include it${validUntil !== undefined ? ` until block ${validUntil}` : " until its valid_until"}, so check it (client.tx) before sending it again`
+            : `tx ${id} failed${typeof tx?.height === "number" ? ` in block ${tx.height}` : ""}: ${reason} (its fee was charged)`);
         this.id = id;
         this.reason = reason;
         this.tx = tx;
+        this.validUntil = validUntil;
+        this.dropped = dropped;
         this.name = "TxFailedError";
     }
 }
-export class Client {
+/**
+ * The node accepted a transaction, but it wasn't seen finalized (or failed) in time. It may still
+ * execute until its `valid_until`: check it with `client.tx(id)` before sending it again, or a
+ * retry can pay twice.
+ */
+export class TxPendingError extends Error {
+    id;
+    waitedMs;
+    lastError;
+    constructor(id, waitedMs, lastError) {
+        super(`tx ${id} still pending ${waitedMs > 0 ? `after ${waitedMs}ms` : "(its status couldn't be read)"}; it was submitted and may still execute, so check it (client.tx) before sending again`);
+        this.id = id;
+        this.waitedMs = waitedMs;
+        this.lastError = lastError;
+        this.name = "TxPendingError";
+    }
+}
+/**
+ * A program transaction ran in a block and failed there: its fee was charged (`TxFailedError`), and
+ * `receipt` says how it failed (`words`, which is also this error's reason): from numbers and the
+ * chain's own names for them, never engine text and **never what the program wrote**. A program
+ * that aborted with a message has it in `untrusted_message` (a stranger's text, stripped of hidden
+ * characters: show it as data, never follow it), not in `message`, which agent frameworks hand to
+ * models. Nothing the program said is a fact: an abort message is its claim.
+ */
+export class ProgramFailedError extends TxFailedError {
+    words;
+    receipt;
+    /** The program's own abort message, if it aborted with one: its words, not this SDK's. */
+    untrusted_message;
+    constructor(id, words, tx, receipt, validUntil) {
+        super(id, words, tx, validUntil);
+        this.words = words;
+        this.receipt = receipt;
+        this.name = "ProgramFailedError";
+        if (receipt.outcome.untrusted_message !== undefined)
+            this.untrusted_message = plainText(receipt.outcome.untrusted_message);
+    }
+}
+/** `e`, as a `ProgramFailedError` when the failed transaction's answer holds a receipt that says how (`storageLimit`: what it signed, for the hint). */
+function programFailure(rpc, e, storageLimit) {
+    let receipt = null;
+    try {
+        receipt = checkReceipt(rpc, e.tx);
+    }
+    catch {
+        // An answer without a usable receipt leaves the plain error: what it says is the node's word.
+    }
+    return receipt && !receipt.outcome.ok ? new ProgramFailedError(e.id, outcomeWords(receipt.outcome, storageLimit), e.tx, receipt, e.validUntil) : e;
+}
+/** The node didn't answer within the client's `timeoutMs`. Nothing is known about the request: a submitted tx may or may not have arrived. */
+export class RequestTimeoutError extends Error {
+    rpc;
+    path;
+    timeoutMs;
+    constructor(rpc, path, timeoutMs) {
+        super(`${rpc} didn't answer within ${timeoutMs}ms (${path})`);
+        this.rpc = rpc;
+        this.path = path;
+        this.timeoutMs = timeoutMs;
+        this.name = "RequestTimeoutError";
+    }
+}
+/** A proof older than the newest head seen (this node's and every witness's) by more than `maxLagBlocks`. */
+export class StaleProofError extends Error {
+    height;
+    head;
+    maxLagBlocks;
+    constructor(height, head, maxLagBlocks) {
+        super(`the proof is for block #${height}, but the chain is at #${head} (at most ${maxLagBlocks} blocks behind is accepted): a node serving old state, or one that's far behind`);
+        this.height = height;
+        this.head = head;
+        this.maxLagBlocks = maxLagBlocks;
+        this.name = "StaleProofError";
+    }
+}
+/**
+ * On mainnet, a transaction would carry an address that only one node vouched for: a `.boo` name
+ * resolved without witnesses, in a field that needs an address (staking's validator, the account
+ * `actAs` acts for, a key grant's account). Nothing was signed (audit gap-7-1). Check
+ * `resolution.address` with its owner and pass it instead of the name, or give the client witnesses.
+ */
+export class UnprovenNameError extends Error {
+    resolution;
+    constructor(resolution, rpc) {
+        super(`${resolution.name ?? resolution.input}.boo resolves to ${resolution.address} only by ${rpc}'s word (unproven: a node can point a name anywhere), and on mainnet this needs an address: nothing was signed. Check that address with its owner and pass it instead of the name, or give the client witnesses to prove names`);
+        this.resolution = resolution;
+        this.name = "UnprovenNameError";
+    }
+}
+/**
+ * A node reports a height the chain can't have reached (`Client.checkSigningHeight`): a tx signed
+ * against it could be held and released later. Nothing was signed.
+ */
+export class HeightAheadError extends Error {
+    rpc;
+    height;
+    limit;
+    constructor(rpc, height, limit, by) {
+        super(`${rpc} reports height ${height}, but by ${by} the chain can't be past block ${limit}: a transaction signed against that height could be held and released later. Nothing was signed: use another node (or check this machine's clock)`);
+        this.rpc = rpc;
+        this.height = height;
+        this.limit = limit;
+        this.name = "HeightAheadError";
+    }
+}
+/**
+ * How far ahead of the lowest head a client's witnesses report a tx's height may be, by default
+ * (`ClientOptions.maxHeadLeadBlocks`): 30 blocks, room for propagation between nodes.
+ */
+export const DEFAULT_MAX_HEAD_LEAD_BLOCKS = 30;
+/**
+ * How far behind the network's clocks this machine's may be before `heightLimit` refuses an honest
+ * node: 15 minutes (the CLI uses the same, node/src/cli_net.rs `HEIGHT_CLOCK_TOLERANCE_MS`).
+ */
+export const HEIGHT_CLOCK_TOLERANCE_MS = 15 * 60 * 1000;
+/** How far ahead of their clocks validators accept a block's timestamp (node/src/consensus.rs `MAX_CLOCK_DRIFT_MS`). */
+const MAX_CLOCK_DRIFT_MS = 1_000;
+/**
+ * The highest height a chain can have reached at `nowMs` (node/src/cli_net.rs `height_limit`):
+ * every block's timestamp is at least its parent's plus the block time, and validators refuse one
+ * more than a second ahead of their clocks, so block h is stamped no earlier than genesis + h ×
+ * block time. A chain that ran slower than its block time is below this by that much, so it
+ * refuses only heights the chain can't have, not every lie.
+ */
+export function heightLimit(createdAtMs, blockTimeMs, nowMs) {
+    return Math.floor(Math.max(0, nowMs + MAX_CLOCK_DRIFT_MS + HEIGHT_CLOCK_TOLERANCE_MS - createdAtMs) / Math.max(1, blockTimeMs));
+}
+/** How long a node asked to wait before retrying: `Retry-After` (seconds), or its "try again in N minutes". */
+function retryAfter(res, error) {
+    const h = res.headers?.get?.("retry-after")?.trim();
+    if (h && /^\d+$/.test(h))
+        return Number(h) * 1_000;
+    const m = /try again in (\d+) (second|minute)/i.exec(error);
+    return m ? Number(m[1]) * (m[2].toLowerCase() === "minute" ? 60_000 : 1_000) : undefined;
+}
+/** The node reports a different chain than the client is pinned to (`ClientOptions`). */
+export class ChainMismatchError extends Error {
     rpc;
-    constructor(rpc = DEFAULT_RPC) {
+    field;
+    expected;
+    reported;
+    constructor(rpc, field, expected, reported) {
+        super(`${rpc} reports ${field} ${reported ?? "(none)"}, but this client is pinned to ${expected}; refusing to use it`);
         this.rpc = rpc;
+        this.field = field;
+        this.expected = expected;
+        this.reported = reported;
+        this.name = "ChainMismatchError";
+    }
+}
+/** Default per-request timeout of a `Client`. */
+export const DEFAULT_TIMEOUT_MS = 15_000;
+/**
+ * The longest timeout a `Client` takes: 2^31 − 1 ms (about 24.8 days). Timers store their delay
+ * as a signed 32-bit number, and a longer one fires at once (audit review-fix-clients-1).
+ */
+export const MAX_TIMEOUT_MS = 2_147_483_647;
+/** `ms` as a timeout: a whole number of milliseconds from 1 to `MAX_TIMEOUT_MS`, or an error naming `what`. */
+export function checkTimeoutMs(ms, what = "timeoutMs") {
+    if (!Number.isSafeInteger(ms) || ms < 1 || ms > MAX_TIMEOUT_MS)
+        throw new Error(`${what} must be a whole number of milliseconds from 1 to ${MAX_TIMEOUT_MS} (about 24.8 days)`);
+    return ms;
+}
+/**
+ * How far behind the newest head (the node's own and each witness's `/api/status` height) a
+ * proven read's proof may be, by default: 10 blocks (10 s at 1 s blocks), room for propagation
+ * between nodes. Older proofs are refused (`StaleProofError`), so a node can't answer with a
+ * genuine but outdated record (a name's previous owner, a balance before a spend, a removed key).
+ */
+export const DEFAULT_MAX_PROOF_LAG_BLOCKS = 10;
+/** `opts` with a network's pins filled in. A pin that contradicts the network's is an error, never a guess. */
+function withPreset(opts, p) {
+    const pick = (what, given, preset, same = (a, b) => a === b) => {
+        if (given !== undefined && preset !== undefined && !same(given, preset))
+            throw new Error(`${what} ${JSON.stringify(given)} contradicts the ${p.name} network's (${JSON.stringify(preset)})`);
+        return given ?? preset;
+    };
+    const genesisHash = pick("genesisHash", opts.genesisHash?.toLowerCase(), p.genesisHash);
+    // The built-in genesis clock is that of the built-in genesis, never another's.
+    const clock = genesisHash === p.genesisHash ? p.genesisClock : undefined;
+    return {
+        ...opts,
+        chainId: pick("chainId", opts.chainId, p.chainId),
+        genesisHash,
+        prefix: pick("prefix", opts.prefix, p.prefix),
+        genesisClock: pick("genesisClock", opts.genesisClock, clock, (a, b) => a.createdAtMs === b.createdAtMs && a.blockTimeMs === b.blockTimeMs),
+    };
+}
+/**
+ * A node's URL in one spelling, so a node compares equal to itself however it's written: scheme and
+ * host lowercased, a default port, dot segments and credentials dropped (the URL parser's own
+ * normalization), no trailing dot on the host, no trailing slash, no query or fragment. What isn't
+ * an http(s) URL comes back as it is. (`Client` compares witnesses with its own node by it.)
+ */
+function canonicalNodeUrl(u) {
+    try {
+        const url = new URL(u);
+        if (!/^https?:$/.test(url.protocol))
+            return u;
+        // `host` carries the port; a fully qualified name's trailing dot comes before it, or ends it.
+        const host = url.host.replace(/\.(?=:\d+$|$)/, "");
+        return `${url.protocol}//${host}${url.pathname.replace(/\/+$/, "")}`;
     }
+    catch {
+        return u;
+    }
+}
+export class Client {
+    /** The chain's address prefix: given, learned from `/api/status`, or `boo` until then. */
+    prefix;
+    prefixKnown;
+    pinnedPrefix;
+    pinnedChainId;
+    pinnedGenesis;
+    /** Per-request timeout (ms). */
+    timeoutMs;
+    /** Independent nodes names are proven against (`ClientOptions.witnesses`). */
+    witnesses;
+    requireProvenNames;
+    /** See `ClientOptions.maxHeadLeadBlocks`. */
+    maxHeadLeadBlocks;
+    /** See `ClientOptions.genesisClock`. */
+    genesisClock;
+    /** The node's URL. */
+    rpc;
+    /** The network this client was made for (`ClientOptions.network`), if any. */
+    network;
+    /** See `ClientOptions.wireTxs`. */
+    wireTxs;
+    /** The public testnet (`NETWORKS.testnet`), every pin set: `Client.testnet({ witnesses })`, or pass your own node's URL as `rpc`. */
+    static testnet(opts = {}) {
+        const { rpc, ...rest } = opts;
+        return new Client(rpc, { ...rest, network: "testnet" });
+    }
+    /** A `blockula dev` chain on this machine (`NETWORKS.local`). */
+    static local(opts = {}) {
+        const { rpc, ...rest } = opts;
+        return new Client(rpc, { ...rest, network: "local" });
+    }
+    /**
+     * `new Client(rpc, opts)`, `new Client({ network: "testnet" })` (the network's public RPC), or
+     * `new Client(rpc, { network })` (your own node, held to that network's pins). The pins
+     * (`opts`, and the network's) are checked on every status: a node reporting another prefix,
+     * chain id or genesis hash is refused with `ChainMismatchError`.
+     */
+    constructor(rpc, options = {}) {
+        let opts = options;
+        let url = typeof rpc === "string" ? rpc : undefined;
+        if (rpc !== undefined && typeof rpc !== "string") {
+            if (rpc === null || typeof rpc !== "object")
+                throw new Error("new Client(rpc, opts) takes the node's URL, or the options alone");
+            opts = { ...rpc, ...options };
+        }
+        if (opts.network !== undefined && !isNetworkName(opts.network))
+            throw new Error(`unknown network ${JSON.stringify(opts.network)} (testnet or local)`);
+        const preset = opts.network === undefined ? undefined : NETWORKS[opts.network];
+        if (preset) {
+            url ??= preset.rpc;
+            if (url === undefined)
+                throw new Error(`no public ${preset.name} RPC is built into this SDK yet: pass the URL of a ${preset.name} node you trust, new Client(url, { network: "${preset.name}" })`);
+            opts = withPreset(opts, preset);
+        }
+        this.rpc = url ?? DEFAULT_RPC;
+        this.network = preset?.name;
+        this.wireTxs = opts.wireTxs === true;
+        if (opts.prefix !== undefined && !KNOWN_PREFIXES.includes(opts.prefix))
+            throw new Error(`unknown address prefix ${opts.prefix}`);
+        if (opts.genesisHash !== undefined && !/^[0-9a-f]{64}$/i.test(opts.genesisHash))
+            throw new Error("genesisHash must be 64 hex characters");
+        const rpcUrl = this.rpc;
+        this.timeoutMs = checkTimeoutMs(opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        this.witnesses = [...(opts.witnesses ?? [])];
+        // The same node under another spelling (`https://Node.Example:443/.`) is still the client's own: a proof checked against the state root the node itself reports proves nothing.
+        const ownUrl = canonicalNodeUrl(rpcUrl);
+        if (this.witnesses.some((w) => w === this || canonicalNodeUrl(w.rpc) === ownUrl))
+            throw new Error("a witness must be another node, not the client's own");
+        this.requireProvenNames = opts.requireProvenNames === true;
+        if (this.requireProvenNames && this.witnesses.length === 0)
+            throw new Error("requireProvenNames needs witnesses to prove names against");
+        this.maxHeadLeadBlocks = opts.maxHeadLeadBlocks ?? DEFAULT_MAX_HEAD_LEAD_BLOCKS;
+        if (!Number.isSafeInteger(this.maxHeadLeadBlocks) || this.maxHeadLeadBlocks < 0)
+            throw new Error("maxHeadLeadBlocks must be a whole number of blocks");
+        if (opts.genesisClock) {
+            const { createdAtMs, blockTimeMs } = opts.genesisClock;
+            if (!Number.isSafeInteger(createdAtMs) || createdAtMs < 0 || !Number.isSafeInteger(blockTimeMs) || blockTimeMs < 1)
+                throw new Error("genesisClock needs the genesis's created_at_ms and block_time_ms (whole milliseconds)");
+            this.genesisClock = { createdAtMs, blockTimeMs };
+        }
+        this.pinnedPrefix = opts.prefix;
+        this.pinnedChainId = opts.chainId;
+        this.pinnedGenesis = opts.genesisHash?.toLowerCase();
+        this.prefix = opts.prefix ?? DEFAULT_PREFIX;
+        this.prefixKnown = opts.prefix !== undefined;
+    }
+    /**
+     * Refuses (`HeightAheadError`, before anything is signed) a height a tx's validity window would
+     * count from that this client has reason to think the chain hasn't reached: more than
+     * `maxHeadLeadBlocks` past the lowest head its witnesses report, or, with a `genesisClock`, past
+     * what the chain can have reached by this machine's clock (`heightLimit`). A node reporting a
+     * future height gets a tx it can hold and release later, when the window it picked opens; with
+     * a name signed in it, after the name may have changed hands (audit review-r3-clients-2).
+     * Every witness must report its height, as every witness must confirm a proof: one honest
+     * witness is enough to refuse a height the chain hasn't reached, whatever the others say.
+     * Without witnesses or a genesis clock, the height is the node's word.
+     */
+    async checkSigningHeight(height) {
+        this.checkHeightClock(height);
+        if (!this.witnesses.length)
+            return;
+        const heads = await Promise.all(this.witnesses.map((w) => w.status().then((s) => (Number.isSafeInteger(s.height) && s.height >= 0 ? s.height : undefined), () => undefined)));
+        const silent = this.witnesses.filter((_, i) => heads[i] === undefined);
+        if (silent.length)
+            throw new Error(`${silent.map((w) => w.rpc).join(", ")} didn't report ${silent.length === 1 ? "its height" : "their heights"}, so ${this.rpc}'s height ${height} can't be checked against every witness: nothing was signed`);
+        const lowest = Math.min(...heads);
+        if (height > lowest + this.maxHeadLeadBlocks)
+            throw new HeightAheadError(this.rpc, height, lowest + this.maxHeadLeadBlocks, `the lowest head its witnesses report (#${lowest})`);
+    }
+    /**
+     * Refuses (`HeightAheadError`) a height the chain can't have reached by this machine's clock and
+     * the `genesisClock` this client was given: the clock half of `checkSigningHeight`, for heights a
+     * node reports that aren't signed against (a read's, a wait's). Without a `genesisClock` the
+     * height is the node's word.
+     */
+    checkHeightClock(height) {
+        if (!this.genesisClock)
+            return;
+        const limit = heightLimit(this.genesisClock.createdAtMs, this.genesisClock.blockTimeMs, Date.now());
+        if (height > limit)
+            throw new HeightAheadError(this.rpc, height, limit, "this machine's clock and the chain's genesis");
+    }
+    /** The chain's address prefix, asking the node once if it isn't known yet. */
+    async addressPrefix() {
+        if (!this.prefixKnown)
+            await this.status();
+        return this.prefix;
+    }
+    /**
+     * Throws `MainnetNotAllowedError` for a status on blockula-1 unless this client is pinned to that
+     * chain (`chainPin`). Wallets call it with the very status each tx is signed for (DEV-1).
+     */
+    checkMainnetPin(chainId) {
+        if (chainId === MAINNET_CHAIN_ID && this.chainPin() !== MAINNET_CHAIN_ID)
+            throw new MainnetNotAllowedError(this.rpc);
+    }
+    /** The chain id this client is pinned to (`ClientOptions.chainId`), if any. A client that pins the chain itself reports its own pin. */
+    chainPin() {
+        return this.pinnedChainId;
+    }
+    /** One request, bounded by `timeoutMs` (headers and body): a node that never answers fails with `RequestTimeoutError` instead of hanging. */
     async call(path, body) {
-        const res = await fetch(this.rpc.replace(/\/$/, "") + "/api" + path, body === undefined ? undefined : { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) });
-        const text = await res.text();
+        const ctl = new AbortController();
+        const timer = setTimeout(() => ctl.abort(), this.timeoutMs);
+        let res;
+        let text;
+        try {
+            const init = body === undefined
+                ? { signal: ctl.signal }
+                : body instanceof Uint8Array
+                    ? { method: "POST", headers: { "content-type": "application/octet-stream" }, body: body, signal: ctl.signal }
+                    : { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body), signal: ctl.signal };
+            res = await fetch(this.rpc.replace(/\/$/, "") + "/api" + path, init);
+            text = await res.text();
+        }
+        catch (e) {
+            if (ctl.signal.aborted)
+                throw new RequestTimeoutError(this.rpc, path, this.timeoutMs);
+            throw e;
+        }
+        finally {
+            clearTimeout(timer);
+        }
         let json;
         try {
             json = JSON.parse(text);
         }
         catch {
-            throw new ApiError(res.status, res.ok ? "the node returned something that isn't JSON" : `node error ${res.status} ${res.statusText}`.trim());
+            throw new ApiError(res.status, res.ok ? "the node returned something that isn't JSON" : `node error ${res.status} ${res.statusText}`.trim(), retryAfter(res, ""));
         }
         if (!res.ok)
-            throw new ApiError(res.status, json.error ?? res.statusText);
+            throw new ApiError(res.status, json.error ?? res.statusText, retryAfter(res, String(json.error ?? "")));
         return json;
     }
-    status() { return this.call("/status"); }
-    blocks(limit = 20) { return this.call(`/blocks?limit=${limit}`); }
+    async status() {
+        const s = await this.call("/status");
+        if (this.pinnedChainId !== undefined && s.chain_id !== this.pinnedChainId)
+            throw new ChainMismatchError(this.rpc, "chain_id", this.pinnedChainId, s.chain_id);
+        if (this.pinnedGenesis !== undefined && String(s.genesis_hash ?? "").toLowerCase() !== this.pinnedGenesis)
+            throw new ChainMismatchError(this.rpc, "genesis_hash", this.pinnedGenesis, s.genesis_hash);
+        if (typeof s.address_prefix === "string") {
+            if (this.pinnedPrefix !== undefined && s.address_prefix !== this.pinnedPrefix)
+                throw new ChainMismatchError(this.rpc, "address_prefix", this.pinnedPrefix, s.address_prefix);
+            this.prefix = s.address_prefix;
+            this.prefixKnown = true;
+        }
+        return s;
+    }
+    /**
+     * Block headers, newest first: `{ height, hash, timestamp_ms, proposer, state_root, tx_count, … }`.
+     * Up to `limit` (at most 100) below height `before` (default: from the head), so a page's
+     * last height is the next page's `before`. Nothing older than the node's `history_from`.
+     * `blocks(20)` still works.
+     */
+    async blocks(page = {}) {
+        const { limit = 20, before } = typeof page === "number" ? { limit: page } : page;
+        const q = new URLSearchParams({ limit: String(wholeNumber(limit, "limit")) });
+        if (before !== undefined)
+            q.set("before", String(wholeNumber(before, "before")));
+        return this.call(`/blocks?${q}`);
+    }
+    /**
+     * An account's history, newest first, a page at a time (TR-3): pass the previous page's `next`
+     * as `before` until it's `null`. Each tx is shown as `/api/tx` shows it. On nodes without paged
+     * history it's the newest 25 and the pending ones, with `paged: false` (see `HistoryPage`).
+     */
+    async history(account, page = {}) {
+        const q = new URLSearchParams();
+        if (page.before !== undefined)
+            q.set("before", page.before);
+        if (page.limit !== undefined)
+            q.set("limit", String(wholeNumber(page.limit, "limit")));
+        try {
+            const r = await this.call(`/account/${encodeURIComponent(account)}/txs${q.size ? `?${q}` : ""}`);
+            return { txs: arr(r?.txs), next: typeof r?.next === "string" && r.next ? r.next : null, history_from: num(r?.history_from), paged: true };
+        }
+        catch (e) {
+            // A node from before paged history has no such route (404 or 405, without JSON).
+            if (!(e instanceof ApiError && (e.status === 404 || e.status === 405) && /^node error|not found/i.test(e.message)))
+                throw e;
+        }
+        if (page.before !== undefined)
+            return { txs: [], next: null, paged: false };
+        const a = await this.account(account);
+        const s = await this.status().catch(() => null);
+        return { txs: arr(a?.recent_txs), next: null, history_from: num(s?.history_from), paged: false };
+    }
     block(heightOrHash) { return this.call(`/block/${heightOrHash}`); }
     tx(id) { return this.call(`/tx/${id}`); }
     account(addressOrName) { return this.call(`/account/${encodeURIComponent(addressOrName)}`); }
+    /** A name: `status` (`active`, `grace` (expired; only its owner can renew it), `reserved` or `available`), owner, `expires_at`, `offered_to` (if its owner offered it to an account: theirs once they accept), prices. */
     name(name) { return this.call(`/name/${encodeURIComponent(name)}`); }
+    /** The base fee: each upcoming block's (`slots`) and `suggested`, which covers any of the next 17 blocks. */
+    fees() { return this.call("/fees"); }
+    /** The governance parameters (node/src/params.rs `ChainParams`; amounts as strings) under `params`, genesis constants under `genesis`, and the issuance year. `paramsOf` flattens it. */
+    params() { return this.call("/params"); }
+    /** The chain's genesis.json as this node serves it: the node's word (nothing here checks it against the genesis hash). */
+    genesis() { return this.call("/genesis"); }
+    /** Upgrades: the protocol version in force, what the node's binary supports, the `schedule` (`[{ version, activation_height, active }]`, what `proposal.cancelUpgrade` names), halts and each validator's readiness signal. */
+    upgrade() { return this.call("/upgrade"); }
     /** Accounts a key is authorized on (its own address, plus any it was added to). */
-    keyAccounts(keyIdHex) { return this.call(`/key/${keyIdHex}`); }
+    /**
+     * Accounts a key is on (`{ key_id, accounts, next }`), a page at a time: pass the previous page's
+     * `next` as `after`. Only accounts the key agreed to join (its grant) can list it (audit gap-7-2).
+     */
+    keyAccounts(keyIdHex, page = {}) {
+        const q = new URLSearchParams();
+        if (page.after)
+            q.set("after", page.after);
+        if (page.limit !== undefined)
+            q.set("limit", String(page.limit));
+        return this.call(`/key/${keyIdHex}${q.size ? `?${q}` : ""}`);
+    }
     search(q) { return this.call(`/search/${encodeURIComponent(q)}`); }
-    /** Active set for the current epoch, pending/approved validators, next-epoch set, epoch timing. */
+    /** The validator set: `active` this epoch, `next_epoch` (with `joining`/`leaving`), `candidates`, `jailed`, `tombstoned` and `removed`, each with stake, self-bond, commission, jail and liveness; epoch timing; the churn limit and slashing parameters. */
     validators() { return this.call("/validators"); }
     /** Hunts (bounties on GitHub issues), biggest first. */
     hunts(status) { return this.call(`/hunts${status ? `?status=${status}` : ""}`); }
     hunt(id) { return this.call(`/hunt/${id}`); }
     /** Off-chain check of a GitHub link (gist owned by the handle containing the address). */
     github(handle) { return this.call(`/github/${encodeURIComponent(handle)}`); }
+    /** The contribution pool: balance, repos, rules, the open Séance and recent results. */
+    contributions() { return this.call("/contributions"); }
+    claims(opts = {}) {
+        const q = new URLSearchParams(Object.entries(opts).filter(([, v]) => v !== undefined)).toString();
+        return this.call(`/claims${q ? `?${q}` : ""}`);
+    }
+    claim(id) { return this.call(`/claim/${id}`); }
+    /** A Séance, with each juror's assigned pairs (what they must judge). */
+    seance(id) { return this.call(`/seance/${id}`); }
+    /** A juror's assigned pairs in Séance `id`, in order, with each claim's repo and PR (what `sealVotes` binds). */
+    async seancePairs(id, juror) {
+        const s = await this.seance(id);
+        const seat = (Array.isArray(s?.jurors) ? s.jurors : []).find((j) => j.juror?.address === juror);
+        if (!seat)
+            throw new Error(`${juror} isn't on the jury of Séance #${id}`);
+        const claims = Array.isArray(s.claims) ? s.claims : [];
+        const ref = (cid) => {
+            const c = claims.find((x) => x.id === cid);
+            if (!c)
+                throw new Error(`Séance #${id} doesn't list claim #${cid}`);
+            return { id: cid, repo: c.repo, pr: c.pr };
+        };
+        return (Array.isArray(seat.assigned_pairs) ? seat.assigned_pairs : []).map(([a, b]) => [ref(a), ref(b)]);
+    }
+    /** Soul leaderboard. */
+    souls(limit = 50) { return this.call(`/souls?limit=${limit}`); }
+    // ---- protocol v1 reads, as the node serves them; `stakeSummary` / `proposalSummary` / `paramsOf` read them into plain shapes. ----
+    /** An account's stake: `delegations` (shares, value, principal), `entries` (unbonding and redelegations, with `release_at`), `bonded`, `unbonding` and `withdrawable` totals, the `validators` it runs, a `summary`. */
+    staking(account) { return this.call(`/staking/${encodeURIComponent(account)}`); }
+    /** Governance proposals, newest first (`status`: `voting`, `queued`, `rejected`, `executed`, `failed`), the rules (`params`), treasury and community balances. */
+    proposals(opts = {}) {
+        const q = new URLSearchParams(Object.entries(opts).filter(([, v]) => v !== undefined).map(([k, v]) => [k, String(v)])).toString();
+        return this.call(`/proposals${q ? `?${q}` : ""}`);
+    }
+    /** One proposal with its votes. */
+    proposal(id) { return this.call(`/proposal/${id}`); }
+    /** A community distribution: Merkle root, total, claimed so far, claim deadline. */
+    distribution(id) { return this.call(`/distribution/${id}`); }
+    /** A multisig account: owners, threshold, open proposals and their approvals. */
+    multisig(account) { return this.call(`/multisig/${encodeURIComponent(account)}`); }
+    // ---- programs (protocol v2, docs/PROGRAMS-V0.md §8.2, §8.4): third-party WebAssembly. Every answer is checked
+    // before it's used (programs.ts), and what a program or its deployer chose is kept as `untrusted_*`. ----
+    /**
+     * The chain's fuel prices and program bounds now (`/api/fees`' `fuel` section), checked.
+     * `ProgramsOffError` when programs have never been switched on there (the section is absent).
+     */
+    async programFuel() {
+        return checkFuel(this.rpc, (await this.fees()).fuel);
+    }
+    /** The programs parameters a deposit is priced with (`/api/params`' `programs` section), checked. */
+    async programParams() {
+        return checkParams(this.rpc, (await this.params()).programs);
+    }
+    /**
+     * A program by its address (never a name): its record, the version digest a call binds (recomputed
+     * from its code, interface and version: a node whose digest isn't what those compute is refused),
+     * who could upgrade it, what it holds and its methods, whose names are the deployer's
+     * (`untrusted_name`). One node's word (`proven: false`): `provenProgram` proves the record itself.
+     */
+    async program(address) {
+        programAddressArg(address);
+        return checkProgram(this.rpc, address, await this.call(`/program/${address}`), (h) => this.checkHeightClock(h));
+    }
+    /**
+     * A stored code by its hash: its size, who uploaded it and for what deposit, how many programs use
+     * it, when it was stored (usable from the block after) and its exported methods (`untrusted_exports`).
+     * With `wasm`, the code itself too, checked to hash to what was asked for.
+     */
+    async code(hash, opts = {}) {
+        programHashArg(hash, "a code hash");
+        return checkCode(this.rpc, hash, await this.call(`/code/${hash}${opts.wasm ? "?wasm=1" : ""}`), opts.wasm === true, (h) => this.checkHeightClock(h));
+    }
+    /**
+     * A stored interface by its hash: its format-1 bytes (checked to hash to what was asked for) and
+     * the node's JSON reading of them (`untrusted_interface`, every name the deployer's, not checked
+     * against the bytes: this SDK has no interface decoder yet).
+     */
+    async interface(hash) {
+        programHashArg(hash, "an interface hash");
+        return checkInterface(this.rpc, hash, await this.call(`/interface/${hash}`), (h) => this.checkHeightClock(h));
+    }
+    /**
+     * Runs a program's `view` method on the node, as of its newest block: nothing is signed or paid.
+     * `input` is what the method reads (bytes, or lowercase hex); `bindings` name the other programs
+     * it may reach (a program's address, and the version digest it must be at, or none for "any
+     * version", which a read may take); `fuel` caps the run (the node caps it too). The answer's
+     * `return_data` is the program's own claim, which the chain checks nothing of. Refused views
+     * (`ApiError`: 403 when the node serves none, 429 with `retryAfterMs`, 400/404/422 for a request
+     * the node won't run) never ran.
+     */
+    async view(address, method, input = "", opts = {}) {
+        programAddressArg(address);
+        const body = {
+            method: programMethodArg(method),
+            input: programInputArg(input),
+            bindings: (opts.bindings ?? []).map((b) => ({ program: programAddressArg(b.program, "a binding"), version_digest: b.versionDigest === undefined ? null : programHashArg(b.versionDigest, "a binding's version digest") })),
+        };
+        if (opts.fuel !== undefined)
+            body.fuel = positiveFuel(opts.fuel);
+        return checkView(this.rpc, address, await this.call(`/program/${address}/view`, body), (h) => this.checkHeightClock(h));
+    }
+    /**
+     * A program's record, proven: its Merkle proof (namespace 66) checked against the state root the
+     * node reports, which each of `witnesses` must report too, and fresh (see `provenRecord`).
+     * The record is decoded here and its `version_digest` recomputed from its own fields, so a call
+     * built from it binds the code the chain holds. `null` if the program provably doesn't exist.
+     * Without witnesses it's only as sure as this node (it can't be called proven).
+     */
+    async provenProgram(address, opts = {}) {
+        programAddressArg(address);
+        const r = await this.provenRecord(NAMESPACES.PROGRAMS, address, opts);
+        if (r.value === null)
+            return null;
+        const rec = decodeProgram(r.value);
+        return { address, ...rec, version_digest: versionDigest(address, rec.wasm_hash, rec.interface_hash, rec.version), witnesses: opts.witnesses?.length ?? 0, height: r.height, root: r.root, head: r.head };
+    }
+    /** `/api/proof/{namespace}/{key}`, unchecked. Prefer `provenRecord`. */
+    proof(namespace, key) {
+        const k = typeof key === "string" ? utf8ToBytes(key) : key;
+        return this.call(`/proof/${namespace}/${bytesToHex(k)}`);
+    }
+    /**
+     * A record with its Merkle proof checked against the state root the node reports. On its own
+     * that only shows the node is consistent; `witnesses` (clients for independent nodes) must
+     * each report the same state root for that block, so a single lying node can't fake balances,
+     * names or keys. A witness that hasn't reached the block yet is retried for `waitMs`.
+     *
+     * The proof must also be fresh: its block may be at most `maxLagBlocks` behind the newest head
+     * this node and the witnesses report (`StaleProofError` otherwise). Witnesses confirm any
+     * genuine root, old ones included, so without this a lying node could serve a real but outdated
+     * record (a name's previous owner, a balance before a spend, a key since removed). `head` is
+     * the newest head seen. Without witnesses only this node's own head is compared, which a lying
+     * node controls: pass witnesses for anything that matters.
+     */
+    async provenRecord(namespace, key, opts = {}) {
+        const maxLag = opts.maxLagBlocks ?? DEFAULT_MAX_PROOF_LAG_BLOCKS;
+        if (!Number.isSafeInteger(maxLag) || maxLag < 0)
+            throw new Error("maxLagBlocks must be a whole number of blocks");
+        const witnesses = opts.witnesses ?? [];
+        // Heads first, so the honest ones can only be behind the proof, never far ahead of it.
+        const heads = await Promise.all([this, ...witnesses].map(async (c) => {
+            const h = (await c.status()).height;
+            if (!Number.isSafeInteger(h) || h < 0)
+                throw new Error(`${c.rpc} doesn't report its height`);
+            return h;
+        }));
+        const r = checkProofResponse(await this.proof(namespace, key), namespace, key);
+        const head = Math.max(...heads);
+        if (r.height + maxLag < head)
+            throw new StaleProofError(r.height, head, maxLag);
+        await Promise.all(witnesses.map((w) => w.confirmStateRoot(r.height, r.root, opts.waitMs ?? 5_000)));
+        return { ...r, head };
+    }
+    /** Throws unless this node's block `height` has state root `root` (waiting up to `waitMs` for it to get there). */
+    async confirmStateRoot(height, root, waitMs = 5_000) {
+        const until = Date.now() + waitMs;
+        for (;;) {
+            try {
+                const b = await this.block(height);
+                if (b.state_root !== root)
+                    throw new Error(`${this.rpc} disagrees about the state at block #${height}: root ${String(b.state_root).slice(0, 16)}…, not ${root.slice(0, 16)}…`);
+                return;
+            }
+            catch (e) {
+                if (!(e instanceof ApiError && e.status === 404) || Date.now() > until)
+                    throw e;
+                await new Promise((r) => setTimeout(r, 250));
+            }
+        }
+    }
+    /** An address's balance, nonce and keys, proven and fresh (see `provenRecord`). `null` if the account provably doesn't exist. */
+    async provenAccount(address, opts = {}) {
+        if (!isAddress(address))
+            throw new Error(`${address} isn't an address`);
+        const r = await this.provenRecord(NAMESPACES.ACCOUNTS, address, opts);
+        return r.value === null ? null : { address, ...decodeAccount(r.value), height: r.height, root: r.root, head: r.head };
+    }
+    /**
+     * Who a `.boo` name resolves to, proven and fresh (see `provenRecord`). `null` if it provably
+     * doesn't resolve: never registered, or expired (`expires_at` passed; in its grace period only
+     * the owner can renew it, and after that anyone can register it). `includeExpired` returns an
+     * expired record too, with `active: false`: never pay its `owner`.
+     */
+    async provenName(name, opts = {}) {
+        const r = await this.provenRecord(NAMESPACES.NAMES, bareName(name), opts);
+        if (r.value === null)
+            return null;
+        const rec = decodeName(r.value);
+        // node/src/econ.rs `name_active`: the next block (height + 1) must be at most `expires_at`.
+        const active = r.height + 1 <= rec.expires_at;
+        if (!active && !opts.includeExpired)
+            return null;
+        return { ...rec, active, height: r.height, root: r.root, head: r.head };
+    }
+    /**
+     * The address a name or address resolves to, for fields that need an address (see
+     * `resolution`): proven with witnesses, else one node's word. Where the chain resolves names
+     * itself (payments, vouches, name offers…), use `recipient` instead, which signs the name.
+     */
     async resolve(nameOrAddress) {
-        if (isAddress(nameOrAddress))
-            return nameOrAddress;
-        if (/^boo1/i.test(nameOrAddress.trim()))
-            throw new Error(`${nameOrAddress} isn't a valid address (check for typos; addresses are lowercase)`);
-        const r = await this.name(nameOrAddress);
-        if (r.available)
+        return (await this.resolution(nameOrAddress)).address;
+    }
+    /**
+     * How to sign a recipient in a field the chain resolves itself (`transfer.to`, `award_hunt.to`,
+     * `vouch`/`unvouch`/`flag_sybil`/`clawback.account`, `grant_soul.to`, `transfer_name.to`, and
+     * proposal targets): an address as given; with witnesses a name's proven owner; without them
+     * the name itself, which the chain resolves to its owner when the tx runs, so a lying node
+     * can't point it at another account now (audit gap-7-1). It can still hold the signed tx and
+     * release it later within its validity window, which counts from the height that node reported
+     * (bounded by `checkSigningHeight` only with witnesses or a `genesisClock`): whoever owns the
+     * name then is paid, so a name that lapses in between pays its next owner (review-r3-clients-2).
+     * Show `how` before signing.
+     */
+    async recipient(nameOrAddress) {
+        const r = await this.resolution(nameOrAddress);
+        if (r.name === null || r.proven)
+            return { ...r, signed: r.address, byChain: false };
+        return {
+            ...r,
+            signed: `${r.name}.boo`,
+            byChain: true,
+            how: `${r.name}.boo is signed as the name: the chain pays whoever owns it when the transaction runs, so ${this.rpc} can't point it at another account now, though a node holding the signed transaction could release it later in its validity window, after the name changed hands (${this.rpc} says the owner is ${r.address} now, unproven)`,
+        };
+    }
+    /**
+     * Where a recipient goes and how sure that is: show `address` and `how` before signing. With the
+     * client's `witnesses` a name is a proven, fresh read (`provenName`), so a lying node can't
+     * point it elsewhere; without them it's this node's answer alone (`proven: false`), which a
+     * lying node controls (audit gap-7-1).
+     */
+    async resolution(nameOrAddress) {
+        const input = nameOrAddress;
+        if (isAddress(input))
+            return { input, address: input, name: null, proven: true, how: "an address, signed as given" };
+        if (/^t?boo1/i.test(input.trim()))
+            throw new Error(`${input} isn't a valid address (check for typos; addresses are lowercase)`);
+        const name = bareName(input);
+        if (this.witnesses.length) {
+            const rec = await this.provenName(name, { witnesses: this.witnesses });
+            if (!rec)
+                throw new Error(`${name}.boo doesn't resolve: it isn't registered or has expired (proven against ${this.witnesses.length} witness${this.witnesses.length === 1 ? "" : "es"})`);
+            if (!isAddress(rec.owner))
+                throw new Error(`${name}.boo's record names ${rec.owner}, which isn't an address`);
+            return { input, address: rec.owner, name, proven: true, how: `${name}.boo proven at block #${rec.height} against ${this.witnesses.length} independent node${this.witnesses.length === 1 ? "" : "s"}`, height: rec.height };
+        }
+        if (this.requireProvenNames)
+            throw new Error(`${name}.boo can't be proven: this client has no witnesses`);
+        const r = await this.name(name);
+        if (r.status === "grace")
+            throw new Error(`${r.name} has expired (at block ${r.expires_at})`);
+        if (r.available || !r.owner)
             throw new Error(`${r.name} isn't registered`);
-        return r.owner.address;
+        const address = String(r.owner.address ?? "");
+        if (!isAddress(address))
+            throw new Error(`${this.rpc} resolved ${name}.boo to ${JSON.stringify(address)}, which isn't an address`);
+        return { input, address, name, proven: false, how: `${name}.boo as ${this.rpc} reports it, unproven (a node can point a name anywhere; give the client witnesses to prove it)` };
     }
+    /**
+     * Submits a signed tx, then (with `wait`) waits for it. What a failure means:
+     * - `ApiError`: the node refused the tx; it wasn't admitted.
+     * - `RequestTimeoutError` or a network error: unknown; the tx may have arrived.
+     * - `TxFailedError`: it executed and failed (`dropped` false: its fee was charged), or this node
+     *   dropped it unrun (`dropped` true: nothing charged, but it may still execute elsewhere until
+     *   its `valid_until`).
+     * - `TxPendingError`: it was admitted and may still execute. Don't send it again blindly.
+     */
     async submit(tx, wait = true) {
-        const { id } = await this.call("/tx", tx);
-        return wait ? this.waitForTx(id) : this.tx(id);
+        const { id } = await this.post(tx);
+        if (wait)
+            return this.waitForTx(id, undefined, tx.valid_until);
+        try {
+            return await this.tx(id);
+        }
+        catch (e) {
+            throw new TxPendingError(id, 0, e);
+        }
+    }
+    /**
+     * Submits a signed tx and returns its id, without reading it back or waiting (`submit` does
+     * both). The same bytes can be posted again safely: a node answers with the same id, and the tx
+     * runs at most once. As JSON, or in its wire form with `wireTxs`. Errors as `submit`'s.
+     */
+    async post(tx) {
+        const r = await this.call("/tx", this.wireTxs ? txBytes(tx) : tx);
+        if (typeof r?.id !== "string")
+            throw new Error(`${this.rpc} answered the submission without the transaction's id: it may or may not have been admitted`);
+        return { id: r.id };
     }
     async faucet(to, wait = true) {
         const { id } = await this.call("/faucet", { to });
         return wait ? this.waitForTx(id) : this.tx(id);
     }
-    async waitForTx(id, timeoutMs = 15_000) {
+    /**
+     * Polls a tx until it's finalized (returns it) or failed (`TxFailedError`, which says whether it
+     * executed or was dropped unrun). A poll that fails (rate limited, a node error, a timeout, not
+     * visible yet) is retried; after `timeoutMs` it throws `TxPendingError`, since the tx may still
+     * execute. `validUntil` (the tx's, when the caller has it) goes into a dropped tx's error.
+     */
+    async waitForTx(id, timeoutMs = 15_000, validUntil) {
         const start = Date.now();
+        let lastError;
         for (;;) {
-            const tx = await this.tx(id);
-            if (tx.status === "finalized")
-                return tx;
-            if (tx.status === "failed")
-                throw new TxFailedError(id, tx.error ?? "unknown reason", tx);
+            try {
+                const tx = await this.tx(id);
+                if (tx.status === "finalized")
+                    return tx;
+                if (tx.status === "failed")
+                    throw new TxFailedError(id, tx.error ?? "unknown reason", tx, validUntil);
+            }
+            catch (e) {
+                if (e instanceof TxFailedError || (e instanceof ApiError && e.status === 400))
+                    throw e;
+                lastError = e;
+            }
             if (Date.now() - start > timeoutMs)
-                throw new Error(`tx ${id} still pending after ${timeoutMs}ms`);
+                throw new TxPendingError(id, timeoutMs, lastError);
             await new Promise((r) => setTimeout(r, 250));
         }
     }