@blockula/sdk 0.5.1 → 1.0.0

package/dist/index.d.ts

@@ -1,10 +1,15 @@
-import { type SeanceClaimRef, type Action, type BaseFee, type ProposalKind, type Tx, type UnsignedTx } from "./tx.js";
+import { type SeanceClaimRef, type Action, type BaseFee, type ProposalKind, type ProgramPolicy, type Tx, type UnsignedTx } from "./tx.js";
 import { type ProofResponse, type ProvenRecord } from "./proof.js";
+import { type ProgramCodeInfo, type ProgramCost, type ProgramFuel, type ProgramInfo, type ProgramInterfaceInfo, type ProgramParams, type ProgramReceipt, type ProgramViewResult } from "./programs.js";
+import { type NetworkName } 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 declare const DEFAULT_RPC = "http://localhost:7070";
 /** Address prefixes: `boo` on mainnet (and dev chains), `tboo` on public testnets. */
 export declare const KNOWN_PREFIXES: readonly ["boo", "tboo"];
@@ -21,7 +26,11 @@ export declare function keyId(publicKey: Uint8Array): string;
 export declare function addressPrefix(s: string): string | undefined;
 /** Whether `s` is an address: with any known prefix, or exactly `prefix` when given. */
 export declare function isAddress(s: string, prefix?: string): boolean;
-/** An amount of FANG: a decimal string ("1.5"), a number, or bigint drops. */
+/**
+ * An amount of FANG: a decimal string ("1.5") or bigint drops (1 FANG = 10⁹ drops).
+ * A JS number is still accepted, but that form is deprecated and will be dropped: floats can't
+ * hold most decimal amounts exactly (`0.1 + 0.2`). Pass a string.
+ */
 export type Amount = string | number | bigint;
 /** A `.boo` name as the chain stores it (node/src/types.rs `normalize_name`): lowercase, without the suffix. */
 export declare function bareName(name: string): string;
@@ -202,7 +211,38 @@ export interface TxOptions {
     tip?: string | number | bigint;
     /** Blocks from now the tx stays valid (at most the chain's `max_tx_validity_blocks`, an hour of blocks). Default: the wallet's `validForBlocks` (600). */
     validForBlocks?: number;
+    /**
+     * Room for the base fee to rise before the tx is included (TR-6): its `fee` becomes this many
+     * times the base fee `/api/fees` fixes for the next 17 blocks (`suggested`), plus the tip. Only
+     * the including block's base fee and the tip are charged, so headroom costs nothing; without it a
+     * tx queued behind full blocks for longer than that can stop covering the base fee and be
+     * dropped (with every later tx from the account). 1 to 100; default the wallet's `feeHeadroom` (1).
+     */
+    feeHeadroom?: number;
+    /**
+     * The tx's `fee` outright (FANG, or bigint drops): the most it may be charged, base fee plus tip.
+     * At least what it costs at `suggested` now. Overrides `feeHeadroom`.
+     */
+    maxFee?: Amount;
+}
+/** `Wallet.send`'s options. */
+export interface SendOptions extends TxOptions {
+    /** Public, up to 256 bytes, written by the payer: an order or user id you issued. */
+    memo?: string;
+    /** Wait for it to finalize (default true); `false` returns as soon as a node admitted it. */
+    wait?: boolean;
+    /**
+     * Called with the signed tx and its id before it's submitted, in the wallet's queue (so parallel
+     * sends still get one nonce each): store both here, and every outcome is recoverable by
+     * resubmitting the same bytes (`client.post(tx)`). If it throws, nothing is submitted, the
+     * error is passed on, and the next tx takes the nonce.
+     */
+    onSigned?: (tx: Tx, id: string) => void | Promise<void>;
 }
+/** The most `feeHeadroom` a tx may ask for: 100 × the base fee. */
+export declare 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 declare const MIN_NEW_ACCOUNT = 10000000n;
 /** `Wallet.build`'s options: a tx's, plus the resolutions of names it carries as addresses. */
 export interface BuildOptions extends TxOptions {
     /** `Client.resolution`s of names in `action`'s address fields (refused on mainnet unless proven). */
@@ -246,7 +286,16 @@ export declare class Wallet {
     tip: bigint;
     /** Default validity (blocks from now) for this wallet's transactions. */
     validForBlocks: number;
+    /** Default `feeHeadroom` for this wallet's transactions (1: none). See `TxOptions.feeHeadroom`. */
+    feeHeadroom: number;
     private readonly 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.
+     */
+    private queue;
+    /** The nonce after the last tx this wallet submitted, for one chain and account, and that tx. */
+    private cursor?;
     private acting?;
     /** How `actAs` found the account, when that was one node's unproven word (checked when signing on mainnet). */
     private actingUnproven?;
@@ -319,6 +368,35 @@ export declare class Wallet {
      * found that way (audit gap-7-1). Checked against the very status the tx is signed for.
      */
     private buildChecked;
+    /**
+     * 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.
+     */
+    private feeFor;
+    /**
+     * 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.
+     */
+    private nonceFor;
+    /** Runs `job` after every job queued before it (its outcome doesn't stop the next one). */
+    private enqueue;
+    /**
+     * 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.
+     */
+    private submitQueued;
     /**
      * 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
@@ -328,10 +406,63 @@ export declare class Wallet {
      * from the height the node reported, and release it later, by when the name may have lapsed
      * and been registered again (audit gap-7-1, review-r3-clients-2). See `Client.recipient`.
      */
-    send(to: string, amount: string | number | bigint, opts?: {
+    send(to: string, amount: Amount, opts?: SendOptions): Promise<any>;
+    /**
+     * `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).
+     */
+    private pay;
+    /**
+     * 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.
+     */
+    private openingCost;
+    /**
+     * 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.
+     */
+    private opened;
+    /**
+     * 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.
+     */
+    quote(to: string, amount: Amount, opts?: {
         memo?: string;
+    } & TxOptions): Promise<Quote>;
+    /**
+     * 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`.
+     */
+    sendMany(payments: PaymentOrder[], opts?: {
+        concurrency?: number;
         wait?: boolean;
-    } & TxOptions): Promise<any>;
+        patienceMs?: number;
+        onSigned?: SendOptions["onSigned"];
+    } & TxOptions): Promise<PaymentResult[]>;
     registerName(name: string, opts?: {
         wait?: boolean;
     } & TxOptions): Promise<any>;
@@ -566,19 +697,222 @@ export declare class Wallet {
     claimDistribution(distributionId: number, amount: Amount, proof: string[], opts?: TxOptions): Promise<any>;
     /** Low-level (validator nodes do this automatically): a matured claim's PR was reverted by commit `revertSha`. */
     attestRevert(claimId: number, revertSha: string, opts?: TxOptions): Promise<any>;
+    /** The chain's fuel prices, with programs required to be on (`ProgramsOffError`) and to admit this kind of transaction now. */
+    private programsFor;
+    /** Waits (up to `waitMs`) for the node's head to pass `height`: what block `height` stored is usable from the next one (§2.1). */
+    private waitPast;
+    /**
+     * 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).
+     */
+    private finalThen;
+    /**
+     * 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.
+     */
+    private waitUsable;
+    /** 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. */
+    private programForCall;
+    /**
+     * 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.
+     */
+    private resolveBindings;
+    /**
+     * 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`.
+     */
+    private sendProgram;
+    /**
+     * 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.
+     */
+    uploadCode(wasm: Uint8Array | string, iface: Uint8Array | string, opts?: ProgramTxOptions & {
+        storageLimit?: Amount;
+    }): Promise<UploadedCode>;
+    /**
+     * 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.
+     */
+    createProgram(opts: CreateProgramOptions): Promise<CreatedProgram>;
+    /**
+     * 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.
+     */
+    callProgram(calls: ProgramCallInput[], opts?: ProgramCallOptions): Promise<ProgramTxResult>;
+    /**
+     * 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`.
+     */
+    call(program: string, method: string, input?: Uint8Array | string, opts?: ProgramCallOptions & {
+        value?: Amount;
+        versionDigest?: string;
+    }): Promise<ProgramTxResult>;
+    /**
+     * 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.
+     */
+    programsPause(opts?: TxOptions & {
+        onSigned?: SendOptions["onSigned"];
+    }): Promise<any>;
     /** This account's shares in a validator's pool, for `"all"`; anything else is parsed and checked. */
     private sharesOf;
     /** A proposal kind with its accounts as `Client.recipient` signs them (the chain resolves names when the proposal is made). */
     private resolveKind;
+    /**
+     * 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.
+     */
     balance(): Promise<string>;
+    /**
+     * 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()`.
+     */
+    balances(): Promise<Balances>;
     /** Dev/test chains only: drip 100 FANG to this wallet. */
     faucet(wait?: boolean): Promise<any>;
 }
-/** 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 declare class ApiError extends Error {
     readonly status: number;
-    constructor(status: number, message: string);
+    readonly retryAfterMs?: number | undefined;
+    constructor(status: number, message: string, retryAfterMs?: number | undefined);
 }
+/**
+ * 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 declare class MainnetNotAllowedError extends Error {
+    readonly rpc: string;
+    constructor(rpc: string);
+}
+/** The most txs a node holds pending from one sender (node/src/chain.rs `MAX_PENDING_PER_SENDER`). */
+export declare const MAX_PENDING_PER_SENDER = 64;
+/** `Wallet.balances()`: an account's balances in bigint drops, and as FANG text. */
+export interface Balances {
+    /** Everything the account holds (staked FANG isn't in it). */
+    balance: bigint;
+    /** What it can pay or send now, fees included: the "can pay" number. */
+    transferable: bigint;
+    /** What vesting and vote locks hold. */
+    locked: bigint;
+    /** Whether the chain has opened this account yet. */
+    exists: boolean;
+    display: {
+        balance: string;
+        transferable: string;
+        locked: string;
+    };
+}
+/** `Wallet.quote()`: what a payment would cost, in bigint drops (see `quote`). */
+export interface Quote {
+    amount: bigint;
+    /** The base fee at `suggested` for its size, plus the tip. */
+    fee: bigint;
+    /** The most it can be charged (its `fee` field). */
+    maxFee: bigint;
+    /** Burned from the payer when the payment opens the recipient's account; 0 otherwise. */
+    creationFee: bigint;
+    /** amount + fee + creationFee. */
+    total: bigint;
+    /** What the payer could still move afterwards, counting `maxFee`; negative when it can't pay. */
+    transferableAfter: bigint;
+    enough: boolean;
+    /** The recipient has no account yet: this payment opens it. */
+    opensAccount: boolean;
+    /** How the recipient gets signed: show `how` before paying. */
+    recipient: Recipient;
+    display: {
+        amount: string;
+        fee: string;
+        maxFee: string;
+        creationFee: string;
+        total: string;
+        transferableAfter: string;
+    };
+}
+/** One payment for `Wallet.sendMany`. */
+export type PaymentOrder = {
+    to: string;
+    amount: Amount;
+    memo?: string;
+} & Omit<TxOptions, "maxFee">;
+/** What happened to one payment of `Wallet.sendMany`. */
+export type PaymentResult = {
+    ok: true;
+    to: string;
+    amount: Amount;
+    tx: any;
+} | {
+    ok: false;
+    to: string;
+    amount: Amount;
+    error: unknown;
+};
 /**
  * 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
@@ -614,6 +948,21 @@ export declare class TxPendingError extends Error {
     readonly lastError?: unknown;
     constructor(id: string, waitedMs: number, lastError?: unknown);
 }
+/**
+ * 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 declare class ProgramFailedError extends TxFailedError {
+    readonly words: string;
+    readonly receipt: ProgramReceipt;
+    /** The program's own abort message, if it aborted with one: its words, not this SDK's. */
+    readonly untrusted_message?: string;
+    constructor(id: string, words: string, tx: unknown, receipt: ProgramReceipt, validUntil?: number);
+}
 /** 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 declare class RequestTimeoutError extends Error {
     readonly rpc: string;
@@ -676,9 +1025,24 @@ export declare class ChainMismatchError extends Error {
 }
 /** What a `Client` requires of the node. Every `/api/status` (including the one `Wallet.build` signs against) is checked. */
 export interface ClientOptions {
+    /**
+     * A network this SDK knows (`NETWORKS`): its public RPC (when no URL is given) and every pin it
+     * has (chain id, genesis hash, address prefix, genesis clock), set up front. Pins you pass too
+     * must agree with it.
+     */
+    network?: NetworkName;
+    /**
+     * Submit txs in their wire form (`txBytes`, `application/octet-stream`): about half the bytes
+     * of JSON. Off by default: the JSON form is refused outright when it has a field the node doesn't
+     * know (422), where the wire form leaves such a field out.
+     */
+    wireTxs?: boolean;
     /** The address prefix you expect (`boo` or `tboo`). */
     prefix?: string;
-    /** The chain id the node must report (e.g. `blockula-1`). */
+    /**
+     * The chain id the node must report (e.g. `blockula-testnet-2`). Wallets sign on `blockula-1`
+     * only through a client pinned to it (`MainnetNotAllowedError`).
+     */
     chainId?: string;
     /** The genesis hash (hex) the node must report. */
     genesisHash?: string;
@@ -772,12 +1136,104 @@ export interface ProvenOptions {
     /** How many blocks the proof may be behind the newest head seen (default `DEFAULT_MAX_PROOF_LAG_BLOCKS`). */
     maxLagBlocks?: number;
 }
+/** Options of a program transaction (`Wallet.uploadCode`, `createProgram`, `callProgram`, `call`): a tx's, and how long to wait. */
+export interface ProgramTxOptions extends TxOptions {
+    /** Called with the signed tx and its id before it's submitted (as `SendOptions.onSigned`): store them, and every outcome is recoverable. */
+    onSigned?: SendOptions["onSigned"];
+    /** How long to wait (ms) for what the transaction needs to be usable, and for the block after its own (default 60 s). */
+    waitMs?: number;
+}
+/** What `callProgram` and `call` take beyond a tx's options. */
+export interface ProgramCallOptions extends ProgramTxOptions {
+    /** Fuel to run the calls, at most `program_max_tx_fuel` (default that). Reserved fuel is paid for and never refunded. */
+    fuelLimit?: number;
+    /** The most the calls' storage deposits may bond (FANG). Default 0: no new storage; a method that writes needs a limit. */
+    storageLimit?: Amount;
+    /** Programs the calls may reach besides their own. */
+    bindings?: ProgramBindingInput[];
+}
+/** A program the transaction may reach: by address, at the version digest given, or the version in force now when none is (`ANY_PROGRAM_VERSION` for any). */
+export interface ProgramBindingInput {
+    program: string;
+    versionDigest?: string;
+}
+/** One call of `callProgram`. */
+export interface ProgramCallInput {
+    /** The program's address, never a name. */
+    program: string;
+    /** A `call` method of its interface. */
+    method: string;
+    /** What the method reads: bytes, or lowercase hex. Default none. */
+    input?: Uint8Array | string;
+    /** FANG sent with the call (only to a payable method). */
+    value?: Amount;
+    /** The version digest the user was shown for this program: the call is refused if the program isn't the one it names. */
+    versionDigest?: string;
+}
+/** What a finalized program transaction gave: the node's answer, its checked receipt, and what it cost its signer. */
+export interface ProgramTxResult {
+    tx: any;
+    receipt: ProgramReceipt;
+    cost: ProgramCost;
+}
+/** `Wallet.uploadCode`'s result. */
+export interface UploadedCode extends ProgramTxResult {
+    wasmHash: string;
+    interfaceHash: string;
+    /** What this upload bonded (drops): 0 when both were stored already. */
+    deposit: bigint;
+}
+/** What `Wallet.createProgram` takes. */
+export interface CreateProgramOptions extends ProgramTxOptions {
+    /** The stored code's hash and the stored interface's (`uploadCode` returns them). */
+    wasmHash: string;
+    interfaceHash: string;
+    /** Run the interface's `Init` method as the program is created (present exactly when the interface has one). */
+    init?: {
+        method: string;
+        input?: Uint8Array | string;
+        value?: Amount;
+    };
+    /** Fuel for the initializer, at most `program_max_tx_fuel` (default that). */
+    fuelLimit?: number;
+    /** The most the record's deposit and the initializer's writes may bond (FANG; default the record's deposit plus 10%). */
+    storageLimit?: Amount;
+    bindings?: ProgramBindingInput[];
+    /** An account (an address) that may upgrade the program once upgrades exist; without it the program is immutable. */
+    authority?: string;
+    delayBlocks?: number;
+    policy?: ProgramPolicy;
+    /** The program takes plain transfers to its address. */
+    acceptsTransfers?: boolean;
+}
+/** `Wallet.createProgram`'s result: the program's address, only once the create has applied. */
+export interface CreatedProgram extends ProgramTxResult {
+    address: string;
+    /** The program as the node reads it a block after the create. */
+    program: ProgramInfo;
+}
 /** A record proven against a state root, and the newest head height that root was checked against. */
 export type ProvenRead = ProvenRecord & {
     head: number;
 };
+/** A page of an account's history (`Client.history`), newest first. */
+export interface HistoryPage {
+    /**
+     * Finalized txs sent by the account or naming it, as `/api/tx` shows them (`to` is
+     * `{ address, name }`). Pending ones are in `client.account(id).recent_txs`.
+     */
+    txs: any[];
+    /** The cursor of the next (older) page, for `before`; `null` at the end. */
+    next: string | null;
+    /** The first block the node holds: nothing older is in its history. */
+    history_from?: number;
+    /**
+     * False on a node without paged history (`/api/account/{id}/txs`): `txs` is then `/api/account`'s
+     * `recent_txs` (its pending txs and the newest 25 finalized ones), and there's no `next`.
+     */
+    paged: boolean;
+}
 export declare class Client {
-    readonly rpc: string;
     /** The chain's address prefix: given, learned from `/api/status`, or `boo` until then. */
     prefix: string;
     private prefixKnown;
@@ -796,8 +1252,27 @@ export declare class Client {
         createdAtMs: number;
         blockTimeMs: number;
     };
-    /** `opts` pins the chain: a node reporting another prefix, chain id or genesis hash is refused with `ChainMismatchError`. */
-    constructor(rpc?: string, opts?: ClientOptions);
+    /** The node's URL. */
+    readonly rpc: string;
+    /** The network this client was made for (`ClientOptions.network`), if any. */
+    readonly network?: NetworkName;
+    /** See `ClientOptions.wireTxs`. */
+    readonly wireTxs: boolean;
+    /** The public testnet (`NETWORKS.testnet`), every pin set: `Client.testnet({ witnesses })`, or pass your own node's URL as `rpc`. */
+    static testnet(opts?: Omit<ClientOptions, "network"> & {
+        rpc?: string;
+    }): Client;
+    /** A `blockula dev` chain on this machine (`NETWORKS.local`). */
+    static local(opts?: Omit<ClientOptions, "network"> & {
+        rpc?: string;
+    }): Client;
+    /**
+     * `new Client(rpc, opts)`, `new Client({ network: "testnet" })` (the network's public RPC), or
+     * `new Client(rpc, { network })` (your own node, held to that network's pins). The pins
+     * (`opts`, and the network's) are checked on every status: a node reporting another prefix,
+     * chain id or genesis hash is refused with `ChainMismatchError`.
+     */
+    constructor(rpc?: string | ClientOptions, options?: ClientOptions);
     /**
      * Refuses (`HeightAheadError`, before anything is signed) a height a tx's validity window would
      * count from that this client has reason to think the chain hasn't reached: more than
@@ -810,12 +1285,44 @@ export declare class Client {
      * Without witnesses or a genesis clock, the height is the node's word.
      */
     checkSigningHeight(height: number): Promise<void>;
+    /**
+     * 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: number): void;
     /** The chain's address prefix, asking the node once if it isn't known yet. */
     addressPrefix(): Promise<string>;
+    /**
+     * 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: unknown): void;
+    /** The chain id this client is pinned to (`ClientOptions.chainId`), if any. A client that pins the chain itself reports its own pin. */
+    protected chainPin(): string | undefined;
     /** One request, bounded by `timeoutMs` (headers and body): a node that never answers fails with `RequestTimeoutError` instead of hanging. */
     private call;
     status(): Promise<any>;
-    blocks(limit?: number): Promise<any>;
+    /**
+     * 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.
+     */
+    blocks(page?: number | {
+        limit?: number;
+        before?: number;
+    }): Promise<any[]>;
+    /**
+     * 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`).
+     */
+    history(account: string, page?: {
+        before?: string;
+        limit?: number;
+    }): Promise<HistoryPage>;
     block(heightOrHash: number | string): Promise<any>;
     tx(id: string): Promise<any>;
     account(addressOrName: string): Promise<any>;
@@ -884,6 +1391,82 @@ export declare class Client {
     distribution(id: number): Promise<any>;
     /** A multisig account: owners, threshold, open proposals and their approvals. */
     multisig(account: string): Promise<any>;
+    /**
+     * 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).
+     */
+    programFuel(): Promise<ProgramFuel>;
+    /** The programs parameters a deposit is priced with (`/api/params`' `programs` section), checked. */
+    programParams(): Promise<ProgramParams>;
+    /**
+     * 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.
+     */
+    program(address: string): Promise<ProgramInfo>;
+    /**
+     * 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.
+     */
+    code(hash: string, opts?: {
+        wasm?: boolean;
+    }): Promise<ProgramCodeInfo>;
+    /**
+     * 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).
+     */
+    interface(hash: string): Promise<ProgramInterfaceInfo>;
+    /**
+     * 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.
+     */
+    view(address: string, method: string, input?: Uint8Array | string, opts?: {
+        bindings?: {
+            program: string;
+            versionDigest?: string;
+        }[];
+        fuel?: number;
+    }): Promise<ProgramViewResult>;
+    /**
+     * 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).
+     */
+    provenProgram(address: string, opts?: ProvenOptions): Promise<{
+        creator: string;
+        created_at: number;
+        wasm_hash: string;
+        interface_hash: string;
+        version: number;
+        authority: string | null;
+        upgrade_delay_blocks: number;
+        policy: "open" | "additive";
+        accepts_transfers: boolean;
+        storage: {
+            items: number;
+            bytes: number;
+            deposit: string;
+        };
+        sponsored: string;
+        record_deposit: string;
+        record_payer: string;
+        address: string;
+        version_digest: string;
+        witnesses: number;
+        height: number;
+        root: string;
+        head: number;
+    } | null>;
     /** `/api/proof/{namespace}/{key}`, unchecked. Prefer `provenRecord`. */
     proof(namespace: number, key: string | Uint8Array): Promise<ProofResponse>;
     /**
@@ -967,6 +1550,14 @@ export declare class Client {
      * - `TxPendingError`: it was admitted and may still execute. Don't send it again blindly.
      */
     submit(tx: Tx, wait?: boolean): Promise<any>;
+    /**
+     * 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.
+     */
+    post(tx: Tx): Promise<{
+        id: string;
+    }>;
     faucet(to: string, wait?: boolean): Promise<any>;
     /**
      * Polls a tx until it's finalized (returns it) or failed (`TxFailedError`, which says whether it