@quaivault/sdk 0.1.1 → 0.2.1

package/dist/index.d.cts

@@ -1,8 +1,10 @@
 import * as quais from 'quais';
 import { Provider, Signer, Contract, Interface } from 'quais';
 export { Provider, Signer } from 'quais';
+import * as node_worker_threads from 'node:worker_threads';
 import * as _supabase_postgrest_js from '@supabase/postgrest-js';
-import { SupabaseClient } from '@supabase/supabase-js';
+import { PostgrestClient } from '@supabase/postgrest-js';
+import { RealtimeChannel } from '@supabase/realtime-js';
 import { z } from 'zod';
 export { Erc1155Abi, Erc20Abi, Erc721Abi, MultiSendCallOnlyAbi, QuaiVaultAbi, QuaiVaultFactoryAbi, QuaiVaultProxyAbi, QuaiVaultProxyBytecode, SocialRecoveryModuleAbi } from './abi/index.cjs';
 
@@ -61,8 +63,36 @@ interface NetworkConfig {
  * is removed (approval epochs), so they must never gate a signature.
  */
 type Consistency = 'auto' | 'indexed' | 'chain';
+/**
+ * Source of "now", in Unix **seconds**, for decisions compared against chain time.
+ *
+ * The contracts decide with `block.timestamp`. Everything the SDK derives locally —
+ * a transaction's `ready` vs `timelocked`, what a caller may do next, whether a
+ * recovery period has elapsed — is a *prediction* of that, and a machine whose clock is
+ * wrong predicts wrongly. Containers, CI runners and VMs resumed from a snapshot drift
+ * in ways a desktop usually does not.
+ *
+ * Supplying a clock lets a consumer that has measured the offset feed it back in:
+ *
+ * ```ts
+ * const skew = localSeconds - blockTimestamp;      // positive: local clock is ahead
+ * connect({ now: () => Date.now() / 1000 - skew });
+ * ```
+ *
+ * A function rather than a scalar offset on purpose. An offset needs a sign convention,
+ * and getting it backwards doubles the error instead of cancelling it — silently. Here
+ * the arithmetic sits in the caller's own code, where it reads as what it means.
+ *
+ * This never affects elapsed-time measurement (retry backoff, timeouts, poll
+ * intervals). Those are durations: if the clock is 12 seconds fast, 30 seconds is still
+ * 30 seconds.
+ *
+ * Detection is deliberately not the SDK's job — it would mean an RPC call on behalf of
+ * a consumer who may not want one, and a cached value with no clear invalidation.
+ */
+type Clock = () => number;
 interface ClientOptions {
-    network?: NetworkConfig | keyof typeof networks;
+    network?: NetworkConfig | NetworkName;
     provider?: Provider;
     signer?: Signer;
     /** Private key for a local signer. Prefer the `QUAIVAULT_PRIVATE_KEY` env var. */
@@ -75,6 +105,11 @@ interface ClientOptions {
     maxIndexerLagBlocks?: number;
     /** Read env vars for anything not passed explicitly. Default true. */
     useEnv?: boolean;
+    /**
+     * Source of "now" for time compared against chain timestamps. See {@link Clock}.
+     * Defaults to the local clock.
+     */
+    now?: Clock;
     /**
      * Retry policy for transient RPC and indexer failures. Applies to reads only —
      * writes are never retried, since a resubmit risks a double broadcast.
@@ -129,8 +164,16 @@ interface VaultTransaction {
     value: bigint;
     data: Hex;
     proposer: Address;
-    /** Unix seconds when the proposal was recorded on chain. */
+    /**
+     * Unix seconds when the proposal was recorded on chain, or 0 when unknown.
+     *
+     * Only chain reads carry a timestamp: the vault stores one in the transaction
+     * struct, but the indexer records the *block* instead. On an indexed read this is 0
+     * and {@link proposedAtBlock} carries the position. Never render 0 as a date.
+     */
     proposedAt: number;
+    /** Block the proposal was recorded in. Only populated on indexer reads. */
+    proposedAtBlock?: number;
     kind: TransactionKind;
     decoded?: DecodedCall;
     /** One-line human-readable description. */
@@ -283,8 +326,10 @@ interface RecoveryRequest {
     expiration: number;
     status: RecoveryStatus;
     executed: boolean;
-    /** Guardians who have approved. Only populated on indexer reads. */
-    approvedBy?: Address[];
+    /**
+     * Who initiated the recovery. Only populated on indexer reads — the module's struct
+     * does not retain it.
+     */
     initiator?: Address;
     source: 'indexer' | 'chain';
 }
@@ -302,7 +347,15 @@ interface Pagination {
 }
 interface Page<T> {
     data: T[];
+    /**
+     * Approximate size of the full result set.
+     *
+     * Taken from the query planner rather than a full scan, so it is exact on small
+     * tables and an estimate on large ones. Use it to size a progress bar, not to decide
+     * whether to keep paging — {@link hasMore} is what answers that.
+     */
     total: number;
+    /** Whether another page exists. Always exact. */
     hasMore: boolean;
 }
 interface IndexerHealth {
@@ -315,13 +368,6 @@ interface IndexerHealth {
     error?: string;
 }
 
-/**
- * Retry policy for transient RPC and indexer failures.
- *
- * Scoped deliberately to **reads**. Retrying a write risks broadcasting the same
- * transaction twice — a resubmit that looks like a timeout to the client may already
- * be in the mempool — so every write path in this SDK calls through unretried.
- */
 interface RetryOptions {
     /** Total attempts including the first. Default 3. */
     maxAttempts?: number;
@@ -388,6 +434,11 @@ interface ResolvedConfig {
     consistency: Consistency;
     maxIndexerLagBlocks: number;
     retry: RetryOptions;
+    /**
+     * Resolved source of "now" in Unix seconds. Always set — falls back to the local
+     * clock — so consumers never branch on its presence.
+     */
+    now: Clock;
 }
 /** A `ResolvedConfig` with the private key removed. Safe to log. */
 type PublicConfig = Omit<ResolvedConfig, 'privateKey'> & {
@@ -424,6 +475,13 @@ declare class Connection {
     vault(address: Address, write?: boolean): Contract;
     factory(address: Address, write?: boolean): Contract;
     socialRecovery(address: Address, write?: boolean): Contract;
+    /**
+     * Read-only handle to a token contract.
+     *
+     * No write variant: the SDK never calls a token directly. Moving tokens goes
+     * through the vault's proposal flow, which encodes the transfer as calldata.
+     */
+    token(address: Address, standard: 'ERC20' | 'ERC721' | 'ERC1155'): Contract;
 }
 
 interface MineSaltOptions {
@@ -462,9 +520,31 @@ interface ResolvedMineJob {
  */
 declare const syncStrategy: MiningStrategy;
 /**
- * Node-only multi-core miner. Falls back to {@link syncStrategy} when
- * `node:worker_threads` is unavailable (browsers, restricted runtimes).
+ * Node-only multi-core miner, degrading to {@link syncStrategy} whenever workers turn
+ * out not to be usable.
+ *
+ * Two distinct failures land here. `node:worker_threads` may not exist at all
+ * (browsers, restricted runtimes). Or it exists, but the worker cannot boot — the
+ * source below is inlined as a string and resolves `quais` with a bare `require`,
+ * which no bundler traces, so a packaged consumer's worker dies on its first line.
+ *
+ * Both retreat to the sync miner rather than failing, and that retreat is always safe:
+ * mining is pure computation over random salts with no side effects and no on-chain
+ * state, so re-running it in process yields an equally valid answer. Deployment
+ * getting slower is a far better outcome than deployment becoming impossible.
+ */
+interface WorkerRuntime {
+    Worker: typeof node_worker_threads.Worker;
+    parallelism: number;
+}
+/**
+ * Build the strategy over an injectable worker runtime.
+ *
+ * The injection point exists so the retreat path can be tested: a worker that dies on
+ * its first line is the single most likely failure in a packaged consumer, and a
+ * fallback nothing exercises is a fallback nobody can trust.
  */
+declare function createWorkerThreadsStrategy(load?: () => Promise<WorkerRuntime | null>): MiningStrategy;
 declare const workerThreadsStrategy: MiningStrategy;
 /** Prefer worker_threads on Node; the sync miner degrades gracefully everywhere else. */
 declare function defaultStrategy(): MiningStrategy;
@@ -541,13 +621,19 @@ declare class Factory {
 }
 
 /**
- * The indexer uses one Postgres schema per network, chosen at runtime, so the
- * client cannot be pinned to supabase-js's default `"public"` schema generic.
+ * The indexer uses one Postgres schema per network, chosen at runtime, so the client
+ * cannot be pinned to postgrest-js's default `"public"` schema generic.
  */
-type AnySupabaseClient = SupabaseClient<any, any, any, any, any>;
+type AnyPostgrestClient = PostgrestClient<any, any, any>;
 /**
  * Thin wrapper over the indexer's Supabase project.
  *
+ * Built on `@supabase/postgrest-js` and `@supabase/realtime-js` directly rather than
+ * the `@supabase/supabase-js` umbrella. The umbrella's constructor instantiates auth,
+ * storage and functions clients unconditionally, so no bundler can shake them out —
+ * and this SDK uses none of the three. Going direct costs 57 KB → 22 KB gzip, and the
+ * only thing given up is `createClient`'s URL and header wiring, reproduced below.
+ *
  * The anon key is a public read-only credential: the indexer's RLS grants `anon`
  * SELECT on every table and nothing else, with all writes reserved for
  * `service_role`. It carries no authority beyond reading already-public chain data.
@@ -555,16 +641,34 @@ type AnySupabaseClient = SupabaseClient<any, any, any, any, any>;
 declare class IndexerClient {
     readonly config: IndexerConfig;
     private readonly client;
+    private realtime;
     private healthCache;
     private inflightHealth;
-    /** Health results are reused for this long to keep read paths cheap. */
+    /**
+     * Health results are reused for this long to keep read paths cheap.
+     *
+     * This and `waitForBlock`'s deadline are elapsed-time arithmetic, so they use the
+     * raw local clock rather than `ClientOptions.now` — see the note in `chain/retry.ts`.
+     */
     readonly healthCacheMs: number;
     constructor(config: IndexerConfig, options?: {
         healthCacheMs?: number;
     });
-    /** Raw Supabase client, for queries the SDK does not wrap. */
-    get raw(): AnySupabaseClient;
+    /** The PostgREST client, for queries the SDK does not wrap. */
+    get rest(): AnyPostgrestClient;
     from(table: string): _supabase_postgrest_js.PostgrestQueryBuilder<any, any, any, string, unknown>;
+    /**
+     * Realtime client, constructed on first use.
+     *
+     * Lazy because it opens a WebSocket and starts a heartbeat, and the large majority
+     * of SDK usage never calls `watch()`. Nothing here should cost a socket unless
+     * somebody asked to follow a vault.
+     */
+    private realtimeClient;
+    /** Open a Realtime channel. See `watchVault`, which is what callers should use. */
+    channel(name: string): RealtimeChannel;
+    /** Close a channel opened by {@link channel}. */
+    removeChannel(channel: RealtimeChannel): Promise<void>;
     /**
      * Run a query, parse each row, and surface failures as `IndexerQueryError`.
      *
@@ -575,15 +679,36 @@ declare class IndexerClient {
      * multiplied attempts if it were ever made to work. Chain reads, which do reject,
      * are retried in `src/chain/retry.ts`.
      */
-    select<S extends z.ZodTypeAny>(table: string, schema: S, build: (q: ReturnType<AnySupabaseClient["from"]>) => PromiseLike<{
+    select<S extends z.ZodTypeAny>(table: string, schema: S, build: (q: ReturnType<AnyPostgrestClient["from"]>) => PromiseLike<{
         data: unknown[] | null;
         error: {
             message: string;
             code?: string;
         } | null;
     }>): Promise<Array<z.infer<S>>>;
+    /**
+     * Paged select: an exact `hasMore`, an approximate `total`.
+     *
+     * Both halves of that are deliberate. An `exact` count makes Postgres scan every
+     * matching row on every page request, which is invisible on a young vault and
+     * quadratic on a busy one — so the count is `estimated`, cheap and good enough for
+     * "roughly how much history is there".
+     *
+     * But `hasMore` derived from an estimate would be a lie a caller can act on: a
+     * paging loop that stops early drops real rows. So callers request one row beyond
+     * the page and this trims it, which answers "is there another page" exactly, for
+     * the cost of a single extra row.
+     */
+    selectPage<S extends z.ZodTypeAny>(table: string, schema: S, limit: number, build: (q: ReturnType<AnyPostgrestClient['from']>) => PromiseLike<{
+        data: unknown[] | null;
+        error: {
+            message: string;
+            code?: string;
+        } | null;
+        count?: number | null;
+    }>): Promise<Page<z.infer<S>>>;
     /** Single-row variant. Returns null for PostgREST's "no rows" code. */
-    selectOne<S extends z.ZodTypeAny>(table: string, schema: S, build: (q: ReturnType<AnySupabaseClient["from"]>) => PromiseLike<{
+    selectOne<S extends z.ZodTypeAny>(table: string, schema: S, build: (q: ReturnType<AnyPostgrestClient["from"]>) => PromiseLike<{
         data: unknown | null;
         error: {
             message: string;
@@ -1132,24 +1257,56 @@ declare class IndexerQueries {
     vaultsForGuardian(guardian: Address, options?: Pagination): Promise<WalletRow[]>;
     pendingTransactions(vault: Address, options?: Pagination): Promise<TransactionRow[]>;
     transaction(vault: Address, txHash: string): Promise<TransactionRow | null>;
+    /**
+     * Several transactions by hash, chunked for the same reasons as
+     * {@link activeConfirmationsBatch} — hashes are long, and they go in the query string.
+     *
+     * Rows come back in no particular order and hashes with no row are simply absent;
+     * the caller matches them up.
+     */
+    transactionsByHash(vault: Address, txHashes: string[]): Promise<TransactionRow[]>;
     transactionHistory(vault: Address, options?: Pagination & {
         status?: string[];
     }): Promise<Page<TransactionRow>>;
     /** All confirmations for one transaction, including revoked ones. */
     confirmations(vault: Address, txHash: string): Promise<ConfirmationRow[]>;
     /**
-     * Active confirmations for many transactions in one round trip.
+     * Active confirmations for many transactions, in as few round trips as is safe.
      *
      * "Active" here means not revoked. It does NOT mean the confirming address is
      * still an owner — the indexer does not deactivate confirmations when an owner is
      * removed, while the contract invalidates them via approval epochs. Callers must
      * intersect with the active owner set; `Vault` does this for you.
+     *
+     * Chunked rather than issued as one `in(...)`, because a single filter fails two
+     * ways at scale. PostgREST reads filters from the query string, and each 32-byte
+     * hash costs ~70 characters there — a full {@link MAX_LIMIT} page of hashes builds a
+     * ~14 KB request line, past the 8 KB cap most reverse proxies apply by default. The
+     * response is bounded too: {@link CONFIRMATION_CHUNK} transactions can carry at most
+     * `chunk × MAX_OWNERS` rows, and the chunk is sized to keep that under the
+     * `max-rows` ceiling PostgREST deployments commonly set, so a busy vault cannot be
+     * silently short-served.
      */
     activeConfirmationsBatch(vault: Address, txHashes: string[]): Promise<Map<string, ConfirmationRow[]>>;
     modules(vault: Address): Promise<string[]>;
     delegatecallTargets(vault: Address): Promise<string[]>;
     deposits(vault: Address, options?: Pagination): Promise<Page<DepositRow>>;
     tokenTransfers(vault: Address, options?: Pagination): Promise<Page<TokenTransferRow>>;
+    /**
+     * Scan up to `budget` of the most recent transfer rows, paging past {@link MAX_LIMIT}.
+     *
+     * `tokenTransfers` clamps a single request, so a caller asking for more than the cap
+     * silently received a short page — and then computed "did I see everything?" from
+     * that short page's `hasMore`, which reported truncation the caller had not actually
+     * hit. Paging here keeps the caller's budget meaningful and makes the returned
+     * `hasMore` mean what it says: rows exist beyond the budget that was scanned.
+     *
+     * Pages by offset over a descending order, so a transfer landing mid-scan can shift
+     * rows by one. That is acceptable for token *discovery* — a duplicate collapses into
+     * the same map key and a missed row costs at most one candidate that the next call
+     * picks up. Do not reuse this for anything that must see each row exactly once.
+     */
+    tokenTransferScan(vault: Address, budget: number): Promise<Page<TokenTransferRow>>;
     tokens(addresses: string[]): Promise<TokenRow[]>;
     signedMessages(vault: Address): Promise<SignedMessageRow[]>;
     recoveryConfig(vault: Address): Promise<{
@@ -1167,6 +1324,8 @@ interface RecoveryModuleContext {
     queries: IndexerQueries | null;
     vaultAddress: Address;
     moduleAddress: Address | undefined;
+    /** Source of "now" for comparisons against chain timestamps. See {@link Clock}. */
+    now?: Clock;
 }
 /**
  * Guardian-based recovery for one vault.
@@ -1183,6 +1342,16 @@ declare class RecoveryModule {
     get address(): Address;
     private contract;
     private get vault();
+    /**
+     * The vault this module acts on, through the same retrying facade every other vault
+     * read in the SDK uses. Recovery reaches into the vault for three checks — is the
+     * module enabled, is the caller an owner, who are the current owners — and each of
+     * them gates a write, so none of them should be the one read that silently skips
+     * transient-failure handling.
+     */
+    /** Now, in Unix seconds, for anything compared against a chain timestamp. */
+    private now;
+    private vaultContract;
     /** Whether the module is currently enabled on the vault. */
     isEnabled(): Promise<boolean>;
     config(): Promise<RecoveryConfig>;
@@ -1252,7 +1421,7 @@ declare class RecoveryModule {
         chainTxHash: Hex;
     }>;
     /** What `caller` may do to a recovery right now, and when blocked actions unlock. */
-    affordances(recoveryHash: Bytes32, caller?: Address): Promise<RecoveryAffordance[]>;
+    affordances(recoveryHash: Bytes32, caller?: Address, at?: number): Promise<RecoveryAffordance[]>;
     private buildFromChain;
     private validateNewOwners;
     private assertLive;
@@ -1265,7 +1434,13 @@ declare class RecoveryModule {
 interface TokenBalance {
     token: Address;
     standard: 'ERC20' | 'ERC721' | 'ERC1155';
+    /**
+     * Ticker as the token reports it — deployer-controlled, so passed through
+     * {@link sanitizeText} and capped. Falls back to `???` when the token has none or
+     * supplied nothing printable.
+     */
     symbol: string;
+    /** Display name. Same provenance and treatment as {@link symbol}. */
     name: string;
     decimals: number;
     /** ERC20: raw units. ERC721: number held. ERC1155: total across ids. */
@@ -1306,12 +1481,22 @@ interface BalanceOptions {
     /**
      * How many recent transfer rows to scan when discovering tokens. Default 500.
      *
-     * A vault with more transfers than this may not surface its oldest holdings, so
-     * raise it for long-lived vaults. Reported back in {@link VaultBalances.truncated}.
+     * Scanned across as many indexer requests as it takes, so this is a real budget
+     * rather than a single page size. A vault with more transfers than this may not
+     * surface its oldest holdings, so raise it for long-lived vaults. Reported back in
+     * {@link VaultBalances.truncated}.
      */
     transferScanLimit?: number;
     /** Cap on ERC721 ids ownership-checked per token. Default 100. */
     maxTokenIdChecks?: number;
+    /**
+     * Ceiling on in-flight RPC reads. Default 8.
+     *
+     * Applied at both fan-out levels independently, so the true ceiling is the square
+     * of this. Raise it against a private node; lower it if a shared endpoint is
+     * rate-limiting you.
+     */
+    concurrency?: number;
 }
 /**
  * Aggregate a vault's holdings.
@@ -1404,8 +1589,10 @@ declare const interfaces: {
 declare const MAX_EXECUTION_DELAY: number;
 declare const MAX_OWNERS = 20;
 declare const MAX_MODULES = 50;
-/** Head of the Zodiac module linked list. */
+/** Head of the Zodiac module linked list. Never valid as an owner, module or guardian. */
 declare const SENTINEL_MODULES = "0x0000000000000000000000000000000000000001";
+/** Rejected everywhere an address is committed to a role. */
+declare const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
 declare const selfCall: {
     addOwner: (owner: Address) => Hex;
     removeOwner: (owner: Address) => Hex;
@@ -1486,6 +1673,34 @@ interface VaultContext {
     contracts: ContractAddresses;
     consistency: Consistency;
     maxIndexerLagBlocks: number;
+    /**
+     * Source of "now" for comparisons against chain timestamps. See {@link Clock}.
+     * Optional so a hand-built context still works; defaults to the local clock.
+     */
+    now?: Clock;
+    /** Set by {@link Vault.pinned}. Never consulted by a write precondition. */
+    view?: VaultView;
+}
+/**
+ * Owners and threshold, captured at one instant.
+ *
+ * The SDK deliberately holds no read cache: the owner set decides which approvals
+ * count toward the threshold, and serving a stale one silently would reintroduce the
+ * exact bug `buildTransaction` intersects confirmations to avoid. An implicit TTL
+ * would make that failure invisible and intermittent.
+ *
+ * So the staleness window is the caller's to open, and to see. `capturedAt` is right
+ * there in the object; a CLI rendering one screen can pin a view for that screen and
+ * know precisely what it pinned.
+ */
+interface VaultView {
+    owners: Address[];
+    threshold: number;
+    /** Indexer head when this was taken; absent if the snapshot came from chain. */
+    indexedAtBlock?: number;
+    /** Unix seconds. How stale the snapshot is allowed to get is the caller's call. */
+    capturedAt: number;
+    source: 'indexer' | 'chain';
 }
 /** A handle to one deployed vault. Cheap to construct; performs no I/O until used. */
 declare class Vault {
@@ -1503,13 +1718,84 @@ declare class Vault {
      */
     private useIndexer;
     private requireQueries;
+    /**
+     * The indexer's head, for stamping onto records read from it.
+     *
+     * Reads the cached health result rather than querying `indexer_state` directly.
+     * `useIndexer()` has just called `health()` on this same code path and the result is
+     * cached, so this is free — whereas a `state()` call is a second round trip per
+     * hydration, paid on every indexed read purely to fill one advisory field.
+     *
+     * Undefined when the indexer is not answering: a head of 0 would read as "indexed at
+     * genesis" rather than "unknown".
+     */
+    private indexerHead;
+    /**
+     * Now, in Unix seconds, for anything compared against a chain timestamp.
+     *
+     * Never used to measure elapsed time — see the duration sites in
+     * {@link waitForExecutable}, which stay on the raw local clock deliberately.
+     */
+    private now;
     private contract;
     /** Owners, threshold, timelock floor, nonce and balance. Always read from chain. */
     info(): Promise<VaultInfo>;
-    /** Active owners. Prefers the indexer, falls back to chain. */
+    /**
+     * Capture owners and threshold once, for reuse across a burst of reads.
+     *
+     * Pair with {@link pinned}:
+     *
+     * ```ts
+     * const view = await vault.view();
+     * const pinned = vault.pinned(view);
+     * // every read below shares one owner/threshold read
+     * const txs = await pinned.transactions(hashes);
+     * ```
+     */
+    view(): Promise<VaultView>;
+    /**
+     * A handle that answers {@link owners} and {@link threshold} from `view` instead of
+     * re-reading them.
+     *
+     * Reads only. Write preconditions go through `chainOwners` / `chainThreshold`, which
+     * bypass the snapshot by construction — pinning a view can never cause this SDK to
+     * sign against a stale owner set. Everything else about the handle, including the
+     * connection and the recovery module, is shared with the original.
+     */
+    pinned(view: VaultView): Vault;
+    /** Active owners. Prefers a pinned view, then the indexer, then chain. */
     owners(): Promise<Address[]>;
+    /**
+     * Owners straight from the chain, bypassing the indexer entirely.
+     *
+     * {@link owners} prefers the indexer, which is right for display and wrong for
+     * anything that gates a write. A lagging indexer would let the SDK build a proposal
+     * against an owner set that no longer exists — admitting a `removeOwner` that drops
+     * the vault below its threshold, or rejecting one that is perfectly valid. Every
+     * propose-time precondition reads through here instead.
+     */
+    private chainOwners;
     isOwner(address: Address): Promise<boolean>;
+    /**
+     * Whether `owner`'s approval on `txHash` currently counts toward the threshold.
+     *
+     * Reads the chain, and accounts for approval-epoch invalidation: removing an owner
+     * bumps the vault's epoch and voids every approval that address made, so a
+     * confirmation the indexer still lists may already be dead. This is the authoritative
+     * answer.
+     *
+     * Public because it is one of the two inputs {@link computeAffordances} needs. Without
+     * it a consumer wanting affordances at an adjusted time had no way to assemble an
+     * `AffordanceContext` short of reimplementing this method against the raw contract.
+     */
+    hasApproved(txHash: Bytes32, owner: Address): Promise<boolean>;
+    /** Approvals required to execute. Prefers a pinned view, then the indexer, then chain. */
     threshold(): Promise<number>;
+    /**
+     * Threshold straight from the chain. The write-path counterpart to {@link threshold},
+     * for the same reason {@link chainOwners} exists.
+     */
+    private chainThreshold;
     balance(): Promise<bigint>;
     /**
      * Enabled modules, in linked-list order.
@@ -1527,6 +1813,20 @@ declare class Vault {
     /** The vault-transaction hash for a given call, at a given nonce. */
     transactionHash(to: Address, value: bigint, data: Hex, nonce?: number): Promise<Bytes32>;
     transaction(txHash: Bytes32): Promise<VaultTransaction>;
+    /**
+     * Several transactions at once, keyed by hash.
+     *
+     * The plural form exists because the singular one is expensive to loop: each
+     * `transaction()` re-reads the owner set, the threshold and the indexer head, so
+     * fetching fifty costs fifty times that. This resolves the whole set the way the
+     * listing methods already do — one query for the rows, one owner/threshold read
+     * shared across them, one batched confirmations query.
+     *
+     * Hashes the indexer does not have fall back to chain reads, bounded by a pool.
+     * Hashes that exist nowhere are simply absent from the map rather than throwing:
+     * one unknown hash should not lose the caller the other forty-nine.
+     */
+    transactions(txHashes: Bytes32[]): Promise<Map<Bytes32, VaultTransaction>>;
     pendingTransactions(options?: Pagination): Promise<VaultTransaction[]>;
     transactionHistory(options?: Pagination & {
         status?: string[];
@@ -1550,7 +1850,17 @@ declare class Vault {
      * What `caller` may legally do to `txHash` right now, and when blocked actions
      * become available. Defaults to the connected signer's address.
      */
-    affordances(txHash: Bytes32, caller?: Address): Promise<Affordance[]>;
+    affordances(txHash: Bytes32, caller?: Address, at?: number): Promise<Affordance[]>;
+    /**
+     * Shared body of {@link affordances}, taking the transaction either as a value or as
+     * an in-flight promise.
+     *
+     * The promise form is the point: a caller that already holds the record (like
+     * {@link describe}) passes it and skips a redundant fetch, while `affordances()`
+     * passes the unawaited promise so the transaction read still overlaps the two
+     * ownership probes rather than serialising behind them.
+     */
+    private resolveAffordances;
     /**
      * Proposal builders.
      *
@@ -1770,6 +2080,11 @@ declare class Vault {
  * called, so building a client is cheap and safe at module scope.
  */
 declare class QuaiVaultClient {
+    /**
+     * Source of "now" for time compared against chain timestamps. Resolved once from
+     * {@link ClientOptions.now}, defaulting to the local clock. See {@link Clock}.
+     */
+    readonly now: Clock;
     /**
      * Resolved configuration, with the private key stripped and the indexer key
      * masked — safe to log. The key itself is consumed once when building the signer.
@@ -1828,6 +2143,23 @@ declare const QuaiVault: {
     connect: typeof connect;
 };
 
+/**
+ * Map with a bounded number of in-flight promises, preserving input order.
+ *
+ * A plain `Promise.all` over a fan-out the caller does not control is a liability:
+ * `balances()` can reach `maxTokens × maxTokenIdChecks` — 5,000 with the defaults —
+ * concurrent RPC reads from one call, and a batched transaction read fans out over
+ * however many hashes the caller passed. Public endpoints rate-limit long before
+ * either, and the failures come back as transient errors on reads that would each
+ * have succeeded on their own.
+ *
+ * Rejections propagate: the first failure rejects the whole call, matching
+ * `Promise.all`. Callers that want per-item tolerance catch inside `fn`.
+ */
+declare function mapPooled<T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
+/** Default ceiling on concurrent chain reads issued by one SDK call. */
+declare const DEFAULT_CONCURRENCY = 8;
+
 /**
  * Raw `Transaction` struct as returned by `QuaiVault.transactions(bytes32)`.
  * Field names match the Solidity struct.
@@ -1923,6 +2255,25 @@ declare class FactoryContract {
     registerWallet(wallet: Address): Promise<ContractTransactionResponse>;
 }
 
+/**
+ * Typed, retrying facade over an ERC20/721/1155 contract.
+ *
+ * Tokens are only ever read, never written to — the vault's own proposal flow is what
+ * moves them — so there is no write half here and no signer involved.
+ */
+declare class TokenContract {
+    readonly contract: Contract;
+    private readonly retry;
+    constructor(contract: Contract, retry?: RetryOptions);
+    private read;
+    /** ERC20 units held, or — for ERC721 — the number of tokens held. */
+    balanceOf(owner: Address): Promise<bigint>;
+    /** ERC721 only. Reverts for a burned or never-minted id. */
+    ownerOf(tokenId: string | bigint): Promise<string>;
+    /** ERC1155 only. One call for many ids, so it stays a single round trip. */
+    balanceOfBatch(owners: Address[], ids: Array<string | bigint>): Promise<bigint[]>;
+}
+
 /** Raw `RecoveryConfig` struct from `getRecoveryConfig(address)`. */
 interface RawRecoveryConfig {
     guardians: string[];
@@ -2141,6 +2492,38 @@ declare function predictVaultAddress(args: {
  */
 declare function shardPrefixOf(address: Address): string;
 
+/**
+ * Display sanitisation for attacker-controlled strings.
+ *
+ * Two values reach a consumer's screen without ever having been vetted by anyone:
+ *
+ * - **Token metadata.** `symbol()` and `name()` are whatever the token's deployer
+ *   chose. Getting one indexed against a vault costs one transfer of one unit.
+ * - **Revert reasons.** `Error(string)` data comes from the contract a vault called,
+ *   which for an external call is an arbitrary address the proposer picked.
+ *
+ * In a browser both are inert — the DOM escapes them. In a terminal they are not. An
+ * ANSI escape can move the cursor up and overwrite lines the SDK already printed, so
+ * a token named `"\x1b[2A\x1b[KAll checks passed"` can forge SDK output. Bidi
+ * overrides can reverse a rendered address while leaving the underlying bytes intact,
+ * which is the same trick that makes malicious source look benign.
+ *
+ * Sanitising here rather than in each consumer means a CLI, a TUI and a log pipeline
+ * all inherit it, and none of them has to remember. Only human-facing fields are
+ * scrubbed — machine-readable ones (`DecodedRevert.args`) keep the raw bytes, because
+ * a consumer comparing against an expected value needs exactly what was on chain.
+ */
+/** Default cap. Long enough for any legitimate token name, short enough to not wrap. */
+declare const DEFAULT_TEXT_LIMIT = 128;
+/**
+ * Strip control and direction-manipulating characters, collapse surrounding
+ * whitespace, and cap the length.
+ *
+ * Returns `''` for a non-string or for input that was entirely unsafe, so callers can
+ * `sanitizeText(x) || fallback`.
+ */
+declare function sanitizeText(value: unknown, maxLength?: number): string;
+
 /**
  * Address validation for Quai's dual-ledger, sharded address space.
  *
@@ -2189,7 +2572,7 @@ declare function assertQuaiAddress(value: unknown, label?: string): Address;
 declare function assertQuaiAddresses(values: readonly unknown[], label: string): Address[];
 
 /** Machine-readable error codes. Stable across releases. */
-type QuaiVaultErrorCode = 'CONFIG' | 'NOT_CONNECTED' | 'NO_SIGNER' | 'NO_INDEXER' | 'INDEXER_QUERY' | 'INDEXER_STALE' | 'VALIDATION' | 'NOT_FOUND' | 'PRECONDITION' | 'REVERT' | 'SALT_MINING' | 'STALE_PROPOSAL' | 'UNSUPPORTED';
+type QuaiVaultErrorCode = 'ABORTED' | 'CONFIG' | 'NOT_CONNECTED' | 'NO_SIGNER' | 'NO_INDEXER' | 'INDEXER_QUERY' | 'INDEXER_STALE' | 'VALIDATION' | 'NOT_FOUND' | 'PRECONDITION' | 'REVERT' | 'SALT_MINING' | 'STALE_PROPOSAL' | 'UNSUPPORTED';
 declare class QuaiVaultError extends Error {
     readonly code: QuaiVaultErrorCode;
     /** What the caller can do about it, in plain language. */
@@ -2205,6 +2588,18 @@ declare class QuaiVaultError extends Error {
     /** Structured form, for logs and machine consumers. */
     toJSON(): Record<string, unknown>;
 }
+/**
+ * A caller-supplied `AbortSignal` fired.
+ *
+ * Every long-running operation the SDK exposes — retries, indexer polling, salt
+ * mining, waiting for a timelock — accepts a signal, and each used to report abort
+ * differently: a bare `Error('Aborted')` in two places, a `PreconditionError` in a
+ * third. Consumers switching on `err.code` to distinguish "the user pressed Ctrl-C"
+ * from "this genuinely failed" could not do so. They can now.
+ */
+declare class AbortError extends QuaiVaultError {
+    constructor(operation?: string);
+}
 declare class ConfigError extends QuaiVaultError {
     constructor(message: string, remediation?: string);
 }
@@ -2268,4 +2663,4 @@ declare function knownErrorSelectors(): Array<{
     signature: string;
 }>;
 
-export { type Address, type AddressCheck, type AddressLedger, type Affordance, type AffordanceBlocker, type AffordanceContext, type ApprovalRecord, type BalanceOptions, type BatchCall, type Bytes32, type ClientOptions, ConfigError, Connection, type Consistency, type ContractAddresses, type CreateProgress, type CreateVaultParams, type CreateVaultResult, type DecodeContext, type DecodeResult, type DecodedBatchCall, type DecodedCall, type DecodedRevert, type DryRunResult, ENV_VARS, type ExecuteOutcome, type ExecuteResult, Factory, type FactoryContext, FactoryContract, type Hex, IndexerClient, type IndexerConfig, type IndexerHealth, IndexerQueries, IndexerQueryError, MAX_EXECUTION_DELAY, MAX_MODULES, MAX_OWNERS, type MineSaltOptions, type MinedSalt, type MiningStrategy, type NetworkConfig, type NetworkName, NoIndexerError, NoSignerError, NotFoundError, Operation, type Page, type Pagination, PreconditionError, type ProposeOptions, type ProposeResult, QuaiVault, QuaiVaultClient, QuaiVaultError, type QuaiVaultErrorCode, type RawRecovery, type RawRecoveryConfig, type RawRecoveryState, type RawTransactionState, type RawTransactionStruct, type ReceiptLike, type RecoveryAction, type RecoveryAffordance, type RecoveryConfig, RecoveryContract, RecoveryModule, type RecoveryModuleContext, type RecoveryRequest, type RecoveryStatus, type ResolvedConfig, type RetryOptions, RevertError, SENTINEL_MODULES, SaltMiningError, StaleProposalError, type Subscription, type TokenBalance, type TransactionKind, type TransactionStatus, ValidationError, Vault, type VaultAction, type VaultBalances, type VaultContext, VaultContract, type VaultInfo, type VaultTransaction, type WatchEvent, type WatchOptions, type WatchTopic, allowedActions, assertQuaiAddress, assertQuaiAddresses, classifyExecution, computeAffordances, computeBytecodeHash, computeFullSalt, connect, decodeCall, decodeMultiSendPayload, decodeRevert, decodeRevertFromError, defaultStrategy, deriveRecoveryStatus, deriveStatus, encodeInitData, encodeMultiSend, encodeMultiSendPayload, executableAfterOf, extractProposedTxHash, schemas as indexerSchemas, inspectAddress, interfaces, isNetworkName, isTerminal, isTransient, isUsableQuaiAddress, knownErrorSelectors, loadBalances, mainnet, mineSalt, minimumExpiration, networks, nowSeconds, predictVaultAddress, recoveryCall, remediationFor, resolveConfig, selfCall, shardPrefixOf, syncStrategy, testnet, token as tokenCalls, watchVault, withRetry, workerThreadsStrategy };
+export { AbortError, type Address, type AddressCheck, type AddressLedger, type Affordance, type AffordanceBlocker, type AffordanceContext, type ApprovalRecord, type BalanceOptions, type BatchCall, type Bytes32, type ClientOptions, type Clock, ConfigError, Connection, type Consistency, type ContractAddresses, type CreateProgress, type CreateVaultParams, type CreateVaultResult, DEFAULT_CONCURRENCY, DEFAULT_TEXT_LIMIT, type DecodeContext, type DecodeResult, type DecodedBatchCall, type DecodedCall, type DecodedRevert, type DryRunResult, ENV_VARS, type ExecuteOutcome, type ExecuteResult, Factory, type FactoryContext, FactoryContract, type Hex, IndexerClient, type IndexerConfig, type IndexerHealth, IndexerQueries, IndexerQueryError, MAX_EXECUTION_DELAY, MAX_MODULES, MAX_OWNERS, type MineSaltOptions, type MinedSalt, type MiningStrategy, type NetworkConfig, type NetworkName, NoIndexerError, NoSignerError, NotFoundError, Operation, type Page, type Pagination, PreconditionError, type ProposeOptions, type ProposeResult, QuaiVault, QuaiVaultClient, QuaiVaultError, type QuaiVaultErrorCode, type RawRecovery, type RawRecoveryConfig, type RawRecoveryState, type RawTransactionState, type RawTransactionStruct, type ReceiptLike, type RecoveryAction, type RecoveryAffordance, type RecoveryConfig, RecoveryContract, RecoveryModule, type RecoveryModuleContext, type RecoveryRequest, type RecoveryStatus, type ResolvedConfig, type RetryOptions, RevertError, SENTINEL_MODULES, SaltMiningError, StaleProposalError, type Subscription, type TokenBalance, TokenContract, type TransactionKind, type TransactionStatus, ValidationError, Vault, type VaultAction, type VaultBalances, type VaultContext, VaultContract, type VaultInfo, type VaultTransaction, type VaultView, type WatchEvent, type WatchOptions, type WatchTopic, type WorkerRuntime, ZERO_ADDRESS, allowedActions, assertQuaiAddress, assertQuaiAddresses, classifyExecution, computeAffordances, computeBytecodeHash, computeFullSalt, connect, createWorkerThreadsStrategy, decodeCall, decodeMultiSendPayload, decodeRevert, decodeRevertFromError, defaultStrategy, deriveRecoveryStatus, deriveStatus, encodeInitData, encodeMultiSend, encodeMultiSendPayload, executableAfterOf, extractProposedTxHash, schemas as indexerSchemas, inspectAddress, interfaces, isNetworkName, isTerminal, isTransient, isUsableQuaiAddress, knownErrorSelectors, loadBalances, mainnet, mapPooled, mineSalt, minimumExpiration, networks, nowSeconds, predictVaultAddress, recoveryCall, remediationFor, resolveConfig, sanitizeText, selfCall, shardPrefixOf, syncStrategy, testnet, token as tokenCalls, watchVault, withRetry, workerThreadsStrategy };