@blockula/sdk 0.5.1 → 1.0.2

package/dist/index.js

@@ -2,14 +2,19 @@ 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 { base64urlnopad, bech32m } from "@scure/base";
-import { DEFAULT_TIP_CAP_MULTIPLE, KEY_POP_CONTEXT, PUBLIC_KEY_LEN, SIGNATURE_LEN, actionDigest, baseFee, formatFang, keyPopMessage, maxTip, parseFang, parseSoul, proposalDigest, seanceCommitment, seancePairsDigest, signingBytes } from "./tx.js";
-import { NAMESPACES, checkProofResponse, decodeAccount, decodeName } from "./proof.js";
+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, TESTNET_RETIRED, 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";
 /** Address prefixes: `boo` on mainnet (and dev chains), `tboo` on public testnets. */
 export const KNOWN_PREFIXES = ["boo", "tboo"];
@@ -58,6 +63,17 @@ const wholeNumber = (n, what) => {
         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))
@@ -289,6 +305,10 @@ export function proposalSummary(raw, rules) {
         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) {
@@ -346,7 +366,16 @@ export class Wallet {
     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;
@@ -381,6 +410,11 @@ export class Wallet {
      */
     async actAs(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;
@@ -423,6 +457,8 @@ export class Wallet {
             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)
@@ -479,6 +515,8 @@ export class Wallet {
         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);
@@ -494,17 +532,116 @@ export class Wallet {
             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;
-        const unsigned = { chain_id: status.chain_id, genesis_hash: status.genesis_hash, from: this.account, nonce: account?.next_nonce ?? 0, fee: "0", tip: tip.toString(), valid_until: status.height + validFor, action: act, memo };
-        unsigned.fee = (baseFee(unsigned, fees.suggested) + tip).toString();
+        // 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: price it at the lowest upcoming one.
+            // 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);
+            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);
     }
+    /**
+     * 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
@@ -515,20 +652,156 @@ export class Wallet {
      * and been registered again (audit gap-7-1, review-r3-clients-2). See `Client.recipient`.
      */
     async send(to, amount, opts = {}) {
+        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 tx = await this.build({ type: "transfer", to: recipient.signed, amount: parseFang(amount).toString() }, opts.memo, opts);
-        return this.client.submit(tx, opts.wait ?? true);
+        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 }, "", opts);
-        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. `grant` is the
      * key's consent to this account (`keyGrant` on that device, or its grant code).
      */
     async addOwnerKey(grant, label) {
-        return this.client.submit(await this.build(await this.grantAction(grant, label, { type: "owner" })));
+        return this.submitQueued(await this.grantAction(grant, label, { type: "owner" }), "", {}, []);
     }
     /**
      * Let an agent/app key spend from this account, transfers only, within a limit. `grant` is the
@@ -543,10 +816,10 @@ export class Wallet {
         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.client.submit(await this.build((height) => ({ ...base, role: { type: "session", limit, period_blocks: opts.periodBlocks, expires_at: height + opts.expiresInBlocks } })));
+        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 }, "", {}, []);
     }
     /**
      * Register a validator owned by this account, self-bonding `bond` FANG into its stake pool (at
@@ -555,22 +828,22 @@ export class Wallet {
      * 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 }, "", {}, []);
     }
     /** 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 }, "", {}, []);
     }
     /** 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) {
@@ -578,42 +851,42 @@ export class Wallet {
             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.client.submit(await this.build((height) => ({ type: "create_hunt", repo: opts.repo, issue: opts.issue, amount, expires_at: height + opts.expiresInBlocks, title: opts.title })));
+        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: 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.recipient(to)).signed;
-        return this.client.submit(await this.build({ type: "award_hunt", hunt_id: huntId, to: addr, pr, ...(familiarKey ? { familiar_key: familiarKey } : {}) }));
+        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.client.submit(await this.build({ type: "submit_claim", repo, pr, ...(familiarKey ? { familiar_key: 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.client.submit(await this.build({ type: "vouch", account: (await this.client.recipient(account)).signed }));
+        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.client.submit(await this.build({ type: "unvouch", account: (await this.client.recipient(account)).signed }));
+        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.client.submit(await this.build({ type: "join_jury", bond: parseFang(bond).toString() }));
+        return this.submitQueued({ type: "join_jury", bond: parseFang(bond).toString() }, "", {}, []);
     }
     async leaveJury() {
-        return this.client.submit(await this.build({ type: "leave_jury" }));
+        return this.submitQueued({ type: "leave_jury" }, "", {}, []);
     }
     /**
      * Seal a Séance judgment: one of "a", "b" or "=" per assigned pair (see `client.seance(id)`),
@@ -630,47 +903,47 @@ export class Wallet {
             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.client.submit(await this.build({ type: "commit_votes", seance_id: seanceId, commitment, pairs_digest }));
+        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.client.submit(await this.build({ type: "reveal_votes", seance_id: seanceId, votes, spam, salt }));
+        return this.submitQueued({ type: "reveal_votes", seance_id: seanceId, votes, spam, salt }, "", {}, []);
     }
     async fundPool(amount) {
-        return this.client.submit(await this.build({ type: "fund_pool", amount: parseFang(amount).toString() }));
+        return this.submitQueued({ type: "fund_pool", amount: parseFang(amount).toString() }, "", {}, []);
     }
     /** Withdraw every contribution reward that has vested so far. */
     async withdrawVested() {
-        return this.client.submit(await this.build({ type: "withdraw_vested" }));
+        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.client.submit(await this.build({ type: "set_repo", 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.client.submit(await this.build({ type: "grant_soul", to: (await this.client.recipient(to)).signed, amount: parseSoul(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.client.submit(await this.build({ type: "reject_claim", claim_id: 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.client.submit(await this.build({ type: "flag_sybil", account: (await this.client.recipient(account)).signed, 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.client.submit(await this.build({ type: "clawback", account: (await this.client.recipient(account)).signed, 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.client.submit(await this.buildChecked(action, opts.memo ?? "", opts, unproven), opts.wait ?? true);
+        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
@@ -914,6 +1187,389 @@ export class Wallet {
             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 };
+        });
+    }
+    /**
+     * 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") {
@@ -941,8 +1597,48 @@ export class Wallet {
                 return kind;
         }
     }
-    balance() {
-        return this.client.addressPrefix().then(() => this.client.account(this.account)).then((a) => a.balance_display, () => "0 FANG");
+    /**
+     * 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. */
     async faucet(wait = true) {
@@ -957,15 +1653,72 @@ function shownDigest(shown, now, what) {
     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). */
+/**
+ * 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";
     }
 }
+/**
+ * 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
@@ -1021,6 +1774,39 @@ export class TxPendingError extends Error {
         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;
@@ -1099,6 +1885,14 @@ const MAX_CLOCK_DRIFT_MS = 1_000;
 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;
@@ -1134,8 +1928,44 @@ export function checkTimeoutMs(ms, what = "timeoutMs") {
  * 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 {
-    rpc;
     /** The chain's address prefix: given, learned from `/api/status`, or `boo` until then. */
     prefix;
     prefixKnown;
@@ -1151,16 +1981,58 @@ export class Client {
     maxHeadLeadBlocks;
     /** See `ClientOptions.genesisClock`. */
     genesisClock;
-    /** `opts` pins the chain: a node reporting another prefix, chain id or genesis hash is refused with `ChainMismatchError`. */
-    constructor(rpc = DEFAULT_RPC, opts = {}) {
-        this.rpc = rpc;
+    /** The node's URL. */
+    rpc;
+    /** The network this client was made for (`ClientOptions.network`), if any. */
+    network;
+    /** See `ClientOptions.wireTxs`. */
+    wireTxs;
+    /** A node of blockula-testnet-2 (`NETWORKS.testnet`), every pin set: `Client.testnet({ rpc })`. The public testnet was retired and has no public node, so `rpc` is required. */
+    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: "local" })` (the network's built-in 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(preset.name === "testnet" ? TESTNET_RETIRED : `no public ${preset.name} RPC is built into this SDK: 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 ?? [])];
-        if (this.witnesses.some((w) => w === this || w.rpc.replace(/\/$/, "") === rpc.replace(/\/$/, "")))
+        // 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)
@@ -1192,11 +2064,7 @@ export class Client {
      * Without witnesses or a genesis clock, the height is the node's word.
      */
     async checkSigningHeight(height) {
-        if (this.genesisClock) {
-            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");
-        }
+        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)));
@@ -1207,12 +2075,37 @@ export class Client {
         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 ctl = new AbortController();
@@ -1220,7 +2113,11 @@ export class Client {
         let res;
         let text;
         try {
-            const init = body === undefined ? { signal: ctl.signal } : { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body), signal: ctl.signal };
+            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();
         }
@@ -1237,10 +2134,10 @@ export class Client {
             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;
     }
     async status() {
@@ -1257,7 +2154,45 @@ export class Client {
         }
         return s;
     }
-    blocks(limit = 20) { return this.call(`/blocks?limit=${limit}`); }
+    /**
+     * 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)}`); }
@@ -1332,6 +2267,82 @@ export class Client {
     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;
@@ -1483,7 +2494,7 @@ export class Client {
      * - `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);
+        const { id } = await this.post(tx);
         if (wait)
             return this.waitForTx(id, undefined, tx.valid_until);
         try {
@@ -1493,6 +2504,17 @@ export class Client {
             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);