@arkade-os/sdk 0.4.59 → 0.4.61

package/dist/{wallet-EyVDhqzP.d.ts → wallet-BVIfg2ic.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-C9DsPSm8.js';
+import { a as Identity, J as DescriptorProvider, p as RelativeTimelock, K as Network, L as CSVMultisigTapscript, 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, 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 './index-BcRCHnzN.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-B_oKWm1k.js';
+import { D as DefaultVtxo, a as DelegateVtxo } from './delegate-BySzD37I.js';
 
 /**
  * Capability a wallet exposes so descriptor-blind consumers — Boltz swaps and
@@ -24,17 +24,106 @@ 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
-     * signer.
+     * Returns the wallet identity itself when `descriptor` is the identity's
+     * own key (a static wallet's descriptor, or an HD wallet's baseline key).
+     *
+     * Throws {@link ForeignDescriptorError} for a descriptor this wallet
+     * cannot sign for. Never silently substitutes another key: an identity
+     * handed out for a foreign descriptor signs happily with the wrong key,
+     * and that surfaces only as a rejected transaction or a dead script —
+     * far from the call that caused it.
+     *
+     * The returned identity must actually sign — `sign`, `signMessage` and
+     * `signerSession`, not just `xOnlyPublicKey`. A watch-only identity
+     * carrying the right key is not a signer, and `contractSigner` refuses it
+     * as `WalletCannotSignError`: returning one here would otherwise pass
+     * every check and throw at push time, after the contract is funded.
      */
     signerForDescriptor(descriptor: string): Promise<Identity>;
 }
+/**
+ * Thrown by {@link HDWalletCapable.signerForDescriptor} when the wallet holds
+ * no key for the requested descriptor — it belongs to another seed, or to an
+ * identity this wallet does not carry. A typed refusal 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;
+    });
+}
+/** 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} implementation
+ * so they cannot drift: the page-side and worker-side wallets answering
+ * differently for one descriptor is a signer that passes a public-key check
+ * and then throws on every signature — after the artifact is funded.
+ */
+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, 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 {
+    /**
+     * The signing descriptor a new artifact (a swap, an invoice, a contract)
+     * should bind to. **The wallet decides what that means**: an HD wallet
+     * allocates a fresh index, advancing the watermark; a static wallet
+     * answers with its one `tr(pubkey)` descriptor every time. Consumers must
+     * not probe the wallet's shape or mint key material of their own — they
+     * ask, and use what comes back with
+     * {@link HDWalletCapable.signerForDescriptor}.
+     *
+     * `undefined` only for implementations that genuinely cannot answer;
+     * `Wallet` always answers. Callers that must work against such wallets
+     * fall back to the identity key — never to a random one.
+     *
+     * Distinct from {@link HDWalletCapable.getCurrentSigningDescriptor}, which
+     * peeks: on an HD wallet, two artifacts bound to a peek share a key.
+     * Whether the returned descriptor is unique per call is a property of the
+     * wallet, not of this method — anything deriving per-artifact secrets
+     * from the descriptor 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 lower index is a no-op.
+     * On a static wallet there is no watermark: the wallet's own descriptor
+     * is accepted as a no-op.
+     *
+     * Throws on a descriptor this wallet cannot derive, or an HD descriptor
+     * 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;
@@ -152,17 +241,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;
@@ -443,6 +521,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
@@ -638,6 +731,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[];
@@ -647,6 +746,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
@@ -976,18 +1082,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.
      */
@@ -1330,6 +1498,22 @@ declare class Wallet extends ReadonlyWallet implements IWallet, HDWalletCapable
      * @see HDWalletCapable.getCurrentSigningDescriptor
      */
     getCurrentSigningDescriptor(): Promise<string | undefined>;
+    /**
+     * @see HDAllocationCapable.getNextSigningDescriptor
+     *
+     * Every `Wallet` answers — this is where the wallet's key-provisioning
+     * policy lives, so consumers never have to branch on wallet shape:
+     * - HD: allocate a fresh index through the contract manager (which owns
+     *   cross-context serialization and the look-ahead band).
+     * - custom provider: whatever the provider allocates.
+     * - static / `auto`: the identity key as a bare `tr(pubkey)` descriptor —
+     *   the same answer every call, because that IS the static policy.
+     */
+    getNextSigningDescriptor(): Promise<string | undefined>;
+    /**
+     * @see HDAllocationCapable.advanceSigningDescriptorWatermark
+     */
+    advanceSigningDescriptorWatermark(descriptor: string): Promise<void>;
     /**
      * @see HDWalletCapable.getUsedSigningDescriptors
      *
@@ -1338,9 +1522,18 @@ 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
+     *
+     * Fail-loud contract: the returned identity is always the descriptor's
+     * own key. A descriptor this wallet cannot sign for throws
+     * {@link ForeignDescriptorError} instead of silently substituting the
+     * baseline identity — that identity would sign happily with the wrong
+     * key, and the failure would only surface as a rejected transaction or a
+     * dead script, far from the call that caused it.
      */
     signerForDescriptor(descriptor: string): Promise<Identity>;
     /**
@@ -1479,6 +1672,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
@@ -1681,6 +1881,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<{
@@ -1707,4 +1910,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, resolveCheckpointExitDelayPolicy as E, selectVirtualCoins as F, waitForIncomingFunds as G, type HDWalletCapable as H, type IncomingFunds as I, MUTINYNET_MIN_CHECKPOINT_EXIT_DELAY_SECONDS as M, 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, 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, type ServerInfoSource as p, ServerResponseMismatchError as q, assertValidBatchExpiry as r, assertValidServerUnrollScript as s, defaultBatchExpiryPolicy as t, defaultCheckpointExitDelayPolicy as u, getRandomId as v, isArkError as w, isHDWalletCapable as x, maybeArkError as y, resolveBatchExpiryPolicy as z };
+export { ArkError as A, type BatchExpiryPolicy as B, type CheckpointExitDelayPolicy as C, DEFAULT_MIN_BATCH_EXPIRY_SECONDS as D, maybeArkError as E, ForeignDescriptorError as F, resolveBatchExpiryPolicy as G, type HDWalletCapable as H, type IncomingFunds as I, resolveCheckpointExitDelayPolicy as J, resolveDescriptorSigner as K, selectVirtualCoins as L, MAX_USED_SIGNING_DESCRIPTORS_LOOK_AHEAD as M, signingDescriptorIndex as N, strictSigningDescriptorIndex as O, type ProviderConnectionState as P, waitForIncomingFunds as Q, ReadonlyWallet as R, SIGNET_MIN_CHECKPOINT_EXIT_DELAY_SECONDS as S, Wallet as W, type HDAllocationCapable as a, type ReceiveRotatorFactory as b, type ReceiveRotatorBootOpts as c, type ReceiveRotatorBoot 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 };