@arkade-os/sdk 0.5.0-rc.9 → 0.5.0

package/dist/wallet-DGLXuwXT.d.ts

@@ -0,0 +1,1874 @@
+import { W as WalletRepository, P as PageRequest, O as Outpoint, F as PageResult, D as ExtendedVirtualCoin, H as ScriptVtxoCursor, J as ScriptVtxoPageOptions, K as StoredVtxo, L as VtxoRepositoryKey, E as ExtendedCoin, M as TransactionHistoryPageFilter, Q as TransactionHistoryPageCursor, h as ArkTransaction, U as WalletState, a3 as DescriptorProvider, a4 as DescriptorSigningRequest, a5 as Transaction, l as GetNewAddressesOptions, m as NewAddress, a as Identity, x as RelativeTimelock, a6 as Network, a7 as BatchStartedEvent, a8 as TreeSigningStartedEvent, a9 as TxTree, aa as TreeNoncesEvent, ab as BatchFinalizationEvent, ac as BatchFinalizedEvent, ad as BatchFailedEvent, ae as TreeTxEvent, af as TreeSignatureEvent, o as SettlementEvent, b as WalletConfig, C as ContractRepository, k as IContractManager, ag as IReadonlyWallet, ah as ReadonlyIdentity, ai as OnchainProvider, v as ArkProvider, w as IndexerProvider, aj as DelegateProvider, ak as ReadonlyWalletConfig, Y as IntentRepository, $ as VirtualTxRepository, al as ExitCaptureMode, am as ExitDataSource, i as ActivityRegistry, an as IReadonlyAssetManager, ao as ContractSyncState, ap as RecipientArkadeAddressContext, G as GetArkadeInfoOptions, A as ArkadeInfo, c as ArkadeReader, aq as NetworkName, ar as ArkAddress, e as WalletBalance, f as GetVtxosFilter, N as NormalizedExtendedVirtualCoin, g as GetSpendableVtxosFilter, as as ContractWithVtxos, at as selectPendingRecoveryOutpoints, j as Activity, au as Coin, av as ContractManager, aw as ContractManagerConfig, I as IWallet, ax as CSVMultisigTapscript, ay as SettlementConfig, d as ArkadeBroadcaster, q as IAssetManager, az as VtxoManager, n as IDelegateManager, S as SettleParams, R as Recipient, aA as SignerSession, aB as SignedIntent, aC as Intent, p as SendParams, aD as TimeHeight } from './index-CZw-MMfY.js';
+import { TransactionOutput } from '@scure/btc-signer/psbt.js';
+import { Bytes } from '@scure/btc-signer/utils.js';
+import { D as DefaultVtxo, a as DelegateVtxo } from './delegate-DNbiUgy8.js';
+
+/**
+ * IndexedDB-based implementation of WalletRepository.
+ */
+declare class IndexedDBWalletRepository implements WalletRepository {
+    readonly version: 2;
+    private readonly connection;
+    constructor(dbName?: string);
+    clear(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+    getVtxosPage(address: string, page: PageRequest<Outpoint>): Promise<PageResult<ExtendedVirtualCoin, Outpoint>>;
+    saveVtxos(address: string, vtxos: ExtendedVirtualCoin[]): Promise<void>;
+    deleteVtxos(address: string): Promise<void>;
+    getVtxosForScriptPage(script: string, page: PageRequest<ScriptVtxoCursor>, options?: ScriptVtxoPageOptions): Promise<PageResult<StoredVtxo, ScriptVtxoCursor>>;
+    saveVtxosForScript(key: VtxoRepositoryKey, vtxos: ExtendedVirtualCoin[]): Promise<void>;
+    deleteVtxosForScript(script: string): Promise<void>;
+    getUtxosPage(address: string, page: PageRequest<Outpoint>): Promise<PageResult<ExtendedCoin, Outpoint>>;
+    private pageByAddress;
+    saveUtxos(addressOrBatch: string | ReadonlyMap<string, ExtendedCoin[]>, utxos?: ExtendedCoin[]): Promise<void>;
+    deleteUtxos(address: string): Promise<void>;
+    getTransactionHistoryPage(filter: TransactionHistoryPageFilter, page: PageRequest<TransactionHistoryPageCursor>): Promise<PageResult<ArkTransaction, TransactionHistoryPageCursor>>;
+    saveTransactions(address: string, txs: ArkTransaction[]): Promise<void>;
+    deleteTransactions(address: string): Promise<void>;
+    getWalletState(): Promise<WalletState | null>;
+    saveWalletState(state: WalletState): Promise<void>;
+    private getDB;
+}
+
+/**
+ * A {@link DescriptorProvider} decorator that adds a **keyring**: raw
+ * private keys imported from outside the wallet's derivation tree, each
+ * addressed by a `tr(<pubkey>)` descriptor.
+ *
+ * Resolution is union-shaped — `signWithDescriptor` /
+ * `signMessageWithDescriptor` serve a descriptor from the wrapped
+ * provider's derivation tree *or* from the keyring, whichever owns it —
+ * so the wallet's existing descriptor routing
+ * (`InputSignerRouter`) signs foreign-key contracts with no changes: an
+ * imported contract carrying `metadata.signingDescriptor` is signable by
+ * construction rather than throwing `MissingSigningDescriptorError`.
+ *
+ * Allocation is *not* extended: `getNextSigningDescriptor` always
+ * delegates to the wrapped provider. The keyring holds foreign keys the
+ * wallet was handed; it never mints receive addresses.
+ *
+ * Lifecycle: entries persist under
+ * `WalletRepository.getWalletState().settings.keyring` (same
+ * no-migration pattern as `HDDescriptorProvider`), so an import survives
+ * the restarts a recovery spans, and {@link deleteKey} purges it when
+ * recovery completes. The repository is the source of truth: the async
+ * signing/purge APIs converge on sibling instances' imports and purges
+ * (see {@link refresh}), so any tab/worker sharing the repo can complete
+ * a recovery another one started.
+ *
+ * **Keys are stored unencrypted.** This is a deliberate, scoped
+ * decision: the intended use is a short-lived, purge-on-completion hold
+ * of a key that guards funds already destined for this wallet. At-rest
+ * encryption is a possible hardening follow-up. Do not use this to hold
+ * long-lived key material.
+ *
+ * @example
+ * ```ts
+ * const provider = await KeyringDescriptorProvider.create(hdProvider, walletRepo);
+ * const descriptor = await provider.importKey(foreignPrivKey);
+ * // descriptor: tr(<x-only pubkey hex>)
+ * // ... import a contract with metadata.signingDescriptor = descriptor,
+ * //     let the wallet's recovery machinery settle it, then:
+ * await provider.deleteKey(descriptor);
+ * ```
+ */
+declare class KeyringDescriptorProvider implements DescriptorProvider {
+    /**
+     * The wrapped provider. Exposed so callers that need to reach a
+     * concrete provider type behind the decorator (e.g. the wallet's
+     * restore path, which branches on `HDDescriptorProvider`) can
+     * unwrap it rather than mis-classify the decorator.
+     */
+    readonly base: DescriptorProvider;
+    private readonly walletRepository;
+    /**
+     * In-memory mirror of the persisted keyring, keyed by x-only pubkey
+     * hex. Required because {@link isOurs} is synchronous while
+     * persistence is not. The **repository is the source of truth**: the
+     * async APIs write through to it and {@link refresh} re-seeds this
+     * mirror from it when a signing request names a foreign key the
+     * mirror doesn't know — a sibling instance (another tab/worker on
+     * the same repo) may have imported it after this instance was
+     * constructed. The sync views ({@link isOurs}, {@link hasKey},
+     * {@link listKeyringDescriptors}) answer from the last-known
+     * snapshot.
+     */
+    private readonly keys;
+    private constructor();
+    /**
+     * Wrap `base` with a keyring, loading any previously imported keys
+     * from the repository. Unlike `HDDescriptorProvider.create`, this
+     * *does* read at construction: `isOurs` is synchronous and must be
+     * able to answer for persisted keys from the first call.
+     */
+    static create(base: DescriptorProvider, walletRepository: WalletRepository): Promise<KeyringDescriptorProvider>;
+    /**
+     * Import a raw private key into the keyring and return its
+     * `tr(<x-only pubkey>)` descriptor handle. Idempotent: re-importing
+     * the same key returns the same descriptor and leaves storage
+     * unchanged.
+     */
+    importKey(privateKey: Uint8Array): Promise<string>;
+    /**
+     * Purge a keyring entry. Returns `true` when an entry was removed,
+     * `false` when the descriptor was not in the keyring (already
+     * purged, or never ours) — so a repeated purge is a safe no-op.
+     *
+     * Always goes through storage, never trusting the in-memory mirror:
+     * the entry may have been imported by a sibling instance after this
+     * one was constructed, and skipping the persistent purge on a memory
+     * miss would leave that key at rest forever.
+     */
+    deleteKey(descriptor: string): Promise<boolean>;
+    /** True iff `descriptor` resolves to a key held in the keyring. */
+    hasKey(descriptor: string): boolean;
+    /** The `tr(<pubkey>)` descriptors of every key currently held. */
+    listKeyringDescriptors(): string[];
+    /** Allocation is the wrapped provider's job; the keyring never mints. */
+    getNextSigningDescriptor(): Promise<string>;
+    /** Ours iff the wrapped provider claims it, or the keyring holds it. */
+    isOurs(descriptor: string): boolean;
+    /**
+     * Signs each request with the key its descriptor resolves to.
+     * Keyring-owned requests are signed here; every other request is
+     * handed to the wrapped provider in a single batched call, so a
+     * batch-signing identity behind a `StaticDescriptorProvider` still
+     * sees one interaction.
+     *
+     * Results are returned in request order regardless of how the
+     * requests split across the two signers.
+     */
+    signWithDescriptor(requests: DescriptorSigningRequest[]): Promise<Transaction[]>;
+    /** Signs a message with the keyring key, or delegates to the base. */
+    signMessageWithDescriptor(descriptor: string, message: Uint8Array, type?: "schnorr" | "ecdsa"): Promise<Uint8Array>;
+    /**
+     * Split requests into keyring-owned and base-delegated buckets.
+     * `mayBeStale` is set when a delegated descriptor is foreign-shaped —
+     * a sibling instance may have imported its key after this instance
+     * seeded the mirror, so the caller should {@link refresh} once and
+     * re-split before trusting the delegation.
+     */
+    private splitRequests;
+    /**
+     * True when `descriptor` is a bare `tr(<pubkey>)` the base provider
+     * does not own — the only shape a keyring entry can have, so the only
+     * kind of miss a {@link refresh} could turn into a hit.
+     */
+    private isForeignShaped;
+    /**
+     * Re-seed the in-memory mirror from the repository, converging on
+     * imports and purges made by sibling instances on the same repo.
+     * Full replacement, not a merge, so sibling *deletions* propagate
+     * too. Corrupt persisted settings throw, same as {@link create}.
+     *
+     * Only a *miss* triggers a refresh, so that convergence is one-sided:
+     * an entry this instance still believes it holds is never
+     * revalidated, and a sibling's purge can linger in this mirror until
+     * some unrelated foreign-shaped miss re-seeds it. Harmless today —
+     * `deleteKey`'s caller also deletes the contract row carrying the
+     * descriptor, so no signing request can name the stale entry — but it
+     * means the at-rest purge is not a memory purge for siblings.
+     */
+    private refresh;
+    /**
+     * The keyring key for `descriptor`, or `undefined` when the request
+     * belongs to the base provider. Base ownership wins on collision:
+     * a key already in the derivation tree keeps its established signing
+     * path, so importing it cannot reroute existing contracts.
+     */
+    private resolveKey;
+    /**
+     * Read-modify-write the keyring settings through `updateWalletState`,
+     * whose in-process mutex plus cross-context Web Lock keep concurrent
+     * imports/purges — including ones driven from other tabs/workers
+     * sharing the store — from clobbering each other's entries.
+     */
+    private mutate;
+}
+
+/**
+ * Capability a wallet exposes so descriptor-blind consumers (Boltz swaps, other plugins) can bind
+ * artifacts to the wallet's current HD index and later enumerate every used index. Probed
+ * structurally ({@link isHDWalletCapable}) rather than widening `IWallet`, so plugins keep working
+ * against older wallets; a static wallet answers "no HD state" through the same methods.
+ */
+interface HDWalletCapable {
+    /**
+     * The descriptor at the wallet's current receive index, or `undefined` for
+     * static / `auto` wallets and HD wallets that have never rotated. Callers
+     * fall back to the identity key.
+     */
+    getCurrentSigningDescriptor(): Promise<string | undefined>;
+    /**
+     * Every descriptor the wallet may hold keys under, ascending by index: the allocation
+     * watermark's band plus any descriptor persisted on a contract. Empty for static wallets.
+     * `lookAhead` appends that many past the watermark without advancing it, for restore probing.
+     */
+    getUsedSigningDescriptors(opts?: {
+        lookAhead?: number;
+    }): Promise<string[]>;
+    /**
+     * An {@link Identity} whose keys and signatures are those of `descriptor`; the wallet
+     * identity itself when `descriptor` is the identity's own key.
+     *
+     * Throws {@link ForeignDescriptorError} for a descriptor this wallet cannot sign for — never
+     * substitutes another key, which would sign happily and surface only as a rejected tx or a
+     * dead script. The returned identity must actually sign (`sign`, `signMessage`,
+     * `signerSession`): `contractSigner` refuses a watch-only one as `WalletCannotSignError`,
+     * which would otherwise pass every check and throw after the contract is funded.
+     */
+    signerForDescriptor(descriptor: string): Promise<Identity>;
+}
+/**
+ * Thrown by {@link HDWalletCapable.signerForDescriptor} when the wallet holds no key for the
+ * descriptor, so callers can tell "not my key" from transient signing failures.
+ */
+declare class ForeignDescriptorError extends Error {
+    readonly descriptor: string;
+    readonly name = "ForeignDescriptorError";
+    constructor(descriptor: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown by `Wallet.getNewAddresses({ forceNew: true })` when there is no HD stream to advance
+ * (`walletMode: 'static'` / `'auto'`, or a {@link DescriptorProvider} that declined). Typed
+ * rather than a silent repeat, which would surface only as two payers sharing a script.
+ */
+declare class WalletCannotAllocateAddressError extends Error {
+    readonly name = "WalletCannotAllocateAddressError";
+    constructor(reason: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Anything that can derive and sign for a descriptor it claims. */
+type DescriptorOwner = Pick<DescriptorProvider, "isOurs" | "signWithDescriptor" | "signMessageWithDescriptor">;
+/**
+ * The identity that signs `descriptor`, or {@link ForeignDescriptorError}. Shared by every
+ * {@link HDWalletCapable.signerForDescriptor} so page- and worker-side wallets cannot drift into
+ * a signer that passes a pubkey check and then throws on every signature, after funding.
+ */
+declare function resolveDescriptorSigner(descriptor: string, identity: Identity, provider?: DescriptorOwner): Promise<Identity>;
+/** Structural type guard for {@link HDWalletCapable}. */
+declare function isHDWalletCapable(value: unknown): value is HDWalletCapable;
+/**
+ * Allocating a *fresh* index — strictly more than {@link HDWalletCapable}'s descriptor awareness.
+ * A separate probe because widening that guard would silently demote every wallet implementing
+ * only its original surface (including older SDKs') from HD-capable to static.
+ */
+interface HDAllocationCapable {
+    /**
+     * The signing descriptor a new artifact (swap, invoice, contract) should bind to. **The
+     * wallet decides**: an HD wallet allocates a fresh index, advancing the watermark; a static
+     * wallet answers with its one `tr(pubkey)` every time. Consumers must not probe the wallet's
+     * shape or mint key material; they use the answer with
+     * {@link HDWalletCapable.signerForDescriptor}.
+     *
+     * `undefined` only for implementations that genuinely cannot answer (`Wallet` always
+     * answers); callers then fall back to the identity key — never a random one.
+     *
+     * Unlike {@link HDWalletCapable.getCurrentSigningDescriptor}, which peeks (two artifacts bound
+     * to a peek share a key). Per-call uniqueness is a wallet property, so anything deriving
+     * per-artifact secrets must check the descriptor's shape, not the wallet's.
+     */
+    getNextSigningDescriptor(): Promise<string | undefined>;
+    /**
+     * Move the allocation watermark to `descriptor`'s index so later allocations cannot reissue
+     * it. Monotonic; a static wallet accepts its own descriptor as a no-op.
+     *
+     * Throws on a descriptor this wallet cannot derive, or an HD descriptor with no parseable
+     * trailing index: mapping those to index 0 would let a restored artifact's index be reissued.
+     */
+    advanceSigningDescriptorWatermark(descriptor: string): Promise<void>;
+}
+/** Structural type guard for {@link HDAllocationCapable}. */
+declare function isHDAllocationCapable(value: unknown): value is HDAllocationCapable;
+/**
+ * Minting addresses to hand out: beyond {@link HDAllocationCapable}'s bare index, the wallet
+ * builds the scripts, persists them as watched contracts, and reports the rows. A third probe
+ * for the same no-silent-demotion reason.
+ */
+interface AddressAllocationCapable {
+    /**
+     * Fresh addresses of each requested type from one newly allocated HD index, persisted and
+     * watched. An HD wallet burns an index; a wallet with no stream answers with its existing
+     * display addresses or, under `forceNew`, throws {@link WalletCannotAllocateAddressError}.
+     *
+     * Unlike {@link HDAllocationCapable.getNextSigningDescriptor}, allocation and script
+     * registration happen together: split across a process boundary, a failed registration
+     * leaves a burnt index and an unwatched address.
+     */
+    getNewAddresses(opts?: GetNewAddressesOptions): Promise<NewAddress[]>;
+}
+/** Structural type guard for {@link AddressAllocationCapable}. */
+declare function isAddressAllocationCapable(value: unknown): value is AddressAllocationCapable;
+
+/** Wall-clock floor for `batchExpiry` outside regtest. */
+declare const DEFAULT_MIN_BATCH_EXPIRY_SECONDS = 86400n;
+/** Wall-clock floor for `batchExpiry` on regtest (~10 blocks). */
+declare const REGTEST_MIN_BATCH_EXPIRY_SECONDS = 6000n;
+/** Bounds applied to a server-supplied `BatchStartedEvent.batchExpiry`. */
+type BatchExpiryPolicy = {
+    /** Minimum wall-clock delay in seconds, after normalization. */
+    minSeconds: bigint;
+    /**
+     * Reject block-typed timelocks. Mirrors arkd, which allows a block-typed
+     * vtxo tree expiry only on regtest.
+     */
+    requireSeconds: boolean;
+    /** When advertised by the operator, `batchExpiry` must equal it exactly. */
+    advertisedVtxoTreeExpiry?: bigint;
+};
+/**
+ * Default policy for a network.
+ *
+ * Derive it from the locally held {@link Network} — pinned at wallet setup —
+ * rather than from a per-round server field, so the permissive regtest branch
+ * can't be selected by the operator at event time.
+ */
+declare function defaultBatchExpiryPolicy(network: Network): BatchExpiryPolicy;
+/** Resolve a policy for `network`, applying any caller overrides on top. */
+declare function resolveBatchExpiryPolicy(network: Network, overrides?: Partial<BatchExpiryPolicy>): BatchExpiryPolicy;
+/**
+ * Check a server-supplied batch expiry against `policy` and return the timelock
+ * to commit to.
+ *
+ * The sweep leaf of the shared batch output is derived from this value, so it
+ * is never reconstructible from anything else the server sends: validating the
+ * tree only proves it is consistent with whatever value was chosen. Callers
+ * must encode the returned timelock rather than re-deriving their own.
+ *
+ * @throws {ServerResponseMismatchError} if the value is out of policy.
+ */
+declare function assertValidBatchExpiry(batchExpiry: bigint, policy: BatchExpiryPolicy): RelativeTimelock;
+
+declare class ArkError extends Error {
+    readonly code: number;
+    readonly message: string;
+    readonly name: string;
+    readonly metadata?: Record<string, string> | undefined;
+    constructor(code: number, message: string, name: string, metadata?: Record<string, string> | undefined);
+}
+/**
+ * Structured arkd error `name`s the SDK branches on, centralized so call sites don't
+ * hardcode string literals. Not an exhaustive mirror of the server's codes — only the
+ * ones the SDK acts on.
+ */
+declare const ArkErrorName: {
+    readonly DIGEST_MISMATCH: "DIGEST_MISMATCH";
+    readonly VTXO_ALREADY_SPENT: "VTXO_ALREADY_SPENT";
+    readonly INVALID_TX_FILTER: "INVALID_TX_FILTER";
+    readonly TX_FILTERS_LIMIT_EXCEEDED: "TX_FILTERS_LIMIT_EXCEEDED";
+    /**
+     * A CLTV closure was spent before its absolute locktime matured. `submitTx` only, with
+     * metadata `{ locktime, current_locktime, type: "height" | "time" }`. Self-healing, so defer
+     * and retry: the server matures a seconds-locktime against the **chain tip block's
+     * timestamp**, not wall clock, so a prompt spend is rejected until a later block lands.
+     */
+    readonly FORFEIT_CLOSURE_LOCKED: "FORFEIT_CLOSURE_LOCKED";
+    readonly INVALID_INTENT_PROOF: "INVALID_INTENT_PROOF";
+};
+type ArkErrorName = (typeof ArkErrorName)[keyof typeof ArkErrorName];
+/**
+ * Type guard for a structured {@link ArkError}, optionally narrowing to a cataloged
+ * {@link ArkErrorName}; for an uncataloged name, add it there or compare `err.name` after the
+ * one-argument form.
+ *
+ * @example
+ * if (isArkError(maybeArkError(err), ArkErrorName.DIGEST_MISMATCH)) { ... }
+ */
+declare function isArkError(error: unknown, name?: ArkErrorName): error is ArkError;
+/**
+ * Which remote dependency an availability failure refers to; labels the
+ * {@link ProviderUnavailableError} message and `ProviderConnectionState`. Deliberately *not* a
+ * field on the error: structured clone across the service-worker `postMessage` boundary keeps
+ * `message`, `stack` and `cause` but drops own-properties and normalizes a custom `name` to
+ * `"Error"`.
+ */
+type ProviderKind = "arkade" | "indexer";
+/**
+ * A remote provider (Arkade operator or its indexer) is temporarily unreachable: transport
+ * failure, timeout, or a 5xx/429. Retryable, unlike terminal config/auth/schema errors, which
+ * stay a plain `Error`/{@link ArkError}. The low-level error is kept as {@link Error.cause}.
+ */
+declare class ProviderUnavailableError extends Error {
+    /** Always `true`: this error type only ever wraps retryable conditions. */
+    readonly retryable = true;
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * A response doesn't reconcile with what the SDK submitted or validated (a checkpoint txid not
+ * among those submitted, a commitment tx differing from the one validated at tree signing).
+ * Terminal: the two are equal by construction in a well-formed exchange. `retryable` and `name`
+ * don't cross the SW boundary (see {@link ProviderKind}), so every distinguishing detail belongs
+ * in `message`.
+ */
+declare class ServerResponseMismatchError extends Error {
+    readonly retryable = false;
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Try to convert an error to an ArkError class, returning undefined if the error is not an ArkError
+ * @param error - The error to parse
+ * @returns The parsed ArkError, or undefined if the error is not an ArkError
+ */
+declare function maybeArkError(error: any): ArkError | undefined;
+
+/** Where the {@link ArkadeInfo} used to construct a wallet came from. */
+type ServerInfoSource = "live" | "cache";
+
+/**
+ * Batch namespace provides utilities for joining and processing batch session.
+ * The batch settlement process involves multiple events, this namespace provides abstractions and types to handle them.
+ * @see https://docs.arkadeos.com/learn/pillars/batch-swaps
+ * @example
+ * ```typescript
+ * // use wallet handler or create a custom one
+ * const handler = wallet.createBatchHandler(intentId, inputs, expectedRecipients, musig2session);
+ *
+ * const abortController = new AbortController();
+ * // Get event stream from the Arkade provider
+ * const eventStream = arkProvider.getEventStream(
+ *   abortController.signal,
+ *   ['your-topic-1', 'your-topic-2']
+ * );
+ *
+ * // Join the batch and process events
+ * try {
+ *   const commitmentTxid = await Batch.join(eventStream, handler);
+ *   console.log('Batch completed with commitment:', commitmentTxid);
+ * } catch (error) {
+ *   console.error('Batch processing failed:', error);
+ * } finally {
+ *   abortController.abort();
+ * }
+ * ```
+ */
+declare namespace Batch {
+    interface Handler {
+        /**
+         * Called on BatchStarted event.
+         * @returns { skip: boolean } indicating whether the batch should be skipped or not.
+         */
+        onBatchStarted(event: BatchStartedEvent): Promise<{
+            skip: boolean;
+        }>;
+        /**
+         * Called when tree signing starts.
+         * @param event The tree signing started event.
+         * @param vtxoTree The unsigned virtual output tree, reconstructed from the TreeTxEvent events.
+         * @returns Promise resolving to a boolean indicating whether to continue processing.
+         */
+        onTreeSigningStarted(event: TreeSigningStartedEvent, vtxoTree: TxTree): Promise<{
+            skip: boolean;
+        }>;
+        /**
+         * Called when tree nonces are received.
+         * @param event The tree nonces event.
+         * @returns Promise resolving to a boolean indicating whether signing is complete.
+         */
+        onTreeNonces(event: TreeNoncesEvent): Promise<{
+            fullySigned: boolean;
+        }>;
+        /**
+         * Called during batch finalization.
+         * @param event The batch finalization event.
+         * @param vtxoTree The signed virtual output tree, reconstructed from the TreeTxEvent events.
+         * @param connectorTree The connector transaction tree, reconstructed from the TreeTxEvent events.
+         */
+        onBatchFinalization(event: BatchFinalizationEvent, vtxoTree?: TxTree, connectorTree?: TxTree): Promise<void>;
+        /**
+         * Called when batch finalization completes successfully.
+         *
+         * @param event - Batch finalized event
+         */
+        onBatchFinalized?(event: BatchFinalizedEvent): Promise<void>;
+        /**
+         * Called when batch processing fails.
+         *
+         * @param event - Batch failed event
+         */
+        onBatchFailed?(event: BatchFailedEvent): Promise<void>;
+        /**
+         * Called for each virtual output tree transaction chunk received during batch processing.
+         *
+         * @param event - Tree transaction event
+         */
+        onTreeTxEvent?(event: TreeTxEvent): Promise<void>;
+        /**
+         * Called for each tree signature event received during batch processing.
+         *
+         * @param event - Tree signature event
+         */
+        onTreeSignatureEvent?(event: TreeSignatureEvent): Promise<void>;
+    }
+    /**
+     * Options for the join function.
+     *
+     * @property abortController - Abort controller used to cancel batch processing.
+     * @property skipVtxoTreeSigning - Ignore events related to the virtual output tree musig2 signing session.
+     * @property eventCallback - Callback invoked for each settlement event received while joining the batch.
+     */
+    type JoinOptions = Partial<{
+        abortController: AbortController;
+        skipVtxoTreeSigning: boolean;
+        eventCallback: (event: SettlementEvent) => Promise<void>;
+    }>;
+    /**
+     * Start the state machine that will process the batch events and join a batch.
+     * @param eventIterator - The events stream to process.
+     * @param handler - How to react to events.
+     * @param options - Options.
+     */
+    function join(eventIterator: AsyncIterableIterator<SettlementEvent>, handler: Handler, options?: JoinOptions): Promise<string>;
+}
+
+/**
+ * Inputs a {@link ReceiveRotatorFactory} gets at boot to find the current display contract or
+ * allocate a fresh descriptor. Allocation only: `resolveBoot` rebuilds the tapscript afterwards.
+ */
+interface ReceiveRotatorBootOpts {
+    walletRepository: WalletRepository;
+    contractRepository: ContractRepository;
+    serverPubKey: Uint8Array;
+    /** When set, only this contract family is considered for the current display contract. */
+    expectedContractType?: "default" | "delegate";
+    /**
+     * The wallet's baseline (index-0) x-only receive pubkey, used by {@link
+     * WalletReceiveRotator.defaultBoot} when no tagged receive row exists. Such a wallet never
+     * rotated L2, and the raw watermark can't be used: boarding shares the HD index stream, so a
+     * boarding-only allocation may have advanced it.
+     */
+    baselineReceivePubKey?: Uint8Array;
+    /** Receives rotation-failure and backoff diagnostics. Defaults to `console`. */
+    logger?: Logger;
+}
+/**
+ * Output of {@link ReceiveRotatorFactory.createReceiveRotator}: the rotator plus the receive
+ * pubkey resolved at boot (existing tagged display contract's, or freshly allocated).
+ */
+interface ReceiveRotatorBoot {
+    rotator: WalletReceiveRotator;
+    receivePubkey: Uint8Array;
+}
+/**
+ * What {@link WalletReceiveRotator.resolveBoot} returns: the rotator, the offchain tapscript to
+ * use (rebuilt to the boot pubkey if it differs), and the provider, which the wallet keeps so
+ * spends route per-input signing through {@link DescriptorProvider.signWithDescriptor}.
+ */
+interface ReceiveRotatorBootResult {
+    rotator: WalletReceiveRotator;
+    offchainTapscript: DefaultVtxo.Script | DelegateVtxo.Script;
+    provider: DescriptorProvider;
+}
+/**
+ * Opt-in {@link DescriptorProvider} extension for providers driving HD receive rotation
+ * (implemented by {@link HDDescriptorProvider}). Kept out of the core interface so
+ * allocate-and-sign providers needn't know the receive lifecycle; without it the wallet uses
+ * {@link WalletReceiveRotator.defaultBoot}.
+ */
+interface ReceiveRotatorFactory {
+    createReceiveRotator(opts: ReceiveRotatorBootOpts): Promise<ReceiveRotatorBoot | undefined>;
+}
+/**
+ * Parse the trailing HD child index from a materialized signing descriptor
+ * (`tr(...xpub.../0/<index>)`). Returns 0 when absent or unparseable: restore registers the
+ * index-0 baseline untagged, so a missing descriptor legitimately means 0.
+ */
+declare function signingDescriptorIndex(descriptor: unknown): number;
+/**
+ * Strict {@link signingDescriptorIndex}: `undefined` instead of the 0 fallback, for callers
+ * (e.g. watermark moves) where mapping "unparseable" to 0 would silently do nothing.
+ */
+declare function strictSigningDescriptorIndex(descriptor: string): number | undefined;
+/** Minimal logging surface the rotator needs; `console` or any structured logger satisfies it. */
+interface Logger {
+    error(message: string, ...args: unknown[]): void;
+}
+/**
+ * The wallet surface the rotator needs at runtime. An interface to avoid a circular dependency on
+ * `wallet.ts`; `Wallet` satisfies it structurally.
+ */
+interface RotatableWallet {
+    readonly defaultContractScript: string;
+    readonly network: {
+        hrp: string;
+    };
+    readonly arkServerPublicKey: Uint8Array;
+    readonly offchainTapscript: DefaultVtxo.Script | DelegateVtxo.Script;
+    /**
+     * @internal Sole sanctioned write path for `offchainTapscript` after construction; called
+     * once per rotation after the new display contract is persisted.
+     */
+    setOffchainTapscriptForRotation(tapscript: DefaultVtxo.Script | DelegateVtxo.Script): void;
+    getContractManager(): Promise<IContractManager>;
+    getAddress(): Promise<string>;
+}
+/**
+ * Owns the wallet's HD receive-rotation lifecycle; exists only when `walletMode` resolves to a
+ * {@link DescriptorProvider}.
+ *
+ * 1. `resolveBoot()` (before Wallet construction): reuse the display contract's pubkey or
+ *    allocate the first descriptor.
+ * 2. `install(wallet)`: subscribe to `vtxo_received` and rotate on matching events.
+ * 3. `dispose()`: unsubscribe and drain any in-flight rotation.
+ *
+ * NArk parity: the provider is a pure allocator; the current address comes from the contract
+ * repository, not the provider.
+ */
+declare class WalletReceiveRotator {
+    private readonly provider;
+    private unsubscribe?;
+    private chain;
+    /**
+     * Script of the latest tagged display contract, retired by the next `rotate()`. `undefined`
+     * means the untagged index-0 baseline is displayed, which must NOT be deactivated.
+     */
+    private currentTaggedScript;
+    /** Drives exponential backoff so a broken provider isn't hammered on every inbound VTXO. */
+    private consecutiveFailures;
+    /** Unix ms before which `vtxo_received` events skip rotation; 0 = no backoff. */
+    private nextRotationAllowedAt;
+    private readonly logger;
+    private constructor();
+    /**
+     * Resolve `walletMode` to a provider and build the rotator (via its
+     * {@link ReceiveRotatorFactory}, else {@link defaultBoot}). Returns `undefined` for the
+     * static path.
+     *
+     * Resolution errors propagate for `'hd'` and explicit providers (degrading would hide
+     * misconfig); a {@link NonRangeableDescriptorError} is swallowed only under `'auto'`, for
+     * back-compat with identities whose descriptor isn't rangeable.
+     */
+    static resolveBoot(config: WalletConfig, setup: ReceiveRotatorBootOpts & {
+        offchainTapscript: DefaultVtxo.Script | DelegateVtxo.Script;
+    }): Promise<ReceiveRotatorBootResult | undefined>;
+    /**
+     * Default boot any {@link ReceiveRotatorFactory.createReceiveRotator} can delegate to: take
+     * the current display contract from the repository, else allocate/derive the receive pubkey.
+     * Tapscript construction is deliberately left to `resolveBoot`.
+     */
+    static defaultBoot(provider: DescriptorProvider, opts: ReceiveRotatorBootOpts): Promise<ReceiveRotatorBoot>;
+    /**
+     * Subscribe to `vtxo_received` and rotate whenever the current display contract receives
+     * funds. Old display contracts stay watched, so earlier shared addresses keep crediting.
+     */
+    install(wallet: RotatableWallet): Promise<void>;
+    /**
+     * One rotation attempt with exponential backoff. Errors are logged, not rethrown, so `chain`
+     * never rejects and the next `vtxo_received` still runs.
+     */
+    private runRotateWithBackoff;
+    /** Wait for any in-flight rotation to complete (mainly for tests). */
+    drain(): Promise<void>;
+    /**
+     * Run `fn` on the rotation chain. {@link Wallet.rotateServerSigner} uses it because both it
+     * and `rotate()` swap `offchainTapscript`; interleaving could tear the visible receive state.
+     * The chain advances even if `fn` rejects (the caller still sees the rejection).
+     */
+    runExclusive<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Unsubscribe first so no late event queues work, then drain so an in-flight
+     * `createContract` finishes before the contract manager disposes.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Allocate the next descriptor, register it as the new tagged display contract (same
+     * default/delegate shape), swap it in, and mark the previous tagged one `inactive` (still
+     * watched; it just stops being advertised). The untagged index-0 baseline is never retired.
+     */
+    private rotate;
+}
+
+/**
+ * Cap on HD descriptors getUsedSigningDescriptors() materializes past the watermark (bounds
+ * plugin/restore probes; the watermark itself is not moved).
+ */
+declare const MAX_USED_SIGNING_DESCRIPTORS_LOOK_AHEAD = 1000;
+type IncomingFunds = {
+    type: "utxo";
+    coins: Coin[];
+} | {
+    type: "vtxo";
+    newVtxos: ExtendedVirtualCoin[];
+    spentVtxos: ExtendedVirtualCoin[];
+};
+
+/**
+ * Structural rather than {@link ContractWithVtxos} so the worker's repository-built snapshot
+ * (VTXOs without `contractScript`) classifies without a parallel array.
+ */
+type PendingRecoverySnapshot = Parameters<typeof selectPendingRecoveryOutpoints>[0];
+/**
+ * Boarding UTXOs grouped by boarding address, with that address's signer. A flat
+ * {@link ExtendedCoin} can't carry it: it keeps only the encoded leaves, not the owning script's
+ * `serverPubKey` or CSV delay, which deprecated-signer classification needs.
+ */
+interface BoardingUtxoGroup {
+    /** Tapscript of the boarding address the coins sit on. */
+    tapscript: DefaultVtxo.Script;
+    /** Server key of that address, normalized x-only hex. */
+    serverPubKey: string;
+    /** CSV exit timelock decoded from THIS tapscript's exit leaf. */
+    csvTimelock: RelativeTimelock;
+    coins: ExtendedCoin[];
+}
+/**
+ * Why a VTXO at an arkadeCash address could neither be swept nor imported for
+ * recovery by {@link Wallet.claimCash}.
+ *
+ * - `subdust` — below dust, so it sits at an OP_RETURN script with no spendable
+ *   leaf. Unspendable as cash; `createCash` prevents minting these.
+ * - `already-spent` — someone else claimed it first.
+ * - `exited` — unilaterally exited onchain, so the offchain sweep cannot reach it;
+ *   `Unroll.completeUnroll` is the remedy.
+ * - `has-assets` — asset-bearing; the BTC-only sweep would burn the assets.
+ * - `sweep-failed` — spendable, but its own sweep was rejected.
+ * - `recovery-failed` — server-swept and recoverable in principle, but the
+ *   import that hands it to the wallet's recovery machinery failed.
+ *
+ * A server-swept VTXO whose import *succeeds* is not reported here — it lands
+ * in {@link ArkadeCashClaimResult.recovering} instead.
+ */
+type ArkadeCashUnclaimedReason = "subdust" | "already-spent" | "exited" | "has-assets" | "sweep-failed" | "recovery-failed";
+/** Minimal outpoint + value identifying a VTXO in a claim report. */
+interface ArkadeCashVtxoRef {
+    txid: string;
+    vout: number;
+    /** Value in satoshis. */
+    value: number;
+}
+/** A VTXO {@link Wallet.claimCash} left behind, with the reason why. */
+interface ArkadeCashUnclaimedVtxo extends ArkadeCashVtxoRef {
+    reason: ArkadeCashUnclaimedReason;
+}
+/**
+ * Outcome of {@link Wallet.claimCash}: what was swept instantly, what was
+ * imported for background recovery, and what was left behind.
+ *
+ * The shape is open — further buckets may be added as more of the
+ * non-sweepable states become claimable.
+ */
+interface ArkadeCashClaimResult {
+    /** Satoshis swept to this wallet instantly (the thin single-key sweep). */
+    swept: number;
+    /**
+     * Server-swept VTXOs imported for recovery. These funds are not in the
+     * wallet yet: a swept VTXO can only move through a settlement, so
+     * `claimCash` imports it as a signable contract and hands it to the
+     * wallet's own recovery machinery, which settles it back (rotation-aware)
+     * on the normal retry cadence. The amount arrives as a fresh VTXO once
+     * that settlement finalizes.
+     */
+    recovering: {
+        /** Satoshis imported for recovery. */
+        amount: number;
+        vtxos: ArkadeCashVtxoRef[];
+    };
+    unclaimed: {
+        /** Satoshis left behind. */
+        amount: number;
+        vtxos: ArkadeCashUnclaimedVtxo[];
+    };
+}
+/**
+ * Thrown when {@link Wallet.createCash}'s `send` fails after the transaction may already have been
+ * submitted. `cash` carries the private key of the funded output: discard it and the sats may be
+ * stranded. Persist it; {@link Wallet.claimCash} recovers the funds whether or not the send landed.
+ */
+declare class ArkadeCashCreateError extends Error {
+    /** The encoded arkadeCash token controlling the funded output. */
+    readonly cash: string;
+    /** The original failure from `send`. */
+    readonly cause: unknown;
+    constructor(
+    /** The encoded arkadeCash token controlling the funded output. */
+    cash: string, 
+    /** The original failure from `send`. */
+    cause: unknown);
+}
+/**
+ * Thrown by {@link Wallet.claimCash} when the arkadeCash comes from another operator. Its signer
+ * is not the connected operator's active signer, and it is not in the operator's list of
+ * deprecated signers either. Nothing is queried or signed. To claim it, connect to the operator
+ * that issued it.
+ */
+declare class ArkadeCashOperatorMismatchError extends Error {
+    /** The signer in the arkadeCash script, x-only hex. */
+    readonly cashSignerPubKey: string;
+    /** The active signer of the connected operator, x-only hex. */
+    readonly activeSignerPubKey: string;
+    constructor(
+    /** The signer in the arkadeCash script, x-only hex. */
+    cashSignerPubKey: string, 
+    /** The active signer of the connected operator, x-only hex. */
+    activeSignerPubKey: string);
+}
+/**
+ * Freshness of provider-backed sync (server-info source + indexer-sync health). Balances/VTXOs
+ * are always served from the repository regardless. `syncing` says a provider sync is in flight
+ * right now; optional so adding it breaks no implementer, {@link ReadonlyWallet} always sets it.
+ */
+type ProviderConnectionState = {
+    mode: "online";
+    syncing?: boolean;
+    source: "live";
+    lastOnlineAt: number;
+} | {
+    mode: "degraded";
+    syncing?: boolean;
+    source: "cache" | "repository";
+    provider: ProviderKind;
+    reason: string;
+    lastOnlineAt?: number;
+};
+declare class ReadonlyWallet implements IReadonlyWallet {
+    readonly identity: ReadonlyIdentity;
+    readonly network: Network;
+    readonly onchainProvider: OnchainProvider;
+    /** Narrowed so a readonly wallet can't grow a `submitTx` use; `Wallet` re-widens it. */
+    protected readonly arkProvider: Pick<ArkProvider, "getInfo">;
+    readonly indexerProvider: IndexerProvider;
+    readonly dustAmount: bigint;
+    readonly walletRepository: WalletRepository;
+    readonly contractRepository: ContractRepository;
+    readonly delegateProvider?: DelegateProvider | undefined;
+    protected lazyInitialization: boolean;
+    private boardingLoaded;
+    private _contractManager?;
+    private _contractManagerInitializing?;
+    protected readonly watcherConfig?: ReadonlyWalletConfig["watcherConfig"];
+    protected vtxoSyncOverlapMs?: number;
+    protected copySyncOverlapTo(wallet: ReadonlyWallet): void;
+    /** Opt-in intent-lifecycle repository; `undefined` ⇒ intent persistence is a no-op. */
+    intentRepository?: IntentRepository;
+    /**
+     * **Experimental / inert.** Opt-in virtual-tx repository, exposed so callers can pass it to
+     * {@link Unroll.Session.create} as a best-effort raw-tx cache. Normal sync never writes it.
+     */
+    virtualTxRepository?: VirtualTxRepository;
+    /** Opt-in exit-data capture settings; see {@link StorageConfig.exitDataCapture}. */
+    exitDataCapture?: {
+        mode?: ExitCaptureMode;
+        minExitWorthSats?: number;
+        sources?: ExitDataSource[];
+    };
+    private readonly _assetManager;
+    readonly walletContractTimelocks: RelativeTimelock[];
+    protected _pendingSpendOutpoints: Set<string>;
+    protected _heldOutpoints: Set<string>;
+    /** Activity resolvers consumed by {@link getActivityHistory}. */
+    readonly activity: ActivityRegistry;
+    get assetManager(): IReadonlyAssetManager;
+    /**
+     * Active receive tapscript; written only by {@link Wallet.setOffchainTapscriptForRotation}
+     * (sole intended caller: {@link WalletReceiveRotator.rotate}).
+     */
+    protected _offchainTapscript: DefaultVtxo.Script | DelegateVtxo.Script;
+    /**
+     * Current boarding tapscript (QR / onboarding target); written only by
+     * {@link Wallet.setBoardingTapscriptForRotation}. Static / `auto` wallets never rotate it.
+     */
+    protected _boardingTapscript: DefaultVtxo.Script;
+    /**
+     * Active server signer (x-only); written only by
+     * {@link Wallet.setArkServerPublicKeyForRotation} when arkd rotates its signer mid-session.
+     */
+    protected _arkServerPublicKey: Bytes;
+    /**
+     * Whether the LATEST server-info resolution was live or fell back to the cached snapshot.
+     * Updated on every {@link getArkadeInfo} read so recovery (or a fresh fallback) is reflected.
+     */
+    protected _serverInfoSource: ServerInfoSource;
+    /**
+     * Epoch-ms of the last live operator contact, or the cached snapshot's `savedAt` when the
+     * latest resolution fell back.
+     */
+    protected _serverInfoLastOnlineAt?: number;
+    /** @see {@link _serverInfoSource} */
+    get serverInfoSource(): ServerInfoSource;
+    /**
+     * Composed provider-connection freshness: degraded on `arkade` (`cache`) when the latest
+     * server-info resolution fell back, else degraded on `indexer` (`repository`) when an
+     * initialized contract manager has, else online. Never forces a `ContractManager` to
+     * construct, so it is safe for readonly callers.
+     */
+    getProviderConnectionState(): ProviderConnectionState;
+    /**
+     * The contract manager's sync health **without initializing it** (`online` if none exists),
+     * so unlike {@link getContractManager} it never triggers a remote sync.
+     */
+    getContractSyncState(): ContractSyncState;
+    protected constructor(identity: ReadonlyIdentity, network: Network, onchainProvider: OnchainProvider, 
+    /** Narrowed so a readonly wallet can't grow a `submitTx` use; `Wallet` re-widens it. */
+    arkProvider: Pick<ArkProvider, "getInfo">, indexerProvider: IndexerProvider, arkServerPublicKey: Bytes, offchainTapscript: DefaultVtxo.Script | DelegateVtxo.Script, boardingTapscript: DefaultVtxo.Script, dustAmount: bigint, walletRepository: WalletRepository, contractRepository: ContractRepository, delegateProvider?: DelegateProvider | undefined, watcherConfig?: ReadonlyWalletConfig["watcherConfig"], walletContractTimelocks?: RelativeTimelock[]);
+    /**
+     * x-only hex → cutoff of the operator's deprecated signers, cached for OFFLINE read/watch.
+     * Boarding watch/history fan out over {current} ∪ this set so deposits at addresses minted
+     * under a rotated signer stay watched. Deliberately NOT used by the spend path:
+     * {@link getBoardingUtxos} stays current-signer-only (a deprecated-signer input in a plain
+     * settle() is rejected; recovery goes through the migration API).
+     */
+    protected _deprecatedSigners: Map<string, bigint>;
+    /**
+     * Refresh the cached deprecated-signer set from server info; feeds
+     * {@link pendingRecoveryOutpoints}. Lenient: a malformed entry is skipped, never fatal.
+     */
+    refreshDeprecatedSigners(info: {
+        deprecatedSigners?: readonly {
+            pubkey?: string;
+            cutoffDate?: bigint;
+        }[];
+    }): void;
+    /** Boarding WATCH/HISTORY signer set: current ∪ deprecated (spend stays current-only). */
+    protected watchedBoardingSigners(): Set<string>;
+    /**
+     * `serverPubKey` defaults to the live key; spend paths that snapshot it
+     * against mid-flight rotation pass their snapshot, so the check reads from
+     * one rotation epoch.
+     */
+    protected recipientAddressContext(serverPubKey?: Bytes): RecipientArkadeAddressContext;
+    /** Currently-active receive tapscript; changes only on receive rotation. */
+    get offchainTapscript(): DefaultVtxo.Script | DelegateVtxo.Script;
+    /** Current active server signer (x-only, 32 bytes); changes only on server-signer rotation. */
+    get arkServerPublicKey(): Bytes;
+    /**
+     * Server info for the connected Arkade server: live wins, a retryable failure falls back to
+     * the boot snapshot, a terminal one propagates. Live because `signerPubkey`,
+     * `checkpointTapscript` and `fees` move on rotation, and a covenant built against a
+     * superseded signer is unspendable.
+     *
+     * @remarks Reading does NOT re-pin the wallet ({@link arkServerPublicKey}, {@link dustAmount},
+     * tapscripts), so inside a rotation window this can report epoch N+1 while the wallet spends
+     * on N; the provider's `onServerInfoChanged` closes the window. Pass `{ requireLive: true }`
+     * before binding the answer into a covenant to fail closed instead of getting the snapshot.
+     *
+     * @returns The Arkade server's info
+     * @see ArkadeInfo
+     */
+    getArkadeInfo(opts?: GetArkadeInfoOptions): Promise<ArkadeInfo>;
+    /**
+     * Chain reads against this wallet's server for scripts it does not own, bound to the wallet's
+     * own (possibly Expo/injected) `indexerProvider`. `getVtxos` normalizes via
+     * {@link getNormalizedVtxos}. A bound object, not the provider, so an `IReadonlyWallet`
+     * holder gets these two reads and nothing else.
+     */
+    getArkadeReader(): Promise<ArkadeReader>;
+    /**
+     * Current boarding tapscript (on-chain onboarding target); changes only when a fresh boarding
+     * address is explicitly allocated.
+     */
+    get boardingTapscript(): DefaultVtxo.Script;
+    /**
+     * Fired after boarding rotation so a live {@link notifyIncomingFunds} watcher re-subscribes
+     * to the fresh address in-session instead of missing deposits until its next re-init.
+     */
+    private readonly _boardingRotationListeners;
+    /** Register a listener invoked synchronously after each boarding rotation. */
+    protected onBoardingRotation(listener: () => void): () => void;
+    /** A throwing listener is isolated: it can't break the rotation or starve siblings. */
+    protected notifyBoardingRotation(): void;
+    /** Shared setup for ReadonlyWallet.create() and Wallet.create(). */
+    protected static setupWalletConfig(config: ReadonlyWalletConfig, pubKey: Uint8Array): Promise<{
+        arkProvider: ArkProvider;
+        indexerProvider: IndexerProvider;
+        onchainProvider: OnchainProvider;
+        network: Network;
+        networkName: NetworkName;
+        serverPubKey: Uint8Array<ArrayBufferLike>;
+        offchainTapscript: DefaultVtxo.Script | DelegateVtxo.Script;
+        boardingTapscript: DefaultVtxo.Script;
+        dustAmount: bigint;
+        walletRepository: WalletRepository | IndexedDBWalletRepository;
+        contractRepository: ContractRepository;
+        info: ArkadeInfo;
+        serverInfoSource: ServerInfoSource;
+        serverInfoLastOnlineAt: number | undefined;
+        delegateProvider: DelegateProvider | undefined;
+        walletContractTimelocks: RelativeTimelock[];
+    }>;
+    /**
+     * Create a readonly wallet for querying balances, addresses, and history.
+     *
+     * @param config - Readonly wallet configuration
+     * @returns A readonly wallet instance
+     */
+    static create<T extends ReadonlyWallet>(this: {
+        prototype: T;
+    }, config: ReadonlyWalletConfig): Promise<T>;
+    static create(config: ReadonlyWalletConfig): Promise<ReadonlyWallet>;
+    get arkAddress(): ArkAddress;
+    /**
+     * Get the pkScript hex for the wallet's primary offchain address.
+     * For the full wallet-owned script set registered in ContractManager, use getWalletScripts().
+     */
+    get defaultContractScript(): string;
+    /** Returns the wallet's Arkade address. */
+    getAddress(): Promise<string>;
+    /** Returns the onchain boarding address used to move funds into Arkade. */
+    getBoardingAddress(): Promise<string>;
+    /**
+     * Return the wallet's combined onchain and offchain balances.
+     */
+    getBalance(): Promise<WalletBalance>;
+    /** Cached balance; inspect connection state and boarding.loaded before displaying zeros. */
+    getStoredBalance(): Promise<WalletBalance>;
+    private balanceFromSnapshot;
+    /**
+     * Return virtual outputs tracked by the wallet, including escrowed, locked and
+     * awaiting-recovery funds. Coin selection must use {@link getSpendableVtxos}: feeding this
+     * into `settle({ inputs })` or `send({ selectedVtxos })` bypasses the generic-spending gate.
+     *
+     * @param filter - Optional flags controlling whether recoverable or unrolled VTXOs are included
+     */
+    getVtxos(filter?: GetVtxosFilter): Promise<NormalizedExtendedVirtualCoin[]>;
+    /** Cached VTXOs; may be empty before the first sync. Never use for coin selection. */
+    getStoredVtxos(filter?: GetVtxosFilter): Promise<NormalizedExtendedVirtualCoin[]>;
+    /**
+     * @internal The stored VTXOs {@link reserveVtxos} holds, minus any being spent: for renewal,
+     * which skips them, to report the ones it would have renewed. No sync.
+     */
+    getHeldVtxos(): Promise<NormalizedExtendedVirtualCoin[]>;
+    /** @inheritdoc */
+    getSpendableVtxos(filter?: GetSpendableVtxosFilter): Promise<NormalizedExtendedVirtualCoin[]>;
+    /**
+     * Debug-log any explicit input generic selection would have excluded. Explicit-input APIs stay
+     * ungated on purpose (naming an outpoint *is* the intent, and is how an escrowed deposit is
+     * recovered), so this only makes the crossing visible — notably
+     * `settle({ inputs: await wallet.getVtxos() })`. Never throws. Public for worker and plugins.
+     */
+    logUngatedInputs(source: string, inputs: readonly {
+        txid: string;
+        vout: number;
+        script?: string;
+    }[]): Promise<void>;
+    /**
+     * Past-cutoff-signer contracts as a script-level exclusion: the `pendingRecovery` answer for a
+     * caller-supplied input without a synced snapshot (a swept outpoint is unspendable anyway).
+     */
+    private expiredSignerExclusion;
+    /** The intent store's lock set. Fails open, like every other read of it. */
+    private lockedOutpoints;
+    /**
+     * One contract+VTXO read (which may sync against the indexer). Callers needing several views
+     * derive them all from one snapshot so they answer about the same instant.
+     */
+    protected contractSnapshot(filter?: GetSpendableVtxosFilter, options?: {
+        unspentOnly?: boolean;
+    }): Promise<ContractWithVtxos[]>;
+    protected contractSnapshotStored(): Promise<ContractWithVtxos[]>;
+    /**
+     * The two exclusion sets the gate is made of, derived from one snapshot so
+     * {@link getSpendableVtxos} and the balance answer about the same instant.
+     */
+    private spendabilityView;
+    /** The capability probes {@link computeOffchainBalance} needs, over one snapshot. */
+    private balanceCapabilities;
+    /**
+     * Outpoints of not-yet-swept VTXOs whose deprecated signer is past its cutoff (EXPIRED) —
+     * unspendable until they recover; excluded by {@link getBalance} and {@link getSpendableVtxos}.
+     * Takes a fresh (syncing) snapshot; callers that hold one or must not sync use
+     * {@link pendingRecoveryOutpointsIn}.
+     */
+    pendingRecoveryOutpoints(): Promise<Set<string>>;
+    /** {@link pendingRecoveryOutpoints} over a caller-held snapshot; no I/O of its own. */
+    pendingRecoveryOutpointsIn(snapshot: PendingRecoverySnapshot): Set<string>;
+    private selectPendingRecovery;
+    /**
+     * Return wallet transaction history derived from Arkade state and boarding transactions.
+     */
+    getTransactionHistory(): Promise<ArkTransaction[]>;
+    /**
+     * Wallet history grouped by registered activity resolvers. With no resolver match,
+     * rows bucket by transaction key so send/change pairs stay together.
+     */
+    getActivityHistory(): Promise<Activity[]>;
+    /**
+     * Clear the global VTXO sync cursor, forcing a full re-bootstrap on next sync.
+     * Useful for recovery after indexer reprocessing or debugging.
+     */
+    clearSyncCursor(): Promise<void>;
+    /**
+     * Wipe all locally persisted wallet data (VTXOs, UTXOs, history, sync
+     * cursor, contracts, intents). Create a fresh wallet instance afterward.
+     * Intents are kept while any may still be held by arkd, so a later
+     * reconciliation can release them with their stored proofs.
+     */
+    clear(): Promise<void>;
+    private clearIntents;
+    /**
+     * On-chain (P2TR) addresses of every boarding tapscript this wallet uses, current plus
+     * historical rotated, so deposits at old addresses still surface; {@link getBoardingAddress}
+     * stays single-valued.
+     */
+    getBoardingAddresses(): Promise<string[]>;
+    /** Transaction history across the wallet's boarding addresses (current + historical). */
+    getBoardingTxs(): Promise<{
+        boardingTxs: ArkTransaction[];
+        commitmentsToIgnore: Set<string>;
+    }>;
+    /**
+     * Every boarding tapscript whose UTXOs belong to this wallet (rotation spreads them over
+     * several addresses), deduplicated by scriptPubKey. Always includes the index-0 baseline,
+     * which covers the equal-delay case where that row coalesced onto `default`.
+     *
+     * @param allowedSigners - x-only server keys whose persisted boarding rows are included;
+     *   defaults to the current signer (the foreign-ASP guard). Migration widens it to old signers.
+     *   The baseline and current display tapscript are included regardless.
+     */
+    protected getBoardingTapscripts(allowedSigners?: Set<string>): Promise<DefaultVtxo.Script[]>;
+    /**
+     * Fetch and cache boarding UTXOs for the given signer set, grouped per address (see
+     * {@link BoardingUtxoGroup} for why), saving every group in one `saveUtxos`. No
+     * `getInfo()`: the only network calls are the per-address `getCoins`.
+     *
+     * @param allowedSigners - x-only-hex server keys whose boarding addresses to
+     *   fetch (passed through to {@link getBoardingTapscripts}).
+     */
+    getBoardingUtxosForSigners(allowedSigners: Set<string>): Promise<BoardingUtxoGroup[]>;
+    /**
+     * Fetch and cache boarding UTXOs at current and historical boarding addresses, each annotated
+     * with its own address's tapscript so spends use the right per-index leaves. Current-signer
+     * only: old-signer inputs would make a plain `settle()` the server must reject, so their
+     * recovery goes through the deprecated-signer migration API.
+     */
+    getBoardingUtxos(): Promise<ExtendedCoin[]>;
+    /**
+     * @internal {@link getBoardingUtxos} minus those an in-flight settle is spending, for SDK
+     * picks. The getter itself lists them: callers that mirror it (the worker's cache and
+     * broadcasts, balances) must not see a settle's inputs vanish, and then stay gone if it fails.
+     */
+    getSelectableBoardingUtxos(): Promise<ExtendedCoin[]>;
+    getStoredBoardingUtxos(): Promise<ExtendedCoin[]>;
+    /**
+     * Subscribe to onchain and offchain notifications for newly received funds.
+     *
+     * The onchain watcher tracks every boarding address (current + historical) and re-subscribes
+     * automatically when boarding rotates after subscribing, so deposits to a fresh address fire
+     * within the same session.
+     *
+     * @param eventCallback - Callback invoked when matching funds are detected
+     * @returns A function that stops the subscriptions
+     */
+    notifyIncomingFunds(eventCallback: (coins: IncomingFunds) => void): Promise<() => void>;
+    /** Fetch Arkade transaction ids that are still pending final settlement. */
+    fetchPendingTxs(): Promise<string[]>;
+    /**
+     * Get all pkScript hex strings for the wallet's own addresses
+     * (both delegate and non-delegate, current and historical).
+     */
+    getWalletScripts(): Promise<string[]>;
+    /**
+     * Build a map of scriptHex → VtxoScript for all wallet contracts,
+     * so virtual outputs can be extended with the correct tapscript per contract.
+     */
+    getScriptMap(): Promise<Map<string, DefaultVtxo.Script | DelegateVtxo.Script>>;
+    /**
+     * Get the ContractManager, which manages the wallet's own receive contracts and external ones
+     * (Boltz swaps, HTLCs, …) with resilient multi-contract watching.
+     *
+     * @example
+     * ```typescript
+     * const manager = await wallet.getContractManager();
+     *
+     * // Create a contract for a Boltz swap
+     * const contract = await manager.createContract({
+     *   label: "Boltz Swap",
+     *   type: "vhtlc",
+     *   params: { ... },
+     *   script: swapScript,
+     *   address: swapAddress,
+     * });
+     *
+     * // Start watching for events (includes wallet's default address)
+     * const stop = await manager.onContractEvent((event) => {
+     *   console.log(`${event.type} on ${event.contractScript}`);
+     * });
+     * ```
+     */
+    getContractManager(): Promise<ContractManager>;
+    /**
+     * HD look-ahead configuration for the contract manager. Readonly wallets
+     * have no descriptor provider, hence no watermark to look ahead of.
+     * @see Wallet.lookAheadConfig
+     */
+    protected lookAheadConfig(): ContractManagerConfig["lookAhead"];
+    /** Readonly wallets never settle, so they neither release nor own server intents. */
+    protected intentReconciliationConfig(): ContractManagerConfig["intentReconciliation"];
+    private initializeContractManager;
+    /** Dispose wallet-owned managers and release background resources. */
+    dispose(): Promise<void>;
+    /** Async-dispose hook that forwards to `dispose()`. */
+    [Symbol.asyncDispose](): Promise<void>;
+}
+/**
+ * Main wallet implementation for Bitcoin transactions with Arkade protocol support.
+ *
+ * @example
+ * ```typescript
+ * // Create a wallet with providers
+ * const wallet = await Wallet.create({
+ *   identity: MnemonicIdentity.fromMnemonic('abandon abandon...'),
+ *   arkProvider: new RestArkProvider(),
+ *   onchainProvider: new EsploraProvider()
+ * });
+ *
+ * // Use custom providers and/or URLs (e.g., for Expo/React Native)
+ * const wallet = await Wallet.create({
+ *   identity: MnemonicIdentity.fromMnemonic('abandon abandon...'),
+ *   arkProvider: new ExpoArkProvider('https://arkade.computer'),
+ *   indexerProvider: new ExpoIndexerProvider('https://arkade.computer'),
+ *   onchainProvider: new EsploraProvider('https://mempool.space/api')
+ * });
+ *
+ * // Get addresses
+ * const arkAddress = await wallet.getAddress();
+ * const boardingAddress = await wallet.getBoardingAddress();
+ *
+ * // Send bitcoin
+ * const txid = await wallet.send({
+ *   address: 'ark1q...',
+ *   amount: 50000,
+ * });
+ * ```
+ */
+declare class Wallet extends ReadonlyWallet implements IWallet, HDWalletCapable, AddressAllocationCapable {
+    readonly forfeitOutputScript: Bytes;
+    readonly forfeitPubkey: Bytes;
+    /** Overrides for the `batchExpiry` bounds; defaults derive from `network`. */
+    protected readonly batchExpiryPolicy?: Partial<BatchExpiryPolicy> | undefined;
+    static MIN_FEE_RATE: number;
+    readonly identity: Identity;
+    private readonly _delegateManager?;
+    private _vtxoManager?;
+    private _vtxoManagerInitializing?;
+    private _walletAssetManager?;
+    /**
+     * HD receive rotator; absent for `static` and SingleKey-under-`auto` wallets. Its subscription
+     * installs lazily on first `getVtxoManager()` so the contract manager is up first.
+     */
+    private _receiveRotator?;
+    /** Unsubscribe for `onServerInfoChanged` (mid-session signer rotation). */
+    private _serverInfoUnsub?;
+    /**
+     * Tail of the serialized {@link handleServerInfoChanged} chain; {@link dispose} awaits it so an
+     * in-flight rotation settles before the contract manager is torn down.
+     */
+    private _serverInfoInFlight;
+    /**
+     * React to a mid-session server-info change (`DIGEST_MISMATCH`): refresh deprecated signers
+     * first so boarding watch widens immediately, then rotate via {@link rotateServerSigner} only
+     * if the active signer changed. Old-signer rows stay active. Never throws into the emit loop.
+     */
+    private handleServerInfoChanged;
+    /**
+     * Await an `onServerInfoChanged` handler still applying a rotation. {@link rotateServerSigner}
+     * persists the new signer's rows *before* committing the tapscripts, so a path that refreshes
+     * server info then reads signer-derived state must drain first or it reads torn state and
+     * races the handler. Resolves once idle; handler rejections are swallowed (already logged).
+     *
+     * @internal Invoked by {@link dispose} and the {@link VtxoManager} migration
+     * pass; not part of the stable public API.
+     */
+    settleServerInfoChanges(): Promise<void>;
+    private _receiveRotatorInstalled;
+    /**
+     * Descriptor-aware signer for inputs locked by rotated pubkeys (the rotator's instance).
+     * Undefined for static / non-HD wallets, which only sign with the identity.
+     */
+    private readonly _descriptorProvider?;
+    /**
+     * Keyring holding foreign private keys imported outside the wallet's
+     * derivation tree (see {@link KeyringDescriptorProvider}). Wraps
+     * {@link _descriptorProvider} (or a {@link StaticDescriptorProvider}
+     * over the wallet identity when there is no HD provider) and is the
+     * descriptor provider {@link _signerRouter} actually signs through, so
+     * a contract carrying `metadata.signingDescriptor` for an imported key
+     * is signable by construction.
+     *
+     * Kept separate from {@link _descriptorProvider} on purpose: the latter
+     * still gates HD boarding/receive rotation (a `!provider` check means
+     * "static wallet, no rotation"), and wrapping it with a keyring for
+     * every wallet would break that gate. The keyring is orthogonal — it
+     * only ever adds foreign signable keys, never receive addresses.
+     *
+     * Populated for every {@link Wallet.create}d wallet; the constructor's
+     * param is optional so the router degrades to {@link _descriptorProvider}
+     * if a caller ever omits it.
+     */
+    private readonly _keyring?;
+    /**
+     * The built-in HD provider behind any keyring wrapping, or `undefined` when there is none.
+     * Every HD-specific branch goes through this: a wrapped HD provider (a public `walletMode`
+     * shape) fails `instanceof HDDescriptorProvider` and would silently take the non-HD path.
+     */
+    private get _hdProvider();
+    /** Per-side width of the HD look-ahead band. @see WalletConfig.lookAheadWindow */
+    private readonly _lookAheadWindow;
+    protected intentReconciliationConfig(): ContractManagerConfig["intentReconciliation"];
+    /**
+     * Watch a band of receive scripts around the HD watermark so payments to an externally-issued
+     * address land without a `restore()`. HD only. `candidateDeps` is read at refill time, so a
+     * band rebuilt after {@link rotateServerSigner} fans the new signer set.
+     */
+    protected lookAheadConfig(): ContractManagerConfig["lookAhead"];
+    /**
+     * Every axis an externally issued receive script could use: an issuer sharing the seed (NArk,
+     * a merchant backend) picks its own contract type. From cached state (no `getInfo`) to stay
+     * synchronous and offline-safe.
+     */
+    private receiveCandidateDeps;
+    private readonly _signerRouter;
+    /**
+     * @internal Sole write path for `offchainTapscript`; called by
+     * {@link WalletReceiveRotator.rotate} after the rotated contract is persisted.
+     */
+    setOffchainTapscriptForRotation(tapscript: DefaultVtxo.Script | DelegateVtxo.Script): void;
+    /**
+     * @internal Sole write path for `boardingTapscript`; called by
+     * {@link Wallet.getNewBoardingAddress} after the rotated contract is persisted.
+     */
+    setBoardingTapscriptForRotation(tapscript: DefaultVtxo.Script): void;
+    /**
+     * @internal Sole write path for `arkServerPublicKey`; called by
+     * {@link Wallet.rotateServerSigner} after the rotated rows are persisted.
+     */
+    setArkServerPublicKeyForRotation(serverPubKey: Bytes): void;
+    /**
+     * Checkpoint output script from the server's `checkpointTapscript`; pinned at construction,
+     * re-sourced only via {@link setServerUnrollScriptForRotation}.
+     */
+    protected _serverUnrollScript: CSVMultisigTapscript.Type;
+    get serverUnrollScript(): CSVMultisigTapscript.Type;
+    /**
+     * @internal Sole write path for `serverUnrollScript`; called by
+     * {@link Wallet._doRotateServerSigner} with the rotating `ArkadeInfo`'s checkpoint script.
+     */
+    setServerUnrollScriptForRotation(script: CSVMultisigTapscript.Type): void;
+    /**
+     * Serializes {@link rotateServerSigner} for static / non-HD wallets so two callers can't both
+     * swap the tapscripts; HD wallets use {@link WalletReceiveRotator.runExclusive} instead.
+     */
+    private _serverRotationChain;
+    /**
+     * Allocate a *fresh* on-chain boarding address at the next index of the shared HD stream and
+     * make it the displayed one (NArk: `GetNextContract(NextContractPurpose.Boarding)`).
+     * Persists an `active` `boarding` contract tagged {@link WALLET_RECEIVE_SOURCE} so it is
+     * watched, restored at boot and signable per index.
+     *
+     * A static / `auto` wallet returns {@link getBoardingAddress} unchanged (no index burned). A
+     * custom {@link DescriptorProvider} wallet burns an index per call, including via
+     * {@link maybeRotateBoardingAfterBoard} on every settle consuming a boarding UTXO; retired
+     * addresses stay reachable through {@link getBoardingUtxos}.
+     *
+     * @deprecated Use {@link getNewAddresses} — it mints any combination of
+     * address types at one shared index, and reports the contract row behind
+     * each. Note the difference in display behaviour: this method *swaps* the
+     * advertised boarding address, where `getNewAddresses` mints side
+     * addresses and leaves {@link getBoardingAddress} alone. To keep this
+     * method's behaviour, keep calling this method.
+     */
+    getNewBoardingAddress(): Promise<string>;
+    /**
+     * Allocate a *fresh* address of each requested type, all at **one** new HD index. The way to
+     * issue a second address before the first is paid ({@link getAddress} only advances on
+     * receipt). Each is persisted `active` with its `signingDescriptor`, so it is watched,
+     * counted, and signable via {@link signerForDescriptor}; the look-ahead band slides.
+     *
+     * Rows are deliberately **untagged**: boot adopts the newest {@link WALLET_RECEIVE_SOURCE} row
+     * as the display address, and a side address must not become what the wallet advertises.
+     * {@link getAddress} and {@link getBoardingAddress} are unchanged.
+     *
+     * A wallet with no HD stream (`static` / `auto`) returns its persisted display rows, or with
+     * `forceNew` throws {@link WalletCannotAllocateAddressError} rather than return a stale one.
+     *
+     * @example
+     * ```typescript
+     * const [invoice] = await wallet.getNewAddresses({ forceNew: true });
+     * // hand `invoice.address` to Alice, keep the descriptor with the invoice
+     * const signer = await wallet.signerForDescriptor(invoice.signingDescriptor);
+     * ```
+     */
+    getNewAddresses(opts?: GetNewAddressesOptions): Promise<NewAddress[]>;
+    /**
+     * Shared core of {@link getNewAddresses} and {@link getNewBoardingAddress}.
+     *
+     * @param tagSource - Tag rows {@link WALLET_RECEIVE_SOURCE} so boot adopts them as the display
+     * address; only the deprecated boarding allocator passes `true`.
+     */
+    private allocateAddresses;
+    /**
+     * The wallet's existing display addresses as persisted rows, each minted from the descriptor
+     * that owns its display script ({@link displayDescriptor}) so it signs for `address`.
+     */
+    private currentAddresses;
+    /**
+     * The descriptor owning the current display script for `type`, from its persisted row. Not
+     * derived from the identity: on a rotated wallet that would pair the address with a signer
+     * holding the wrong key. Falls back to the identity's `tr(pubkey)` when no row carries one
+     * (static / `auto`; index-0 baselines have no `signingDescriptor`).
+     */
+    private displayDescriptor;
+    /**
+     * Build, persist and shape one address of `type` owned by `descriptor`. The descriptor is the
+     * sole source of the owner key in both branches, so `address` and `signingDescriptor` can't
+     * drift apart.
+     */
+    private mintAddress;
+    /**
+     * Boarding contract owned by `pubKey`, keeping the current tapscript's other options
+     * (offchain analogue: {@link buildReceiveContract}).
+     */
+    private buildBoardingContract;
+    /**
+     * @see HDWalletCapable.getCurrentSigningDescriptor
+     */
+    getCurrentSigningDescriptor(): Promise<string | undefined>;
+    /**
+     * @see HDAllocationCapable.getNextSigningDescriptor
+     *
+     * Every `Wallet` answers, so consumers never branch on wallet shape: HD allocates through the
+     * contract manager; otherwise the identity key as `tr(pubkey)`, the same every call.
+     */
+    getNextSigningDescriptor(): Promise<string | undefined>;
+    /**
+     * @see HDAllocationCapable.advanceSigningDescriptorWatermark
+     */
+    advanceSigningDescriptorWatermark(descriptor: string): Promise<void>;
+    /**
+     * @see HDWalletCapable.getUsedSigningDescriptors
+     *
+     * Union of the watermark band (covers indices allocated for unpersisted things, e.g. swaps)
+     * and descriptors persisted on contracts (covers rows a restore scan wrote).
+     */
+    getUsedSigningDescriptors(opts?: {
+        lookAhead?: number;
+    }): Promise<string[]>;
+    /**
+     * @see HDWalletCapable.signerForDescriptor
+     *
+     * Fail-loud: a descriptor this wallet can't sign for throws {@link ForeignDescriptorError}
+     * rather than substituting the baseline identity, which would sign with the wrong key.
+     */
+    signerForDescriptor(descriptor: string): Promise<Identity>;
+    /**
+     * Mid-session server-signer rotation. A wallet built before arkd rotated keeps deriving
+     * old-signer receive addresses, and a migration output to one yields a VTXO the server must
+     * reject, so receive state is re-derived under the new signer first.
+     *
+     * Same write-path as {@link WalletReceiveRotator.rotate} with the server key swapped: build the
+     * new tapscripts, register their rows (carrying signing metadata so a descriptor-backed
+     * pubkey still signs), and only then commit visible state. Old-signer rows stay `active` for
+     * the migration pass to drain. Idempotent; serialized against HD receive rotation.
+     *
+     * @internal Invoked by the {@link VtxoManager} migration pass; not part of
+     * the stable public API.
+     */
+    rotateServerSigner(newServerPubKey: Bytes, checkpointTapscript: string): Promise<void>;
+    private _doRotateServerSigner;
+    /**
+     * Serializes `settle`/`send` so VtxoManager's background renewal can't race user
+     * transactions for the same inputs; with `concurrentSpending`, only until inputs are reserved.
+     */
+    private _txLock;
+    private readonly _settlingOutpoints;
+    /** Coalesces concurrent {@link restore} calls into one scan; cleared on settle. */
+    private _restoreInFlight?;
+    private _addPendingSpends;
+    private _removePendingSpends;
+    /**
+     * Hold VTXOs so no SDK-chosen spend picks them; the holder still spends them by naming them.
+     * All-or-nothing: throws {@link VtxoReservedError} if any is held or already being spent.
+     * In-memory, for this `Wallet` instance only.
+     */
+    reserveVtxos(outpoints: readonly Outpoint[]): VtxoReservation;
+    /**
+     * @internal For `AssetManager`: reserves what `fn` submits, hiding it from other picks until
+     * the submit ends. With `concurrentSpending`, `fn` runs under the wallet lock, released once
+     * the inputs are reserved; otherwise `fn` runs unlocked and only the submit takes the lock.
+     */
+    withSpendLock<T>(fn: (submit: OffchainSubmit) => Promise<T>): Promise<T>;
+    private _withTxLock;
+    private _assertNotInFlight;
+    private _assertNotHeld;
+    /**
+     * Explicitly recover this wallet's contracts and balance on a fresh repo: a gap-limit scan
+     * for HD wallets, the single default pubkey otherwise. Throws on operational failure (a
+     * truncated restore is loud), never because of identity/mode. Idempotent.
+     *
+     * Ordering: scan → advance the HD watermark → inline VTXO pull → only THEN surface handler
+     * errors, so safely-discovered funds are recovered even when one handler failed.
+     *
+     * @param opts.gapLimit - Consecutive-unused-index window. Default 20. A non-positive /
+     * non-integer value throws synchronously.
+     *
+     * @note Concurrent calls coalesce onto the running scan; their `gapLimit` is ignored.
+     */
+    restore(opts?: {
+        gapLimit?: number;
+    }): Promise<void>;
+    private _runRestore;
+    readonly settlementConfig: SettlementConfig | false;
+    private _concurrentSpending;
+    private _submitsAwaitingFinalize;
+    /** @see WalletConfig.concurrentSpending */
+    get concurrentSpending(): boolean;
+    /** Public here; `ReadonlyWallet` keeps it protected so a readonly view can't submit. */
+    readonly arkProvider: ArkProvider;
+    /**
+     * Broadcast access bound to this wallet's server, so a plugin needs only the wallet. Not on
+     * {@link ReadonlyWallet}: a readonly wallet or `toReadonly()` view must not be able to submit.
+     */
+    getArkadeBroadcaster(): Promise<ArkadeBroadcaster>;
+    protected constructor(identity: Identity, network: Network, onchainProvider: OnchainProvider, arkProvider: ArkProvider, indexerProvider: IndexerProvider, arkServerPublicKey: Bytes, offchainTapscript: DefaultVtxo.Script | DelegateVtxo.Script, boardingTapscript: DefaultVtxo.Script, serverUnrollScript: CSVMultisigTapscript.Type, forfeitOutputScript: Bytes, forfeitPubkey: Bytes, dustAmount: bigint, walletRepository: WalletRepository, contractRepository: ContractRepository, delegateProvider?: DelegateProvider, watcherConfig?: WalletConfig["watcherConfig"], settlementConfig?: WalletConfig["settlementConfig"], walletContractTimelocks?: RelativeTimelock[], receiveRotator?: WalletReceiveRotator, descriptorProvider?: DescriptorProvider, keyring?: KeyringDescriptorProvider, lookAheadWindow?: number, 
+    /** Overrides for the `batchExpiry` bounds; defaults derive from `network`. */
+    batchExpiryPolicy?: Partial<BatchExpiryPolicy> | undefined);
+    get assetManager(): IAssetManager;
+    getVtxoManager(): Promise<VtxoManager>;
+    dispose(): Promise<void>;
+    /**
+     * Create a full wallet and initialize its background managers.
+     *
+     * @param config - Wallet configuration
+     * @returns A wallet ready to query balances and send transactions
+     * @example
+     * ```typescript
+     * const wallet = await Wallet.create({
+     *   identity,
+     *   arkProvider: new RestArkProvider(),
+     * });
+     * ```
+     */
+    static create<T extends Wallet>(this: {
+        prototype: T;
+    }, config: WalletConfig): Promise<T>;
+    static create(config: WalletConfig): Promise<Wallet>;
+    /**
+     * Convert this wallet to a readonly wallet.
+     *
+     * @returns A readonly wallet with the same configuration but readonly identity
+     * @example
+     * ```typescript
+     * const wallet = await Wallet.create({ identity: MnemonicIdentity.fromMnemonic('abandon abandon...'), ... });
+     * const readonlyWallet = await wallet.toReadonly();
+     *
+     * // Can query balance and addresses
+     * const balance = await readonlyWallet.getBalance();
+     * const address = await readonlyWallet.getAddress();
+     *
+     * // But cannot send transactions (type error)
+     * // readonlyWallet.send(...); // TypeScript error
+     * ```
+     */
+    toReadonly(): Promise<ReadonlyWallet>;
+    /** Returns the delegate manager when delegation support is configured. */
+    getDelegateManager(): Promise<IDelegateManager | undefined>;
+    /**
+     * Settle boarding inputs and/or virtual outputs into a finalized mainnet transaction.
+     *
+     * `params.inputs` is **ungated** (how an escrowed deposit is recovered by hand), so
+     * `settle({ inputs: await wallet.getVtxos() })` bypasses the gate; pass
+     * {@link getSpendableVtxos} to settle "whatever is spendable".
+     *
+     * @param params - Optional settlement inputs and outputs. When omitted, the wallet settles all eligible funds.
+     * @param eventCallback - Optional callback invoked for settlement stream events.
+     * @param hooks - Optional phases for preparation and intent registration.
+     * @returns The finalized Arkade transaction id
+     */
+    settle(params?: SettleParams, eventCallback?: (event: SettlementEvent) => void, hooks?: {
+        onPhase?: (phase: "preparing" | "registration_attempt") => void;
+    }): Promise<string>;
+    private _settleImpl;
+    /**
+     * Rotate-on-board: the boarding analogue of {@link WalletReceiveRotator}'s L2 rotation.
+     * Boarding has no on-chain receive event (the watcher sees only the L2 indexer), so a settle
+     * consuming a boarding UTXO (a non-VTXO, non-arknote input) is the trigger. No-op without a
+     * descriptor provider. Best-effort: the settle has committed, so failures are only logged.
+     */
+    private maybeRotateBoardingAfterBoard;
+    private handleSettlementFinalizationEvent;
+    private unsignableBoardingInputError;
+    /**
+     * Create a batch event handler for settlement flows.
+     *
+     * @param intentId - The intent ID.
+     * @param inputs - Inputs used by the intent.
+     * @param expectedRecipients - Expected recipients to validate in the virtual output tree.
+     * @param session - Optional musig2 signing session. When omitted, signing steps are skipped.
+     */
+    createBatchHandler(intentId: string, inputs: ExtendedCoin[], expectedRecipients: Recipient[], session?: SignerSession): Batch.Handler;
+    /**
+     * Signing jobs keyed by each input's own `witnessUtxo.script`; inputs without one
+     * (cosigner/connector) are silently omitted.
+     */
+    private inputSigningJobsFromWitnessUtxos;
+    /**
+     * Best-effort upsert into {@link intentRepository}; never throws into the settle path.
+     * Preserves fields the event reducer already wrote.
+     */
+    private persistIntentSnapshot;
+    signInputsByWitnessScript(tx: Transaction): Promise<Transaction>;
+    signOnchainBoardingTx(tx: Transaction): Promise<Transaction>;
+    safeRegisterIntent(intent: SignedIntent<Intent.RegisterMessage>, inputs: ExtendedCoin[]): Promise<string>;
+    makeRegisterIntentSignature(coins: ExtendedCoin[], outputs: TransactionOutput[], onchainOutputsIndexes: number[], cosignerPubKeys: string[], validAt?: number): Promise<SignedIntent<Intent.RegisterMessage>>;
+    makeDeleteIntentSignature(coins: ExtendedCoin[]): Promise<SignedIntent<Intent.DeleteMessage>>;
+    makeGetPendingTxIntentSignature(coins: ExtendedVirtualCoin[]): Promise<SignedIntent<Intent.GetPendingTxMessage>>;
+    /**
+     * Finalizes pending transactions by retrieving them from the server and finalizing each one.
+     * Skips the server check entirely when no send was interrupted (no pending tx flag set).
+     * @param vtxos - Optional list of virtual outputs to use instead of retrieving them from the server
+     * @returns Array of transaction IDs that were finalized
+     */
+    finalizePendingTxs(vtxos?: ExtendedVirtualCoin[]): Promise<{
+        finalized: string[];
+        pending: string[];
+    }>;
+    /**
+     * Server unroll scripts a pending checkpoint may have been built under: configured, current,
+     * and one per deprecated signer — else a pre-rotation tx would stay pending forever.
+     */
+    private checkpointUnrollCandidates;
+    private hasPendingTxFlag;
+    private setPendingTxFlag;
+    /**
+     * Create an ArkadeCash bearer instrument: sends `amount` to a DefaultVtxo controlled by a fresh
+     * key and returns the encoded token, claimable via `claimCash()` without sharing an address.
+     *
+     * Short-lived: it carries a private key, so hand it over and claim it promptly. Unclaimed past
+     * its batch expiry it is swept, and `claimCash` can only report it.
+     *
+     * @param amount - Whole sats at or above dust (below dust mints an unspendable OP_RETURN).
+     * @returns The encoded arkadeCash string (e.g., "arkadecash1...")
+     */
+    createCash(amount: number): Promise<string>;
+    /**
+     * Claim an ArkadeCash bearer instrument: sweep what can be swept, recover what
+     * was swept by the server, report the rest.
+     *
+     * Every spendable VTXO at the arkadeCash address is swept to this wallet in
+     * its own offchain transaction, signed with the key carried by the arkadeCash
+     * string. A VTXO the server already swept at batch expiry cannot move
+     * through the thin sweep — only a settlement can lift it — so it is
+     * **imported** as a signable `default` contract (the arkadeCash key is filed
+     * in the keyring) and handed to the wallet's own recovery machinery, which
+     * settles it back on the normal retry cadence. That import is the only
+     * thing `claimCash` persists, and the key is purged once recovery
+     * completes. Anything neither sweepable nor recoverable — subdust, already
+     * claimed, or asset-bearing — is returned in `unclaimed` with a per-VTXO
+     * reason and otherwise ignored.
+     *
+     * The arkadeCash string is the recovery token: a claim interrupted between
+     * submit and finalize is completed by simply re-running `claimCash`, which
+     * drains any pending arkadeCash transaction on the server before sweeping.
+     * The import is idempotent, so re-running is always safe.
+     *
+     * @param cashStr - The encoded arkadeCash string (e.g., "arkadecash1...")
+     * @returns What was swept instantly, what was imported for recovery, and
+     * what was left behind. The shape is open: further buckets may be added.
+     */
+    claimCash(cashStr: string): Promise<ArkadeCashClaimResult>;
+    /**
+     * Import an arkadeCash instrument as a signable, recovery-only contract so the
+     * wallet's own recovery machinery can settle its server-swept VTXOs back.
+     *
+     * Two writes, both idempotent so a re-run (or a resumed claim) is safe:
+     * - the arkadeCash private key is filed in the keyring, returning its
+     *   `tr(<pubkey>)` descriptor;
+     * - a `default` contract for the arkadeCash script is registered carrying that
+     *   descriptor as `metadata.signingDescriptor` (so the signer router can
+     *   sign the swept inputs) and `metadata.recoveryOnly` (so the contract is
+     *   settled in its own isolated intent, never bundled into the wallet's own
+     *   renewal/recovery — a persistently rejected input then dents only its
+     *   own recovery, never the wallet's funds).
+     *
+     * A row may already exist at the script WITHOUT the recovery flags — the
+     * public `createContract` surface lets a consumer register the cash
+     * address (e.g. to watch a note it issued) — and `createContract`'s
+     * same-type idempotency keeps such a row as-is. It is then promoted:
+     * presenting the bearer key IS the authorization to claim, and left
+     * unflagged the row would feed unsignable swept VTXOs into the wallet's
+     * own settles while being invisible to both the isolated recovery pass
+     * and `removeRecoveryContract`'s purge.
+     */
+    private importArkadeCashForRecovery;
+    /** Best-effort, non-blocking trigger of the isolated imported-recovery pass. */
+    private kickImportedRecovery;
+    /**
+     * Retire a contract imported for recovery once its funds have been settled
+     * back: purge the keyring key that backed it, then delete the contract row.
+     * Ends the key-at-rest window opened by {@link importArkadeCashForRecovery}.
+     *
+     * Scoped to recovery-only contracts as a safety guard — it will not touch a
+     * regular wallet contract — and idempotent: a second call (the contract
+     * already gone) is a no-op. Invoked by the isolated recovery pass in
+     * `VtxoManager` (see its `RecoveryContractCapableWallet` capability).
+     *
+     * The write order is load-bearing; do not swap it. The two repositories
+     * cannot be written atomically, so one of them leaks on a partial failure.
+     * Purging the key first leaves a contract row with a dangling descriptor:
+     * visible, harmless, and retried to completion by the next recovery pass
+     * (its VTXOs read back spent, so nothing is signed). The reverse leaves an
+     * unencrypted key that nothing references — the descriptor lived only in
+     * the row just deleted — so no retry can ever find it, breaking the
+     * purge-on-completion bound that justifies storing it in the clear.
+     */
+    removeRecoveryContract(script: string): Promise<void>;
+    /**
+     * Split the VTXOs at an arkadeCash address into three buckets: the ones the
+     * thin sweep can move (`spendable`), the server-swept ones that must go
+     * through a recovery settlement (`recoverable`), and the ones that can
+     * only be reported (`unclaimed`).
+     */
+    private classifyCashVtxos;
+    /** Read every page of an unfiltered VTXO query for the given scripts. */
+    private fetchAllVtxos;
+    /**
+     * Complete sweeps a previous `claimCash` registered but never finalized: a thin
+     * {@link finalizePendingTxs} signed with the arkadeCash key. A drained tx pays whoever
+     * registered it, so finalizing is still right, but only value paid to `myPkScript` counts.
+     *
+     * @param vtxos - VTXOs at the cash contract's own pkScript, spent included; any other
+     * outpoint (subdust above all) would invalidate the proof.
+     * @returns Txs finalized, sats paid to this wallet, and the outpoints consumed to pay it.
+     */
+    private finalizePendingCashTxs;
+    /** Sum the outputs of an ark tx PSBT that pay the given scriptPubKey. */
+    private arkTxAmountPaidTo;
+    /**
+     * Send BTC and/or assets to one or more recipients, passed either as
+     * variadic `Recipient`s or as a single `SendParams` object — the latter
+     * also carries the virtual outputs to spend.
+     *
+     * @param args - Recipients, or a `SendParams` object
+     * @returns Promise resolving to the Arkade transaction ID
+     * @see SendParams
+     *
+     * @example
+     * ```typescript
+     * const txid = await wallet.send({
+     *     address: 'ark1q...',
+     *     amount: 1000, // (optional, default to dust) btc amount to send to the output
+     *     assets: [{ assetId: 'abc123...', amount: 50n }] // (optional) list of assets to send
+     * });
+     *
+     * // choosing the inputs as well as the outputs
+     * const txid = await wallet.send({
+     *     recipients: [{ address: 'ark1q...', amount: 1000 }],
+     *     selectedVtxos: mine, // spent as given, nothing added
+     * });
+     * ```
+     */
+    send(...args: [SendParams] | [Recipient, ...Recipient[]]): Promise<string>;
+    private _sendImpl;
+    /**
+     * Shared submit/persist tail of `send` and {@link sendSelectedVtxosToSelf}; callers own coin
+     * selection, outputs and the synchronous epoch snapshot.
+     */
+    private _submitOffchainSpend;
+    /**
+     * @internal Migration primitive for {@link VtxoManager}: spend the wallet's own
+     * deprecated-signer VTXOs into one full-value output on the *active* signer, via the Ark send
+     * path (not `settle`) so arkd builds checkpoints against the active epoch. No boarding inputs.
+     * The caller must already be on the active signer and have sized the batch. Preserves all
+     * input assets; records no `TxSent` history.
+     */
+    sendSelectedVtxosToSelf(inputs: ExtendedVirtualCoin[], now?: TimeHeight): Promise<string>;
+    /**
+     * Build an offchain transaction from the given inputs and outputs,
+     * sign it, submit to the Arkade provider, and finalize.
+     *
+     * Signs whatever it is handed, ungated — see {@link settle} for the trade.
+     *
+     * @returns The Arkade transaction id and server-signed checkpoint PSBTs (for bookkeeping)
+     */
+    buildAndSubmitOffchainTx(inputs: ExtendedVirtualCoin[], outputs: TransactionOutput[], serverUnrollScript?: CSVMultisigTapscript.Type, options?: {
+        validUntil?: number;
+    }): Promise<{
+        arkTxid: string;
+        signedCheckpointTxs: string[];
+    }>;
+    private _buildAndSubmitOffchainTx;
+    private updateDbAfterOffchainTx;
+    private updateDbAfterSettle;
+}
+/**
+ * Select virtual outputs to reach a target amount, prioritizing those closer to expiry
+ * @param coins List of virtual outputs to select from
+ * @param targetAmount Target amount to reach in satoshis
+ * @returns Selected virtual outputs and change amount
+ */
+declare function selectVirtualCoins(coins: ExtendedVirtualCoin[], targetAmount: number): {
+    inputs: ExtendedVirtualCoin[];
+    changeAmount: bigint;
+};
+/**
+ * Raised when a wait is cancelled through its `AbortSignal` or `timeoutMs`. `name` is
+ * `"AbortError"`, so DOM and SDK aborts can be handled identically.
+ */
+declare class AbortError extends Error {
+    constructor(message?: string);
+}
+/**
+ * A VTXO named for a spend or a hold is held, or already being spent by another operation.
+ * Match on `name`, not `instanceof`: only the name survives the service-worker boundary.
+ */
+declare class VtxoReservedError extends Error {
+    readonly outpoints: readonly string[];
+    readonly holder: "in-flight" | "held";
+    readonly name = "VtxoReservedError";
+    constructor(outpoints: readonly string[], holder: "in-flight" | "held");
+}
+/** A hold placed by {@link Wallet.reserveVtxos}. */
+interface VtxoReservation {
+    readonly outpoints: readonly Outpoint[];
+    /** Idempotent. */
+    release(): void;
+}
+/** @internal Submits an Arkade transaction for {@link Wallet.withSpendLock}'s caller. */
+type OffchainSubmit = (inputs: ExtendedVirtualCoin[], outputs: TransactionOutput[]) => Promise<{
+    arkTxid: string;
+    signedCheckpointTxs: string[];
+}>;
+/** Options for {@link waitForIncomingFunds}. */
+interface WaitForIncomingFundsOptions {
+    /**
+     * Cancels the wait. On abort the underlying subscription is stopped and
+     * the returned promise rejects — with the signal's `reason` when the
+     * caller supplied an `Error`, otherwise an {@link AbortError}.
+     */
+    signal?: AbortSignal;
+    /**
+     * Cancels the wait after this many milliseconds, rejecting with an
+     * {@link AbortError}. Equivalent to passing an `AbortSignal.timeout`
+     * signal, without requiring that API on the target platform.
+     */
+    timeoutMs?: number;
+}
+/**
+ * Wait for incoming funds to the wallet.
+ *
+ * Keeps live network watchers open until it settles. **Cancel it if you won't await it to
+ * completion** (`signal` / `timeoutMs`): a `Promise.race` against a timer abandons the loser
+ * without stopping its watchers, and in a loop stacks subscriptions until the process exits.
+ *
+ * @param wallet - The wallet to wait for incoming funds
+ * @param options - Cancellation options; see {@link WaitForIncomingFundsOptions}
+ * @returns A promise that resolves the next new coins received by the wallet's address
+ * @throws {AbortError} If cancelled via `signal` or `timeoutMs`
+ * @example
+ * ```typescript
+ * // Wake early on a deposit, but give up after 30s and release the watchers.
+ * try {
+ *   const funds = await waitForIncomingFunds(wallet, { timeoutMs: 30_000 })
+ * } catch (e) {
+ *   if ((e as Error).name !== "AbortError") throw e
+ * }
+ * ```
+ */
+declare function waitForIncomingFunds(wallet: Wallet, options?: WaitForIncomingFundsOptions): Promise<IncomingFunds>;
+
+export { type AddressAllocationCapable as A, type BatchExpiryPolicy as B, isArkError as C, DEFAULT_MIN_BATCH_EXPIRY_SECONDS as D, isHDAllocationCapable as E, ForeignDescriptorError as F, isHDWalletCapable as G, type HDWalletCapable as H, type IncomingFunds as I, maybeArkError as J, KeyringDescriptorProvider as K, resolveBatchExpiryPolicy as L, MAX_USED_SIGNING_DESCRIPTORS_LOOK_AHEAD as M, resolveDescriptorSigner as N, selectVirtualCoins as O, type ProviderConnectionState as P, signingDescriptorIndex as Q, ReadonlyWallet as R, type ServerInfoSource as S, strictSigningDescriptorIndex as T, waitForIncomingFunds as U, type VtxoReservation as V, Wallet as W, type HDAllocationCapable as a, type ReceiveRotatorFactory as b, type ReceiveRotatorBootOpts as c, type ReceiveRotatorBoot as d, Batch as e, AbortError as f, ArkError as g, ArkErrorName as h, type ArkadeCashClaimResult as i, ArkadeCashCreateError as j, ArkadeCashOperatorMismatchError as k, type ArkadeCashUnclaimedReason as l, type ArkadeCashUnclaimedVtxo as m, type ArkadeCashVtxoRef as n, type BoardingUtxoGroup as o, IndexedDBWalletRepository as p, type ProviderKind as q, ProviderUnavailableError as r, REGTEST_MIN_BATCH_EXPIRY_SECONDS as s, ServerResponseMismatchError as t, VtxoReservedError as u, type WaitForIncomingFundsOptions as v, WalletCannotAllocateAddressError as w, assertValidBatchExpiry as x, defaultBatchExpiryPolicy as y, isAddressAllocationCapable as z };