@blockula/sdk 0.3.0 → 0.5.1

package/dist/index.d.ts

@@ -1,10 +1,236 @@
-import { type Action, type Tx, type UnsignedTx } from "./tx.js";
+import { type SeanceClaimRef, type Action, type BaseFee, type ProposalKind, type Tx, type UnsignedTx } from "./tx.js";
+import { type ProofResponse, type ProvenRecord } from "./proof.js";
 export * from "./tx.js";
+export * from "./proof.js";
+export * from "./distribution.js";
+export * from "./release.js";
+export * from "./describe.js";
 export declare const DEFAULT_RPC = "http://localhost:7070";
-export declare function addressFromPublicKey(publicKey: Uint8Array): string;
+/** Address prefixes: `boo` on mainnet (and dev chains), `tboo` on public testnets. */
+export declare const KNOWN_PREFIXES: readonly ["boo", "tboo"];
+export declare const DEFAULT_PREFIX = "boo";
+/** Mainnet's chain id (node/src/chain.rs `MAINNET_CHAIN_ID`). */
+export declare const MAINNET_CHAIN_ID = "blockula-1";
+/** How long a transaction stays valid by default: 600 blocks (10 minutes at 1 s blocks). */
+export declare const DEFAULT_VALID_FOR_BLOCKS = 600;
+/** The address of a public key: bech32m(prefix, BLAKE3(public key)). */
+export declare function addressFromPublicKey(publicKey: Uint8Array, prefix?: string): string;
 /** A key's id: BLAKE3(public key) as hex. Same 32 bytes as inside the `boo1…` address it derives. */
 export declare function keyId(publicKey: Uint8Array): string;
-export declare function isAddress(s: string): boolean;
+/** The prefix of a canonical address (`boo`, `tboo`), or `undefined` if `s` isn't one. */
+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. */
+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;
+/**
+ * The most `Wallet.propose` bonds by default without being told (audit gap-7-5): mainnet's genesis
+ * `proposal_deposit` (node/src/params.rs). A node reporting more is refused; pass `deposit`.
+ */
+export declare const DEFAULT_MAX_PROPOSAL_DEPOSIT: bigint;
+/** Highest vote conviction (node/src/params.rs `MAX_CONVICTION`). */
+export declare const MAX_CONVICTION = 6;
+/** Lock periods a vote at each conviction locks its amount for (params.rs `CONVICTION_PERIODS`) … */
+export declare const CONVICTION_PERIODS: readonly [0, 1, 2, 4, 8, 16, 32];
+/** … and its weight in tenths of the amount (`CONVICTION_TENTHS`): 0.1× with no lock, then 1×–6×. */
+export declare const CONVICTION_TENTHS: readonly [1, 10, 20, 30, 40, 50, 60];
+/** A vote's weight in drops: `amount` × the conviction multiplier (params.rs `vote_weight`). */
+export declare function convictionWeight(amount: Amount, conviction: number): bigint;
+/**
+ * Builders for `Wallet.propose` kinds (node/src/types.rs `ProposalKind`). Amounts are FANG (or
+ * bigint drops), Soul is in Soul ("2.5"); names in `to`/`account` are resolved when proposing.
+ */
+export declare const proposal: {
+    /** Set a governance parameter (a key of `/api/params`, e.g. "max_validators") to a raw value (drops, blocks, bps …), within its bounds. */
+    paramChange(key: string, value: bigint | number | string): ProposalKind;
+    /** Pay from the treasury (spends above a share of the treasury need a supermajority). */
+    treasurySpend(to: string, amount: Amount): ProposalKind;
+    /**
+     * Open a community distribution of `total`, claimable with Merkle proofs against `merkleRoot` until block `claimUntil`.
+     * `distributionId` is the id the tree was built for (`buildDistribution(id, …)`): one no distribution has yet,
+     * at most 1,000 past the next proposal id (`client.proposals()`'s `next_distribution_id` is free, and
+     * `max_distribution_id` is the largest allowed; the range only grows). Other proposals landing first don't change
+     * it, so a multisig can take its time approving; if a distribution with that id opens first, the node refuses this
+     * one (nothing is escrowed), or it fails when it runs. Claims close at most 730 days after the proposal's vote ends.
+     */
+    distribution(distributionId: number, merkleRoot: string, total: Amount, claimUntil: number): ProposalKind;
+    /** Put a repo in the contribution pool (weight 1–100; 0 removes it). */
+    setRepo(repo: string, weight: number): ProposalKind;
+    /** Grant Soul (in Soul, "2.5"; at most 100 per grant). */
+    grantSoul(to: string, soul: string | number, reason: string): ProposalKind;
+    flagSybil(account: string, reason: string): ProposalKind;
+    /** Lift a sybil flag: the appeal path for `flagSybil` (nothing the flag took comes back). */
+    unflagSybil(account: string, reason: string): ProposalKind;
+    rejectClaim(claimId: number, reason: string): ProposalKind;
+    clawback(account: string, reason: string): ProposalKind;
+    unlinkGithub(handle: string): ProposalKind;
+    /** Refund every funder of a hunt (escrow can be refunded, never redirected). */
+    refundHunt(huntId: number): ProposalKind;
+    /**
+     * Switch to protocol `version` at block `activationHeight` (needs a supermajority). The version is newer than
+     * every one scheduled or withdrawn (`client.upgrade()`'s `withdrawn.highest_version`) and at most 16 past the
+     * newest scheduled, withdrawn or superseded (`next_version` is the number to use); the activation is at most
+     * 365 days after the proposal's vote ends.
+     */
+    scheduleUpgrade(version: number, activationHeight: number): ProposalKind;
+    /**
+     * Withdraw the upgrade to protocol `version` scheduled at block `activationHeight` (see
+     * `client.upgrade()`), and any scheduled after it, before it activates. Needs a supermajority;
+     * there's no timelock (it runs the block after its vote), and it must run at least 64 blocks
+     * before the activation height, so propose it at least `voting_blocks + 65` blocks ahead.
+     */
+    cancelUpgrade(version: number, activationHeight: number): ProposalKind;
+    /** Turn on a feature flag (e.g. "ghost"). */
+    activateFeature(feature: string): ProposalKind;
+    deactivateFeature(feature: string): ProposalKind;
+    /** A signal with no on-chain effect. */
+    text(): ProposalKind;
+};
+/** One pool an account has stake in (`/api/staking/{account}` `delegations[]`). */
+export interface StakeDelegation {
+    validator: string;
+    validator_name: string | null;
+    /** Pool shares held (what `undelegate` takes). */
+    shares: string;
+    /** Their current value, in drops. */
+    value: string;
+    /** What went in, less what sales and slashes took (value above it is earnings). */
+    principal: string;
+    /** This is the validator's owner's self-bond. */
+    self_bond: boolean;
+}
+/** Stake on its way out (`entries[]` of type `unbonding`): paid out by `withdrawUnbonded` from `completes_at`. */
+export interface StakeUnbonding {
+    id: number;
+    validator: string;
+    amount: string;
+    started_at: number;
+    completes_at: number;
+    ready: boolean;
+}
+/** Stake moved between pools (`entries[]` of type `redelegation`): slashable by `from` until `completes_at`. */
+export interface StakeRedelegation {
+    id: number;
+    from: string;
+    to: string;
+    amount: string;
+    completes_at: number;
+}
+/** An account's stake, from `/api/staking/{account}`. */
+export interface StakeSummary {
+    delegations: StakeDelegation[];
+    unbonding: StakeUnbonding[];
+    redelegations: StakeRedelegation[];
+    /** Total value staked, in drops. */
+    bonded: string;
+    /** Total unbonding, in drops. */
+    unbonding_total: string;
+    /** Unbonding that has finished (what `withdrawUnbonded` pays now), in drops. */
+    withdrawable: string;
+    /** The node's plain-English summary. */
+    summary: string;
+}
+export declare function stakeSummary(raw: unknown): StakeSummary;
+/**
+ * Shares worth about `value` drops in a delegation (rounded down, at most all of them), at the
+ * value the delegation reports. That's a node's word: to unbond an amount, pass
+ * `wallet.undelegate(validator, { amount })`, which the chain converts itself (audit gap-7-5).
+ */
+export declare function sharesFor(d: StakeDelegation, value: Amount): bigint;
+/** `/api/params`' governance parameters as a key → value map (values as strings: amounts can exceed 2^53). */
+export declare function paramsOf(raw: unknown): Record<string, string>;
+/** A proposal, from `/api/proposals` (`proposals[]`) or `/api/proposal/{id}`. Amounts are in drops. */
+export interface ProposalSummary {
+    id: number;
+    title: string;
+    url: string;
+    /**
+     * The node's own summary text. No digest covers it, so a lying node can make it say anything
+     * (audit gap-7-6): show `does` instead, and never present this as what the proposal does.
+     */
+    summary: string;
+    /** What it does, rendered here from `kind` (`describeKind`): what a vote on it binds. */
+    does: string;
+    kind: ProposalKind | null;
+    /**
+     * `proposalDigest(kind, title, url)`: what a vote binds. `null` when this client can't compute
+     * it exactly (`digest_error` says why, e.g. a number past 2^53): it can't vote on it either.
+     */
+    digest: string | null;
+    digest_error?: string;
+    proposer: string | null;
+    proposer_name: string | null;
+    /** `voting`, `queued`, `rejected`, `executed` or `failed`. */
+    status: string;
+    deposit: string;
+    /** Conviction-weighted ayes and nays (what the majority counts) … */
+    aye: string;
+    nay: string;
+    /** … and the raw FANG behind them (what quorum counts). */
+    aye_amount: string;
+    nay_amount: string;
+    /** aye_amount + nay_amount. */
+    turnout: string;
+    voters: number;
+    /** The quorum it had to reach and whether it did: known once voting closed. */
+    quorum?: string;
+    quorum_reached?: boolean;
+    /** Bootstrap-council votes so far (one per validator); `of` is the set's size at the close. */
+    council: {
+        ayes: number;
+        nays: number;
+        of?: number;
+    };
+    /** Whether it needs `supermajority_bps` of the weight (upgrades, feature activations, issuance parameters, large spends). */
+    supermajority: boolean;
+    /** Last block votes count in, and when a passed proposal runs (after the timelock). */
+    voting_ends_at: number;
+    executes_at?: number;
+    /** Why it was rejected or failed, or what it did. */
+    outcome: string;
+    /** With `rules` (`/api/proposals`' `params`): the share of the weight its ayes need, in basis points. */
+    threshold_bps?: number;
+}
+export declare function proposalSummary(raw: unknown, rules?: {
+    supermajority_bps?: number;
+}): ProposalSummary;
+/** Per-transaction options. */
+export interface TxOptions {
+    /** Paid to the block's proposer on top of the base fee: FANG ("0.001") or bigint drops. Default: the wallet's `tip` (0). At most `tip_cap_multiple` (20) × the base fee (`maxTip`), from transferable FANG. */
+    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;
+}
+/** `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). */
+    resolutions?: Resolution[];
+}
+/**
+ * A key's consent to being added to one account (audit gap-7-2): its public key and its
+ * signature over `keyPopMessage(chain_id, genesis_hash, account, key_id)` (context
+ * `KEY_POP_CONTEXT`). The key's holder makes it (`Wallet.keyGrant`) and hands it to the account's
+ * owner (`encodeKeyGrant`: a grant code to paste), who adds the key with it (`addOwnerKey`,
+ * `addSessionKey`). Nobody can put a key on an account without it, so `/api/key` lists only
+ * accounts the key agreed to.
+ */
+export interface KeyGrant {
+    /** The account the key agrees to join. */
+    account: string;
+    key_id: string;
+    /** Hex ML-DSA-65 public key. */
+    public_key: string;
+    /** Hex proof of possession. */
+    pop: string;
+}
+/** A grant as one pasteable string: `bkgrant1.<account>.<base64url(public key ‖ pop)>`. */
+export declare function encodeKeyGrant(g: KeyGrant): string;
+/** Parses a grant code (`encodeKeyGrant`). Whitespace is ignored, so a wrapped paste works. */
+export declare function decodeKeyGrant(code: string): KeyGrant;
+/** Whether `g` is a valid consent by its key to join `g.account` on the chain `(chainId, genesisHash)`. */
+export declare function verifyKeyGrant(g: KeyGrant, chainId: string, genesisHash: string): boolean;
 /**
  * Wallet = one ML-DSA-65 key (from a 32-byte seed, FIPS 204 ξ) acting for one account.
  * By default the account is the key's own address. Call `actAs(account)` to use a key that
@@ -14,16 +240,30 @@ export declare class Wallet {
     readonly seed: Uint8Array;
     client: Client;
     readonly publicKey: Uint8Array;
-    /** This key's own address. */
-    readonly address: string;
-    /** The account this wallet acts for (defaults to `address`). */
-    account: string;
     /** WebAuthn credential id, when the wallet was unlocked by a passkey. Not secret. */
     credentialId?: Uint8Array;
+    /** Default tip (drops) for this wallet's transactions. */
+    tip: bigint;
+    /** Default validity (blocks from now) for this wallet's transactions. */
+    validForBlocks: number;
     private readonly secretKey;
+    private acting?;
+    /** How `actAs` found the account, when that was one node's unproven word (checked when signing on mainnet). */
+    private actingUnproven?;
     private constructor();
+    /** This key's own address, with the chain's prefix once the client knows it (`await client.addressPrefix()`). */
+    get address(): string;
+    /** The account this wallet acts for (defaults to `address`). */
+    get account(): string;
+    set account(account: string);
     get keyId(): string;
-    /** Act for another account this key has been authorized on. Accepts a name or address. */
+    /**
+     * Act for another account this key has been authorized on. Accepts a name or address. A name
+     * needs an address here (every tx names the account it acts for), so it's resolved: proven with
+     * the client's witnesses. Without them it's one node's word, and on mainnet nothing is signed
+     * for an account found that way (`UnprovenNameError`): check the address and pass it instead
+     * (audit gap-7-1).
+     */
     actAs(account: string): Promise<this>;
     static generate(client?: Client): Wallet;
     static fromSeed(seed: string | Uint8Array, client?: Client): Wallet;
@@ -34,30 +274,88 @@ export declare class Wallet {
     static fromPasskeyPrf(prfOutput: Uint8Array, client?: Client): Wallet;
     get seedHex(): string;
     sign(tx: UnsignedTx): Tx;
-    build(action: Action, memo?: string): Promise<Tx>;
-    /** Send FANG to a `.boo` name or `boo1…` address. `amount` is in FANG ("1.5") or bigint drops. */
+    /**
+     * This key's consent to being added to `account` (an address, or a name resolved by the
+     * client: proven when it has witnesses; on mainnet an unproven name is refused, pass the address)
+     * on the client's chain: hand `encodeKeyGrant(grant)` to the account's owner, who adds the key
+     * with it. Pass `chain` to sign offline.
+     */
+    keyGrant(account: string | Resolution, chain?: {
+        chainId: string;
+        genesisHash: string;
+    }): Promise<KeyGrant>;
+    /**
+     * The `add_key` action for a grant (an object or its code): it must be for this account and
+     * verify on the client's chain, so a wrong or damaged code fails here, before anything is signed.
+     */
+    private grantAction;
+    /**
+     * Builds and signs a tx: `fee` = the highest base fee already fixed for the next blocks
+     * (`/api/fees` `suggested`) + `tip`, `valid_until` = the current height + `validForBlocks`, and
+     * the chain's id and genesis hash from `/api/status`. Only the base fee of the block that
+     * includes it (+ the tip) is charged. A tip above `tip_cap_multiple` × the lowest upcoming base
+     * fee (`/api/fees` `lowest`, see `maxTip`) is refused here, as nodes would refuse it. To sign
+     * offline, build an `UnsignedTx` yourself (with the chain's `genesis_hash`) and `sign` it.
+     *
+     * `action` may be a function of the height `valid_until` is counted from, for actions that
+     * carry an absolute block height of their own (a session key's or a hunt's expiry): computed
+     * from the same status read, a node that lies about the height can stretch them by at most
+     * `max_tx_validity_blocks`, since validators refuse a `valid_until` further ahead than that
+     * (audit gap-7-3).
+     *
+     * That height is checked first (`Client.checkSigningHeight`: against the witnesses' heads and,
+     * when the client knows its genesis clock, the clock), since a node reporting one the chain
+     * hasn't reached gets a tx it can hold and release later.
+     *
+     * `opts.resolutions`: how names in fields that need an address got into `action` (their
+     * `Client.resolution`s). On mainnet a tx carrying one that only one node vouched for isn't
+     * signed (`UnprovenNameError`), checked against the very status the tx is signed for, as the
+     * helpers do (audit gap-7-1). Fields the chain resolves itself take `Client.recipient(x).signed`.
+     */
+    build(action: Action | ((height: number) => Action), memo?: string, opts?: BuildOptions): Promise<Tx>;
+    /**
+     * `build`, refusing on mainnet a tx that carries an address only one node vouched for: `unproven`
+     * (the helpers' resolutions of names in fields that need an address) or the account `actAs`
+     * found that way (audit gap-7-1). Checked against the very status the tx is signed for.
+     */
+    private buildChecked;
+    /**
+     * Send FANG to a `.boo` name or an address. `amount` is in FANG ("1.5") or bigint drops. A name
+     * is signed as its proven owner's address when the client has witnesses (who you checked is who
+     * gets paid, even if the name changes hands before the tx runs), and as the name itself when it
+     * doesn't: the chain then pays whoever owns it when the tx runs. A lying node can't point it at
+     * another account now, but it can hold the signed tx until its validity window, which counts
+     * from the height the node reported, and release it later, by when the name may have lapsed
+     * and been registered again (audit gap-7-1, review-r3-clients-2). See `Client.recipient`.
+     */
     send(to: string, amount: string | number | bigint, opts?: {
         memo?: string;
         wait?: boolean;
-    }): Promise<any>;
+    } & TxOptions): Promise<any>;
     registerName(name: string, opts?: {
         wait?: boolean;
-    }): Promise<any>;
-    /** Authorize another device's key (e.g. a second passkey) with full control. */
-    addOwnerKey(keyIdHex: string, label: string): Promise<any>;
+    } & TxOptions): Promise<any>;
+    /**
+     * 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).
+     */
+    addOwnerKey(grant: KeyGrant | string, label: string): Promise<any>;
     /**
-     * Let an agent/app key spend from this account, transfers only, within a limit.
-     * Example: `addSessionKey(agentKeyId, "claude", { limit: "10", periodBlocks: 86_400, expiresInBlocks: 30 * 86_400 })`.
+     * Let an agent/app key spend from this account, transfers only, within a limit. `grant` is the
+     * key's consent to this account (the agent's grant code).
+     * Example: `addSessionKey(grantCode, "claude", { limit: "10", periodBlocks: 86_400, expiresInBlocks: 30 * 86_400 })`.
      */
-    addSessionKey(keyIdHex: string, label: string, opts: {
+    addSessionKey(grant: KeyGrant | string, label: string, opts: {
         limit: string | number | bigint;
         periodBlocks: number;
         expiresInBlocks: number;
     }): Promise<any>;
     removeKey(keyIdHex: string): Promise<any>;
     /**
-     * Offer a validator: bonds `bond` FANG from this account. `consensusKeyHex` is the validator
-     * node's ML-DSA-65 public key (see `blockula validator init`). Pending until an admin approves.
+     * Register a validator owned by this account, self-bonding `bond` FANG into its stake pool (at
+     * least the chain's `min_self_bond`). `consensusKey` is the validator node's ML-DSA-65 public
+     * key and `pop` its proof of possession (see `blockula validator init`). It's a candidate: at
+     * each epoch boundary the top `max_validators` pools by stake form the next active set.
      */
     registerValidator(opts: {
         consensusKey: string;
@@ -66,9 +364,9 @@ export declare class Wallet {
         bond: string | number | bigint;
         pop: string;
     }): Promise<any>;
-    /** Season 0 admins only. */
+    /** Dev and test chains with admins only: pin a validator into the set ahead of stake. */
     approveValidator(validator: string): Promise<any>;
-    /** Season 0 admins only. */
+    /** Dev and test chains with admins only: take a validator out of the set for good. */
     removeValidator(validator: string): Promise<any>;
     /** Claim a GitHub handle. Verify it by creating a public gist (as that user) containing this account's address. */
     linkGithub(handle: string, gistId: string): Promise<any>;
@@ -82,13 +380,196 @@ export declare class Wallet {
         expiresInBlocks: number;
     }): Promise<any>;
     fundHunt(huntId: number, amount: string | number | bigint): Promise<any>;
-    /** Pay a hunt's bounty (creator or admin). `to` may be a .boo name; it's resolved and the address is signed. */
+    /** Pay a hunt's bounty (creator or admin). `to` may be a .boo name: signed as `Client.recipient` says (the proven address, or the name for the chain to resolve). */
     awardHunt(huntId: number, to: string, pr: number, familiarKey?: string): Promise<any>;
     cancelHunt(huntId: number): Promise<any>;
     /** Mark one of this account's session keys (an agent) as a Familiar. */
     registerFamiliar(keyIdHex: string, label: string): Promise<any>;
+    /** Claim a merged PR (authored by this account's linked GitHub handle) for the contribution pool. Bonded; validators check it on GitHub. */
+    submitClaim(repo: string, pr: number, familiarKey?: string): Promise<any>;
+    /** Stake 10 FANG on a newcomer being a real, distinct person (needs 10 Soul). */
+    vouch(account: string): Promise<any>;
+    /** Withdraw your vouch for `account` (after the lock), or pass your own account to decline one. */
+    unvouch(account: string): Promise<any>;
+    /** Join (or top up) the Séance juror pool. Needs 5 Soul; owner keys only. */
+    joinJury(bond?: string | number | bigint): Promise<any>;
+    leaveJury(): Promise<any>;
+    /**
+     * Seal a Séance judgment: one of "a", "b" or "=" per assigned pair (see `client.seance(id)`),
+     * plus claim ids you think are spam. Keep the returned `salt`: `revealVotes` needs it.
+     *
+     * The judgment binds the pairs it was made on (audit gap-7-6): pass `pairs`, the claims (id,
+     * repo, PR) you showed the juror in order, or they're read from the client (`seancePairs`). A
+     * node that showed other pairs or PRs makes the commitment fail instead of misdirecting it.
+     */
+    sealVotes(seanceId: number, votes: string, spam?: number[], salt?: string, opts?: {
+        pairs?: [SeanceClaimRef, SeanceClaimRef][];
+    }): Promise<{
+        tx: any;
+        salt: string;
+        votes: string;
+        spam: number[];
+    }>;
+    revealVotes(seanceId: number, votes: string, spam: number[], salt: string): Promise<any>;
+    fundPool(amount: string | number | bigint): Promise<any>;
+    /** Withdraw every contribution reward that has vested so far. */
+    withdrawVested(): Promise<any>;
+    /** Admins of dev and test chains only (elsewhere: a governance proposal). Weight 1–100; 0 removes the repo. */
+    setRepo(repo: string, weight: number): Promise<any>;
+    /** Admins of dev and test chains only (elsewhere: a governance proposal). `soul` in Soul ("2.5"), up to 100 per grant. */
+    grantSoul(to: string, soul: string | number, reason: string): Promise<any>;
+    /** Admins of dev and test chains only (elsewhere: a governance proposal). */
+    rejectClaim(claimId: number, reason: string): Promise<any>;
+    /** Admins of dev and test chains only (elsewhere: a governance proposal). */
+    flagSybil(account: string, reason: string): Promise<any>;
+    /** Admins of dev and test chains only (elsewhere: a governance proposal). */
+    clawback(account: string, reason: string): Promise<any>;
     /** Reclaim the bond of a removed validator this account owns. */
     unbond(validator: string): Promise<any>;
+    /** Submits one action (the shared tail of the helpers below); `unproven`: see `buildChecked`. */
+    private act;
+    /**
+     * A validator by address, or by a `.boo` name its account holds. Staking needs the address, so
+     * a name is resolved (proven with the client's witnesses); on mainnet a tx with an unproven one
+     * isn't signed (audit gap-7-1): pass the validator's address.
+     */
+    private validatorAddress;
+    /** `r`, unless it's an unproven name on mainnet (`UnprovenNameError`); `buildChecked` checks again against the signing status. */
+    private addressNeeded;
+    /** Stake `amount` (FANG, or bigint drops) in a validator's pool. Your stake earns its share of issuance and is slashed with the pool. */
+    delegate(validator: string, amount: Amount, opts?: TxOptions): Promise<any>;
+    /**
+     * Start unbonding stake in a validator's pool: `{ amount }` (FANG, or bigint drops), `shares`,
+     * or `"all"` (every share you hold there, read from `/api/staking`). An amount is signed as an
+     * amount and the chain converts it at the pool's price when the tx runs, so no node's report of
+     * the stake decides how much unbonds (audit gap-7-5); prefer it to `sharesFor`. It stops
+     * earning now and can be withdrawn with `withdrawUnbonded` once the unbonding period (21 days
+     * on mainnet) is over.
+     */
+    undelegate(validator: string, shares: bigint | string | "all" | {
+        amount: Amount;
+    }, opts?: TxOptions): Promise<any>;
+    /** Move `shares` (or `"all"`) from one pool to another without waiting out the unbonding period. */
+    redelegate(fromValidator: string, toValidator: string, shares: bigint | string | "all", opts?: TxOptions): Promise<any>;
+    /** Pay out every unbonding entry that has finished unbonding. */
+    withdrawUnbonded(opts?: TxOptions): Promise<any>;
+    /** A validator's owner: set the pool's commission (basis points, 0–10000; it moves a little per epoch at most) and, optionally, new addresses. */
+    updateValidator(opts: {
+        commissionBps: number;
+        p2pAddr?: string;
+        httpAddr?: string;
+    } & TxOptions): Promise<any>;
+    /** Bring a jailed validator back (its owner, after the jail period). */
+    unjail(validator: string, opts?: TxOptions): Promise<any>;
+    /** Low-level (nodes do this automatically): two conflicting signed votes, hex-encoded as the node's evidence reporter emits them. */
+    reportEquivocation(evidenceHex: string, opts?: TxOptions): Promise<any>;
+    /** Low-level (validator nodes do this automatically): commit to a beacon secret for `epoch`. */
+    beaconCommit(epoch: number, commitmentHex: string, opts?: TxOptions): Promise<any>;
+    /** Low-level (validator nodes do this automatically): reveal the beacon secret committed for `epoch`. */
+    beaconReveal(epoch: number, secretHex: string, opts?: TxOptions): Promise<any>;
+    /**
+     * A member of a set of one or two, signing with its consensus key: admit candidate `validator`
+     * into the set at the end of `epoch` (default: the epoch the next block is in; the tx fails in
+     * any other). The newcomer will be needed for every quorum, so this is the operator's decision,
+     * once an epoch per member; it joins once a quorum of the members admitted it and its node
+     * showed up (`validatorReady`).
+     */
+    admitValidator(validator: string, opts?: {
+        epoch?: number;
+    } & TxOptions): Promise<any>;
+    /** Low-level (candidate nodes do this automatically, in the epoch's last tenth, once a set of one or two admitted them): a candidate's consensus key signals its node is running in `epoch`. */
+    validatorReady(epoch: number, opts?: TxOptions): Promise<any>;
+    /**
+     * Put a proposal to a vote (build `kind` with `proposal.*`). Bonds `deposit` (default: the
+     * chain's `proposal_deposit`), refunded once the proposal reaches quorum and burned if it
+     * doesn't. Names in the kind (`to`, `account`) are signed as `Client.recipient` says: the proven
+     * address with witnesses, else the name, which the chain resolves when the proposal is made
+     * (it stores the address, which voters then see and bind).
+     *
+     * The default deposit is what the node reports, and a node can report anything, so it's
+     * bounded (audit gap-7-5): every witness of the client must report the same value, and it may
+     * be at most `maxDeposit` (default `DEFAULT_MAX_PROPOSAL_DEPOSIT`, mainnet's 1,000 FANG).
+     * Pass `deposit` to bond an amount you checked yourself.
+     */
+    propose(kind: ProposalKind, opts: {
+        title: string;
+        url?: string;
+        deposit?: Amount;
+        maxDeposit?: Amount;
+    } & TxOptions): Promise<any>;
+    /**
+     * Vote on a proposal with `amount` of your unlocked holdings (liquid, staked or unbonding;
+     * unvested tokens can't vote). `conviction` 0–6 locks `amount` for 0, 1, 2, 4, 8, 16 or 32 lock
+     * periods after the vote ends, for 0.1×, 1×, 2× … 6× the weight (see `convictionWeight`).
+     * Voting again replaces your vote. A validator's consensus key or owner voting before the
+     * bootstrap council ends also casts that validator's council vote.
+     *
+     * The vote binds the proposal's content (audit gap-7-6): pass `proposal`, the kind, title and
+     * link you showed the voter (e.g. the `client.proposal(id)` object you rendered, described with
+     * `describeKind`), or it's read from the client. A node that showed another proposal's content
+     * makes the vote fail. If you showed it earlier and only kept its digest
+     * (`proposalSummary(raw).digest`), pass `digest`: a proposal that reads differently now is
+     * refused before anything is signed.
+     */
+    vote(proposalId: number, aye: boolean, amount: Amount, conviction?: number, opts?: TxOptions & {
+        proposal?: {
+            kind: ProposalKind;
+            title: string;
+            url?: string;
+        };
+        digest?: string;
+    }): Promise<any>;
+    /** Release every vote lock that has expired. */
+    unlock(opts?: TxOptions): Promise<any>;
+    /**
+     * Make this account an M-of-N multisig of its owner keys (`ownerKeyIds`): owner-only actions
+     * then need `multisigPropose` plus approvals up to `threshold`. Session keys keep working
+     * within their limits.
+     */
+    multisigCreate(ownerKeyIds: string[], threshold: number, opts?: TxOptions): Promise<any>;
+    /** Propose an action for this multisig account; it runs once enough owners approve. */
+    multisigPropose(action: Action, opts?: TxOptions): Promise<any>;
+    /**
+     * Approve open multisig proposal `id`. The approval binds the action (audit gap-7-6): pass
+     * `action`, the one you showed the approver (decode it and describe it with `describeAction`,
+     * don't trust a summary), or it's read from `client.multisig(account)`. A node that showed
+     * another action makes the approval fail. `digest`: the `actionDigest` of what you showed, if
+     * that's all you kept; an action that reads differently now is refused before anything is signed.
+     * A `vote` binds its proposal by digest, not by id: show it with `reviewAction(action, {
+     * proposal: await client.proposal(action.proposal_id) })`, which describes the proposal only if
+     * its content has that digest, and don't offer the approval unless it's `readable` (gap-7-6).
+     * Pass that proposal read as `proposal` here: approving a vote is refused, before anything is
+     * signed, unless the proposal shown (else one read now) has exactly the content the vote binds.
+     * The approval counts on this wallet's account (`actAs`), which the digest doesn't bind: on
+     * mainnet act for an address you checked, not a name one node resolved.
+     */
+    multisigApprove(id: number, opts?: TxOptions & {
+        action?: Action;
+        digest?: string;
+        proposal?: unknown;
+    }): Promise<any>;
+    /** Extend a name you own by `years` (1–10), at the chain's renewal price per year. */
+    renewName(name: string, years?: number, opts?: TxOptions): Promise<any>;
+    /**
+     * Offer a name you own to another account (a `.boo` name or address, signed as `Client.recipient` says). It
+     * stays yours until they accept it (`acceptName`); offering it again replaces the offer, and
+     * `withdrawNameOffer` withdraws it. Nobody can be given a name without saying yes.
+     */
+    transferName(name: string, to: string, opts?: TxOptions): Promise<any>;
+    /** Accept a name offered to the account you act for (`client.name(n).offered_to`): it becomes yours. */
+    acceptName(name: string, opts?: TxOptions): Promise<any>;
+    /** Withdraw your offer of a name you own (the same tx as `acceptName`: the chain tells them apart by who owns the name). */
+    withdrawNameOffer(name: string, opts?: TxOptions): Promise<any>;
+    /** Give up a name you own; anyone can register it afterwards. */
+    releaseName(name: string, opts?: TxOptions): Promise<any>;
+    /** Claim your share of a community distribution with the Merkle proof published alongside it (hex hashes). */
+    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>;
+    /** 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;
     balance(): Promise<string>;
     /** Dev/test chains only: drip 100 FANG to this wallet. */
     faucet(wait?: boolean): Promise<any>;
@@ -98,35 +579,400 @@ export declare class ApiError extends Error {
     readonly status: number;
     constructor(status: number, message: string);
 }
-/** A transaction that was rejected at execution (fee charged) or dropped from the mempool. */
+/**
+ * The node reports a transaction as failed. Two different things (audit review-fix-clients-2):
+ * - `dropped` false: it executed in block `tx.height` and failed there. Its fee was charged; it
+ *   can't execute again.
+ * - `dropped` true: this node dropped it from its mempool without running it (evicted by a
+ *   higher tip, replaced, not included, or an earlier tx from the account was dropped). Nothing
+ *   was charged, but other nodes may still hold it and include it until its `valid_until`
+ *   (`validUntil`, when known): check `client.tx(id)` before sending it again, or a retry can pay twice.
+ */
+/**
+ * Whether a `/api/tx` answer of status "failed" is a tx the node dropped from its mempool without
+ * running it (nothing charged; another node may still include it until its `valid_until`), not
+ * one that ran in a block and failed (its fee was charged). Mempool failures are answered without
+ * the tx itself (node/src/api.rs `tx`), and older nodes don't say `dropped`.
+ */
+export declare function txDropped(answer: unknown): boolean;
 export declare class TxFailedError extends Error {
     readonly id: string;
     readonly reason: string;
     readonly tx: any;
-    constructor(id: string, reason: string, tx: any);
+    readonly validUntil?: number | undefined;
+    readonly dropped: boolean;
+    constructor(id: string, reason: string, tx: any, validUntil?: number | undefined);
+}
+/**
+ * The node accepted a transaction, but it wasn't seen finalized (or failed) in time. It may still
+ * execute until its `valid_until`: check it with `client.tx(id)` before sending it again, or a
+ * retry can pay twice.
+ */
+export declare class TxPendingError extends Error {
+    readonly id: string;
+    readonly waitedMs: number;
+    readonly lastError?: unknown;
+    constructor(id: string, waitedMs: number, lastError?: unknown);
+}
+/** 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;
+    readonly path: string;
+    readonly timeoutMs: number;
+    constructor(rpc: string, path: string, timeoutMs: number);
+}
+/** A proof older than the newest head seen (this node's and every witness's) by more than `maxLagBlocks`. */
+export declare class StaleProofError extends Error {
+    readonly height: number;
+    readonly head: number;
+    readonly maxLagBlocks: number;
+    constructor(height: number, head: number, maxLagBlocks: number);
+}
+/**
+ * On mainnet, a transaction would carry an address that only one node vouched for: a `.boo` name
+ * resolved without witnesses, in a field that needs an address (staking's validator, the account
+ * `actAs` acts for, a key grant's account). Nothing was signed (audit gap-7-1). Check
+ * `resolution.address` with its owner and pass it instead of the name, or give the client witnesses.
+ */
+export declare class UnprovenNameError extends Error {
+    readonly resolution: Resolution;
+    constructor(resolution: Resolution, rpc: string);
+}
+/**
+ * A node reports a height the chain can't have reached (`Client.checkSigningHeight`): a tx signed
+ * against it could be held and released later. Nothing was signed.
+ */
+export declare class HeightAheadError extends Error {
+    readonly rpc: string;
+    readonly height: number;
+    readonly limit: number;
+    constructor(rpc: string, height: number, limit: number, by: string);
+}
+/**
+ * How far ahead of the lowest head a client's witnesses report a tx's height may be, by default
+ * (`ClientOptions.maxHeadLeadBlocks`): 30 blocks, room for propagation between nodes.
+ */
+export declare const DEFAULT_MAX_HEAD_LEAD_BLOCKS = 30;
+/**
+ * How far behind the network's clocks this machine's may be before `heightLimit` refuses an honest
+ * node: 15 minutes (the CLI uses the same, node/src/cli_net.rs `HEIGHT_CLOCK_TOLERANCE_MS`).
+ */
+export declare const HEIGHT_CLOCK_TOLERANCE_MS: number;
+/**
+ * The highest height a chain can have reached at `nowMs` (node/src/cli_net.rs `height_limit`):
+ * every block's timestamp is at least its parent's plus the block time, and validators refuse one
+ * more than a second ahead of their clocks, so block h is stamped no earlier than genesis + h ×
+ * block time. A chain that ran slower than its block time is below this by that much, so it
+ * refuses only heights the chain can't have, not every lie.
+ */
+export declare function heightLimit(createdAtMs: number, blockTimeMs: number, nowMs: number): number;
+/** The node reports a different chain than the client is pinned to (`ClientOptions`). */
+export declare class ChainMismatchError extends Error {
+    readonly rpc: string;
+    readonly field: "chain_id" | "genesis_hash" | "address_prefix";
+    readonly expected: string;
+    readonly reported: string | undefined;
+    constructor(rpc: string, field: "chain_id" | "genesis_hash" | "address_prefix", expected: string, reported: string | undefined);
+}
+/** What a `Client` requires of the node. Every `/api/status` (including the one `Wallet.build` signs against) is checked. */
+export interface ClientOptions {
+    /** The address prefix you expect (`boo` or `tboo`). */
+    prefix?: string;
+    /** The chain id the node must report (e.g. `blockula-1`). */
+    chainId?: string;
+    /** The genesis hash (hex) the node must report. */
+    genesisHash?: string;
+    /** How long one request may take before it fails with `RequestTimeoutError` (default 15 s, at most `MAX_TIMEOUT_MS`). */
+    timeoutMs?: number;
+    /**
+     * Clients for independent nodes of the same chain. With witnesses, every name this client
+     * resolves for a signature is a proven read (`provenName`): the record's Merkle proof must check
+     * out against a state root each witness reports for that block, and be fresh. Without them
+     * (audit gap-7-1):
+     * - where the chain resolves names itself (`Wallet.send`, `awardHunt`, `vouch`/`unvouch`,
+     *   `grantSoul`, `flagSybil`, `clawback`, `transferName`, proposal targets), the name is signed
+     *   as the name (`recipient`): the chain pays whoever owns it when the tx runs, so a lying node
+     *   can't point it at another account now, only hold it within its validity window;
+     * - where an address is needed (`delegate`/`undelegate`/`redelegate`/`unjail`, `actAs`,
+     *   `keyGrant`), a name is one node's unproven answer, and on mainnet nothing is signed with it
+     *   (`UnprovenNameError`): pass the address.
+     */
+    witnesses?: Client[];
+    /** Refuse to resolve a `.boo` name for a signature unless it's proven (needs `witnesses`). */
+    requireProvenNames?: boolean;
+    /**
+     * With witnesses: how far ahead of the lowest head they report the height a tx is signed
+     * against may be (default `DEFAULT_MAX_HEAD_LEAD_BLOCKS`). See `Client.checkSigningHeight`.
+     */
+    maxHeadLeadBlocks?: number;
+    /**
+     * The chain's genesis time and block time (`created_at_ms` and `block_time_ms` of the
+     * genesis.json that hashes to `genesisHash`, as published with it), as pins: with them, a
+     * status claiming a height the chain can't have reached by this machine's clock is refused
+     * before anything is signed (`Client.checkSigningHeight`). Not the node's word, so don't take
+     * them from it.
+     */
+    genesisClock?: {
+        createdAtMs: number;
+        blockTimeMs: number;
+    };
+}
+/** Where a recipient (a `.boo` name or an address) goes, and how sure that is (`Client.resolution`). */
+export interface Resolution {
+    /** What was asked for. */
+    input: string;
+    /** The address that gets signed. */
+    address: string;
+    /** The bare name, when `input` was one. */
+    name: string | null;
+    /** An address as given, or a name proven against the client's witnesses; `false`: one node's word. */
+    proven: boolean;
+    /** How it was resolved, in plain English (show it with the address before signing). */
+    how: string;
+    /** The block a proven name was read at. */
+    height?: number;
 }
+/** A recipient in a field the chain resolves itself, as it gets signed (`Client.recipient`). */
+export interface Recipient extends Resolution {
+    /**
+     * What goes into the action: an address as given, a name's proven owner (with witnesses), or
+     * the name itself (`alice.boo`) when nothing proved it.
+     */
+    signed: string;
+    /**
+     * `signed` is the name: the chain resolves it to whoever owns it when the tx runs, so no node
+     * can point it at another account now (one holding the signed tx can still release it later,
+     * by when the name may have changed hands: see `recipient`). `address` is then just the node's
+     * current answer, for display.
+     */
+    byChain: boolean;
+}
+/** Default per-request timeout of a `Client`. */
+export declare const DEFAULT_TIMEOUT_MS = 15000;
+/**
+ * The longest timeout a `Client` takes: 2^31 − 1 ms (about 24.8 days). Timers store their delay
+ * as a signed 32-bit number, and a longer one fires at once (audit review-fix-clients-1).
+ */
+export declare const MAX_TIMEOUT_MS = 2147483647;
+/** `ms` as a timeout: a whole number of milliseconds from 1 to `MAX_TIMEOUT_MS`, or an error naming `what`. */
+export declare function checkTimeoutMs(ms: number, what?: string): number;
+/**
+ * How far behind the newest head (the node's own and each witness's `/api/status` height) a
+ * proven read's proof may be, by default: 10 blocks (10 s at 1 s blocks), room for propagation
+ * between nodes. Older proofs are refused (`StaleProofError`), so a node can't answer with a
+ * genuine but outdated record (a name's previous owner, a balance before a spend, a removed key).
+ */
+export declare const DEFAULT_MAX_PROOF_LAG_BLOCKS = 10;
+/** Options of the proven reads (`provenRecord`, `provenAccount`, `provenName`). */
+export interface ProvenOptions {
+    /** Clients for independent nodes: each must report the same state root for the proof's block, and its head bounds how old the proof may be. */
+    witnesses?: Client[];
+    /** How long to wait for a witness that hasn't reached the proof's block yet (default 5 s). */
+    waitMs?: number;
+    /** How many blocks the proof may be behind the newest head seen (default `DEFAULT_MAX_PROOF_LAG_BLOCKS`). */
+    maxLagBlocks?: number;
+}
+/** A record proven against a state root, and the newest head height that root was checked against. */
+export type ProvenRead = ProvenRecord & {
+    head: number;
+};
 export declare class Client {
     readonly rpc: string;
-    constructor(rpc?: string);
+    /** The chain's address prefix: given, learned from `/api/status`, or `boo` until then. */
+    prefix: string;
+    private prefixKnown;
+    private readonly pinnedPrefix?;
+    private readonly pinnedChainId?;
+    private readonly pinnedGenesis?;
+    /** Per-request timeout (ms). */
+    readonly timeoutMs: number;
+    /** Independent nodes names are proven against (`ClientOptions.witnesses`). */
+    readonly witnesses: Client[];
+    readonly requireProvenNames: boolean;
+    /** See `ClientOptions.maxHeadLeadBlocks`. */
+    readonly maxHeadLeadBlocks: number;
+    /** See `ClientOptions.genesisClock`. */
+    readonly genesisClock?: {
+        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);
+    /**
+     * Refuses (`HeightAheadError`, before anything is signed) a height a tx's validity window would
+     * count from that this client has reason to think the chain hasn't reached: more than
+     * `maxHeadLeadBlocks` past the lowest head its witnesses report, or, with a `genesisClock`, past
+     * what the chain can have reached by this machine's clock (`heightLimit`). A node reporting a
+     * future height gets a tx it can hold and release later, when the window it picked opens; with
+     * a name signed in it, after the name may have changed hands (audit review-r3-clients-2).
+     * Every witness must report its height, as every witness must confirm a proof: one honest
+     * witness is enough to refuse a height the chain hasn't reached, whatever the others say.
+     * Without witnesses or a genesis clock, the height is the node's word.
+     */
+    checkSigningHeight(height: number): Promise<void>;
+    /** The chain's address prefix, asking the node once if it isn't known yet. */
+    addressPrefix(): Promise<string>;
+    /** 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(heightOrHash: number | string): Promise<any>;
     tx(id: string): Promise<any>;
     account(addressOrName: string): Promise<any>;
+    /** A name: `status` (`active`, `grace` (expired; only its owner can renew it), `reserved` or `available`), owner, `expires_at`, `offered_to` (if its owner offered it to an account: theirs once they accept), prices. */
     name(name: string): Promise<any>;
+    /** The base fee: each upcoming block's (`slots`) and `suggested`, which covers any of the next 17 blocks. */
+    fees(): Promise<{
+        height: number;
+        lag: number;
+        slots: ({
+            height: number;
+            max_block_bytes: number;
+        } & BaseFee)[];
+        suggested: BaseFee;
+        lowest?: BaseFee;
+        tip_cap_multiple?: number;
+        account_creation_fee: string;
+        [k: string]: unknown;
+    }>;
+    /** The governance parameters (node/src/params.rs `ChainParams`; amounts as strings) under `params`, genesis constants under `genesis`, and the issuance year. `paramsOf` flattens it. */
+    params(): Promise<any>;
+    /** The chain's genesis.json as this node serves it: the node's word (nothing here checks it against the genesis hash). */
+    genesis(): Promise<any>;
+    /** Upgrades: the protocol version in force, what the node's binary supports, the `schedule` (`[{ version, activation_height, active }]`, what `proposal.cancelUpgrade` names), halts and each validator's readiness signal. */
+    upgrade(): Promise<any>;
     /** Accounts a key is authorized on (its own address, plus any it was added to). */
-    keyAccounts(keyIdHex: string): Promise<any>;
+    /**
+     * Accounts a key is on (`{ key_id, accounts, next }`), a page at a time: pass the previous page's
+     * `next` as `after`. Only accounts the key agreed to join (its grant) can list it (audit gap-7-2).
+     */
+    keyAccounts(keyIdHex: string, page?: {
+        after?: string;
+        limit?: number;
+    }): Promise<any>;
     search(q: string): Promise<any>;
-    /** Active set for the current epoch, pending/approved validators, next-epoch set, epoch timing. */
+    /** The validator set: `active` this epoch, `next_epoch` (with `joining`/`leaving`), `candidates`, `jailed`, `tombstoned` and `removed`, each with stake, self-bond, commission, jail and liveness; epoch timing; the churn limit and slashing parameters. */
     validators(): Promise<any>;
     /** Hunts (bounties on GitHub issues), biggest first. */
     hunts(status?: "open" | "awarded" | "cancelled" | "expired"): Promise<any>;
     hunt(id: number): Promise<any>;
     /** Off-chain check of a GitHub link (gist owned by the handle containing the address). */
     github(handle: string): Promise<any>;
+    /** The contribution pool: balance, repos, rules, the open Séance and recent results. */
+    contributions(): Promise<any>;
+    claims(opts?: {
+        status?: "pending" | "verified" | "in_seance" | "scored" | "spam" | "rejected";
+        account?: string;
+    }): Promise<any>;
+    claim(id: number): Promise<any>;
+    /** A Séance, with each juror's assigned pairs (what they must judge). */
+    seance(id: number): Promise<any>;
+    /** A juror's assigned pairs in Séance `id`, in order, with each claim's repo and PR (what `sealVotes` binds). */
+    seancePairs(id: number, juror: string): Promise<[SeanceClaimRef, SeanceClaimRef][]>;
+    /** Soul leaderboard. */
+    souls(limit?: number): Promise<any>;
+    /** An account's stake: `delegations` (shares, value, principal), `entries` (unbonding and redelegations, with `release_at`), `bonded`, `unbonding` and `withdrawable` totals, the `validators` it runs, a `summary`. */
+    staking(account: string): Promise<any>;
+    /** Governance proposals, newest first (`status`: `voting`, `queued`, `rejected`, `executed`, `failed`), the rules (`params`), treasury and community balances. */
+    proposals(opts?: {
+        status?: string;
+        limit?: number;
+    }): Promise<any>;
+    /** One proposal with its votes. */
+    proposal(id: number): Promise<any>;
+    /** A community distribution: Merkle root, total, claimed so far, claim deadline. */
+    distribution(id: number): Promise<any>;
+    /** A multisig account: owners, threshold, open proposals and their approvals. */
+    multisig(account: string): Promise<any>;
+    /** `/api/proof/{namespace}/{key}`, unchecked. Prefer `provenRecord`. */
+    proof(namespace: number, key: string | Uint8Array): Promise<ProofResponse>;
+    /**
+     * A record with its Merkle proof checked against the state root the node reports. On its own
+     * that only shows the node is consistent; `witnesses` (clients for independent nodes) must
+     * each report the same state root for that block, so a single lying node can't fake balances,
+     * names or keys. A witness that hasn't reached the block yet is retried for `waitMs`.
+     *
+     * The proof must also be fresh: its block may be at most `maxLagBlocks` behind the newest head
+     * this node and the witnesses report (`StaleProofError` otherwise). Witnesses confirm any
+     * genuine root, old ones included, so without this a lying node could serve a real but outdated
+     * record (a name's previous owner, a balance before a spend, a key since removed). `head` is
+     * the newest head seen. Without witnesses only this node's own head is compared, which a lying
+     * node controls: pass witnesses for anything that matters.
+     */
+    provenRecord(namespace: number, key: string | Uint8Array, opts?: ProvenOptions): Promise<ProvenRead>;
+    /** Throws unless this node's block `height` has state root `root` (waiting up to `waitMs` for it to get there). */
+    confirmStateRoot(height: number, root: string, waitMs?: number): Promise<void>;
+    /** An address's balance, nonce and keys, proven and fresh (see `provenRecord`). `null` if the account provably doesn't exist. */
+    provenAccount(address: string, opts?: ProvenOptions): Promise<{
+        balance: bigint;
+        nonce: number;
+        keys: import("./proof.js").ProvenKey[];
+        address: string;
+        height: number;
+        root: string;
+        head: number;
+    } | null>;
+    /**
+     * Who a `.boo` name resolves to, proven and fresh (see `provenRecord`). `null` if it provably
+     * doesn't resolve: never registered, or expired (`expires_at` passed; in its grace period only
+     * the owner can renew it, and after that anyone can register it). `includeExpired` returns an
+     * expired record too, with `active: false`: never pay its `owner`.
+     */
+    provenName(name: string, opts?: ProvenOptions & {
+        includeExpired?: boolean;
+    }): Promise<{
+        name: string;
+        owner: string;
+        registered_at: number;
+        expires_at: number;
+        offered_to?: string;
+        grace_blocks?: number;
+        active: boolean;
+        height: number;
+        root: string;
+        head: number;
+    } | null>;
+    /**
+     * The address a name or address resolves to, for fields that need an address (see
+     * `resolution`): proven with witnesses, else one node's word. Where the chain resolves names
+     * itself (payments, vouches, name offers…), use `recipient` instead, which signs the name.
+     */
     resolve(nameOrAddress: string): Promise<string>;
+    /**
+     * How to sign a recipient in a field the chain resolves itself (`transfer.to`, `award_hunt.to`,
+     * `vouch`/`unvouch`/`flag_sybil`/`clawback.account`, `grant_soul.to`, `transfer_name.to`, and
+     * proposal targets): an address as given; with witnesses a name's proven owner; without them
+     * the name itself, which the chain resolves to its owner when the tx runs, so a lying node
+     * can't point it at another account now (audit gap-7-1). It can still hold the signed tx and
+     * release it later within its validity window, which counts from the height that node reported
+     * (bounded by `checkSigningHeight` only with witnesses or a `genesisClock`): whoever owns the
+     * name then is paid, so a name that lapses in between pays its next owner (review-r3-clients-2).
+     * Show `how` before signing.
+     */
+    recipient(nameOrAddress: string): Promise<Recipient>;
+    /**
+     * Where a recipient goes and how sure that is: show `address` and `how` before signing. With the
+     * client's `witnesses` a name is a proven, fresh read (`provenName`), so a lying node can't
+     * point it elsewhere; without them it's this node's answer alone (`proven: false`), which a
+     * lying node controls (audit gap-7-1).
+     */
+    resolution(nameOrAddress: string): Promise<Resolution>;
+    /**
+     * Submits a signed tx, then (with `wait`) waits for it. What a failure means:
+     * - `ApiError`: the node refused the tx; it wasn't admitted.
+     * - `RequestTimeoutError` or a network error: unknown; the tx may have arrived.
+     * - `TxFailedError`: it executed and failed (`dropped` false: its fee was charged), or this node
+     *   dropped it unrun (`dropped` true: nothing charged, but it may still execute elsewhere until
+     *   its `valid_until`).
+     * - `TxPendingError`: it was admitted and may still execute. Don't send it again blindly.
+     */
     submit(tx: Tx, wait?: boolean): Promise<any>;
     faucet(to: string, wait?: boolean): Promise<any>;
-    waitForTx(id: string, timeoutMs?: number): Promise<any>;
+    /**
+     * Polls a tx until it's finalized (returns it) or failed (`TxFailedError`, which says whether it
+     * executed or was dropped unrun). A poll that fails (rate limited, a node error, a timeout, not
+     * visible yet) is retried; after `timeoutMs` it throws `TxPendingError`, since the tx may still
+     * execute. `validUntil` (the tx's, when the caller has it) goes into a dropped tx's error.
+     */
+    waitForTx(id: string, timeoutMs?: number, validUntil?: number): Promise<any>;
 }