@arkade-os/sdk 0.4.27 → 0.4.28

package/dist/types/wallet/vtxo-manager.d.ts

@@ -1,476 +0,0 @@
-import { ExtendedCoin, ExtendedVirtualCoin, IWallet } from "./index.js";
-import { SettlementEvent } from "../providers/ark.js";
-/** Default renewal threshold in seconds (3 days). */
-export declare const DEFAULT_THRESHOLD_SECONDS: number;
-/**
- * Default renewal threshold in milliseconds (3 days).
- */
-export declare const DEFAULT_THRESHOLD_MS: number;
-/**
- * Configuration options for automatic virtual output renewal
- *
- * @see DEFAULT_RENEWAL_CONFIG
- * @deprecated Leave `renewalConfig` undefined and use `settlementConfig` instead.
- * @see SettlementConfig
- */
-export interface RenewalConfig {
-    /**
-     * Enable automatic renewal monitoring
-     *
-     * @defaultValue `false`
-     * @deprecated Explicitly set `settlementConfig` to `false` to disable VTXO renewal.
-     */
-    enabled?: boolean;
-    /**
-     * Threshold in milliseconds to use as threshold for renewal
-     * E.g., 86_400_000 means renew when 24 hours until expiry remains
-     *
-     * @defaultValue `259_200_000` (3 days).
-     * @deprecated Use `SettlementConfig.vtxoThreshold` (in seconds) instead.
-     */
-    thresholdMs?: number;
-}
-/**
- * Configuration for automatic settlement and renewal.
- *
- * Controls two behaviors:
- * 1. **VTXO renewal**: Automatically renew virtual outputs that are close to expiry
- * 2. **Boarding UTXO sweep**: Sweep expired boarding inputs back to a fresh boarding address
- *    via the unilateral exit path (onchain self-spend to restart the timelock)
- *
- * Enabled by default when no config is provided.
- * Pass `false` to explicitly disable all settlement behavior.
- *
- * @remarks
- * VTXO renewal and boarding UTXO sweep are both coordinated by `VtxoManager`, which periodically
- * inspects wallet virtual outputs and boarding inputs and decides whether action is needed.
- *
- * @see DEFAULT_SETTLEMENT_CONFIG
- *
- * @example
- * ```typescript
- * // Default behavior: virtual output renewal at 3 days, boarding sweep enabled, polling every minute
- * const wallet = await Wallet.create({
- *   identity: MnemonicIdentity.fromMnemonic('abandon abandon...'),
- *   arkServerUrl: 'https://arkade.computer',
- * });
- *
- * // Custom expiry threshold of 24 hours
- * const wallet = await Wallet.create({
- *   identity: MnemonicIdentity.fromMnemonic('abandon abandon...'),
- *   arkServerUrl: 'https://arkade.computer',
- *   settlementConfig: {
- *     vtxoThreshold: 60 * 60 * 24, // 24 hours in seconds
- *   },
- * });
- *
- * // Explicitly disable
- * const wallet = await Wallet.create({
- *   identity: MnemonicIdentity.fromMnemonic('abandon abandon...'),
- *   arkServerUrl: 'https://arkade.computer',
- *   settlementConfig: false,
- * });
- * ```
- */
-export interface SettlementConfig {
-    /**
-     * Seconds before virtual output expiry to trigger renewal.
-     *
-     * @defaultValue `259_200` (3 days)
-     */
-    vtxoThreshold?: number;
-    /**
-     * Sweep expired boarding inputs back to a fresh boarding address
-     * via the unilateral exit path (onchain self-spend to restart the timelock).
-     *
-     * When enabled, expired boarding inputs are batched into a single onchain
-     * transaction with multiple inputs and one output.
-     *
-     * A dust check ensures the sweep is only performed when the output
-     * after fees is above dust.
-     *
-     * @defaultValue `true`
-     */
-    boardingUtxoSweep?: boolean;
-    /**
-     * Polling interval in milliseconds for checking boarding inputs.
-     * The poll loop auto-settles new boarding inputs into Arkade and
-     * sweeps expired ones (when boardingUtxoSweep is enabled).
-     *
-     * @defaultValue `60_000` (1 minute)
-     */
-    pollIntervalMs?: number;
-}
-/**
- * Default renewal configuration values.
- *
- * @see RenewalConfig
- * @deprecated Leave `renewalConfig` undefined and use `settlementConfig` instead.
- * @see SettlementConfig
- */
-export declare const DEFAULT_RENEWAL_CONFIG: Required<Omit<RenewalConfig, "enabled">>;
-/**
- * Default settlement configuration values.
- *
- * @see SettlementConfig
- *
- * @example
- * ```typescript
- * const wallet = await Wallet.create({
- *   identity,
- *   arkServerUrl: 'https://arkade.computer',
- *   settlementConfig: DEFAULT_SETTLEMENT_CONFIG,
- * })
- * ```
- */
-export declare const DEFAULT_SETTLEMENT_CONFIG: Required<SettlementConfig>;
-/**
- * Check if a virtual output is expiring soon based on threshold
- *
- * @param vtxo - The virtual output to check
- * @param thresholdMs - Threshold in milliseconds from now
- * @returns true if virtual output expires within threshold, false otherwise
- */
-export declare function isVtxoExpiringSoon(vtxo: ExtendedVirtualCoin, thresholdMs: number): boolean;
-/**
- * Filter virtual outputs that are expiring soon or are recoverable/subdust
- *
- * @param vtxos - Array of virtual outputs to check
- * @param thresholdMs - Threshold in milliseconds from now
- * @param dustAmount - Dust threshold amount in satoshis
- * @returns Array of virtual outputs expiring within threshold
- */
-export declare function getExpiringAndRecoverableVtxos(vtxos: ExtendedVirtualCoin[], thresholdMs: number, dustAmount: bigint): ExtendedVirtualCoin[];
-/**
- * VtxoManager is a unified class for managing virtual output lifecycle operations including
- * recovery of swept/expired virtual outputs and renewal to prevent expiration.
- *
- * Key Features:
- * - **Recovery**: Reclaim swept or expired virtual outputs back to the wallet
- * - **Renewal**: Refresh virtual output expiration time before they expire
- * - **Smart subdust handling**: Automatically includes subdust virtual outputs when economically viable
- * - **Expiry monitoring**: Check for virtual outputs that are expiring soon
- *
- * Virtual outputs become recoverable when:
- * - The Arkade server sweeps them (virtualStatus.state === "swept") and they remain spendable
- * - They are preconfirmed subdust (to consolidate small amounts without locking liquidity on settled virtual outputs)
- *
- * @example
- * ```typescript
- * const wallet = await Wallet.create({
- *   identity,
- *   arkServerUrl: 'https://arkade.computer',
- *   settlementConfig: {
- *      // Seconds before virtual output expiry to trigger renewal
- *      vtxoThreshold: 259_200, // 3 days
- *      // Whether to sweep expired boarding inputs back to a fresh boarding address
- *      boardingUtxoSweep: true,
- *      // Polling interval in milliseconds for checking boarding inputs
- *      pollIntervalMs: 60_000 // 1 minute
- *  },
- * });
- * const manager = await wallet.getVtxoManager();
- *
- * // Check recoverable balance
- * const balance = await manager.getRecoverableBalance();
- * if (balance.recoverable > 0n) {
- *   console.log(`Can recover ${balance.recoverable} sats`);
- *   const txid = await manager.recoverVtxos();
- * }
- *
- * // Check for expiring virtual outputs
- * const expiring = await manager.getExpiringVtxos();
- * if (expiring.length > 0) {
- *   console.log(`${expiring.length} virtual outputs expiring soon`);
- *   const txid = await manager.renewVtxos();
- * }
- * ```
- */
-export interface IVtxoManager {
-    recoverVtxos(eventCallback?: (event: SettlementEvent) => void): Promise<string>;
-    getRecoverableBalance(): Promise<{
-        recoverable: bigint;
-        subdust: bigint;
-        includesSubdust: boolean;
-        vtxoCount: number;
-    }>;
-    getExpiringVtxos(thresholdMs?: number): Promise<ExtendedVirtualCoin[]>;
-    renewVtxos(eventCallback?: (event: SettlementEvent) => void): Promise<string>;
-    getExpiredBoardingUtxos(): Promise<ExtendedCoin[]>;
-    sweepExpiredBoardingUtxos(): Promise<string>;
-    dispose(): Promise<void>;
-}
-export declare class VtxoManager implements AsyncDisposable, IVtxoManager {
-    readonly wallet: IWallet;
-    /** @deprecated Use settlementConfig instead */
-    readonly renewalConfig?: RenewalConfig | undefined;
-    readonly settlementConfig: SettlementConfig | false;
-    private contractEventsSubscription?;
-    private readonly contractEventsSubscriptionReady;
-    private disposePromise?;
-    private pollTimeoutId?;
-    private knownBoardingUtxos;
-    private sweptBoardingUtxos;
-    private pollInProgress;
-    private pollDone?;
-    private disposed;
-    private consecutivePollFailures;
-    private startupPollTimeoutId?;
-    private static readonly MAX_BACKOFF_MS;
-    private renewalInProgress;
-    private lastRenewalTimestamp;
-    private static readonly RENEWAL_COOLDOWN_MS;
-    private lastPeriodicSettleTimestamp;
-    private consecutivePeriodicSettleFailures;
-    private static readonly PERIODIC_SETTLE_COOLDOWN_MS;
-    private static readonly PERIODIC_SETTLE_MAX_BACKOFF_MS;
-    private lastVtxoSpentRefreshTimestamp;
-    private vtxoSpentRefreshPromise?;
-    private static readonly VTXO_SPENT_REFRESH_COOLDOWN_MS;
-    constructor(wallet: IWallet, 
-    /** @deprecated Use settlementConfig instead */
-    renewalConfig?: RenewalConfig | undefined, settlementConfig?: SettlementConfig | false);
-    /**
-     * Recover swept/expired virtual outputs by settling them back to the wallet's Arkade address.
-     *
-     * This method:
-     * 1. Fetches all virtual outputs (including recoverable ones)
-     * 2. Filters for swept but still spendable virtual outputs and preconfirmed subdust
-     * 3. Includes subdust virtual outputs if the total value >= dust threshold
-     * 4. Settles everything back to the wallet's Arkade address
-     *
-     * Note: Settled virtual outputs with long expiry are NOT recovered to avoid locking liquidity unnecessarily.
-     * Only preconfirmed subdust is recovered to consolidate small amounts.
-     *
-     * @param eventCallback - Optional callback to receive settlement events
-     * @returns Settlement transaction ID
-     * @throws Error if no recoverable virtual outputs found
-     *
-     * @example
-     * ```typescript
-     * const manager = await wallet.getVtxoManager();
-     *
-     * // Simple recovery
-     * const txid = await manager.recoverVtxos();
-     *
-     * // With event callback
-     * const txid = await manager.recoverVtxos((event) => {
-     *   console.log('Settlement event:', event.type);
-     * });
-     * ```
-     */
-    recoverVtxos(eventCallback?: (event: SettlementEvent) => void): Promise<string>;
-    /**
-     * Get information about recoverable balance without executing recovery.
-     *
-     * Useful for displaying to users before they decide to recover funds.
-     *
-     * @returns Object containing recoverable amounts and subdust information
-     *
-     * @example
-     * ```typescript
-     * const manager = await wallet.getVtxoManager();
-     * const balance = await manager.getRecoverableBalance();
-     *
-     * if (balance.recoverable > 0n) {
-     *   console.log(`You can recover ${balance.recoverable} sats`);
-     *   if (balance.includesSubdust) {
-     *     console.log(`This includes ${balance.subdust} sats from subdust virtual outputs`);
-     *   }
-     * }
-     * ```
-     */
-    getRecoverableBalance(): Promise<{
-        recoverable: bigint;
-        subdust: bigint;
-        includesSubdust: boolean;
-        vtxoCount: number;
-    }>;
-    /**
-     * Get virtual outputs that are expiring soon based on renewal configuration
-     *
-     * @param thresholdMs - Optional override for threshold in milliseconds
-     * @returns Array of expiring virtual outputs, empty array if renewal is disabled or no virtual outputs expiring
-     *
-     * @example
-     * ```typescript
-     * const wallet = await Wallet.create({
-     *  identity,
-     *  arkServerUrl: 'https://arkade.computer',
-     *  settlementConfig: {
-     *      vtxoThreshold: 86_400 // 24 hours
-     *  },
-     * });
-     * const manager = await wallet.getVtxoManager();
-     * const expiringVtxos = await manager.getExpiringVtxos();
-     * if (expiringVtxos.length > 0) {
-     *   console.log(`${expiringVtxos.length} virtual outputs expiring soon`);
-     * }
-     * ```
-     */
-    getExpiringVtxos(thresholdMs?: number): Promise<ExtendedVirtualCoin[]>;
-    /**
-     * Renew expiring virtual outputs by settling them back to the wallet's address
-     *
-     * This method collects all expiring spendable virtual outputs (including recoverable ones) and settles
-     * them back to the wallet, effectively refreshing their expiration time. This is the
-     * primary way to prevent virtual outputs from expiring.
-     *
-     * @param eventCallback - Optional callback for settlement events
-     * @returns Settlement transaction ID
-     * @throws Error if no virtual outputs available to renew
-     * @throws Error if total amount is below dust threshold
-     *
-     * @example
-     * ```typescript
-     * const manager = await wallet.getVtxoManager();
-     *
-     * // Simple renewal
-     * const txid = await manager.renewVtxos();
-     *
-     * // With event callback
-     * const txid = await manager.renewVtxos((event) => {
-     *   console.log('Settlement event:', event.type);
-     * });
-     * ```
-     */
-    renewVtxos(eventCallback?: (event: SettlementEvent) => void): Promise<string>;
-    /**
-     * Get boarding inputs whose timelock has expired.
-     *
-     * These inputs can no longer be onboarded cooperatively via `settle()` and
-     * must be swept back to a fresh boarding address using the unilateral exit path.
-     *
-     * @returns Array of expired boarding inputs
-     *
-     * @example
-     * ```typescript
-     * const manager = await wallet.getVtxoManager();
-     * const expired = await manager.getExpiredBoardingUtxos();
-     * if (expired.length > 0) {
-     *   console.log(`${expired.length} expired boarding inputs to sweep`);
-     * }
-     * ```
-     */
-    getExpiredBoardingUtxos(prefetchedUtxos?: ExtendedCoin[]): Promise<ExtendedCoin[]>;
-    /**
-     * Sweep expired boarding inputs back to a fresh boarding address via
-     * the unilateral exit path (onchain self-spend).
-     *
-     * This builds a raw onchain transaction that:
-     * - Uses all expired boarding inputs as inputs (spent via the CSV exit script path)
-     * - Has a single output to the wallet's boarding address (restarts the timelock)
-     * - Batches multiple expired boarding inputs into one transaction
-     * - Skips the sweep if the output after fees would be below dust
-     *
-     * No Arkade server involvement is needed — this is a pure onchain transaction.
-     *
-     * @returns The broadcast transaction ID
-     * @throws Error if no expired boarding inputs are found
-     * @throws Error if output after fees is below dust (not economical to sweep)
-     * @throws Error if boarding input sweep is not enabled in settlementConfig
-     *
-     * @example
-     * ```typescript
-     * const wallet = await Wallet.create({
-     *   identity,
-     *   arkServerUrl: 'https://arkade.computer',
-     *   settlementConfig: {
-     *     boardingUtxoSweep: true,
-     *   },
-     * });
-     * const manager = await wallet.getVtxoManager();
-     *
-     * try {
-     *   const txid = await manager.sweepExpiredBoardingUtxos();
-     *   console.log('Swept expired boarding inputs:', txid);
-     * } catch (e) {
-     *   console.log('No sweep needed or not economical');
-     * }
-     * ```
-     */
-    sweepExpiredBoardingUtxos(prefetchedUtxos?: ExtendedCoin[]): Promise<string>;
-    /** Asserts sweep capability and returns the typed wallet. */
-    private getSweepWallet;
-    /** Decodes the boarding tapscript exit path to extract the CSV timelock. */
-    private getBoardingTimelock;
-    /** Returns the TapLeafScript for the boarding tapscript's exit (CSV) path. */
-    private getBoardingExitLeaf;
-    /** Returns the pkScript (output script) of the boarding tapscript. */
-    private getBoardingOutputScript;
-    /** Returns the onchain provider for fee estimation and broadcasting. */
-    private getOnchainProvider;
-    /** Returns the Ark provider for intent fee and server info lookups. */
-    private getArkProvider;
-    /** Returns the Bitcoin network configuration from the wallet. */
-    private getNetwork;
-    /** Returns the wallet's identity for transaction signing. */
-    private getIdentity;
-    private initializeSubscription;
-    /**
-     * VTXO_ALREADY_SPENT means the server's authoritative view of VTXO state
-     * is ahead of ours — cross-instance race, pre-lock snapshot drift, or an
-     * SSE gap left stale data in the local cache. Silent-swallowing
-     * guarantees the same error on the next cycle because nothing
-     * reconciles the cache.
-     *
-     * The cursor-derived delta sync filters by `created_at`, so a VTXO that
-     * was created before the cursor but spent recently can never be
-     * reconciled by `refreshVtxos()`. Use `refreshOutpoints` for surgical
-     * recovery: query the indexer for the specific stale outpoint and
-     * upsert its authoritative state into the wallet repository.
-     *
-     * Throttled because the same VTXO can fire repeatedly before the
-     * upsert observably propagates through the renewal selector.
-     */
-    private maybeRefreshAfterVtxoSpent;
-    /**
-     * Extract the offending VTXO outpoint from a `VTXO_ALREADY_SPENT` error,
-     * if the server attached one in `metadata.vtxo_outpoint`. Returns
-     * `undefined` when the error isn't a parsed ArkError, isn't this code,
-     * or doesn't carry the metadata.
-     */
-    private extractSpentOutpoint;
-    /**
-     * Reconcile the chosen VTXOs with the indexer's authoritative state
-     * before submitting a settle intent. Pulls the canonical record for
-     * each candidate outpoint via {@link IContractManager.refreshOutpoints}
-     * (which upserts the result into the wallet repository), then
-     * re-selects through the standard expiring-vtxo filter so anything
-     * the refresh flagged as spent is dropped.
-     *
-     * Best-effort: a failed refresh just falls back to the original
-     * candidates and lets the post-submit `VTXO_ALREADY_SPENT` recovery
-     * handle whatever slipped through.
-     */
-    private revalidateBeforeSettle;
-    /** Computes the next poll delay, applying exponential backoff on failures. */
-    private getNextPollDelay;
-    /**
-     * Starts a polling loop that:
-     * 1. Auto-settles new boarding inputs into Arkade
-     * 2. Sweeps expired boarding inputs (when boardingUtxoSweep is enabled)
-     *
-     * Uses setTimeout chaining (not setInterval) so a slow/blocked poll
-     * cannot stack up and the next delay can incorporate backoff.
-     */
-    private startBoardingUtxoPoll;
-    private schedulePoll;
-    private pollBoardingUtxos;
-    /**
-     * Auto-settle new (unexpired) boarding inputs AND near-expiry VTXOs into
-     * Arkade in a single intent. Skips boarding UTXOs that are already expired
-     * (those are handled by sweep) and those already in-flight (tracked in
-     * knownBoardingUtxos). If the event-driven renewal path is currently
-     * running, VTXOs are omitted from this cycle to avoid double-spending.
-     *
-     * Failure bookkeeping: after every settle *attempt*, lastPeriodicSettleTimestamp
-     * is armed and consecutive failures are counted so the next attempt is
-     * blocked by an exponentially growing cooldown (capped). This stops a
-     * persistently failing input from producing identical RegisterIntent +
-     * DeleteIntent retries on every 60s poll.
-     */
-    private runPeriodicSettle;
-    dispose(): Promise<void>;
-    [Symbol.asyncDispose](): Promise<void>;
-}