@arkade-os/sdk 0.4.58 → 0.4.60

package/dist/{ark-ClaVUg4e.d.cts → ark-D2_yNhfz.d.cts}

@@ -532,6 +532,17 @@ interface Network {
     pubKeyHash: number;
     scriptHash: number;
     wif: number;
+    /**
+     * Canonical name this network was resolved from, when known.
+     *
+     * `bech32` cannot separate the tb-family — testnet, signet and mutinynet
+     * share every field above — so anything that has to tell them apart (a
+     * per-network timelock floor, for one) has no other handle. Optional
+     * because a hand-built `Network` carries no name: consumers must read a
+     * missing one as "unknown" and fall back to their strictest branch rather
+     * than guess at one.
+     */
+    name?: NetworkName;
 }
 declare const getNetwork: (network: NetworkName) => Network;
 declare const networks: {
@@ -541,6 +552,62 @@ declare const networks: {
     mutinynet: Network;
     regtest: Network;
 };
+/** Covenant co-signer ("emulator") for the mainnet Arkade deployment. */
+declare const BITCOIN_EMULATOR_PUBKEY: "0239c196415da47b26456a101daaa12ba9e445bfe153197f1e2b750bf40e52092e";
+/** Covenant co-signer ("emulator") for the hosted mutinynet Arkade deployment. */
+declare const MUTINYNET_EMULATOR_PUBKEY: "03f823b9b2febc81f4af967e77aed2f541cbd3397c6d8f5a72e32eb7b471af889a";
+/** Covenant co-signer ("emulator") shipped with the `arkade-regtest` stack. */
+declare const REGTEST_EMULATOR_PUBKEY: "02999413c46fa10ada5cbc4bcc79a1d09160c2ba3cfc812705d7a13e5e545fb2a9";
+/**
+ * The pinned co-signer key for `network`, as 33-byte compressed lowercase hex.
+ *
+ * @throws if the network carries no name, or names one with no deployed
+ *   emulator. Fail closed on both counts: the return value ends up in a
+ *   covenant leaf that decides who can move the funds, so there is no
+ *   defensible fallback. Guessing a neighbour's key (the tb-family share every
+ *   other field on {@link Network}) would build a leaf co-signed by a service
+ *   that will never sign for it — funds locked to a key nobody holds — and
+ *   returning an empty string just moves the same failure somewhere harder to
+ *   read. A hand-assembled `Network` carries no `name` and lands here too,
+ *   matching how the per-network timelock floors treat an unnamed network.
+ *
+ *   Deliberately NOT falling back to whatever key the emulator reports about
+ *   itself: that is the self-report this pin exists to stop trusting, and doing
+ *   it only on unpinned networks would make the guarantee depend on
+ *   `network.name` with no signal to the caller that it had lapsed. The
+ *   unnamed case is the sharp one — a hand-built `Network` can carry
+ *   bitcoin-equivalent parameters, so a silent fallback would drop to
+ *   "trust the endpoint" on exactly the input that looks most like mainnet.
+ *   Callers who mean it pass {@link resolveEmulatorPubkey}'s override, which
+ *   the thrown message names.
+ */
+declare function defaultEmulatorPubkey(network: Network): string;
+/**
+ * Resolve the co-signer key for `network`, letting a caller substitute its own.
+ *
+ * The override is the escape hatch for three situations, and the first is the
+ * one that matters operationally:
+ *
+ * 1. **A network rotated its emulator key and this SDK has not shipped the new
+ *    constant yet.** Since `Arkade.connect` no longer asks the service which
+ *    key it signs with, a rotation is invisible here until the constant is
+ *    updated — covenants keep building against the retired key and fail only
+ *    when a claim is attempted. Passing the new key restores service without
+ *    waiting for a release, so a rotation is a config change rather than an
+ *    outage.
+ * 2. A private or self-hosted emulator, including on a network with no pinned
+ *    key at all (signet, testnet, a hand-built `Network`).
+ * 3. Tests and local stacks.
+ *
+ * Supplying it means co-signing with a different service: every covenant built
+ * from the returned key can be completed by whoever holds it and by no one
+ * else, so it is a statement that you trust that operator in place of the
+ * network's. Prefer {@link defaultEmulatorPubkey} unless that is deliberate.
+ *
+ * A malformed override throws rather than being passed through — a typo here
+ * would otherwise surface as an unspendable contract long after the fact.
+ */
+declare function resolveEmulatorPubkey(network: Network, override?: string): string;
 
 /**
  * The default base URLs for esplora API providers.
@@ -903,6 +970,27 @@ declare function classifyContractSigner(contractServerPubKeyHex: string, info: A
  */
 declare function isCooperativelyMigratable(status: SignerStatus): boolean;
 
+/**
+ * Outpoints (`txid:vout`) of VTXOs that are NOT cooperatively spendable because
+ * their contract's signer is past its cutoff (`EXPIRED`) and the VTXO has not
+ * yet been swept by the server. Such funds are unspendable until they recover
+ * (the server sweeps the batch at expiry, then the swept output re-settles under
+ * the active signer), so `getBalance` buckets them under `pendingRecovery` and
+ * coin selection skips them — otherwise a send would pick a VTXO the operator
+ * will not co-sign and fail at submit.
+ *
+ * Pure + offline: classification uses a cached {@link SignerSet}, never a fresh
+ * GetInfo. `MIGRATABLE` / `DUE_NOW` (still cooperatively spendable), already-
+ * swept (recoverable), `CURRENT`, and `UNKNOWN_SIGNER` rows are all left alone.
+ */
+declare function selectPendingRecoveryOutpoints(contractsWithVtxos: ReadonlyArray<{
+    contract: {
+        params: {
+            serverPubKey?: string;
+        };
+    };
+    vtxos: ReadonlyArray<VirtualCoin>;
+}>, signerSet: SignerSet, nowSeconds?: number): Set<string>;
 /**
  * Configuration options for automatic virtual output renewal
  *
@@ -1769,9 +1857,19 @@ interface ContractFilter {
     state?: ContractState | ContractState[];
     /** Filter by contract type(s) */
     type?: string | string[];
+    /**
+     * Filter by watch state(s). Rows written before the field existed
+     * have no stored value and match `"watched"`.
+     * @see ContractWatchState
+     */
+    watch?: ContractWatchState | ContractWatchState[];
 }
 interface ContractRepository extends AsyncDisposable {
-    readonly version: 1;
+    /**
+     * 2 — {@link Contract.watch}. An implementation must persist and
+     * round-trip it, and treat a row without one as `"watched"`.
+     */
+    readonly version: 2;
     /**
      * Clear all data from storage.
      */
@@ -1905,150 +2003,521 @@ interface VirtualTxRepository extends AsyncDisposable {
     pruneForSpentVtxo(vtxo: Outpoint): Promise<void>;
 }
 
-type RefreshVtxosOptions = {
+/** One transaction's participation in one logical action. */
+interface GroupMembership {
     /**
-     * Narrow the refresh to these scripts. A subset query, so the
-     * cursor is not advanced: contracts outside the list may have data
-     * we'd skip.
+     * Stable id of the action; txs sharing it group together. Third-party
+     * resolvers should namespace it (`"vendor:thing"`) to avoid colliding with
+     * other resolvers' groups. SDK built-ins use namespaced ids such as `boarding:`.
+     * A membership with an empty groupId is dropped.
      */
-    scripts?: string[];
+    groupId: string;
+    /** Human label for the action, e.g. "Dice game". */
+    label?: string;
+    /** App category for icon/filtering, e.g. "game". */
+    kind?: string;
     /**
-     * Time window overriding the cursor-derived one. The cursor never
-     * advances on a windowed query because the window may skip data
-     * outside its bounds.
+     * Free-form row data. Same-group metadata is shallow-merged with
+     * earlier-resolver keys winning.
      */
-    after?: number;
-    /** @see after */
-    before?: number;
+    metadata?: Record<string, unknown>;
     /**
-     * When true and `scripts` is not set, refresh every contract in
-     * the repository rather than the watcher's watched set — which
-     * differs only for rows the watcher never registered, since
-     * retirement doesn't narrow that set
-     * (see {@link ContractWatcher.getWatchedContracts}).
-     *
-     * Because this is a *superset* of the watched set, the cursor
-     * invariant still holds and the cursor advances normally (unless
-     * `after` / `before` is also supplied).
-     *
-     * @defaultValue `false`
+     * This tx's unsigned sat contribution to this group. Defaults to the tx's
+     * full amount; the builder applies direction. Use it to split a batched tx
+     * across groups. Same-key receive rows paired with a sent row are treated
+     * as change and excluded from `Activity.amount`. A membership with a
+     * non-finite amount (NaN/Infinity) is dropped.
      */
-    includeInactive?: boolean;
-};
-/**
- * A single `Discoverable` handler's discovery failure, captured during a
- * {@link IContractManager.scanContracts} run instead of aborting the loop.
- *
- * TODO(next major): rename `index` → `fromIndex` so the pair reads
- * `fromIndex`/`toIndex`. It stays `index` here only to keep this exported
- * shape backward-compatible.
- */
-interface HandlerError {
-    handler: string;
-    /** The failed index, or the first index of a failed `discoverRange` window. */
-    index: number;
-    /** Inclusive end of a failed `discoverRange` window; absent for a single index. */
-    toIndex?: number;
-    error: unknown;
+    amount?: number;
 }
-/**
- * Outcome of a {@link IContractManager.scanContracts} run.
- */
-interface ScanResult {
-    /** @deprecated Alias of {@link ScanResult.highestConfirmedUsedIndex}. */
-    lastIndexUsed: number;
+/** A pluggable resolver keyed by `id`. */
+interface ActivityResolver {
     /**
-     * Highest HD index at which any handler confirmed a contract (`-1` if none),
-     * including hits past {@link ScanResult.truncatedAt}. Safe to record
-     * unconditionally: the HD watermark it feeds is a monotonic max over a scan
-     * that always restarts at 0, so it cannot skip an index — while withholding
-     * it risks re-issuing a funded index as a fresh receive address.
+     * Registry key — override or remove by it. Namespace it (`"vendor:games"`)
+     * so independent libraries don't clobber each other; `use()` overwrites
+     * silently on a duplicate id.
      */
-    highestConfirmedUsedIndex: number;
+    id: string;
     /**
-     * First index a handler failed at, making it *indeterminate* — neither a hit
-     * nor a confirmed miss. The scan stops there, so indices `>= truncatedAt` are
-     * unverified and the caller must retry (scanning is idempotent). `undefined`
-     * when the scan closed a genuine gap.
+     * Load correlation data before `resolve` runs. If it rejects, this resolver
+     * contributes no memberships.
      */
-    truncatedAt?: number;
-    /** Per-handler discovery failures. Non-empty implies `truncatedAt` is set. */
-    handlerErrors: HandlerError[];
+    prepare?(): Promise<void>;
+    /** Pure and synchronous. The groups this tx belongs to, or undefined to leave it plain. */
+    resolve(tx: ArkTransaction): GroupMembership[] | undefined;
+}
+/** The non-id, non-amount part of a {@link GroupMembership}. */
+interface ActivityIntent {
+    /** Human label for the action, e.g. "Dice game". */
+    label?: string;
+    /** App category for icon/filtering, e.g. "game". */
+    kind?: string;
+    /** Free-form row data, shallow-merged across the group's resolvers (first-writer-wins). */
+    metadata?: Record<string, unknown>;
+}
+/** One logical activity. */
+interface Activity {
+    /** The groupId, or the natural tx key for untagged rows. */
+    id: string;
+    /** Merged intent for the group, if any resolver tagged it. */
+    intent?: ActivityIntent;
+    /** Member txs, oldest-first. */
+    txs: ArkTransaction[];
+    /** Signed net sats: positive received, negative sent; same-key change rows are excluded. */
+    amount: number;
+    /** Earliest member createdAt (ms since epoch). */
+    createdAt: number;
+    /** True once every member tx is settled. */
+    settled: boolean;
+}
+/** Resolver registry keyed by id. */
+declare class ActivityRegistry {
+    private readonly resolvers;
+    /** Add a resolver, or override an existing one with the same id (kept in place). */
+    use(resolver: ActivityResolver): void;
+    /** Remove a resolver (built-in or custom) by id. */
+    remove(id: string): void;
+    /** The registered resolver ids, in registration order. */
+    list(): string[];
+    /** All registered resolvers, in registration (priority) order. */
+    all(): ActivityResolver[];
 }
+/** Built-in resolver: labels on-chain boarding (deposit) transactions. */
+declare function boardingResolver(): ActivityResolver;
+/** Built-in resolver: labels collaborative exits (VTXOs forfeited to chain in a batch). */
+declare function collabExitResolver(): ActivityResolver;
 /**
- * Options for {@link IContractManager.scanContracts}.
+ * Built-in resolver: labels the genesis transaction of a minted asset — "Asset
+ * mint" on the issuer's sent tx, "Asset receive" when the fresh supply arrives
+ * in the genesis tx itself. An asset id encodes its genesis txid; reissues and
+ * transfers carry the asset under a different `arkTxid`, so they are left plain.
+ *
+ * `metadata.amount` is the decimal string of the asset's `bigint` amount, kept
+ * as a string so large supplies survive JSON round-trips without truncation.
+ * Recover the value with `BigInt(metadata.amount as string)` — using it
+ * directly in arithmetic coerces (`"10" + 1` is `"101"`, not `11`) and loses
+ * precision past `Number.MAX_SAFE_INTEGER`.
  */
-interface ScanContractsOptions {
-    /** Default 20. A non-positive / non-integer value throws. */
-    gapLimit?: number;
-    /**
-     * Number of HD indices probed per window (default
-     * {@link DEFAULT_SCAN_BATCH}). The gap loop stays gap-limit bounded and
-     * the discovered set is identical regardless of batch size; the window is
-     * also the unit a batching handler ({@link Discoverable.discoverRange})
-     * collapses into one request, so it doubles as the batch width. A
-     * non-positive / non-integer value throws. Ignored when `hd` is false (the
-     * static pass probes only index 0).
-     */
-    batchSize?: number;
-    /** HD mode → unbounded gap loop guided by the gap counter; false → probe only index 0 (single static pass). */
-    hd: boolean;
-    /**
-     * Materialize the descriptor at an HD index. Pure derivation; a throw
-     * here is structural/fatal and propagates out of `scanContracts`.
-     */
-    materialize: (index: number) => string;
-    /** Read-only context injected into every `discoverAt` call. */
-    deps: DiscoveryDeps;
-}
+declare function assetMintResolver(): ActivityResolver;
 /**
- * Freshness of the ContractManager's provider-backed sync. `degraded` means the
- * most recent sync (boot, best-effort read, or contract hydration) hit a
- * retryable indexer/operator failure and the manager is serving repository
- * state; it returns to `online` on the next successful sync. This only
- * describes sync freshness — never wallet data itself.
+ * A registry pre-populated with the SDK's built-in resolvers: `boarding`,
+ * `collab-exit`, and `asset-mint`.
  */
-type ContractSyncState = {
-    mode: "online";
-    lastSyncedAt?: number;
-} | {
-    mode: "degraded";
-    reason: string;
-    lastSyncedAt?: number;
-};
-interface IContractManager extends Disposable {
+declare function createDefaultActivityRegistry(): ActivityRegistry;
+
+/**
+ * Intent proof implementation for Bitcoin message signing.
+ *
+ * Intent proof defines a standard for signing Bitcoin messages as well as proving
+ * ownership of outputs.
+ *
+ * This namespace provides utilities for creating and validating Intent proof.
+ *
+ * It is greatly inspired by BIP322.
+ * @see https://github.com/bitcoin/bips/blob/master/bip-0322.mediawiki
+ *
+ * @example
+ * ```typescript
+ * // Create a Intent proof
+ * const proof = Intent.create(
+ *   "Hello Bitcoin!",
+ *   [input],
+ *   [output]
+ * );
+ *
+ * // Sign the proof
+ * const signedProof = await identity.sign(proof);
+ *
+ */
+declare namespace Intent {
+    type Proof = Transaction;
     /**
-     * Create and register a new contract.
-     *
-     * Implementations may validate that:
-     * - A handler exists for `params.type`
-     * - `params.script` matches the script derived from `params.params`
+     * Creates a new Intent proof unsigned transaction.
      *
-     * The contract script is used as the unique identifier.
-     */
-    createContract(params: CreateContractParams): Promise<Contract>;
-    /**
-     * List contracts with optional filters.
+     * This function constructs a special transaction that can be signed to prove
+     * ownership of onchain and virtual outputs. The proof includes the message to be
+     * signed and the inputs/outputs that demonstrate ownership.
      *
-     * @example
-     * ```typescript
-     * const vhtlcs = await manager.getContracts({ type: "vhtlc" });
-     * const active = await manager.getContracts({ state: "active" });
-     * ```
+     * @param message - The Intent message to be signed, either raw string of Message object
+     * @param ins - Array of transaction inputs to prove ownership of
+     * @param outputs - Optional array of transaction outputs
+     * @returns An unsigned Intent proof transaction
      */
-    getContracts(filter?: GetContractsFilter): Promise<Contract[]>;
+    function create(message: string | Message, ins: (TransactionInput | ExtendedCoin)[], outputs?: TransactionOutput[]): Proof;
     /**
-     * List contracts and their current virtual outputs.
+     * Compute the fee paid by an intent proof transaction.
      *
-     * If no filter is provided, returns all contracts with their virtual outputs.
-     */
-    getContractsWithVtxos(filter?: GetContractsFilter): Promise<ContractWithVtxos[]>;
-    /**
-     * Latest provider-sync health (online vs. degraded to repository data).
-     * See {@link ContractSyncState}.
+     * @param proof - Intent proof transaction
+     * @returns The fee in satoshis
      */
-    getSyncState(): ContractSyncState;
-    /**
+    function fee(proof: Proof): number;
+    type RegisterMessage = {
+        type: "register";
+        onchain_output_indexes: number[];
+        valid_at: number;
+        expire_at: number;
+        cosigners_public_keys: string[];
+    };
+    type DeleteMessage = {
+        type: "delete";
+        expire_at: number;
+    };
+    type GetPendingTxMessage = {
+        type: "get-pending-tx";
+        expire_at: number;
+    };
+    type Message = RegisterMessage | DeleteMessage | GetPendingTxMessage;
+    /**
+     * Serialize an intent message to the canonical JSON string used for signing.
+     *
+     * @param message - Intent message payload
+     * @returns Canonical string form of the message
+     */
+    function encodeMessage(message: Message): string;
+}
+
+/**
+ * A source of unilateral-exit chain data for a set of VTXOs. Sources are tried
+ * in order by the resolver; a source returns `null` (chain) or omits keys (psbts)
+ * for data it cannot supply — a "miss" — and the resolver falls through.
+ */
+interface ExitDataSource {
+    readonly name: string;
+    /** Full ancestry chain for a vtxo (all pages merged), or null on a miss. */
+    getVtxoChain(vtxo: Outpoint): Promise<ChainTx[] | null>;
+    /** Base64 PSBTs this source has, keyed by (unsigned) txid. Absent key = miss. */
+    getVirtualTxs(txids: string[]): Promise<Map<string, string>>;
+}
+/** Reads exit chain data through an ordered chain of sources. */
+interface ExitChainResolver {
+    getVtxoChain(vtxo: Outpoint): Promise<ChainTx[]>;
+    getVirtualTxs(txids: string[]): Promise<string[]>;
+}
+/**
+ * Assemble the standard exit-data resolver: local repo (if configured) → any
+ * extra sources (e.g. a future provider) → indexer. Read-through persists to the
+ * repository. With no repository this is exactly the indexer path (a no-op seam).
+ */
+declare function createExitChainResolver(params: {
+    indexer: IndexerProvider;
+    repository?: VirtualTxRepository;
+    extraSources?: ExitDataSource[];
+}): ExitChainResolver;
+
+type ExitCaptureMode = "lite" | "full";
+
+/**
+ * Delegate identity and fee information returned by `getDelegateInfo`.
+ */
+interface DelegateInfo {
+    /** Delegate public key. */
+    pubkey: string;
+    /** Delegate fee amount or expression returned by the delegate. */
+    fee: string;
+    /** Address for delegate fee collection. Sourced from `delegatorAddress` in Fulmine response, for now. */
+    delegateAddress: string;
+    /** @deprecated alias for @see DelegateInfo.delegateAddress */
+    delegatorAddress?: string;
+}
+/**
+ * Optional delegate behavior flags.
+ */
+interface DelegateOptions {
+    /**
+     * Instruct the delegate not to replace an existing delegation
+     * (meaning a signed register intent and its forfeit transactions)
+     * that already includes at least one virtual output from this request.
+     *
+     * @defaultValue `false`
+     */
+    rejectReplace?: boolean;
+}
+/**
+ * Provider interface for remote delegation service.
+ */
+interface DelegateProvider {
+    /**
+     * Request delegation for a signed register intent and its forfeit transactions.
+     *
+     * @param intent - Signed register intent to delegate
+     * @param forfeitTxs - Forfeit transactions associated with the delegation request
+     * @param options - Optional delegate behavior flags
+     */
+    delegate(intent: SignedIntent<Intent.RegisterMessage>, forfeitTxs: string[], options?: DelegateOptions): Promise<void>;
+    /**
+     * Fetch delegate metadata such as pubkey, fee, and delegate address.
+     *
+     * @returns Delegate identity and fee information
+     */
+    getDelegateInfo(): Promise<DelegateInfo>;
+}
+/** @deprecated alias for @see DelegateProvider */
+type DelegatorProvider = DelegateProvider;
+/**
+ * REST-based delegate provider implementation.
+ * @example
+ * ```typescript
+ * const provider = new RestDelegateProvider('https://delegate.example.com');
+ * const info = await provider.getDelegateInfo();
+ * await provider.delegate(intent, forfeitTxs);
+ * ```
+ */
+declare class RestDelegateProvider implements DelegateProvider {
+    url: string;
+    /**
+     * Create a REST delegate provider targeting the given base URL.
+     *
+     * @param url - Base URL of the remote delegation service.
+     */
+    constructor(url: string);
+    /**
+     * Submit a delegation request to the remote delegation service.
+     *
+     * @param intent - Signed register intent to delegate
+     * @param forfeitTxs - Forfeit transactions associated with the delegation request
+     * @param options - Optional delegate behavior flags
+     * @throws Error if the remote service rejects the request
+     */
+    delegate(intent: SignedIntent<Intent.RegisterMessage>, forfeitTxs: string[], options?: DelegateOptions): Promise<void>;
+    /**
+     * Fetch delegate metadata exposed by the remote delegation service.
+     *
+     * @returns Delegate identity and fee information
+     * @throws Error if the remote service returns invalid data
+     */
+    getDelegateInfo(): Promise<DelegateInfo>;
+}
+/** @deprecated alias for @see RestDelegateProvider */
+declare const RestDelegatorProvider: typeof RestDelegateProvider;
+type RestDelegatorProvider = RestDelegateProvider;
+
+interface IDelegateManager {
+    /**
+     * Delegate virtual outputs to the remote delegation service.
+     *
+     * Vtxos that are not locked to a delegate-type contract (no tap leaf
+     * matches the delegate's pubkey) are filtered out silently, since they
+     * cannot be co-signed by the delegate.
+     *
+     * @param vtxos - Virtual outputs to delegate
+     * @param destination - Arkade address that should receive renewed funds
+     * @param delegateAt - Optional timestamp to force a specific delegation time
+     * @returns Successfully delegated and failed outpoint groups
+     */
+    delegate(vtxos: ContractVtxo[], destination: string, delegateAt?: Date): Promise<{
+        delegated: Outpoint[];
+        failed: {
+            outpoints: Outpoint[];
+            error: unknown;
+        }[];
+    }>;
+    /** Fetch delegate metadata such as pubkey, fee, and delegate address. */
+    getDelegateInfo(): Promise<DelegateInfo>;
+}
+/** @deprecated alias for @see IDelegateManager */
+type IDelegatorManager = IDelegateManager;
+declare class DelegateManagerImpl implements IDelegateManager {
+    readonly delegateProvider: DelegateProvider;
+    readonly arkInfoProvider: Pick<ArkProvider, "getInfo">;
+    readonly identity: Identity;
+    /** Create a delegate manager from the configured provider, Arkade info source, and wallet identity. */
+    constructor(delegateProvider: DelegateProvider, arkInfoProvider: Pick<ArkProvider, "getInfo">, identity: Identity);
+    getDelegateInfo(): Promise<DelegateInfo>;
+    delegate(vtxos: ContractVtxo[], destination: string, delegateAt?: Date): Promise<{
+        delegated: Outpoint[];
+        failed: {
+            outpoints: Outpoint[];
+            error: unknown;
+        }[];
+    }>;
+}
+/** @deprecated alias for @see DelegateManagerImpl */
+declare const DelegatorManagerImpl: typeof DelegateManagerImpl;
+type DelegatorManagerImpl = DelegateManagerImpl;
+
+/**
+ * Tapscript fields derived purely from a contract's params. They are identical
+ * for every VTXO locked to the same contract, so they can be memoized per
+ * contract (see {@link ContractTapscriptCache}).
+ */
+type ContractTapscripts = Pick<ExtendedVirtualCoin, "forfeitTapLeafScript" | "intentTapLeafScript" | "tapTree">;
+/**
+ * Cache of per-contract tapscript data, keyed by `contract.script`. Building
+ * the taproot tree via `handler.createScript(contract.params)` is the dominant
+ * cost when annotating large VTXO sets; passing a shared cache across an
+ * annotation batch rebuilds it once per distinct contract instead of once per
+ * VTXO (see #521).
+ */
+type ContractTapscriptCache = Map<string, ContractTapscripts>;
+declare function getRandomId(): string;
+/**
+ * What a recipient Arkade address must match. An address failing either check
+ * belongs to another network or operator, so this wallet's operator cannot
+ * create the VTXO where the recipient's wallet expects it.
+ */
+type RecipientAddressContext = {
+    hrp: string;
+    signerSet: SignerSet;
+};
+
+/**
+ * An input for {@link IContractManager.assertSpendableNow}.
+ *
+ * The outpoint and script are what identify the owning contract. A full
+ * {@link VirtualCoin} is accepted and preferred: a relative (CSV) timelock is
+ * measured from this coin's own confirmation, so `status.block_height` /
+ * `status.block_time` are the only way to answer one. Pass the coin where you
+ * have it; the bare shape still answers every absolute (CLTV) question.
+ */
+type AssertSpendableInput = {
+    txid: string;
+    vout: number;
+    script: string;
+};
+type RefreshVtxosOptions = {
+    /**
+     * Narrow the refresh to these scripts. A subset query, so the
+     * cursor is not advanced: contracts outside the list may have data
+     * we'd skip.
+     */
+    scripts?: string[];
+    /**
+     * Time window overriding the cursor-derived one. The cursor never
+     * advances on a windowed query because the window may skip data
+     * outside its bounds.
+     */
+    after?: number;
+    /** @see after */
+    before?: number;
+    /**
+     * When true and `scripts` is not set, refresh every contract in
+     * the repository rather than the watcher's watched set — which
+     * differs only for rows the watcher never registered, since
+     * retirement doesn't narrow that set
+     * (see {@link ContractWatcher.getWatchedContracts}).
+     *
+     * Because this is a *superset* of the watched set, the cursor
+     * invariant still holds and the cursor advances normally (unless
+     * `after` / `before` is also supplied).
+     *
+     * @defaultValue `false`
+     */
+    includeInactive?: boolean;
+};
+/**
+ * A single `Discoverable` handler's discovery failure, captured during a
+ * {@link IContractManager.scanContracts} run instead of aborting the loop.
+ *
+ * TODO(next major): rename `index` → `fromIndex` so the pair reads
+ * `fromIndex`/`toIndex`. It stays `index` here only to keep this exported
+ * shape backward-compatible.
+ */
+interface HandlerError {
+    handler: string;
+    /** The failed index, or the first index of a failed `discoverRange` window. */
+    index: number;
+    /** Inclusive end of a failed `discoverRange` window; absent for a single index. */
+    toIndex?: number;
+    error: unknown;
+}
+/**
+ * Outcome of a {@link IContractManager.scanContracts} run.
+ */
+interface ScanResult {
+    /** @deprecated Alias of {@link ScanResult.highestConfirmedUsedIndex}. */
+    lastIndexUsed: number;
+    /**
+     * Highest HD index at which any handler confirmed a contract (`-1` if none),
+     * including hits past {@link ScanResult.truncatedAt}. Safe to record
+     * unconditionally: the HD watermark it feeds is a monotonic max over a scan
+     * that always restarts at 0, so it cannot skip an index — while withholding
+     * it risks re-issuing a funded index as a fresh receive address.
+     */
+    highestConfirmedUsedIndex: number;
+    /**
+     * First index a handler failed at, making it *indeterminate* — neither a hit
+     * nor a confirmed miss. The scan stops there, so indices `>= truncatedAt` are
+     * unverified and the caller must retry (scanning is idempotent). `undefined`
+     * when the scan closed a genuine gap.
+     */
+    truncatedAt?: number;
+    /** Per-handler discovery failures. Non-empty implies `truncatedAt` is set. */
+    handlerErrors: HandlerError[];
+}
+/**
+ * Options for {@link IContractManager.scanContracts}.
+ */
+interface ScanContractsOptions {
+    /** Default 20. A non-positive / non-integer value throws. */
+    gapLimit?: number;
+    /**
+     * Number of HD indices probed per window (default
+     * {@link DEFAULT_SCAN_BATCH}). The gap loop stays gap-limit bounded and
+     * the discovered set is identical regardless of batch size; the window is
+     * also the unit a batching handler ({@link Discoverable.discoverRange})
+     * collapses into one request, so it doubles as the batch width. A
+     * non-positive / non-integer value throws. Ignored when `hd` is false (the
+     * static pass probes only index 0).
+     */
+    batchSize?: number;
+    /** HD mode → unbounded gap loop guided by the gap counter; false → probe only index 0 (single static pass). */
+    hd: boolean;
+    /**
+     * Materialize the descriptor at an HD index. Pure derivation; a throw
+     * here is structural/fatal and propagates out of `scanContracts`.
+     */
+    materialize: (index: number) => string;
+    /** Read-only context injected into every `discoverAt` call. */
+    deps: DiscoveryDeps;
+}
+/**
+ * Freshness of the ContractManager's provider-backed sync. `degraded` means the
+ * most recent sync (boot, best-effort read, or contract hydration) hit a
+ * retryable indexer/operator failure and the manager is serving repository
+ * state; it returns to `online` on the next successful sync. This only
+ * describes sync freshness — never wallet data itself.
+ */
+type ContractSyncState = {
+    mode: "online";
+    lastSyncedAt?: number;
+} | {
+    mode: "degraded";
+    reason: string;
+    lastSyncedAt?: number;
+};
+interface IContractManager extends Disposable {
+    /**
+     * Create and register a new contract.
+     *
+     * Implementations may validate that:
+     * - A handler exists for `params.type`
+     * - `params.script` matches the script derived from `params.params`
+     *
+     * The contract script is used as the unique identifier.
+     */
+    createContract(params: CreateContractParams): Promise<Contract>;
+    /**
+     * List contracts with optional filters.
+     *
+     * @example
+     * ```typescript
+     * const vhtlcs = await manager.getContracts({ type: "vhtlc" });
+     * const active = await manager.getContracts({ state: "active" });
+     * ```
+     */
+    getContracts(filter?: GetContractsFilter): Promise<Contract[]>;
+    /**
+     * List contracts and their current virtual outputs.
+     *
+     * If no filter is provided, returns all contracts with their virtual outputs.
+     */
+    getContractsWithVtxos(filter?: GetContractsFilter): Promise<ContractWithVtxos[]>;
+    /**
+     * Latest provider-sync health (online vs. degraded to repository data).
+     * See {@link ContractSyncState}.
+     */
+    getSyncState(): ContractSyncState;
+    /**
      * Stamp raw virtual outputs with the correct per-contract tapscripts
      * (forfeit, intent, tap tree).
      *
@@ -2060,7 +2529,43 @@ interface IContractManager extends Disposable {
      * in wallet/handler code, and keeps the wallet from silently stamping the
      * default tapscript onto a non-default vtxo.
      */
-    annotateVtxos(vtxos: VirtualCoin[]): Promise<NormalizedExtendedVirtualCoin[]>;
+    annotateVtxos(vtxos: VirtualCoin[], tapscripts?: ContractTapscriptCache): Promise<NormalizedExtendedVirtualCoin[]>;
+    /**
+     * Throw unless every one of `vtxos` still has an annotatable contract.
+     *
+     * Spending does not re-derive tapscripts — it uses the ones stored on the
+     * coin — so a contract that stopped being annotatable (handler no longer
+     * registered, or params its handler now rejects) still builds and submits a
+     * transaction fine, and only fails afterwards, in the bookkeeping that
+     * re-annotates the inputs. Calling this before submitting turns that into a
+     * refusal to spend, naming the contract, rather than a broadcast whose local
+     * state could not be recorded.
+     */
+    assertAnnotatable(vtxos: readonly {
+        txid: string;
+        vout: number;
+        script: string;
+    }[]): Promise<void>;
+    /**
+     * Throw when one of `vtxos` belongs to a contract that provably cannot be
+     * spent right now, asking each owning handler's
+     * {@link ContractHandler.assertSpendableNow}.
+     *
+     * The complement of {@link isContractGenericallySpendable}, which keeps
+     * escrow out of generic selection and leaves explicit-input APIs open on
+     * purpose. This does not close that door — it makes walking through it too
+     * early report itself locally, naming the timelock, instead of coming back
+     * as a protocol-level rejection after the round trip.
+     *
+     * Handlers answer only where they are certain, so contracts with no opinion
+     * (which is all of them but VHTLC today) pass through untouched and cost
+     * nothing — not even a chain-tip read.
+     *
+     * Optional so that adding it is not a breaking change for an embedder with
+     * its own `IContractManager`. An implementation that omits it simply offers
+     * no opinion, which is the same answer every non-VHTLC contract gives.
+     */
+    assertSpendableNow?(vtxos: readonly AssertSpendableInput[], walletPubKey?: () => Promise<string | undefined>): Promise<void>;
     /**
      * Update mutable contract fields.
      *
@@ -2069,13 +2574,29 @@ interface IContractManager extends Disposable {
     updateContract(script: string, updates: Partial<Omit<Contract, "script" | "createdAt">>): Promise<Contract>;
     /**
      * Convenience helper to update only the contract state. Note
-     * `inactive` does not stop watching; see {@link ContractState} and
-     * {@link deleteContract}.
+     * `inactive` governs receive-address selection and does not stop
+     * watching; see {@link ContractState} and
+     * {@link setContractWatchState}.
      */
     setContractState(script: string, state: ContractState): Promise<void>;
     /**
-     * Delete a contract by script and stop watching it. This — not
-     * retiring via {@link setContractState} — is the stop-watching path.
+     * Convenience helper to update only the contract's watch state.
+     *
+     * `retained` is how an owner says "this script is done": it leaves
+     * the subscription and the sweep, while the row — and so history,
+     * annotation and restore — is untouched. `awaiting-funds` asks for
+     * coverage only until the script is funded, after which the manager
+     * demotes it to `retained` itself.
+     *
+     * @see ContractWatchState
+     */
+    setContractWatchState(script: string, watch: ContractWatchState): Promise<void>;
+    /**
+     * Delete a contract by script, dropping both the row and the watch.
+     * Destructive: the row is what keeps the contract's VTXOs
+     * annotatable and its transactions readable in history, so to stop
+     * watching a finished contract use
+     * {@link setContractWatchState}(`"retained"`) instead.
      */
     deleteContract(script: string): Promise<void>;
     /**
@@ -2127,6 +2648,17 @@ interface IContractManager extends Disposable {
      * coalesce into a single drain.
      */
     refillLookAhead(): Promise<void>;
+    /**
+     * Allocate the next signing descriptor through the manager-owned HD
+     * watermark path. Returns `undefined` when look-ahead/allocation is not
+     * configured.
+     */
+    getNextSigningDescriptor(): Promise<string | undefined>;
+    /**
+     * Advance the HD signing descriptor watermark to `index` and refill the
+     * watched look-ahead band. No-op when look-ahead/allocation is not configured.
+     */
+    advanceSigningDescriptorWatermark(index: number): Promise<void>;
     /**
      * Explicit, gap-limit contract discovery used by `wallet.restore()`.
      *
@@ -2223,6 +2755,33 @@ interface ContractManagerConfig {
      * {@link ContractManager.refillLookAhead}.
      */
     lookAhead?: LookAheadConfig;
+    /**
+     * Current chain tip height, for the `blockHeight` a {@link PathContext}
+     * carries. Absent, or resolving `undefined`, leaves `blockHeight` unset.
+     *
+     * `isCltvSatisfied` answers `false` outright for a height-typed locktime
+     * when `blockHeight` is missing, so every such path was reported
+     * unspendable however mature it was. Nothing populated this before, which
+     * made that the only behaviour available. Seconds-typed locktimes read
+     * `currentTime` and are unaffected either way.
+     *
+     * Block-typed CSV is not fixed by this. `isCsvSpendable` also needs the
+     * VTXO's confirmation height, and `status.block_height` is never populated
+     * for a virtual coin, so it stays `false` regardless of the tip.
+     *
+     * Both fields matter. `height` answers height-typed timelocks; `time` (the
+     * tip's timestamp, in SECONDS) is what seconds-typed ones should be judged
+     * against, because the machine's clock is an estimate of chain time and a
+     * drifting one reads the boundary wrong.
+     *
+     * Resolve `undefined` rather than rejecting when the tip cannot be read:
+     * the callers treat it as "unknown", which is the pre-existing behaviour,
+     * and a path query is not worth failing over a provider hiccup.
+     */
+    chainTip?: () => Promise<{
+        height: number;
+        time: number;
+    } | undefined>;
 }
 /**
  * Wallet-injected surface backing the HD look-ahead window. Kept as a
@@ -2234,6 +2793,10 @@ interface LookAheadConfig {
     size: number;
     /** Current allocation watermark (`lastIndexUsed ?? -1`). */
     currentWatermark(): Promise<number>;
+    /** Allocate the next signing descriptor, advancing the watermark. */
+    allocate?(): Promise<string | undefined>;
+    /** Advance the allocation watermark to a confirmed/restored index. */
+    advanceWatermark?(index: number): Promise<void>;
     /** Signing descriptor at an HD index. Pure derivation. */
     materialize(index: number): string;
     /**
@@ -2242,7 +2805,10 @@ interface LookAheadConfig {
      * `rotateServerSigner` fans the new signer set.
      */
     candidateDeps(): CandidateDeps;
-    /** Fired after a speculative entry at `index` is promoted to a real row. */
+    /**
+     * Fired after a speculative entry at `index` is promoted to a real row.
+     * @deprecated Use `advanceWatermark`; kept for external LookAheadConfig users.
+     */
     onPromoted?(index: number): Promise<void>;
 }
 /**
@@ -2309,12 +2875,24 @@ declare class ContractManager implements IContractManager {
     private syncDegradedReason?;
     /** Epoch-ms of the last successful provider sync, if any. */
     private lastSyncedAt?;
+    /** Last chain tip read, with the epoch-ms it was read at. @see currentChainTip */
+    private chainTipCache?;
+    /** In-flight chain tip read, so concurrent cache misses share one. */
+    private chainTipInflight?;
     /** Speculative look-ahead scripts, keyed by script. @see LookAheadEntry */
     private lookAheadEntries;
     /** In-flight look-ahead drain, if any. @see scheduleLookAheadDrain */
     private lookAheadDrain?;
     /** A refill was requested while a drain was running. */
     private lookAheadDirty;
+    /** A fire-and-forget drain failed, so the band is behind the watermark and
+     * owes a retry. @see requestLookAheadDrain */
+    private lookAheadRefillOwed;
+    /** Set by {@link dispose}, cleared by a re-`initialize`. A drain is a
+     * fire-and-forget async loop that outlives the synchronous `dispose()`,
+     * so it re-checks this at every await boundary instead of running on
+     * against a torn-down watcher. */
+    private disposed;
     private constructor();
     /**
      * Static factory method for creating a new ContractManager.
@@ -2334,6 +2912,17 @@ declare class ContractManager implements IContractManager {
      */
     getSyncState(): ContractSyncState;
     private markSyncOnline;
+    /** Contracts a sync could not annotate, as `script → reason`. */
+    private annotationFailures;
+    private annotationDegradedReason;
+    /**
+     * Fold one batch's verdict in: what it annotated clears, what it could not
+     * sets. Merged rather than replaced because a batch can cover a subset of
+     * the wallet's contracts (a single-contract fetch, the pending-only
+     * reconcile), and those must not erase what a wider sync found. A row
+     * repaired by an upgrade clears itself on the next batch that includes it.
+     */
+    private recordAnnotationFailures;
     private markSyncDegraded;
     private initialize;
     /**
@@ -2358,6 +2947,10 @@ declare class ContractManager implements IContractManager {
     private reconcileStaleIntents;
     /** @see IContractManager.refillLookAhead */
     refillLookAhead(): Promise<void>;
+    /** @see IContractManager.getNextSigningDescriptor */
+    getNextSigningDescriptor(): Promise<string | undefined>;
+    /** @see IContractManager.advanceSigningDescriptorWatermark */
+    advanceSigningDescriptorWatermark(index: number): Promise<void>;
     /**
      * Serialized drain of the look-ahead band: concurrent callers join the
      * active drain and mark it dirty, an idle call starts a new one. Promotion
@@ -2368,7 +2961,13 @@ declare class ContractManager implements IContractManager {
     private scheduleLookAheadDrain;
     /**
      * Request a drain without awaiting it. Used from inside a sync (promotion),
-     * where awaiting the drain that the sync itself is part of would deadlock.
+     * and after an allocation the drain must not be able to fail — the
+     * watermark already moved, and a retry would burn another index.
+     *
+     * A failure here is not terminal: it leaves the watch band behind the
+     * watermark, so funded indices inside it would go unregistered and the
+     * balance would under-report for the rest of the session. Record the debt
+     * so the next contract event retries it. @see handleContractEvent
      */
     private requestLookAheadDrain;
     /**
@@ -2401,6 +3000,7 @@ declare class ContractManager implements IContractManager {
      * exist. Targeted + explicitly windowed, so the global cursor stays put.
      */
     private runLookAheadCatchUp;
+    private advanceLookAheadWatermark;
     /**
      * Promote every look-ahead entry funded by `vtxos` into a real repository
      * row, returning the persisted rows keyed by script.
@@ -2505,7 +3105,15 @@ declare class ContractManager implements IContractManager {
      */
     getContracts(filter?: GetContractsFilter): Promise<Contract[]>;
     getContractsWithVtxos(filter?: GetContractsFilter, pageSize?: number): Promise<ContractWithVtxos[]>;
-    annotateVtxos(vtxos: VirtualCoin[]): Promise<NormalizedExtendedVirtualCoin[]>;
+    annotateVtxos(vtxos: VirtualCoin[], tapscripts?: ContractTapscriptCache): Promise<NormalizedExtendedVirtualCoin[]>;
+    /** @inheritdoc */
+    assertAnnotatable(vtxos: readonly {
+        txid: string;
+        vout: number;
+        script: string;
+    }[]): Promise<void>;
+    /** @inheritdoc */
+    assertSpendableNow(vtxos: readonly AssertSpendableInput[], walletPubKey?: () => Promise<string | undefined>): Promise<void>;
     private buildContractsDbFilter;
     /**
      * Update a contract.
@@ -2526,18 +3134,39 @@ declare class ContractManager implements IContractManager {
     updateContractParams(script: string, updates: Contract["params"]): Promise<Contract>;
     /**
      * Set a contract's state. Retiring (`inactive`) keeps it watched;
-     * see {@link ContractState}. To stop watching, use
-     * {@link deleteContract}.
+     * see {@link ContractState}. To stop watching while keeping the row,
+     * use {@link setContractWatchState}.
      */
     setContractState(script: string, state: ContractState): Promise<void>;
+    /** @see IContractManager.setContractWatchState */
+    setContractWatchState(script: string, watch: ContractWatchState): Promise<void>;
     /**
-     * Delete a contract. Also removes it from the watcher — the only way
-     * to stop watching a contract (retiring it via
-     * {@link setContractState} does not).
+     * Delete a contract, dropping the row along with the watch. To stop
+     * watching a finished contract without losing its history, use
+     * {@link setContractWatchState}(`"retained"`).
      *
      * @param script - Contract script
      */
     deleteContract(script: string): Promise<void>;
+    /**
+     * Chain tip height for a {@link PathContext}, or `undefined` when there is
+     * no source configured or it cannot be read.
+     *
+     * Cached for {@link CHAIN_TIP_TTL_MS} so a caller resolving paths for many
+     * contracts does not pay a provider round trip each time. Blocks arrive
+     * ~10 minutes apart, so a cache this short can only ever be one block
+     * stale, and a stale-low height is the conservative direction: a path is
+     * reported unspendable slightly longer than it truly is, never spendable
+     * before it is.
+     */
+    private currentChainTip;
+    /**
+     * One chain tip read, bounded by {@link CHAIN_TIP_TIMEOUT_MS}. Never
+     * rejects: an unreadable tip is "unknown", which is what the callers did
+     * before a tip existed at all, and a path query is not worth failing over
+     * a provider hiccup.
+     */
+    private readChainTip;
     /**
      * Get currently spendable paths for a contract.
      *
@@ -2547,6 +3176,11 @@ declare class ContractManager implements IContractManager {
     /**
      * Get every currently valid spending path for a contract.
      *
+     * No `blockHeight`: this enumerates paths "regardless of current
+     * spendability", so no handler evaluates a timelock here and the tip would
+     * be fetched only to be discarded — leaving a purely local answer waiting
+     * on the network for nothing.
+     *
      * @param options - Options for getting spending paths
      */
     getAllSpendingPaths(options: GetAllSpendingPathsOptions): Promise<PathSelection[]>;
@@ -2603,6 +3237,20 @@ declare class ContractManager implements IContractManager {
      * other contracts still need to pick up.
      */
     private syncContracts;
+    /**
+     * Demote every `awaiting-funds` contract in `contracts` that has been
+     * funded — the automatic half of {@link ContractWatchState}.
+     *
+     * Runs after the sync has persisted, so the funding VTXO is saved
+     * while the contract is still watched, and reads the repository
+     * rather than this sync's delta: funds that landed while the app was
+     * closed are outside every later window, and a contract asked to
+     * watch until it is funded must still stop once it is.
+     *
+     * Best-effort. A demotion that fails costs coverage that is merely
+     * no longer needed, and must not fail the sync that carried it.
+     */
+    private demoteFundedAwaitingContracts;
     /**
      * Fetch all pending (unfinalized) virtual outputs and upsert them into the
      * repository. This catches virtual outputs whose state changed outside the delta
@@ -2634,14 +3282,48 @@ declare class ContractManager implements IContractManager {
 }
 
 /**
- * Contract lifecycle state. Both states stay monitored — the watcher
- * subscribes and sweeps every registered contract regardless
- * (see {@link ContractWatcher.getWatchedContracts}), because a retired
- * receive address can still be paid. `inactive` only demotes a contract
- * out of receive-address selection; it does **not** unsubscribe it.
- * Use {@link IContractManager.deleteContract} to stop watching.
+ * Contract lifecycle state. Neither state affects coverage: the watcher
+ * subscribes and sweeps a contract according to {@link Contract.watch}
+ * alone, because a retired receive address can still be paid. `inactive`
+ * only demotes a contract out of receive-address selection; it does
+ * **not** unsubscribe it. To stop watching but keep the row, set
+ * {@link ContractWatchState} to `retained`; to drop both, use
+ * {@link IContractManager.deleteContract}.
  */
 type ContractState = "active" | "inactive";
+/**
+ * Whether a contract is covered by background monitoring — the
+ * subscription and the failsafe/indexer sweep
+ * ({@link ContractWatcher.getWatchedContracts}).
+ *
+ * Orthogonal to {@link ContractState}, which governs receive-address
+ * selection only. A contract can be the wallet's display address and
+ * watched, or terminal and retained; the two questions never answer each
+ * other.
+ *
+ * NArk calls this `ContractActivityState` (`Active` / `Inactive` /
+ * `AwaitingFundsBeforeDeactivate`). The concept is the same; the names
+ * differ because TS already spends `active`/`inactive` on
+ * {@link ContractState}, and a row reading `state: "active",
+ * activityState: "inactive"` would be unreadable.
+ */
+type ContractWatchState = 
+/** Subscribed and polled. */
+"watched"
+/**
+ * Watched until the first VTXO lands at the script, then
+ * automatically demoted to `retained` by the contract manager.
+ * For one-shot destinations — a refund address, a swap lockup —
+ * that only need coverage until they are funded.
+ */
+ | "awaiting-funds"
+/**
+ * Kept for history, restore and classification, but absent from
+ * every background channel. The row still resolves in
+ * `getContracts`, still annotates its VTXOs, and still feeds
+ * transaction history; nothing subscribes or polls it.
+ */
+ | "retained";
 /**
  * Represents a contract that can receive and manage virtual outputs.
  *
@@ -2692,6 +3374,11 @@ interface Contract {
     address: string;
     /** Current state of the contract. */
     state: ContractState;
+    /**
+     * Background-monitoring scope. Absent means `watched`.
+     * @see ContractWatchState
+     */
+    watch?: ContractWatchState;
     /** Unix timestamp in milliseconds when this contract was created. */
     createdAt: number;
     /**
@@ -2766,6 +3453,17 @@ interface PathContext {
      * fallback — against the contract's sender/receiver params.
      */
     role?: string;
+    /**
+     * Chain tip timestamp in SECONDS, when known.
+     *
+     * Timelocks mature against chain time, not the machine's clock, so any
+     * seconds-typed comparison should prefer this and fall back to
+     * {@link currentTime} only when it is absent. The two differ by more than
+     * pedantry: the server matures absolute locktimes against median-time-past,
+     * which trails wall clock, and a host whose clock drifts turns a local
+     * decision into a wrong one in whichever direction it drifted.
+     */
+    chainTime?: number;
     /** The specific virtual output being evaluated. */
     vtxo?: VirtualCoin;
 }
@@ -2837,6 +3535,50 @@ interface ContractHandler<P = Record<string, unknown>, S extends VtxoScript = Vt
      * Returns empty array if no paths are available.
      */
     getSpendablePaths(script: S, contract: Contract, context: PathContext): PathSelection[];
+    /**
+     * Whether this contract's VTXOs may be picked by *generic* wallet spending —
+     * send, settle, renewal, asset operations, offboard, `available` balance.
+     * Explicit-input APIs (`settle({ inputs })`, `sendBitcoin({ selectedVtxos })`,
+     * …) stay open regardless: naming an outpoint is the intent this gate protects.
+     *
+     * Pure, synchronous and offline — it runs inside the service worker, so no
+     * chain tip, no network, no live plugin object. Absent or `false` ⇒ NOT
+     * spendable: a type core cannot reason about must not leak by omission.
+     *
+     * No `script` parameter: deriving it costs a taproot tree per contract on a
+     * read path (#521) and no shipped handler needs it. A handler that does can
+     * call its own `createScript(contract.params)`.
+     */
+    isGenericallySpendable?(contract: Contract): boolean;
+    /**
+     * Refuse a spend this contract definitively cannot make right now, with a
+     * reason the caller can act on. Called before anything is signed or
+     * submitted, for inputs the caller named explicitly.
+     *
+     * This is the counterpart to {@link isGenericallySpendable}, not a
+     * duplicate of it. That gate keeps escrow out of GENERIC selection and
+     * deliberately leaves explicit-input APIs open, because naming an outpoint
+     * is the intent it protects. Naming one too early is still a mistake
+     * though, and without this it is a mistake the server reports — as a
+     * protocol-level rejection, after the round trip, in terms that do not name
+     * the timelock that was not yet mature.
+     *
+     * **Throw only on a definite no.** Absent, silent, or unsure all mean "no
+     * opinion" and the spend proceeds. A handler must not refuse merely because
+     * it found no path: `getSpendablePaths` legitimately returns empty for
+     * spendable contracts — `arkade`'s skips every covenant leaf, so a program
+     * spendable only through its emulator-signed leaf reports nothing — and an
+     * unreadable timelock (height-typed with no chain tip) is unknown, not
+     * immature. @see cltvMaturity, which keeps those apart.
+     *
+     * Returning a promise is allowed so a handler needing I/O is not forced to
+     * throw synchronously — callers await the result. Prefer synchronous where
+     * possible: this runs on the path between a caller's decision to spend and
+     * the spend itself.
+     *
+     * @throws Error when the contract provably cannot be spent at `context`
+     */
+    assertSpendableNow?(script: S, contract: Contract, context: PathContext): void | Promise<void>;
 }
 /**
  * What a {@link Discoverable.discoverAt} call returns — exactly the
@@ -3116,6 +3858,8 @@ declare class ContractWatcher {
     /** See {@link withCoalescedSubscription}. */
     private subscriptionBatchDepth;
     private subscriptionUpdateDeferred;
+    /** See {@link reportEventSourceUnavailable} — said once, not per attempt. */
+    private eventSourceReported;
     /**
      * Create a contract watcher with the given providers and polling settings.
      *
@@ -3127,7 +3871,8 @@ declare class ContractWatcher {
      * Add a contract to be watched.
      *
      * Once watching, every contract is subscribed and polled whatever
-     * its state.
+     * its {@link ContractState} — a `retained` one is held for reads
+     * only, and never enters a background channel.
      *
      * @see getWatchedContracts
      */
@@ -3153,15 +3898,22 @@ declare class ContractWatcher {
      */
     getAllContracts(): Contract[];
     /**
-     * Every registered contract, retired (`inactive`) ones included.
+     * Every registered contract except the `retained` ones, retired
+     * (`inactive`) receive addresses included.
      *
      * Feeds both the subscription and the indexer sweep scope, so
      * narrowing it drops a contract from every background channel at
-     * once. Nothing may be narrowed out: an Ark receive address can be
+     * once. `state` may never narrow it: an Ark receive address can be
      * paid again after the wallet has rotated past it, and a payment
      * that lands outside every background channel is invisible until
      * some foreground read happens to sweep it. Retirement therefore
      * governs receive-address selection, not coverage.
+     *
+     * {@link ContractWatchState} is the one thing that does narrow it,
+     * and only when an owner has explicitly said the script is done —
+     * a settled swap lockup, a funded one-shot destination. The row
+     * stays in {@link getAllContracts} so reads, annotation and history
+     * are unaffected.
      */
     getWatchedContracts(): Contract[];
     /**
@@ -3198,400 +3950,82 @@ declare class ContractWatcher {
      */
     private connect;
     /**
-     * Schedule a reconnection attempt.
-     */
-    private scheduleReconnect;
-    /**
-     * Start the failsafe polling interval.
-     */
-    private startFailsafePolling;
-    private pollAllContracts;
-    /**
-     * Poll specific contracts and emit events for changes.
-     */
-    private pollContracts;
-    /**
-     * Run `fn` with subscription updates coalesced into a single
-     * `subscribeForScripts` on the way out.
-     *
-     * {@link addContract} re-subscribes eagerly (the watcher may already be
-     * running), and every subscribe posts the *whole* accumulated script list —
-     * so a restore scan that discovers N contracts sends N growing POSTs,
-     * quadratic in script-slots. Inside this scope those updates are only
-     * marked dirty, flushed once on the way out (success and error path alike).
-     *
-     * A contract added inside the scope is therefore not streaming until the
-     * flush. Nothing in the watcher closes that window — the failsafe poll
-     * replays repository state and cannot see VTXOs no one has fetched yet. The
-     * one caller, `scanContracts`, is covered because `Wallet.restore` follows
-     * it with a bulk `refreshVtxos`. A new caller must provide its own
-     * equivalent catch-up, or keep the scope short enough not to need one.
-     */
-    withCoalescedSubscription<T>(fn: () => Promise<T>): Promise<T>;
-    private tryUpdateSubscription;
-    /**
-     * Update the subscription with scripts that should be watched.
-     *
-     * @see getWatchedContracts
-     */
-    private updateSubscription;
-    /**
-     * Main listening loop for subscription events.
-     */
-    private listenLoop;
-    /**
-     * Handle a subscription update.
-     *
-     * Normalization boundary: `getSubscription` is part of the public `IndexerProvider` interface,
-     * so a consumer implementation may yield legacy-shaped VTXOs. Normalizing on ingest also fixes
-     * the shape of the payloads emitted to external event consumers.
-     */
-    private handleSubscriptionUpdate;
-    /**
-     * Process virtual outputs from subscription and route each VTXO to the
-     * single contract that actually locks it via `vtxo.script`. If the script
-     * doesn't match any watched contract, skip the VTXO rather than fan it
-     * out to every matching contract — fan-out produced phantom state in
-     * non-owning contracts that then never reconciled.
-     */
-    private processSubscriptionVtxos;
-    /**
-     * Emit a virtual output event for a contract.
-     */
-    private emitVtxoEvent;
-}
-
-/**
- * Intent proof implementation for Bitcoin message signing.
- *
- * Intent proof defines a standard for signing Bitcoin messages as well as proving
- * ownership of outputs.
- *
- * This namespace provides utilities for creating and validating Intent proof.
- *
- * It is greatly inspired by BIP322.
- * @see https://github.com/bitcoin/bips/blob/master/bip-0322.mediawiki
- *
- * @example
- * ```typescript
- * // Create a Intent proof
- * const proof = Intent.create(
- *   "Hello Bitcoin!",
- *   [input],
- *   [output]
- * );
- *
- * // Sign the proof
- * const signedProof = await identity.sign(proof);
- *
- */
-declare namespace Intent {
-    type Proof = Transaction;
-    /**
-     * Creates a new Intent proof unsigned transaction.
-     *
-     * This function constructs a special transaction that can be signed to prove
-     * ownership of onchain and virtual outputs. The proof includes the message to be
-     * signed and the inputs/outputs that demonstrate ownership.
-     *
-     * @param message - The Intent message to be signed, either raw string of Message object
-     * @param ins - Array of transaction inputs to prove ownership of
-     * @param outputs - Optional array of transaction outputs
-     * @returns An unsigned Intent proof transaction
-     */
-    function create(message: string | Message, ins: (TransactionInput | ExtendedCoin)[], outputs?: TransactionOutput[]): Proof;
-    /**
-     * Compute the fee paid by an intent proof transaction.
-     *
-     * @param proof - Intent proof transaction
-     * @returns The fee in satoshis
-     */
-    function fee(proof: Proof): number;
-    type RegisterMessage = {
-        type: "register";
-        onchain_output_indexes: number[];
-        valid_at: number;
-        expire_at: number;
-        cosigners_public_keys: string[];
-    };
-    type DeleteMessage = {
-        type: "delete";
-        expire_at: number;
-    };
-    type GetPendingTxMessage = {
-        type: "get-pending-tx";
-        expire_at: number;
-    };
-    type Message = RegisterMessage | DeleteMessage | GetPendingTxMessage;
-    /**
-     * Serialize an intent message to the canonical JSON string used for signing.
-     *
-     * @param message - Intent message payload
-     * @returns Canonical string form of the message
-     */
-    function encodeMessage(message: Message): string;
-}
-
-/**
- * Delegate identity and fee information returned by `getDelegateInfo`.
- */
-interface DelegateInfo {
-    /** Delegate public key. */
-    pubkey: string;
-    /** Delegate fee amount or expression returned by the delegate. */
-    fee: string;
-    /** Address for delegate fee collection. Sourced from `delegatorAddress` in Fulmine response, for now. */
-    delegateAddress: string;
-    /** @deprecated alias for @see DelegateInfo.delegateAddress */
-    delegatorAddress?: string;
-}
-/**
- * Optional delegate behavior flags.
- */
-interface DelegateOptions {
-    /**
-     * Instruct the delegate not to replace an existing delegation
-     * (meaning a signed register intent and its forfeit transactions)
-     * that already includes at least one virtual output from this request.
-     *
-     * @defaultValue `false`
-     */
-    rejectReplace?: boolean;
-}
-/**
- * Provider interface for remote delegation service.
- */
-interface DelegateProvider {
-    /**
-     * Request delegation for a signed register intent and its forfeit transactions.
-     *
-     * @param intent - Signed register intent to delegate
-     * @param forfeitTxs - Forfeit transactions associated with the delegation request
-     * @param options - Optional delegate behavior flags
-     */
-    delegate(intent: SignedIntent<Intent.RegisterMessage>, forfeitTxs: string[], options?: DelegateOptions): Promise<void>;
-    /**
-     * Fetch delegate metadata such as pubkey, fee, and delegate address.
+     * Handle "this environment has no `EventSource`": say so once, loudly and
+     * actionably, and answer whether the caller should skip reconnecting.
      *
-     * @returns Delegate identity and fee information
+     * Reconnecting is pointless here — a missing global is not a dropped
+     * connection, and the default backoff (unlimited attempts, capped at 5s)
+     * would otherwise retry it forever, logging each failure and firing a
+     * `connection_reset` every few seconds for the life of the wallet. Not even
+     * one goes out: subscribers read that event as "the stream dropped, resync
+     * and expect it back", and here it never opened and never will.
+     * Failsafe polling keeps running, so the watcher stays correct and merely
+     * slower; what it loses is push latency.
      */
-    getDelegateInfo(): Promise<DelegateInfo>;
-}
-/** @deprecated alias for @see DelegateProvider */
-type DelegatorProvider = DelegateProvider;
-/**
- * REST-based delegate provider implementation.
- * @example
- * ```typescript
- * const provider = new RestDelegateProvider('https://delegate.example.com');
- * const info = await provider.getDelegateInfo();
- * await provider.delegate(intent, forfeitTxs);
- * ```
- */
-declare class RestDelegateProvider implements DelegateProvider {
-    url: string;
+    private reportEventSourceUnavailable;
     /**
-     * Create a REST delegate provider targeting the given base URL.
-     *
-     * @param url - Base URL of the remote delegation service.
+     * Schedule a reconnection attempt.
      */
-    constructor(url: string);
+    private scheduleReconnect;
     /**
-     * Submit a delegation request to the remote delegation service.
-     *
-     * @param intent - Signed register intent to delegate
-     * @param forfeitTxs - Forfeit transactions associated with the delegation request
-     * @param options - Optional delegate behavior flags
-     * @throws Error if the remote service rejects the request
+     * Start the failsafe polling interval.
      */
-    delegate(intent: SignedIntent<Intent.RegisterMessage>, forfeitTxs: string[], options?: DelegateOptions): Promise<void>;
+    private startFailsafePolling;
+    private pollAllContracts;
     /**
-     * Fetch delegate metadata exposed by the remote delegation service.
-     *
-     * @returns Delegate identity and fee information
-     * @throws Error if the remote service returns invalid data
+     * Poll specific contracts and emit events for changes.
      */
-    getDelegateInfo(): Promise<DelegateInfo>;
-}
-/** @deprecated alias for @see RestDelegateProvider */
-declare const RestDelegatorProvider: typeof RestDelegateProvider;
-type RestDelegatorProvider = RestDelegateProvider;
-
-interface IDelegateManager {
+    private pollContracts;
     /**
-     * Delegate virtual outputs to the remote delegation service.
+     * Run `fn` with subscription updates coalesced into a single
+     * `subscribeForScripts` on the way out.
      *
-     * Vtxos that are not locked to a delegate-type contract (no tap leaf
-     * matches the delegate's pubkey) are filtered out silently, since they
-     * cannot be co-signed by the delegate.
+     * {@link addContract} re-subscribes eagerly (the watcher may already be
+     * running), and every subscribe posts the *whole* accumulated script list —
+     * so a restore scan that discovers N contracts sends N growing POSTs,
+     * quadratic in script-slots. Inside this scope those updates are only
+     * marked dirty, flushed once on the way out (success and error path alike).
      *
-     * @param vtxos - Virtual outputs to delegate
-     * @param destination - Arkade address that should receive renewed funds
-     * @param delegateAt - Optional timestamp to force a specific delegation time
-     * @returns Successfully delegated and failed outpoint groups
+     * A contract added inside the scope is therefore not streaming until the
+     * flush. Nothing in the watcher closes that window — the failsafe poll
+     * replays repository state and cannot see VTXOs no one has fetched yet. The
+     * one caller, `scanContracts`, is covered because `Wallet.restore` follows
+     * it with a bulk `refreshVtxos`. A new caller must provide its own
+     * equivalent catch-up, or keep the scope short enough not to need one.
      */
-    delegate(vtxos: ContractVtxo[], destination: string, delegateAt?: Date): Promise<{
-        delegated: Outpoint[];
-        failed: {
-            outpoints: Outpoint[];
-            error: unknown;
-        }[];
-    }>;
-    /** Fetch delegate metadata such as pubkey, fee, and delegate address. */
-    getDelegateInfo(): Promise<DelegateInfo>;
-}
-/** @deprecated alias for @see IDelegateManager */
-type IDelegatorManager = IDelegateManager;
-declare class DelegateManagerImpl implements IDelegateManager {
-    readonly delegateProvider: DelegateProvider;
-    readonly arkInfoProvider: Pick<ArkProvider, "getInfo">;
-    readonly identity: Identity;
-    /** Create a delegate manager from the configured provider, Arkade info source, and wallet identity. */
-    constructor(delegateProvider: DelegateProvider, arkInfoProvider: Pick<ArkProvider, "getInfo">, identity: Identity);
-    getDelegateInfo(): Promise<DelegateInfo>;
-    delegate(vtxos: ContractVtxo[], destination: string, delegateAt?: Date): Promise<{
-        delegated: Outpoint[];
-        failed: {
-            outpoints: Outpoint[];
-            error: unknown;
-        }[];
-    }>;
-}
-/** @deprecated alias for @see DelegateManagerImpl */
-declare const DelegatorManagerImpl: typeof DelegateManagerImpl;
-type DelegatorManagerImpl = DelegateManagerImpl;
-
-/** One transaction's participation in one logical action. */
-interface GroupMembership {
+    withCoalescedSubscription<T>(fn: () => Promise<T>): Promise<T>;
+    private tryUpdateSubscription;
     /**
-     * Stable id of the action; txs sharing it group together. Third-party
-     * resolvers should namespace it (`"vendor:thing"`) to avoid colliding with
-     * other resolvers' groups. SDK built-ins use namespaced ids such as `boarding:`.
-     * A membership with an empty groupId is dropped.
+     * Update the subscription with scripts that should be watched.
+     *
+     * @see getWatchedContracts
      */
-    groupId: string;
-    /** Human label for the action, e.g. "Dice game". */
-    label?: string;
-    /** App category for icon/filtering, e.g. "game". */
-    kind?: string;
+    private updateSubscription;
     /**
-     * Free-form row data. Same-group metadata is shallow-merged with
-     * earlier-resolver keys winning.
+     * Main listening loop for subscription events.
      */
-    metadata?: Record<string, unknown>;
+    private listenLoop;
     /**
-     * This tx's unsigned sat contribution to this group. Defaults to the tx's
-     * full amount; the builder applies direction. Use it to split a batched tx
-     * across groups. Same-key receive rows paired with a sent row are treated
-     * as change and excluded from `Activity.amount`. A membership with a
-     * non-finite amount (NaN/Infinity) is dropped.
+     * Handle a subscription update.
+     *
+     * Normalization boundary: `getSubscription` is part of the public `IndexerProvider` interface,
+     * so a consumer implementation may yield legacy-shaped VTXOs. Normalizing on ingest also fixes
+     * the shape of the payloads emitted to external event consumers.
      */
-    amount?: number;
-}
-/** A pluggable resolver keyed by `id`. */
-interface ActivityResolver {
+    private handleSubscriptionUpdate;
     /**
-     * Registry key — override or remove by it. Namespace it (`"vendor:games"`)
-     * so independent libraries don't clobber each other; `use()` overwrites
-     * silently on a duplicate id.
+     * Process virtual outputs from subscription and route each VTXO to the
+     * single contract that actually locks it via `vtxo.script`. If the script
+     * doesn't match any watched contract, skip the VTXO rather than fan it
+     * out to every matching contract — fan-out produced phantom state in
+     * non-owning contracts that then never reconciled.
      */
-    id: string;
+    private processSubscriptionVtxos;
     /**
-     * Load correlation data before `resolve` runs. If it rejects, this resolver
-     * contributes no memberships.
+     * Emit a virtual output event for a contract.
      */
-    prepare?(): Promise<void>;
-    /** Pure and synchronous. The groups this tx belongs to, or undefined to leave it plain. */
-    resolve(tx: ArkTransaction): GroupMembership[] | undefined;
-}
-/** The non-id, non-amount part of a {@link GroupMembership}. */
-interface ActivityIntent {
-    /** Human label for the action, e.g. "Dice game". */
-    label?: string;
-    /** App category for icon/filtering, e.g. "game". */
-    kind?: string;
-    /** Free-form row data, shallow-merged across the group's resolvers (first-writer-wins). */
-    metadata?: Record<string, unknown>;
-}
-/** One logical activity. */
-interface Activity {
-    /** The groupId, or the natural tx key for untagged rows. */
-    id: string;
-    /** Merged intent for the group, if any resolver tagged it. */
-    intent?: ActivityIntent;
-    /** Member txs, oldest-first. */
-    txs: ArkTransaction[];
-    /** Signed net sats: positive received, negative sent; same-key change rows are excluded. */
-    amount: number;
-    /** Earliest member createdAt (ms since epoch). */
-    createdAt: number;
-    /** True once every member tx is settled. */
-    settled: boolean;
-}
-/** Resolver registry keyed by id. */
-declare class ActivityRegistry {
-    private readonly resolvers;
-    /** Add a resolver, or override an existing one with the same id (kept in place). */
-    use(resolver: ActivityResolver): void;
-    /** Remove a resolver (built-in or custom) by id. */
-    remove(id: string): void;
-    /** The registered resolver ids, in registration order. */
-    list(): string[];
-    /** All registered resolvers, in registration (priority) order. */
-    all(): ActivityResolver[];
-}
-/** Built-in resolver: labels on-chain boarding (deposit) transactions. */
-declare function boardingResolver(): ActivityResolver;
-/** Built-in resolver: labels collaborative exits (VTXOs forfeited to chain in a batch). */
-declare function collabExitResolver(): ActivityResolver;
-/**
- * Built-in resolver: labels the genesis transaction of a minted asset — "Asset
- * mint" on the issuer's sent tx, "Asset receive" when the fresh supply arrives
- * in the genesis tx itself. An asset id encodes its genesis txid; reissues and
- * transfers carry the asset under a different `arkTxid`, so they are left plain.
- *
- * `metadata.amount` is the decimal string of the asset's `bigint` amount, kept
- * as a string so large supplies survive JSON round-trips without truncation.
- * Recover the value with `BigInt(metadata.amount as string)` — using it
- * directly in arithmetic coerces (`"10" + 1` is `"101"`, not `11`) and loses
- * precision past `Number.MAX_SAFE_INTEGER`.
- */
-declare function assetMintResolver(): ActivityResolver;
-/**
- * A registry pre-populated with the SDK's built-in resolvers: `boarding`,
- * `collab-exit`, and `asset-mint`.
- */
-declare function createDefaultActivityRegistry(): ActivityRegistry;
-
-/**
- * A source of unilateral-exit chain data for a set of VTXOs. Sources are tried
- * in order by the resolver; a source returns `null` (chain) or omits keys (psbts)
- * for data it cannot supply — a "miss" — and the resolver falls through.
- */
-interface ExitDataSource {
-    readonly name: string;
-    /** Full ancestry chain for a vtxo (all pages merged), or null on a miss. */
-    getVtxoChain(vtxo: Outpoint): Promise<ChainTx[] | null>;
-    /** Base64 PSBTs this source has, keyed by (unsigned) txid. Absent key = miss. */
-    getVirtualTxs(txids: string[]): Promise<Map<string, string>>;
-}
-/** Reads exit chain data through an ordered chain of sources. */
-interface ExitChainResolver {
-    getVtxoChain(vtxo: Outpoint): Promise<ChainTx[]>;
-    getVirtualTxs(txids: string[]): Promise<string[]>;
+    private emitVtxoEvent;
 }
-/**
- * Assemble the standard exit-data resolver: local repo (if configured) → any
- * extra sources (e.g. a future provider) → indexer. Read-through persists to the
- * repository. With no repository this is exactly the indexer path (a no-op seam).
- */
-declare function createExitChainResolver(params: {
-    indexer: IndexerProvider;
-    repository?: VirtualTxRepository;
-    extraSources?: ExitDataSource[];
-}): ExitChainResolver;
-
-type ExitCaptureMode = "lite" | "full";
 
 /**
  * Wallet receive-address strategy.
@@ -3675,8 +4109,10 @@ interface BaseWalletConfig {
     /**
      * Minimum accepted checkpoint exit delay decoded from `ArkInfo.checkpointTapscript`,
      * as wall-clock seconds. Defaults per network — see
-     * `defaultCheckpointExitDelayPolicy`. Lowering it below the default relaxes a
-     * fund-safety bound; intended for local testing.
+     * `defaultCheckpointExitDelayPolicy`, which already carries the value the
+     * hosted signet and mutinynet Arkade Services advertise, so neither needs
+     * this set. Lowering it below the default relaxes a fund-safety bound;
+     * intended for local testing.
      */
     minCheckpointExitDelaySeconds?: bigint;
     /**
@@ -3900,8 +4336,15 @@ interface WalletBalance {
     pendingRecovery: number;
     /** Total balance across offchain, recoverable, pending-recovery, and boarding funds. */
     total: number;
-    /** Asset balance entries (`assetId` & `amount`) */
+    /** Asset balance entries (`assetId` & `amount`) the wallet owns. */
     assets: Asset[];
+    /**
+     * The subset of {@link assets} generic spending will accept, i.e. the asset
+     * analogue of {@link available}. Assets have no owned/spendable split of
+     * their own, so `assets - availableAssets` is what is held but not
+     * selectable — escrowed, intent-locked or awaiting recovery.
+     */
+    availableAssets: Asset[];
 }
 /**
  * Parameters accepted by `OnchainWallet.send`.
@@ -3924,7 +4367,13 @@ interface SendBitcoinParams {
      * @deprecated Does not appear to have ever been used.
      */
     memo?: string;
-    /** Optional explicit virtual output selection used by `Wallet.sendBitcoin`. */
+    /**
+     * Optional explicit virtual output selection used by `Wallet.sendBitcoin`.
+     * Ungated, like `settle({ inputs })`: whatever is named here is spent, even
+     * if generic selection would skip it.
+     *
+     * @see IReadonlyWallet.getSpendableVtxos
+     */
     selectedVtxos?: ExtendedVirtualCoin[];
 }
 /**
@@ -4453,6 +4902,20 @@ interface IReadonlyWallet {
      * @see GetVtxosFilter
      */
     getVtxos(filter?: GetVtxosFilter): Promise<NormalizedExtendedVirtualCoin[]>;
+    /**
+     * The subset of {@link getVtxos} that generic spending may select: the same
+     * filter, minus contracts the generic-spending gate closes, minus funds
+     * awaiting recovery under a past-cutoff signer, minus outpoints locked by an
+     * in-flight intent. Every implicit coin selection in the SDK reads this;
+     * `getVtxos` stays the raw reporting/recovery read.
+     *
+     * Both exclusion sets are derived from one contract snapshot, so they cannot
+     * disagree about which VTXOs exist.
+     *
+     * @param filter - Same flags, same defaults, as {@link getVtxos}
+     * @see GetVtxosFilter
+     */
+    getSpendableVtxos(filter?: GetVtxosFilter): Promise<NormalizedExtendedVirtualCoin[]>;
     /** @returns Onchain boarding inputs tracked by the wallet. */
     getBoardingUtxos(): Promise<ExtendedCoin[]>;
     /** @returns Wallet transaction history derived from boarding and Arkade activity. */
@@ -4477,6 +4940,94 @@ interface IReadonlyWallet {
     clear(): Promise<void>;
 }
 
+/**
+ * Where the SDK gets its `EventSource`.
+ *
+ * Every server-sent-events stream this SDK opens — settlement events, the tx
+ * feed, the indexer script subscription — needs one, and until now each site
+ * reached for the global. That works in browsers and, via
+ * {@link ExpoArkProvider}/{@link ExpoIndexerProvider}, in React Native. It does
+ * NOT work in Node, which exposes `EventSource` only behind
+ * `--experimental-eventsource` (24.x) — so a CLI, a server-side wallet or a
+ * background worker got a `ReferenceError` out of the stream and everything
+ * event-driven degraded to whatever polling happened to be running.
+ *
+ * Resolution order, per call: an explicit per-provider factory, then whatever
+ * {@link configureEventSource} was given, then the global. When none answers,
+ * {@link resolveEventSource} throws {@link EventSourceUnavailableError} rather
+ * than a bare `ReferenceError`, so callers can tell "this environment has no
+ * SSE" from "the connection dropped" — a distinction that matters, because the
+ * first is not worth reconnecting for and the second is.
+ */
+/**
+ * The slice of `EventSource` this SDK actually uses.
+ *
+ * Structural rather than the DOM type on purpose: Node's `eventsource` package
+ * and the React Native polyfills are not DOM `EventSource`s, and demanding one
+ * made every consumer launder a perfectly capable object through
+ * `as unknown as EventSource` — a cast that hides real mismatches as readily as
+ * it waves through this one.
+ */
+interface EventSourceLike {
+    addEventListener(type: "message" | "error", listener: (event: MessageEvent) => void): void;
+    removeEventListener(type: "message" | "error", listener: (event: MessageEvent) => void): void;
+    close(): void;
+}
+/** Opens an SSE connection to `url`. `new EventSource(url)`, as a value. */
+type EventSourceFactory = (url: string) => EventSourceLike;
+/** Options shared by every provider that opens an SSE stream. */
+interface EventSourceCapable {
+    /**
+     * Where this provider gets its `EventSource`, overriding
+     * {@link configureEventSource} and the global. Use it when one process
+     * needs different transports per connection; otherwise configure once.
+     */
+    eventSource?: EventSourceFactory;
+}
+/**
+ * No `EventSource` could be resolved, so no SSE stream can be opened.
+ *
+ * A property of the environment, not of the connection: retrying cannot fix it,
+ * which is why {@link ContractWatcher} reports it once and stops reconnecting
+ * instead of looping on it.
+ */
+declare class EventSourceUnavailableError extends Error {
+    constructor();
+}
+/**
+ * Type guard for {@link EventSourceUnavailableError}.
+ *
+ * Falls back to the `name` because a custom error crossing the service-worker
+ * `postMessage` boundary arrives as a plain `Error` — the same reason
+ * `ProviderUnavailableError` keeps its state in the message.
+ */
+declare function isEventSourceUnavailableError(error: unknown): error is Error;
+/**
+ * Set the `EventSource` every provider uses by default. Call once at startup,
+ * before opening a wallet; pass `undefined` to go back to the global.
+ *
+ * This exists because the provider-level option cannot reach providers the SDK
+ * builds for you — `Wallet.create({ arkServerUrl })` constructs both itself.
+ *
+ * @example
+ * ```typescript
+ * import { EventSource } from "eventsource";
+ * configureEventSource((url) => new EventSource(url));
+ * ```
+ */
+declare function configureEventSource(factory?: EventSourceFactory): void;
+/** What {@link configureEventSource} last set, if anything. */
+declare function getConfiguredEventSource(): EventSourceFactory | undefined;
+/**
+ * Resolve the factory to open a stream with, or throw
+ * {@link EventSourceUnavailableError}.
+ *
+ * The global is read on every call rather than captured at module load: a test
+ * (or a polyfill) that assigns `globalThis.EventSource` after import must still
+ * be seen.
+ */
+declare function resolveEventSource(override?: EventSourceFactory): EventSourceFactory;
+
 type PaginationOptions = {
     pageIndex?: number;
     pageSize?: number;
@@ -4744,7 +5295,9 @@ interface IndexerProvider {
  */
 declare class RestIndexerProvider implements IndexerProvider {
     serverUrl: string;
-    constructor(serverUrl?: string);
+    /** Overrides {@link configureEventSource} for this provider's subscription. */
+    protected readonly eventSource?: EventSourceFactory;
+    constructor(serverUrl?: string, options?: EventSourceCapable);
     getVtxoTree(batchOutpoint: Outpoint, opts?: PaginationOptions): Promise<{
         vtxoTree: Tx[];
         page?: PageResponse;
@@ -5040,7 +5593,9 @@ interface ArkProvider {
  */
 declare class RestArkProvider implements ArkProvider {
     serverUrl: string;
-    constructor(serverUrl?: string);
+    /** Overrides {@link configureEventSource} for this provider's streams. */
+    protected readonly eventSource?: EventSourceFactory;
+    constructor(serverUrl?: string, options?: EventSourceCapable);
     /**
      * Last server-info digest seen (from {@link getInfo}). Sent as `X-Digest`
      * on outgoing requests so arkd can reject a client whose cached info is
@@ -5234,4 +5789,4 @@ declare namespace ProtoTypes {
     export {  };
 }
 
-export { type TreeSignatureEvent as $, type ArkTransaction as A, type VirtualTxRepository as B, type ContractRepository as C, type VirtualTx as D, type ExtendedCoin as E, type VtxoBranch as F, type GetVtxosFilter as G, ChainedTxType as H, type IWallet as I, type Network as J, CSVMultisigTapscript as K, type SignerSet as L, type BatchStartedEvent as M, type NormalizedExtendedVirtualCoin as N, type Outpoint as O, type TreeSigningStartedEvent as P, TxTree as Q, type Recipient as R, type SendBitcoinParams as S, type TxNotification as T, type TreeNoncesEvent as U, VtxoScript as V, type WalletRepository as W, type BatchFinalizationEvent as X, type BatchFinalizedEvent as Y, type BatchFailedEvent as Z, type TreeTxEvent as _, type Identity as a, type BatchSignableIdentity as a$, type DescriptorProvider as a0, type IReadonlyWallet as a1, type ReadonlyIdentity as a2, type OnchainProvider as a3, type DelegateProvider as a4, type ReadonlyWalletConfig as a5, type ExitCaptureMode as a6, type ExitDataSource as a7, type IReadonlyAssetManager as a8, type ContractSyncState as a9, type IssuanceParams as aA, type ReissuanceParams as aB, type BurnParams as aC, type RenewVtxosOptions as aD, type ContractWithVtxos as aE, type PathSelection as aF, type ContractEvent as aG, type AssetDetails as aH, type IssuanceResult as aI, type DelegateInfo as aJ, type MigrationGlobalSkipReason as aK, type MigrationLegSkipReason as aL, type SignerStatus as aM, type StorageConfig as aN, type IVtxoManager as aO, type ExplorerTransaction as aP, type EncodedVtxoScript as aQ, type Status as aR, type ChainTx as aS, type PathContext as aT, type ActivityIntent as aU, type ActivityResolver as aV, type ArkIntentState as aW, type ArkTapscript as aX, type AssetMetadata as aY, type BaseWalletConfig as aZ, type BatchInfo as a_, type NetworkName as aa, type ArkInfo as ab, ArkAddress as ac, type Coin as ad, ContractManager as ae, type ContractManagerConfig as af, type SettlementConfig as ag, VtxoManager as ah, type SignerSession as ai, type SignedIntent as aj, Intent as ak, type TimeHeight as al, type DescriptorSigningRequest as am, Transaction as an, type IntentFeeConfig as ao, type OffchainInput as ap, FeeAmount as aq, type OnchainInput as ar, type FeeOutput as as, type ContractWatcherConfig as at, type Asset as au, type FeeInfo as av, type CreateContractParams as aw, type GetContractsFilter as ax, type GetSpendablePathsOptions as ay, type GetAllSpendingPathsOptions as az, type WalletConfig as b, type VirtualStatus as b$, CLTVMultisigTapscript as b0, type CandidateDeps as b1, ChainTxType as b2, type CommitmentTx as b3, ConditionCSVMultisigTapscript as b4, ConditionMultisigTapscript as b5, type ContractBalance as b6, type ContractEventCallback as b7, type ContractHandler as b8, type ContractState as b9, type Nonces as bA, type Output as bB, type PageResponse as bC, type PaginationOptions as bD, PartialSig as bE, type ProviderClass as bF, RestDelegateProvider as bG, RestDelegatorProvider as bH, type ScanContractsOptions as bI, type ScanResult as bJ, type ScheduledSession as bK, SettlementEventType as bL, type SignRequest as bM, type SignerClassification as bN, type SubscriptionEvent as bO, type SubscriptionHeartbeat as bP, type TapLeaves as bQ, TapTreeCoder as bR, TapscriptType as bS, type TreeNonces as bT, type TreePartialSigs as bU, type Tx as bV, type TxHistoryRecord as bW, type TxKey as bX, type TxTag as bY, type TxTreeNode as bZ, TxType as b_, type ContractVtxo as ba, ContractWatcher as bb, DelegateManagerImpl as bc, type DelegateOptions as bd, DelegatorManagerImpl as be, type DelegatorProvider as bf, type DeprecatedSignerMigrationReport as bg, type DeprecatedSignerReport as bh, DigestMismatchError as bi, type Discoverable as bj, type DiscoveredContract as bk, type DiscoveryDeps as bl, ESPLORA_URL as bm, EsploraProvider as bn, type ExitChainResolver as bo, type ExtendedContractVtxo as bp, type GroupMembership as bq, type HandlerError as br, type IDelegatorManager as bs, INTENT_TERMINAL_STATES as bt, IndexerTxType as bu, type KnownMetadata as bv, type MigrateDeprecatedSignerOptions as bw, type MigrationLegReport as bx, type MigrationVtxoRef as by, MultisigTapscript as bz, type WalletBalance as c, type Vtxo as c0, type VtxoChain as c1, type VtxoType as c2, type WalletMode as c3, assetMintResolver as c4, boardingResolver as c5, canRecoverOnchain as c6, canSpendOffchain as c7, classifyAgainstSignerSet as c8, classifyContractSigner as c9, collabExitResolver as ca, createDefaultActivityRegistry as cb, createExitChainResolver as cc, decodeTapscript as cd, getNetwork as ce, getSequence as cf, hasCandidates as cg, hasTerminalSpend as ch, isBatchSignable as ci, isCooperativelyMigratable as cj, isDiscoverable as ck, isExpired as cl, isPastExpiry as cm, isRecoverable as cn, isSpendable as co, isSubdust as cp, isTerminalIntentState as cq, isVirtualCoin as cr, isVtxoExpiringSoon as cs, networks as ct, scriptFromTapLeafScript as cu, signerSetFromInfo as cv, toXOnlySignerHex as cw, type TapscriptDeriving as cx, ActivityRegistry as d, type Activity as e, type IContractManager as f, type IDelegateManager as g, type SettleParams as h, type SettlementEvent as i, type IAssetManager as j, RestArkProvider as k, RestIndexerProvider as l, type SubscriptionResponse as m, type ArkProvider as n, type IndexerProvider as o, type RelativeTimelock as p, type TapLeafScript as q, type VirtualCoin as r, type Contract as s, type ExtendedVirtualCoin as t, type VtxoRepositoryKey as u, type WalletState as v, type ContractFilter as w, type IntentRepository as x, type ArkIntent as y, type IntentFilter as z };
+export { type DescriptorProvider as $, type ArkTransaction as A, type VirtualTxRepository as B, type ContractRepository as C, type VirtualTx as D, type ExtendedCoin as E, type VtxoBranch as F, type GetVtxosFilter as G, ChainedTxType as H, type IWallet as I, type Network as J, CSVMultisigTapscript as K, type BatchStartedEvent as L, type TreeSigningStartedEvent as M, type NormalizedExtendedVirtualCoin as N, type Outpoint as O, TxTree as P, type TreeNoncesEvent as Q, type Recipient as R, type SendBitcoinParams as S, type TxNotification as T, type BatchFinalizationEvent as U, VtxoScript as V, type WalletRepository as W, type BatchFinalizedEvent as X, type BatchFailedEvent as Y, type TreeTxEvent as Z, type TreeSignatureEvent as _, type Identity as a, type BaseWalletConfig as a$, type IReadonlyWallet as a0, type ReadonlyIdentity as a1, type OnchainProvider as a2, type DelegateProvider as a3, type ReadonlyWalletConfig as a4, type ExitCaptureMode as a5, type ExitDataSource as a6, type IReadonlyAssetManager as a7, type ContractSyncState as a8, type RecipientAddressContext as a9, type GetSpendablePathsOptions as aA, type GetAllSpendingPathsOptions as aB, type IssuanceParams as aC, type ReissuanceParams as aD, type BurnParams as aE, type RenewVtxosOptions as aF, type PathSelection as aG, type ContractEvent as aH, type AssetDetails as aI, type IssuanceResult as aJ, type DelegateInfo as aK, type MigrationGlobalSkipReason as aL, type MigrationLegSkipReason as aM, type SignerStatus as aN, type StorageConfig as aO, type IVtxoManager as aP, type ExplorerTransaction as aQ, type EncodedVtxoScript as aR, type Status as aS, type ChainTx as aT, type PathContext as aU, type ActivityIntent as aV, type ActivityResolver as aW, type ArkIntentState as aX, type ArkTapscript as aY, type AssetMetadata as aZ, BITCOIN_EMULATOR_PUBKEY as a_, type NetworkName as aa, type ArkInfo as ab, ArkAddress as ac, type ContractWithVtxos as ad, selectPendingRecoveryOutpoints as ae, type Coin as af, ContractManager as ag, type ContractManagerConfig as ah, type SettlementConfig as ai, VtxoManager as aj, type SignerSession as ak, type SignedIntent as al, Intent as am, type TimeHeight as an, type DescriptorSigningRequest as ao, Transaction as ap, type IntentFeeConfig as aq, type OffchainInput as ar, FeeAmount as as, type OnchainInput as at, type FeeOutput as au, type ContractWatcherConfig as av, type Asset as aw, type FeeInfo as ax, type CreateContractParams as ay, type GetContractsFilter as az, type WalletConfig as b, TapscriptType as b$, type BatchInfo as b0, type BatchSignableIdentity as b1, CLTVMultisigTapscript as b2, type CandidateDeps as b3, ChainTxType as b4, type CommitmentTx as b5, ConditionCSVMultisigTapscript as b6, ConditionMultisigTapscript as b7, type ContractBalance as b8, type ContractEventCallback as b9, IndexerTxType as bA, type KnownMetadata as bB, MUTINYNET_EMULATOR_PUBKEY as bC, type MigrateDeprecatedSignerOptions as bD, type MigrationLegReport as bE, type MigrationVtxoRef as bF, MultisigTapscript as bG, type Nonces as bH, type Output as bI, type PageResponse as bJ, type PaginationOptions as bK, PartialSig as bL, type ProviderClass as bM, REGTEST_EMULATOR_PUBKEY as bN, RestDelegateProvider as bO, RestDelegatorProvider as bP, type ScanContractsOptions as bQ, type ScanResult as bR, type ScheduledSession as bS, SettlementEventType as bT, type SignRequest as bU, type SignerClassification as bV, type SignerSet as bW, type SubscriptionEvent as bX, type SubscriptionHeartbeat as bY, type TapLeaves as bZ, TapTreeCoder as b_, type ContractHandler as ba, type ContractState as bb, type ContractVtxo as bc, ContractWatcher as bd, DelegateManagerImpl as be, type DelegateOptions as bf, DelegatorManagerImpl as bg, type DelegatorProvider as bh, type DeprecatedSignerMigrationReport as bi, type DeprecatedSignerReport as bj, DigestMismatchError as bk, type Discoverable as bl, type DiscoveredContract as bm, type DiscoveryDeps as bn, ESPLORA_URL as bo, EsploraProvider as bp, type EventSourceCapable as bq, type EventSourceFactory as br, type EventSourceLike as bs, EventSourceUnavailableError as bt, type ExitChainResolver as bu, type ExtendedContractVtxo as bv, type GroupMembership as bw, type HandlerError as bx, type IDelegatorManager as by, INTENT_TERMINAL_STATES as bz, type WalletBalance as c, type TreeNonces as c0, type TreePartialSigs as c1, type Tx as c2, type TxHistoryRecord as c3, type TxKey as c4, type TxTag as c5, type TxTreeNode as c6, TxType as c7, type VirtualStatus as c8, type Vtxo as c9, isPastExpiry as cA, isRecoverable as cB, isSpendable as cC, isSubdust as cD, isTerminalIntentState as cE, isVirtualCoin as cF, isVtxoExpiringSoon as cG, networks as cH, resolveEmulatorPubkey as cI, resolveEventSource as cJ, scriptFromTapLeafScript as cK, signerSetFromInfo as cL, toXOnlySignerHex as cM, type TapscriptDeriving as cN, type VtxoChain as ca, type VtxoType as cb, type WalletMode as cc, assetMintResolver as cd, boardingResolver as ce, canRecoverOnchain as cf, canSpendOffchain as cg, classifyAgainstSignerSet as ch, classifyContractSigner as ci, collabExitResolver as cj, configureEventSource as ck, createDefaultActivityRegistry as cl, createExitChainResolver as cm, decodeTapscript as cn, defaultEmulatorPubkey as co, getConfiguredEventSource as cp, getNetwork as cq, getRandomId as cr, getSequence as cs, hasCandidates as ct, hasTerminalSpend as cu, isBatchSignable as cv, isCooperativelyMigratable as cw, isDiscoverable as cx, isEventSourceUnavailableError as cy, isExpired as cz, ActivityRegistry as d, type Activity as e, type IContractManager as f, type IDelegateManager as g, type SettleParams as h, type SettlementEvent as i, type IAssetManager as j, RestArkProvider as k, RestIndexerProvider as l, type SubscriptionResponse as m, type ArkProvider as n, type IndexerProvider as o, type RelativeTimelock as p, type TapLeafScript as q, type VirtualCoin as r, type Contract as s, type ExtendedVirtualCoin as t, type VtxoRepositoryKey as u, type WalletState as v, type ContractFilter as w, type IntentRepository as x, type ArkIntent as y, type IntentFilter as z };