@arkade-os/sdk 0.4.58 → 0.4.60

package/dist/{wallet-hQp2qC_M.d.cts → wallet-C_MYHyOj.d.ts}

@@ -1,8 +1,8 @@
-import { a as Identity, p as RelativeTimelock, J as Network, K as CSVMultisigTapscript, L as SignerSet, M as BatchStartedEvent, P as TreeSigningStartedEvent, Q as TxTree, U as TreeNoncesEvent, X as BatchFinalizationEvent, Y as BatchFinalizedEvent, Z as BatchFailedEvent, _ as TreeTxEvent, $ as TreeSignatureEvent, i as SettlementEvent, b as WalletConfig, W as WalletRepository, C as ContractRepository, a0 as DescriptorProvider, f as IContractManager, a1 as IReadonlyWallet, a2 as ReadonlyIdentity, a3 as OnchainProvider, o as IndexerProvider, a4 as DelegateProvider, a5 as ReadonlyWalletConfig, x as IntentRepository, B as VirtualTxRepository, a6 as ExitCaptureMode, a7 as ExitDataSource, d as ActivityRegistry, a8 as IReadonlyAssetManager, a9 as ContractSyncState, n as ArkProvider, aa as NetworkName, ab as ArkInfo, ac as ArkAddress, c as WalletBalance, G as GetVtxosFilter, N as NormalizedExtendedVirtualCoin, A as ArkTransaction, e as Activity, E as ExtendedCoin, ad as Coin, t as ExtendedVirtualCoin, ae as ContractManager, af as ContractManagerConfig, I as IWallet, ag as SettlementConfig, j as IAssetManager, ah as VtxoManager, g as IDelegateManager, S as SendBitcoinParams, h as SettleParams, R as Recipient, ai as SignerSession, aj as SignedIntent, ak as Intent, al as TimeHeight } from './ark-ClaVUg4e.cjs';
+import { a as Identity, p as RelativeTimelock, J as Network, K as CSVMultisigTapscript, L as BatchStartedEvent, M as TreeSigningStartedEvent, P as TxTree, Q as TreeNoncesEvent, U as BatchFinalizationEvent, X as BatchFinalizedEvent, Y as BatchFailedEvent, Z as TreeTxEvent, _ as TreeSignatureEvent, i as SettlementEvent, b as WalletConfig, W as WalletRepository, C as ContractRepository, $ as DescriptorProvider, f as IContractManager, a0 as IReadonlyWallet, a1 as ReadonlyIdentity, a2 as OnchainProvider, o as IndexerProvider, a3 as DelegateProvider, a4 as ReadonlyWalletConfig, x as IntentRepository, B as VirtualTxRepository, a5 as ExitCaptureMode, a6 as ExitDataSource, d as ActivityRegistry, a7 as IReadonlyAssetManager, a8 as ContractSyncState, a9 as RecipientAddressContext, n as ArkProvider, aa as NetworkName, ab as ArkInfo, ac as ArkAddress, c as WalletBalance, G as GetVtxosFilter, N as NormalizedExtendedVirtualCoin, ad as ContractWithVtxos, ae as selectPendingRecoveryOutpoints, A as ArkTransaction, e as Activity, E as ExtendedCoin, af as Coin, t as ExtendedVirtualCoin, ag as ContractManager, ah as ContractManagerConfig, I as IWallet, ai as SettlementConfig, j as IAssetManager, aj as VtxoManager, g as IDelegateManager, S as SendBitcoinParams, h as SettleParams, R as Recipient, ak as SignerSession, al as SignedIntent, am as Intent, an as TimeHeight } from './ark-D2_yNhfz.js';
 import { Transaction } from '@scure/btc-signer';
 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-CVrkEepn.cjs';
+import { D as DefaultVtxo, a as DelegateVtxo } from './delegate-DidNTsKm.js';
 
 /**
  * Capability a wallet exposes so descriptor-blind consumers — Boltz swaps and
@@ -24,8 +24,14 @@ interface HDWalletCapable {
      * 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 descriptors past the watermark without
+     * advancing it, for a restore that must probe indices no local state
+     * mentions yet.
      */
-    getUsedSigningDescriptors(): Promise<string[]>;
+    getUsedSigningDescriptors(opts?: {
+        lookAhead?: number;
+    }): Promise<string[]>;
     /**
      * An {@link Identity} whose keys and signatures are those of `descriptor`.
      * Returns the wallet identity itself when the wallet has no descriptor
@@ -35,6 +41,39 @@ interface HDWalletCapable {
 }
 /** Structural type guard for {@link HDWalletCapable}. */
 declare function isHDWalletCapable(value: unknown): value is HDWalletCapable;
+/**
+ * Allocating a *fresh* index, which is strictly more than
+ * {@link HDWalletCapable}'s descriptor awareness.
+ *
+ * Deliberately a separate probe rather than three more methods on
+ * `HDWalletCapable`: widening that guard would silently demote every wallet
+ * implementing only its original surface — including one built by an older
+ * SDK — from HD-capable to static, which is exactly the breakage it documents
+ * itself as avoiding. Consumers that only read descriptors keep the narrow
+ * probe; anything deriving per-artifact secrets asks for this one.
+ */
+interface HDAllocationCapable {
+    /**
+     * Allocate the next descriptor, advancing the watermark. `undefined` for
+     * static / `auto` wallets, which cannot allocate.
+     *
+     * Distinct from {@link HDWalletCapable.getCurrentSigningDescriptor}, which
+     * peeks: two artifacts bound to a peek share a key.
+     */
+    getNextSigningDescriptor(): Promise<string | undefined>;
+    /**
+     * Move the allocation watermark to `descriptor`'s index so later
+     * allocations cannot reissue it. Monotonic — a lower index is a no-op.
+     *
+     * Throws on a descriptor this wallet cannot derive, or one with no
+     * parseable trailing child index: silently mapping those to index 0 would
+     * move the watermark nowhere and let a restored artifact's index be handed
+     * out again.
+     */
+    advanceSigningDescriptorWatermark(descriptor: string): Promise<void>;
+}
+/** Structural type guard for {@link HDAllocationCapable}. */
+declare function isHDAllocationCapable(value: unknown): value is HDAllocationCapable;
 
 /** Wall-clock floor for `batchExpiry` outside regtest. */
 declare const DEFAULT_MIN_BATCH_EXPIRY_SECONDS = 86400n;
@@ -86,6 +125,27 @@ declare const DEFAULT_MIN_CHECKPOINT_EXIT_DELAY_SECONDS = 86400n;
  * 1-block attack.
  */
 declare const REGTEST_MIN_CHECKPOINT_EXIT_DELAY_SECONDS = 1200n;
+/**
+ * Wall-clock floor for the checkpoint exit delay on mutinynet.
+ *
+ * The hosted mutinynet Arkade Service advertises exactly this: its
+ * `checkpointTapscript` decodes to a 4096s (8 * 512) CSV, sized for a chain
+ * that mines ~30s blocks. {@link DEFAULT_MIN_CHECKPOINT_EXIT_DELAY_SECONDS}
+ * rejects it, which left mutinynet unusable until the caller went and found
+ * `minCheckpointExitDelaySeconds` and then this number.
+ */
+declare const MUTINYNET_MIN_CHECKPOINT_EXIT_DELAY_SECONDS = 4096n;
+/**
+ * Wall-clock floor for the checkpoint exit delay on signet.
+ *
+ * The hosted signet Arkade Service advertises 86016s (168 * 512): a 24h
+ * setting rounded down to BIP-68's 512s granularity, since 86400 is not a
+ * multiple of 512 and so cannot be encoded in a seconds-typed timelock at all.
+ * That lands 384s under {@link DEFAULT_MIN_CHECKPOINT_EXIT_DELAY_SECONDS} and
+ * is rejected by it, so signet needs its own floor for the same reason
+ * mutinynet does.
+ */
+declare const SIGNET_MIN_CHECKPOINT_EXIT_DELAY_SECONDS = 86016n;
 /** Bounds applied to a server-supplied `ArkInfo.checkpointTapscript`. */
 type CheckpointExitDelayPolicy = {
     /** Minimum wall-clock delay in seconds, after normalization. */
@@ -131,17 +191,6 @@ declare function resolveCheckpointExitDelayPolicy(network: Network, overrides?:
  */
 declare function assertValidServerUnrollScript(checkpointTapscript: string, policy: CheckpointExitDelayPolicy): CSVMultisigTapscript.Type;
 
-declare function getRandomId(): string;
-/**
- * What a recipient Arkade address must match. An address failing either check
- * belongs to another network or operator, so this wallet's operator cannot
- * create the VTXO where the recipient's wallet expects it.
- */
-type RecipientAddressContext = {
-    hrp: string;
-    signerSet: SignerSet;
-};
-
 declare class ArkError extends Error {
     readonly code: number;
     readonly message: string;
@@ -422,6 +471,21 @@ interface ReceiveRotatorBootResult {
 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 the
+ * descriptor is absent or carries no parseable child index — restore
+ * registers the index-0 baseline untagged, so a missing descriptor
+ * legitimately maps to 0.
+ */
+declare function signingDescriptorIndex(descriptor: unknown): number;
+/**
+ * Strict sibling of {@link signingDescriptorIndex}: `undefined` instead of
+ * the 0 fallback, for callers that must tell "no parseable index" apart from
+ * index 0 — a watermark move mapped to 0 would move nothing while reporting
+ * success.
+ */
+declare function strictSigningDescriptorIndex(descriptor: string): number | undefined;
 /**
  * Minimal logging surface the rotator needs. `console` satisfies it
  * out of the box; SDK consumers can pass a structured logger
@@ -617,6 +681,12 @@ declare class WalletReceiveRotator {
     private rotate;
 }
 
+/**
+ * Maximum caller-requested HD descriptors materialized past the watermark by
+ * getUsedSigningDescriptors(). Bounds plugin/restore probes without changing
+ * the wallet's actual allocation watermark.
+ */
+declare const MAX_USED_SIGNING_DESCRIPTORS_LOOK_AHEAD = 1000;
 type IncomingFunds = {
     type: "utxo";
     coins: Coin[];
@@ -626,6 +696,13 @@ type IncomingFunds = {
     spentVtxos: ExtendedVirtualCoin[];
 };
 
+/**
+ * What signer classification needs of a snapshot: contract params and the coins
+ * under them. Structural rather than {@link ContractWithVtxos} so a repository-
+ * built snapshot — the worker's, whose VTXOs carry no `contractScript` — can be
+ * classified without allocating a parallel array to satisfy the nominal type.
+ */
+type PendingRecoverySnapshot = Parameters<typeof selectPendingRecoveryOutpoints>[0];
 /**
  * Boarding UTXOs grouped by the boarding address they sit on, carrying that
  * address's signer association explicitly. Returned by
@@ -955,18 +1032,80 @@ declare class ReadonlyWallet implements IReadonlyWallet {
     /**
      * Return virtual outputs tracked by the wallet.
      *
+     * The raw reporting/recovery read: escrowed, locked and awaiting-recovery
+     * funds are all present. Coin selection must use
+     * {@link getSpendableVtxos} instead — feeding this straight into
+     * `settle({ inputs })` or `sendBitcoin({ selectedVtxos })` bypasses the
+     * generic-spending gate.
+     *
      * @param filter - Optional flags controlling whether recoverable or unrolled VTXOs are included
      */
     getVtxos(filter?: GetVtxosFilter): Promise<NormalizedExtendedVirtualCoin[]>;
+    /** @inheritdoc */
+    getSpendableVtxos(filter?: GetVtxosFilter): Promise<NormalizedExtendedVirtualCoin[]>;
+    /**
+     * Debug-log any explicit input generic selection would have excluded, for
+     * each of the three reasons it excludes on. Explicit-input APIs stay ungated
+     * on purpose (naming an outpoint *is* the intent the gate protects, and it
+     * is how an escrowed deposit is recovered once generic selection stops
+     * covering it), so this only makes the crossing visible — notably
+     * `settle({ inputs: await wallet.getVtxos() })`, which launders the raw read
+     * into a spend. Never throws into a spend path.
+     *
+     * Public so the worker handler and plugins can report their own
+     * explicit-input crossings through the same three checks.
+     */
+    logUngatedInputs(source: string, inputs: readonly {
+        txid: string;
+        vout: number;
+        script?: string;
+    }[]): Promise<void>;
+    /**
+     * Contracts whose operator signer is past its rotation cutoff, as an
+     * exclusion over scripts. The outpoint-level `pendingRecovery` set needs a
+     * synced VTXO snapshot to also drop already-swept coins; this answers the
+     * same question about a caller-supplied input without one, and a swept
+     * outpoint is unspendable regardless.
+     */
+    private expiredSignerExclusion;
+    /** The intent store's lock set. Fails open, like every other read of it. */
+    private lockedOutpoints;
+    /**
+     * One contract+VTXO read. `getContractsWithVtxos` opportunistically syncs
+     * against the indexer, so every caller that needs more than one view of the
+     * wallet's coins takes a single snapshot and derives them all from it —
+     * otherwise the gate and the pending-recovery set answer about two different
+     * points in time, and each read costs another sync.
+     */
+    protected contractSnapshot(): 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 VTXOs whose deprecated signer is past its cutoff (EXPIRED) and
      * which have not yet been swept — unspendable until they recover. Offline:
      * classifies the repo's contracts against the cached signer set (active +
      * {@link _deprecatedSigners}, cutoffs included). Empty fast-path when no
      * signer is deprecated. Consumed by {@link getBalance} (the `pendingRecovery`
-     * bucket) and the send coin-selection path so neither counts nor spends them.
+     * bucket) and by {@link getSpendableVtxos} so neither counts nor spends them.
+     *
+     * Takes a fresh {@link contractSnapshot}, which syncs against the indexer.
+     * Callers that already hold a snapshot — or that must not sync at all, like
+     * the worker's balance read — pass it to
+     * {@link pendingRecoveryOutpointsIn} instead.
      */
     pendingRecoveryOutpoints(): Promise<Set<string>>;
+    /**
+     * {@link pendingRecoveryOutpoints} over a snapshot the caller already has:
+     * pure classification against the cached signer set, no repository or
+     * network read of its own.
+     */
+    pendingRecoveryOutpointsIn(snapshot: PendingRecoverySnapshot): Set<string>;
+    private selectPendingRecovery;
     /**
      * Return wallet transaction history derived from Arkade state and boarding transactions.
      */
@@ -1309,6 +1448,14 @@ declare class Wallet extends ReadonlyWallet implements IWallet, HDWalletCapable
      * @see HDWalletCapable.getCurrentSigningDescriptor
      */
     getCurrentSigningDescriptor(): Promise<string | undefined>;
+    /**
+     * @see HDWalletCapable.getNextSigningDescriptor
+     */
+    getNextSigningDescriptor(): Promise<string | undefined>;
+    /**
+     * @see HDWalletCapable.advanceSigningDescriptorWatermark
+     */
+    advanceSigningDescriptorWatermark(descriptor: string): Promise<void>;
     /**
      * @see HDWalletCapable.getUsedSigningDescriptors
      *
@@ -1317,7 +1464,9 @@ declare class Wallet extends ReadonlyWallet implements IWallet, HDWalletCapable
      * alone would miss indices allocated for something the wallet never
      * persisted (a swap, an externally issued invoice).
      */
-    getUsedSigningDescriptors(): Promise<string[]>;
+    getUsedSigningDescriptors(opts?: {
+        lookAhead?: number;
+    }): Promise<string[]>;
     /**
      * @see HDWalletCapable.signerForDescriptor
      */
@@ -1458,6 +1607,13 @@ declare class Wallet extends ReadonlyWallet implements IWallet, HDWalletCapable
     /**
      * Settle boarding inputs and/or virtual outputs into a finalized mainnet transaction.
      *
+     * `params.inputs` is **ungated**: whatever the caller names is settled,
+     * including VTXOs generic selection would skip. That is what makes an
+     * escrowed or otherwise gated deposit recoverable by hand — but it also
+     * means `settle({ inputs: await wallet.getVtxos() })` silently bypasses the
+     * gate. Pass {@link getSpendableVtxos} instead when the intent is "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.
      * @returns The finalized Arkade transaction id
@@ -1660,6 +1816,9 @@ declare class Wallet extends ReadonlyWallet implements IWallet, HDWalletCapable
     /**
      * 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): Promise<{
@@ -1686,4 +1845,4 @@ declare function selectVirtualCoins(coins: ExtendedVirtualCoin[], targetAmount:
  */
 declare function waitForIncomingFunds(wallet: Wallet): Promise<IncomingFunds>;
 
-export { ArkError as A, type BatchExpiryPolicy as B, type CheckpointExitDelayPolicy as C, DEFAULT_MIN_BATCH_EXPIRY_SECONDS as D, selectVirtualCoins as E, waitForIncomingFunds as F, type HDWalletCapable as H, type IncomingFunds as I, type ProviderConnectionState as P, ReadonlyWallet as R, type ServerInfoSource as S, Wallet as W, type ReceiveRotatorFactory as a, type ReceiveRotatorBootOpts as b, type ReceiveRotatorBoot as c, Batch as d, ArkErrorName as e, type ArkadeCashClaimResult as f, ArkadeCashCreateError as g, type ArkadeCashUnclaimedReason as h, type ArkadeCashUnclaimedVtxo as i, type BoardingUtxoGroup as j, DEFAULT_MIN_CHECKPOINT_EXIT_DELAY_SECONDS as k, type ProviderKind as l, ProviderUnavailableError as m, REGTEST_MIN_BATCH_EXPIRY_SECONDS as n, REGTEST_MIN_CHECKPOINT_EXIT_DELAY_SECONDS as o, ServerResponseMismatchError as p, assertValidBatchExpiry as q, assertValidServerUnrollScript as r, defaultBatchExpiryPolicy as s, defaultCheckpointExitDelayPolicy as t, getRandomId as u, isArkError as v, isHDWalletCapable as w, maybeArkError as x, resolveBatchExpiryPolicy as y, resolveCheckpointExitDelayPolicy as z };
+export { ArkError as A, type BatchExpiryPolicy as B, type CheckpointExitDelayPolicy as C, DEFAULT_MIN_BATCH_EXPIRY_SECONDS as D, maybeArkError as E, resolveBatchExpiryPolicy as F, resolveCheckpointExitDelayPolicy as G, type HDWalletCapable as H, type IncomingFunds as I, selectVirtualCoins as J, signingDescriptorIndex as K, strictSigningDescriptorIndex as L, MAX_USED_SIGNING_DESCRIPTORS_LOOK_AHEAD as M, waitForIncomingFunds as N, type ProviderConnectionState as P, ReadonlyWallet as R, SIGNET_MIN_CHECKPOINT_EXIT_DELAY_SECONDS as S, Wallet as W, type ReceiveRotatorFactory as a, type ReceiveRotatorBootOpts as b, type ReceiveRotatorBoot as c, type HDAllocationCapable as d, Batch as e, ArkErrorName as f, type ArkadeCashClaimResult as g, ArkadeCashCreateError as h, type ArkadeCashUnclaimedReason as i, type ArkadeCashUnclaimedVtxo as j, type BoardingUtxoGroup as k, DEFAULT_MIN_CHECKPOINT_EXIT_DELAY_SECONDS as l, MUTINYNET_MIN_CHECKPOINT_EXIT_DELAY_SECONDS as m, type ProviderKind as n, ProviderUnavailableError as o, REGTEST_MIN_BATCH_EXPIRY_SECONDS as p, REGTEST_MIN_CHECKPOINT_EXIT_DELAY_SECONDS as q, type ServerInfoSource as r, ServerResponseMismatchError as s, assertValidBatchExpiry as t, assertValidServerUnrollScript as u, defaultBatchExpiryPolicy as v, defaultCheckpointExitDelayPolicy as w, isArkError as x, isHDAllocationCapable as y, isHDWalletCapable as z };

package/dist/{wallet-DnK09TtT.d.ts → wallet-ipUA1XCp.d.cts}

@@ -1,8 +1,8 @@
-import { a as Identity, p as RelativeTimelock, J as Network, K as CSVMultisigTapscript, L as SignerSet, M as BatchStartedEvent, P as TreeSigningStartedEvent, Q as TxTree, U as TreeNoncesEvent, X as BatchFinalizationEvent, Y as BatchFinalizedEvent, Z as BatchFailedEvent, _ as TreeTxEvent, $ as TreeSignatureEvent, i as SettlementEvent, b as WalletConfig, W as WalletRepository, C as ContractRepository, a0 as DescriptorProvider, f as IContractManager, a1 as IReadonlyWallet, a2 as ReadonlyIdentity, a3 as OnchainProvider, o as IndexerProvider, a4 as DelegateProvider, a5 as ReadonlyWalletConfig, x as IntentRepository, B as VirtualTxRepository, a6 as ExitCaptureMode, a7 as ExitDataSource, d as ActivityRegistry, a8 as IReadonlyAssetManager, a9 as ContractSyncState, n as ArkProvider, aa as NetworkName, ab as ArkInfo, ac as ArkAddress, c as WalletBalance, G as GetVtxosFilter, N as NormalizedExtendedVirtualCoin, A as ArkTransaction, e as Activity, E as ExtendedCoin, ad as Coin, t as ExtendedVirtualCoin, ae as ContractManager, af as ContractManagerConfig, I as IWallet, ag as SettlementConfig, j as IAssetManager, ah as VtxoManager, g as IDelegateManager, S as SendBitcoinParams, h as SettleParams, R as Recipient, ai as SignerSession, aj as SignedIntent, ak as Intent, al as TimeHeight } from './ark-ClaVUg4e.js';
+import { a as Identity, p as RelativeTimelock, J as Network, K as CSVMultisigTapscript, L as BatchStartedEvent, M as TreeSigningStartedEvent, P as TxTree, Q as TreeNoncesEvent, U as BatchFinalizationEvent, X as BatchFinalizedEvent, Y as BatchFailedEvent, Z as TreeTxEvent, _ as TreeSignatureEvent, i as SettlementEvent, b as WalletConfig, W as WalletRepository, C as ContractRepository, $ as DescriptorProvider, f as IContractManager, a0 as IReadonlyWallet, a1 as ReadonlyIdentity, a2 as OnchainProvider, o as IndexerProvider, a3 as DelegateProvider, a4 as ReadonlyWalletConfig, x as IntentRepository, B as VirtualTxRepository, a5 as ExitCaptureMode, a6 as ExitDataSource, d as ActivityRegistry, a7 as IReadonlyAssetManager, a8 as ContractSyncState, a9 as RecipientAddressContext, n as ArkProvider, aa as NetworkName, ab as ArkInfo, ac as ArkAddress, c as WalletBalance, G as GetVtxosFilter, N as NormalizedExtendedVirtualCoin, ad as ContractWithVtxos, ae as selectPendingRecoveryOutpoints, A as ArkTransaction, e as Activity, E as ExtendedCoin, af as Coin, t as ExtendedVirtualCoin, ag as ContractManager, ah as ContractManagerConfig, I as IWallet, ai as SettlementConfig, j as IAssetManager, aj as VtxoManager, g as IDelegateManager, S as SendBitcoinParams, h as SettleParams, R as Recipient, ak as SignerSession, al as SignedIntent, am as Intent, an as TimeHeight } from './ark-D2_yNhfz.cjs';
 import { Transaction } from '@scure/btc-signer';
 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-YDYq1El_.js';
+import { D as DefaultVtxo, a as DelegateVtxo } from './delegate-DNEuM_nK.cjs';
 
 /**
  * Capability a wallet exposes so descriptor-blind consumers — Boltz swaps and
@@ -24,8 +24,14 @@ interface HDWalletCapable {
      * 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 descriptors past the watermark without
+     * advancing it, for a restore that must probe indices no local state
+     * mentions yet.
      */
-    getUsedSigningDescriptors(): Promise<string[]>;
+    getUsedSigningDescriptors(opts?: {
+        lookAhead?: number;
+    }): Promise<string[]>;
     /**
      * An {@link Identity} whose keys and signatures are those of `descriptor`.
      * Returns the wallet identity itself when the wallet has no descriptor
@@ -35,6 +41,39 @@ interface HDWalletCapable {
 }
 /** Structural type guard for {@link HDWalletCapable}. */
 declare function isHDWalletCapable(value: unknown): value is HDWalletCapable;
+/**
+ * Allocating a *fresh* index, which is strictly more than
+ * {@link HDWalletCapable}'s descriptor awareness.
+ *
+ * Deliberately a separate probe rather than three more methods on
+ * `HDWalletCapable`: widening that guard would silently demote every wallet
+ * implementing only its original surface — including one built by an older
+ * SDK — from HD-capable to static, which is exactly the breakage it documents
+ * itself as avoiding. Consumers that only read descriptors keep the narrow
+ * probe; anything deriving per-artifact secrets asks for this one.
+ */
+interface HDAllocationCapable {
+    /**
+     * Allocate the next descriptor, advancing the watermark. `undefined` for
+     * static / `auto` wallets, which cannot allocate.
+     *
+     * Distinct from {@link HDWalletCapable.getCurrentSigningDescriptor}, which
+     * peeks: two artifacts bound to a peek share a key.
+     */
+    getNextSigningDescriptor(): Promise<string | undefined>;
+    /**
+     * Move the allocation watermark to `descriptor`'s index so later
+     * allocations cannot reissue it. Monotonic — a lower index is a no-op.
+     *
+     * Throws on a descriptor this wallet cannot derive, or one with no
+     * parseable trailing child index: silently mapping those to index 0 would
+     * move the watermark nowhere and let a restored artifact's index be handed
+     * out again.
+     */
+    advanceSigningDescriptorWatermark(descriptor: string): Promise<void>;
+}
+/** Structural type guard for {@link HDAllocationCapable}. */
+declare function isHDAllocationCapable(value: unknown): value is HDAllocationCapable;
 
 /** Wall-clock floor for `batchExpiry` outside regtest. */
 declare const DEFAULT_MIN_BATCH_EXPIRY_SECONDS = 86400n;
@@ -86,6 +125,27 @@ declare const DEFAULT_MIN_CHECKPOINT_EXIT_DELAY_SECONDS = 86400n;
  * 1-block attack.
  */
 declare const REGTEST_MIN_CHECKPOINT_EXIT_DELAY_SECONDS = 1200n;
+/**
+ * Wall-clock floor for the checkpoint exit delay on mutinynet.
+ *
+ * The hosted mutinynet Arkade Service advertises exactly this: its
+ * `checkpointTapscript` decodes to a 4096s (8 * 512) CSV, sized for a chain
+ * that mines ~30s blocks. {@link DEFAULT_MIN_CHECKPOINT_EXIT_DELAY_SECONDS}
+ * rejects it, which left mutinynet unusable until the caller went and found
+ * `minCheckpointExitDelaySeconds` and then this number.
+ */
+declare const MUTINYNET_MIN_CHECKPOINT_EXIT_DELAY_SECONDS = 4096n;
+/**
+ * Wall-clock floor for the checkpoint exit delay on signet.
+ *
+ * The hosted signet Arkade Service advertises 86016s (168 * 512): a 24h
+ * setting rounded down to BIP-68's 512s granularity, since 86400 is not a
+ * multiple of 512 and so cannot be encoded in a seconds-typed timelock at all.
+ * That lands 384s under {@link DEFAULT_MIN_CHECKPOINT_EXIT_DELAY_SECONDS} and
+ * is rejected by it, so signet needs its own floor for the same reason
+ * mutinynet does.
+ */
+declare const SIGNET_MIN_CHECKPOINT_EXIT_DELAY_SECONDS = 86016n;
 /** Bounds applied to a server-supplied `ArkInfo.checkpointTapscript`. */
 type CheckpointExitDelayPolicy = {
     /** Minimum wall-clock delay in seconds, after normalization. */
@@ -131,17 +191,6 @@ declare function resolveCheckpointExitDelayPolicy(network: Network, overrides?:
  */
 declare function assertValidServerUnrollScript(checkpointTapscript: string, policy: CheckpointExitDelayPolicy): CSVMultisigTapscript.Type;
 
-declare function getRandomId(): string;
-/**
- * What a recipient Arkade address must match. An address failing either check
- * belongs to another network or operator, so this wallet's operator cannot
- * create the VTXO where the recipient's wallet expects it.
- */
-type RecipientAddressContext = {
-    hrp: string;
-    signerSet: SignerSet;
-};
-
 declare class ArkError extends Error {
     readonly code: number;
     readonly message: string;
@@ -422,6 +471,21 @@ interface ReceiveRotatorBootResult {
 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 the
+ * descriptor is absent or carries no parseable child index — restore
+ * registers the index-0 baseline untagged, so a missing descriptor
+ * legitimately maps to 0.
+ */
+declare function signingDescriptorIndex(descriptor: unknown): number;
+/**
+ * Strict sibling of {@link signingDescriptorIndex}: `undefined` instead of
+ * the 0 fallback, for callers that must tell "no parseable index" apart from
+ * index 0 — a watermark move mapped to 0 would move nothing while reporting
+ * success.
+ */
+declare function strictSigningDescriptorIndex(descriptor: string): number | undefined;
 /**
  * Minimal logging surface the rotator needs. `console` satisfies it
  * out of the box; SDK consumers can pass a structured logger
@@ -617,6 +681,12 @@ declare class WalletReceiveRotator {
     private rotate;
 }
 
+/**
+ * Maximum caller-requested HD descriptors materialized past the watermark by
+ * getUsedSigningDescriptors(). Bounds plugin/restore probes without changing
+ * the wallet's actual allocation watermark.
+ */
+declare const MAX_USED_SIGNING_DESCRIPTORS_LOOK_AHEAD = 1000;
 type IncomingFunds = {
     type: "utxo";
     coins: Coin[];
@@ -626,6 +696,13 @@ type IncomingFunds = {
     spentVtxos: ExtendedVirtualCoin[];
 };
 
+/**
+ * What signer classification needs of a snapshot: contract params and the coins
+ * under them. Structural rather than {@link ContractWithVtxos} so a repository-
+ * built snapshot — the worker's, whose VTXOs carry no `contractScript` — can be
+ * classified without allocating a parallel array to satisfy the nominal type.
+ */
+type PendingRecoverySnapshot = Parameters<typeof selectPendingRecoveryOutpoints>[0];
 /**
  * Boarding UTXOs grouped by the boarding address they sit on, carrying that
  * address's signer association explicitly. Returned by
@@ -955,18 +1032,80 @@ declare class ReadonlyWallet implements IReadonlyWallet {
     /**
      * Return virtual outputs tracked by the wallet.
      *
+     * The raw reporting/recovery read: escrowed, locked and awaiting-recovery
+     * funds are all present. Coin selection must use
+     * {@link getSpendableVtxos} instead — feeding this straight into
+     * `settle({ inputs })` or `sendBitcoin({ selectedVtxos })` bypasses the
+     * generic-spending gate.
+     *
      * @param filter - Optional flags controlling whether recoverable or unrolled VTXOs are included
      */
     getVtxos(filter?: GetVtxosFilter): Promise<NormalizedExtendedVirtualCoin[]>;
+    /** @inheritdoc */
+    getSpendableVtxos(filter?: GetVtxosFilter): Promise<NormalizedExtendedVirtualCoin[]>;
+    /**
+     * Debug-log any explicit input generic selection would have excluded, for
+     * each of the three reasons it excludes on. Explicit-input APIs stay ungated
+     * on purpose (naming an outpoint *is* the intent the gate protects, and it
+     * is how an escrowed deposit is recovered once generic selection stops
+     * covering it), so this only makes the crossing visible — notably
+     * `settle({ inputs: await wallet.getVtxos() })`, which launders the raw read
+     * into a spend. Never throws into a spend path.
+     *
+     * Public so the worker handler and plugins can report their own
+     * explicit-input crossings through the same three checks.
+     */
+    logUngatedInputs(source: string, inputs: readonly {
+        txid: string;
+        vout: number;
+        script?: string;
+    }[]): Promise<void>;
+    /**
+     * Contracts whose operator signer is past its rotation cutoff, as an
+     * exclusion over scripts. The outpoint-level `pendingRecovery` set needs a
+     * synced VTXO snapshot to also drop already-swept coins; this answers the
+     * same question about a caller-supplied input without one, and a swept
+     * outpoint is unspendable regardless.
+     */
+    private expiredSignerExclusion;
+    /** The intent store's lock set. Fails open, like every other read of it. */
+    private lockedOutpoints;
+    /**
+     * One contract+VTXO read. `getContractsWithVtxos` opportunistically syncs
+     * against the indexer, so every caller that needs more than one view of the
+     * wallet's coins takes a single snapshot and derives them all from it —
+     * otherwise the gate and the pending-recovery set answer about two different
+     * points in time, and each read costs another sync.
+     */
+    protected contractSnapshot(): 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 VTXOs whose deprecated signer is past its cutoff (EXPIRED) and
      * which have not yet been swept — unspendable until they recover. Offline:
      * classifies the repo's contracts against the cached signer set (active +
      * {@link _deprecatedSigners}, cutoffs included). Empty fast-path when no
      * signer is deprecated. Consumed by {@link getBalance} (the `pendingRecovery`
-     * bucket) and the send coin-selection path so neither counts nor spends them.
+     * bucket) and by {@link getSpendableVtxos} so neither counts nor spends them.
+     *
+     * Takes a fresh {@link contractSnapshot}, which syncs against the indexer.
+     * Callers that already hold a snapshot — or that must not sync at all, like
+     * the worker's balance read — pass it to
+     * {@link pendingRecoveryOutpointsIn} instead.
      */
     pendingRecoveryOutpoints(): Promise<Set<string>>;
+    /**
+     * {@link pendingRecoveryOutpoints} over a snapshot the caller already has:
+     * pure classification against the cached signer set, no repository or
+     * network read of its own.
+     */
+    pendingRecoveryOutpointsIn(snapshot: PendingRecoverySnapshot): Set<string>;
+    private selectPendingRecovery;
     /**
      * Return wallet transaction history derived from Arkade state and boarding transactions.
      */
@@ -1309,6 +1448,14 @@ declare class Wallet extends ReadonlyWallet implements IWallet, HDWalletCapable
      * @see HDWalletCapable.getCurrentSigningDescriptor
      */
     getCurrentSigningDescriptor(): Promise<string | undefined>;
+    /**
+     * @see HDWalletCapable.getNextSigningDescriptor
+     */
+    getNextSigningDescriptor(): Promise<string | undefined>;
+    /**
+     * @see HDWalletCapable.advanceSigningDescriptorWatermark
+     */
+    advanceSigningDescriptorWatermark(descriptor: string): Promise<void>;
     /**
      * @see HDWalletCapable.getUsedSigningDescriptors
      *
@@ -1317,7 +1464,9 @@ declare class Wallet extends ReadonlyWallet implements IWallet, HDWalletCapable
      * alone would miss indices allocated for something the wallet never
      * persisted (a swap, an externally issued invoice).
      */
-    getUsedSigningDescriptors(): Promise<string[]>;
+    getUsedSigningDescriptors(opts?: {
+        lookAhead?: number;
+    }): Promise<string[]>;
     /**
      * @see HDWalletCapable.signerForDescriptor
      */
@@ -1458,6 +1607,13 @@ declare class Wallet extends ReadonlyWallet implements IWallet, HDWalletCapable
     /**
      * Settle boarding inputs and/or virtual outputs into a finalized mainnet transaction.
      *
+     * `params.inputs` is **ungated**: whatever the caller names is settled,
+     * including VTXOs generic selection would skip. That is what makes an
+     * escrowed or otherwise gated deposit recoverable by hand — but it also
+     * means `settle({ inputs: await wallet.getVtxos() })` silently bypasses the
+     * gate. Pass {@link getSpendableVtxos} instead when the intent is "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.
      * @returns The finalized Arkade transaction id
@@ -1660,6 +1816,9 @@ declare class Wallet extends ReadonlyWallet implements IWallet, HDWalletCapable
     /**
      * 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): Promise<{
@@ -1686,4 +1845,4 @@ declare function selectVirtualCoins(coins: ExtendedVirtualCoin[], targetAmount:
  */
 declare function waitForIncomingFunds(wallet: Wallet): Promise<IncomingFunds>;
 
-export { ArkError as A, type BatchExpiryPolicy as B, type CheckpointExitDelayPolicy as C, DEFAULT_MIN_BATCH_EXPIRY_SECONDS as D, selectVirtualCoins as E, waitForIncomingFunds as F, type HDWalletCapable as H, type IncomingFunds as I, type ProviderConnectionState as P, ReadonlyWallet as R, type ServerInfoSource as S, Wallet as W, type ReceiveRotatorFactory as a, type ReceiveRotatorBootOpts as b, type ReceiveRotatorBoot as c, Batch as d, ArkErrorName as e, type ArkadeCashClaimResult as f, ArkadeCashCreateError as g, type ArkadeCashUnclaimedReason as h, type ArkadeCashUnclaimedVtxo as i, type BoardingUtxoGroup as j, DEFAULT_MIN_CHECKPOINT_EXIT_DELAY_SECONDS as k, type ProviderKind as l, ProviderUnavailableError as m, REGTEST_MIN_BATCH_EXPIRY_SECONDS as n, REGTEST_MIN_CHECKPOINT_EXIT_DELAY_SECONDS as o, ServerResponseMismatchError as p, assertValidBatchExpiry as q, assertValidServerUnrollScript as r, defaultBatchExpiryPolicy as s, defaultCheckpointExitDelayPolicy as t, getRandomId as u, isArkError as v, isHDWalletCapable as w, maybeArkError as x, resolveBatchExpiryPolicy as y, resolveCheckpointExitDelayPolicy as z };
+export { ArkError as A, type BatchExpiryPolicy as B, type CheckpointExitDelayPolicy as C, DEFAULT_MIN_BATCH_EXPIRY_SECONDS as D, maybeArkError as E, resolveBatchExpiryPolicy as F, resolveCheckpointExitDelayPolicy as G, type HDWalletCapable as H, type IncomingFunds as I, selectVirtualCoins as J, signingDescriptorIndex as K, strictSigningDescriptorIndex as L, MAX_USED_SIGNING_DESCRIPTORS_LOOK_AHEAD as M, waitForIncomingFunds as N, type ProviderConnectionState as P, ReadonlyWallet as R, SIGNET_MIN_CHECKPOINT_EXIT_DELAY_SECONDS as S, Wallet as W, type ReceiveRotatorFactory as a, type ReceiveRotatorBootOpts as b, type ReceiveRotatorBoot as c, type HDAllocationCapable as d, Batch as e, ArkErrorName as f, type ArkadeCashClaimResult as g, ArkadeCashCreateError as h, type ArkadeCashUnclaimedReason as i, type ArkadeCashUnclaimedVtxo as j, type BoardingUtxoGroup as k, DEFAULT_MIN_CHECKPOINT_EXIT_DELAY_SECONDS as l, MUTINYNET_MIN_CHECKPOINT_EXIT_DELAY_SECONDS as m, type ProviderKind as n, ProviderUnavailableError as o, REGTEST_MIN_BATCH_EXPIRY_SECONDS as p, REGTEST_MIN_CHECKPOINT_EXIT_DELAY_SECONDS as q, type ServerInfoSource as r, ServerResponseMismatchError as s, assertValidBatchExpiry as t, assertValidServerUnrollScript as u, defaultBatchExpiryPolicy as v, defaultCheckpointExitDelayPolicy as w, isArkError as x, isHDAllocationCapable as y, isHDWalletCapable as z };

package/dist/worker/expo/index.cjs

@@ -1,10 +1,10 @@
 'use strict';
 
-var chunkSYZEQF5D_cjs = require('../../chunk-SYZEQF5D.cjs');
-require('../../chunk-6PY4WYXI.cjs');
-require('../../chunk-F4C67JYB.cjs');
-require('../../chunk-COLJARV4.cjs');
-require('../../chunk-D6RGHPZ5.cjs');
+var chunk2XLNQHG4_cjs = require('../../chunk-2XLNQHG4.cjs');
+require('../../chunk-KNS5MTTI.cjs');
+require('../../chunk-PRFL62ID.cjs');
+require('../../chunk-MZNLCMUP.cjs');
+require('../../chunk-4A4GRSTB.cjs');
 require('../../chunk-5BLDMQED.cjs');
 
 // src/worker/expo/taskQueue.ts
@@ -121,19 +121,19 @@ var AsyncStorageTaskQueue = class {
 
 Object.defineProperty(exports, "CONTRACT_POLL_TASK_TYPE", {
   enumerable: true,
-  get: function () { return chunkSYZEQF5D_cjs.CONTRACT_POLL_TASK_TYPE; }
+  get: function () { return chunk2XLNQHG4_cjs.CONTRACT_POLL_TASK_TYPE; }
 });
 Object.defineProperty(exports, "contractPollProcessor", {
   enumerable: true,
-  get: function () { return chunkSYZEQF5D_cjs.contractPollProcessor; }
+  get: function () { return chunk2XLNQHG4_cjs.contractPollProcessor; }
 });
 Object.defineProperty(exports, "createTaskDependencies", {
   enumerable: true,
-  get: function () { return chunkSYZEQF5D_cjs.createTaskDependencies; }
+  get: function () { return chunk2XLNQHG4_cjs.createTaskDependencies; }
 });
 Object.defineProperty(exports, "runTasks", {
   enumerable: true,
-  get: function () { return chunkSYZEQF5D_cjs.runTasks; }
+  get: function () { return chunk2XLNQHG4_cjs.runTasks; }
 });
 exports.AsyncStorageTaskQueue = AsyncStorageTaskQueue;
 exports.InMemoryTaskQueue = InMemoryTaskQueue;