@arkade-os/sdk 0.4.5 → 0.4.7

package/dist/esm/wallet/wallet.js

@@ -15,7 +15,7 @@ import { createAssetPacket, selectedCoinsToAssetInputs, selectCoinsWithAsset, }
 import { VtxoScript } from '../script/base.js';
 import { CSVMultisigTapscript } from '../script/tapscript.js';
 import { buildOffchainTx, hasBoardingTxExpired, isValidArkAddress, } from '../utils/arkTransaction.js';
-import { DEFAULT_RENEWAL_CONFIG } from './vtxo-manager.js';
+import { DEFAULT_RENEWAL_CONFIG, DEFAULT_SETTLEMENT_CONFIG, VtxoManager, } from './vtxo-manager.js';
 import { ArkNote } from '../arknote/index.js';
 import { Intent } from '../intent/index.js';
 import { RestIndexerProvider } from '../providers/indexer.js';
@@ -611,6 +611,18 @@ export class ReadonlyWallet {
         }
         return manager;
     }
+    async dispose() {
+        const manager = this._contractManager ??
+            (this._contractManagerInitializing
+                ? await this._contractManagerInitializing.catch(() => undefined)
+                : undefined);
+        manager?.dispose();
+        this._contractManager = undefined;
+        this._contractManagerInitializing = undefined;
+    }
+    async [Symbol.asyncDispose]() {
+        await this.dispose();
+    }
 }
 /**
  * Main wallet implementation for Bitcoin transactions with Ark protocol support.
@@ -646,7 +658,9 @@ export class ReadonlyWallet {
  * ```
  */
 export class Wallet extends ReadonlyWallet {
-    constructor(identity, network, networkName, onchainProvider, arkProvider, indexerProvider, arkServerPublicKey, offchainTapscript, boardingTapscript, serverUnrollScript, forfeitOutputScript, forfeitPubkey, dustAmount, walletRepository, contractRepository, renewalConfig, delegatorProvider, watcherConfig) {
+    constructor(identity, network, networkName, onchainProvider, arkProvider, indexerProvider, arkServerPublicKey, offchainTapscript, boardingTapscript, serverUnrollScript, forfeitOutputScript, forfeitPubkey, dustAmount, walletRepository, contractRepository, 
+    /** @deprecated Use settlementConfig */
+    renewalConfig, delegatorProvider, watcherConfig, settlementConfig) {
         super(identity, network, onchainProvider, indexerProvider, arkServerPublicKey, offchainTapscript, boardingTapscript, dustAmount, walletRepository, contractRepository, delegatorProvider, watcherConfig);
         this.networkName = networkName;
         this.arkProvider = arkProvider;
@@ -654,11 +668,31 @@ export class Wallet extends ReadonlyWallet {
         this.forfeitOutputScript = forfeitOutputScript;
         this.forfeitPubkey = forfeitPubkey;
         this.identity = identity;
+        // Backwards-compatible: keep renewalConfig populated for any code reading it
         this.renewalConfig = {
             enabled: renewalConfig?.enabled ?? false,
             ...DEFAULT_RENEWAL_CONFIG,
             ...renewalConfig,
         };
+        // Normalize: prefer settlementConfig, fall back to renewalConfig, default to enabled
+        if (settlementConfig !== undefined) {
+            this.settlementConfig = settlementConfig;
+        }
+        else if (renewalConfig && this.renewalConfig.enabled) {
+            this.settlementConfig = {
+                vtxoThreshold: renewalConfig.thresholdMs
+                    ? renewalConfig.thresholdMs / 1000
+                    : undefined,
+            };
+        }
+        else if (renewalConfig) {
+            // renewalConfig provided but not enabled → disabled
+            this.settlementConfig = false;
+        }
+        else {
+            // No config at all → enabled by default
+            this.settlementConfig = { ...DEFAULT_SETTLEMENT_CONFIG };
+        }
         this._delegatorManager = delegatorProvider
             ? new DelegatorManagerImpl(delegatorProvider, arkProvider, identity)
             : undefined;
@@ -667,6 +701,46 @@ export class Wallet extends ReadonlyWallet {
         this._walletAssetManager ?? (this._walletAssetManager = new AssetManager(this));
         return this._walletAssetManager;
     }
+    async getVtxoManager() {
+        if (this._vtxoManager) {
+            return this._vtxoManager;
+        }
+        if (this._vtxoManagerInitializing) {
+            return this._vtxoManagerInitializing;
+        }
+        this._vtxoManagerInitializing = Promise.resolve(new VtxoManager(this, this.renewalConfig, this.settlementConfig));
+        try {
+            const manager = await this._vtxoManagerInitializing;
+            this._vtxoManager = manager;
+            return manager;
+        }
+        catch (error) {
+            this._vtxoManagerInitializing = undefined;
+            throw error;
+        }
+        finally {
+            this._vtxoManagerInitializing = undefined;
+        }
+    }
+    async dispose() {
+        const manager = this._vtxoManager ??
+            (this._vtxoManagerInitializing
+                ? await this._vtxoManagerInitializing.catch(() => undefined)
+                : undefined);
+        try {
+            if (manager) {
+                await manager.dispose();
+            }
+        }
+        catch {
+            // best-effort teardown; ensure super.dispose() still runs
+        }
+        finally {
+            this._vtxoManager = undefined;
+            this._vtxoManagerInitializing = undefined;
+            await super.dispose();
+        }
+    }
     static async create(config) {
         const pubkey = await config.identity.xOnlyPublicKey();
         if (!pubkey) {
@@ -688,7 +762,9 @@ export class Wallet extends ReadonlyWallet {
         const forfeitPubkey = hex.decode(setup.info.forfeitPubkey).slice(1);
         const forfeitAddress = Address(setup.network).decode(setup.info.forfeitAddress);
         const forfeitOutputScript = OutScript.encode(forfeitAddress);
-        return new Wallet(config.identity, setup.network, setup.networkName, setup.onchainProvider, setup.arkProvider, setup.indexerProvider, setup.serverPubKey, setup.offchainTapscript, setup.boardingTapscript, serverUnrollScript, forfeitOutputScript, forfeitPubkey, setup.dustAmount, setup.walletRepository, setup.contractRepository, config.renewalConfig, config.delegatorProvider, config.watcherConfig);
+        const wallet = new Wallet(config.identity, setup.network, setup.networkName, setup.onchainProvider, setup.arkProvider, setup.indexerProvider, setup.serverPubKey, setup.offchainTapscript, setup.boardingTapscript, serverUnrollScript, forfeitOutputScript, forfeitPubkey, setup.dustAmount, setup.walletRepository, setup.contractRepository, config.renewalConfig, config.delegatorProvider, config.watcherConfig, config.settlementConfig);
+        await wallet.getVtxoManager();
+        return wallet;
     }
     /**
      * Convert this wallet to a readonly wallet.
@@ -791,7 +867,13 @@ export class Wallet extends ReadonlyWallet {
             let amount = 0;
             const exitScript = CSVMultisigTapscript.decode(hex.decode(this.boardingTapscript.exitScript));
             const boardingTimelock = exitScript.params.timelock;
-            const boardingUtxos = (await this.getBoardingUtxos()).filter((utxo) => !hasBoardingTxExpired(utxo, boardingTimelock));
+            // For block-based timelocks, fetch the chain tip height
+            let chainTipHeight;
+            if (boardingTimelock.type === "blocks") {
+                const tip = await this.onchainProvider.getChainTip();
+                chainTipHeight = tip.height;
+            }
+            const boardingUtxos = (await this.getBoardingUtxos()).filter((utxo) => !hasBoardingTxExpired(utxo, boardingTimelock, chainTipHeight));
             const filteredBoardingUtxos = [];
             for (const utxo of boardingUtxos) {
                 const inputFee = estimator.evalOnchainInput({

package/dist/types/index.d.ts

@@ -16,6 +16,7 @@ import { TxTree, TxTreeNode } from "./tree/txTree";
 import { SignerSession, TreeNonces, TreePartialSigs } from "./tree/signingSession";
 import { Ramps } from "./wallet/ramps";
 import { isVtxoExpiringSoon, VtxoManager } from "./wallet/vtxo-manager";
+import type { SettlementConfig } from "./wallet/vtxo-manager";
 import { ServiceWorkerWallet, ServiceWorkerReadonlyWallet } from "./wallet/serviceWorker/wallet";
 import { OnchainWallet } from "./wallet/onchain";
 import { setupServiceWorker } from "./worker/browser/utils";
@@ -48,4 +49,4 @@ import { IContractManager } from "./contracts/contractManager";
 import { closeDatabase, openDatabase } from "./repositories/indexedDB/manager";
 import { WalletMessageHandler } from "./wallet/serviceWorker/wallet-message-handler";
 export { Wallet, ReadonlyWallet, SingleKey, ReadonlySingleKey, SeedIdentity, MnemonicIdentity, ReadonlyDescriptorIdentity, OnchainWallet, Ramps, VtxoManager, DelegatorManagerImpl, RestDelegatorProvider, ESPLORA_URL, EsploraProvider, RestArkProvider, RestIndexerProvider, ArkAddress, DefaultVtxo, DelegateVtxo, VtxoScript, VHTLC, TxType, IndexerTxType, ChainTxType, SettlementEventType, setupServiceWorker, MessageBus, WalletMessageHandler, ServiceWorkerWallet, ServiceWorkerReadonlyWallet, decodeTapscript, MultisigTapscript, CSVMultisigTapscript, ConditionCSVMultisigTapscript, ConditionMultisigTapscript, CLTVMultisigTapscript, TapTreeCoder, ArkPsbtFieldKey, ArkPsbtFieldKeyType, setArkPsbtField, getArkPsbtFields, CosignerPublicKey, VtxoTreeExpiry, VtxoTaprootTree, ConditionWitness, buildOffchainTx, verifyTapscriptSignatures, waitForIncomingFunds, hasBoardingTxExpired, combineTapscriptSigs, isVtxoExpiringSoon, isValidArkAddress, ArkNote, networks, closeDatabase, openDatabase, IndexedDBWalletRepository, IndexedDBContractRepository, InMemoryWalletRepository, InMemoryContractRepository, MIGRATION_KEY, migrateWalletRepository, requiresMigration, getMigrationStatus, rollbackMigration, WalletRepositoryImpl, ContractRepositoryImpl, Intent, BIP322, TxTree, P2A, Unroll, Transaction, ArkError, maybeArkError, Batch, validateVtxoTxGraph, validateConnectorsTxGraph, buildForfeitTx, isRecoverable, isSpendable, isSubdust, isExpired, getSequence, ContractManager, ContractWatcher, contractHandlers, DefaultContractHandler, DelegateContractHandler, VHTLCContractHandler, encodeArkContract, decodeArkContract, contractFromArkContract, contractFromArkContractWithAddress, isArkContract, };
-export type { Identity, ReadonlyIdentity, IWallet, IReadonlyWallet, BaseWalletConfig, WalletConfig, ReadonlyWalletConfig, ProviderClass, ArkTransaction, Coin, ExtendedCoin, ExtendedVirtualCoin, WalletBalance, SendBitcoinParams, SettleParams, Status, VirtualStatus, Outpoint, VirtualCoin, TxKey, TapscriptType, ArkTxInput, OffchainTx, TapLeaves, IncomingFunds, SeedIdentityOptions, MnemonicOptions, NetworkOptions, DescriptorOptions, IndexerProvider, PageResponse, BatchInfo, ChainTx, CommitmentTx, TxHistoryRecord, Vtxo, VtxoChain, Tx, OnchainProvider, ArkProvider, SettlementEvent, FeeInfo, ArkInfo, SignedIntent, Output, TxNotification, ExplorerTransaction, BatchFinalizationEvent, BatchFinalizedEvent, BatchFailedEvent, TreeSigningStartedEvent, TreeNoncesEvent, BatchStartedEvent, TreeTxEvent, TreeSignatureEvent, ScheduledSession, PaginationOptions, SubscriptionResponse, SubscriptionHeartbeat, SubscriptionEvent, Network, NetworkName, ArkTapscript, RelativeTimelock, EncodedVtxoScript, TapLeafScript, SignerSession, TreeNonces, TreePartialSigs, GetVtxosFilter, Asset, Recipient, IssuanceParams, IssuanceResult, ReissuanceParams, BurnParams, AssetDetails, AssetMetadata, KnownMetadata, Nonces, PartialSig, ArkPsbtFieldCoder, TxTreeNode, AnchorBumper, StorageConfig, Contract, ContractVtxo, ContractState, ContractEvent, ContractEventCallback, ContractBalance, ContractWithVtxos, ContractHandler, IContractManager, PathSelection, PathContext, ContractManagerConfig, CreateContractParams, ContractWatcherConfig, ParsedArkContract, DefaultContractParams, DelegateContractParams, VHTLCContractParams, MessageHandler, RequestEnvelope, ResponseEnvelope, IDelegatorManager, DelegatorProvider, DelegateInfo, DelegateOptions, WalletRepository, ContractRepository, MigrationStatus, };
+export type { Identity, ReadonlyIdentity, IWallet, IReadonlyWallet, BaseWalletConfig, WalletConfig, ReadonlyWalletConfig, ProviderClass, ArkTransaction, Coin, ExtendedCoin, ExtendedVirtualCoin, WalletBalance, SendBitcoinParams, SettleParams, Status, VirtualStatus, Outpoint, VirtualCoin, TxKey, TapscriptType, ArkTxInput, OffchainTx, TapLeaves, IncomingFunds, SeedIdentityOptions, MnemonicOptions, NetworkOptions, DescriptorOptions, IndexerProvider, PageResponse, BatchInfo, ChainTx, CommitmentTx, TxHistoryRecord, Vtxo, VtxoChain, Tx, OnchainProvider, ArkProvider, SettlementEvent, FeeInfo, ArkInfo, SignedIntent, Output, TxNotification, ExplorerTransaction, BatchFinalizationEvent, BatchFinalizedEvent, BatchFailedEvent, TreeSigningStartedEvent, TreeNoncesEvent, BatchStartedEvent, TreeTxEvent, TreeSignatureEvent, ScheduledSession, PaginationOptions, SubscriptionResponse, SubscriptionHeartbeat, SubscriptionEvent, Network, NetworkName, ArkTapscript, RelativeTimelock, EncodedVtxoScript, TapLeafScript, SignerSession, TreeNonces, TreePartialSigs, GetVtxosFilter, SettlementConfig, Asset, Recipient, IssuanceParams, IssuanceResult, ReissuanceParams, BurnParams, AssetDetails, AssetMetadata, KnownMetadata, Nonces, PartialSig, ArkPsbtFieldCoder, TxTreeNode, AnchorBumper, StorageConfig, Contract, ContractVtxo, ContractState, ContractEvent, ContractEventCallback, ContractBalance, ContractWithVtxos, ContractHandler, IContractManager, PathSelection, PathContext, ContractManagerConfig, CreateContractParams, ContractWatcherConfig, ParsedArkContract, DefaultContractParams, DelegateContractParams, VHTLCContractParams, MessageHandler, RequestEnvelope, ResponseEnvelope, IDelegatorManager, DelegatorProvider, DelegateInfo, DelegateOptions, WalletRepository, ContractRepository, MigrationStatus, };

package/dist/types/utils/arkTransaction.d.ts

@@ -24,7 +24,7 @@ export type OffchainTx = {
  * @returns Object containing the virtual transaction and checkpoint transactions
  */
 export declare function buildOffchainTx(inputs: ArkTxInput[], outputs: TransactionOutput[], serverUnrollScript: CSVMultisigTapscript.Type): OffchainTx;
-export declare function hasBoardingTxExpired(coin: ExtendedCoin, boardingTimelock: RelativeTimelock): boolean;
+export declare function hasBoardingTxExpired(coin: ExtendedCoin, boardingTimelock: RelativeTimelock, chainTipHeight?: number): boolean;
 /**
  * Verify tapscript signatures on a transaction input
  * @param tx Transaction to verify

package/dist/types/wallet/index.d.ts

@@ -3,7 +3,7 @@ import { ArkProvider, Output, SettlementEvent } from "../providers/ark";
 import { Identity, ReadonlyIdentity } from "../identity";
 import { RelativeTimelock } from "../script/tapscript";
 import { EncodedVtxoScript, TapLeafScript } from "../script/base";
-import { RenewalConfig } from "./vtxo-manager";
+import { RenewalConfig, SettlementConfig } from "./vtxo-manager";
 import { IndexerProvider } from "../providers/indexer";
 import { OnchainProvider } from "../providers/onchain";
 import { ContractWatcherConfig } from "../contracts/contractWatcher";
@@ -96,20 +96,26 @@ export interface ReadonlyWalletConfig extends BaseWalletConfig {
  *   onchainProvider: new EsploraProvider('https://mempool.space/api')
  * });
  *
- * // With renewal configuration
+ * // With settlement configuration
  * const wallet = await Wallet.create({
  *   identity: SingleKey.fromHex('...'),
  *   arkServerUrl: 'https://ark.example.com',
- *   renewalConfig: {
- *     enabled: true,
- *     thresholdMs: 86400000, // 24 hours
- *   }
+ *   settlementConfig: {
+ *     vtxoThreshold: 86400, // 24 hours in seconds
+ *     boardingUtxoSweep: true,
+ *   },
  * });
  * ```
  */
 export interface WalletConfig extends ReadonlyWalletConfig {
     identity: Identity;
+    /** @deprecated Use settlementConfig instead */
     renewalConfig?: RenewalConfig;
+    /**
+     * Configuration for automatic settlement and renewal.
+     * `false` = explicitly disabled, `undefined` = enabled by default, `{}` = enabled with defaults.
+     */
+    settlementConfig?: SettlementConfig | false;
 }
 export type StorageConfig = {
     walletRepository: WalletRepository;

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

@@ -1,8 +1,10 @@
-import { ExtendedVirtualCoin, IWallet } from ".";
+import { ExtendedCoin, ExtendedVirtualCoin, IWallet } from ".";
 import { SettlementEvent } from "../providers/ark";
 export declare const DEFAULT_THRESHOLD_MS: number;
+export declare const DEFAULT_THRESHOLD_SECONDS: number;
 /**
  * Configuration options for automatic VTXO renewal
+ * @deprecated Use SettlementConfig instead
  */
 export interface RenewalConfig {
     /**
@@ -14,13 +16,81 @@ export interface RenewalConfig {
      * Threshold in milliseconds to use as threshold for renewal
      * E.g., 86400000 means renew when 24 hours until expiry remains
      * @default 86400000 (24 hours)
+     * @deprecated Use SettlementConfig.vtxoThreshold (in seconds) instead
      */
     thresholdMs?: number;
 }
+/**
+ * Configuration for automatic settlement and renewal.
+ *
+ * Controls two behaviors:
+ * 1. **VTXO renewal**: Automatically renew VTXOs that are close to expiry
+ * 2. **Boarding UTXO sweep**: Sweep expired boarding UTXOs back to a fresh boarding address
+ *    via the unilateral exit path (on-chain self-spend to restart the timelock)
+ *
+ * Enabled by default when no config is provided.
+ * Pass `false` to explicitly disable all settlement behavior.
+ *
+ * @example
+ * ```typescript
+ * // Default behavior: VTXO renewal at 3 days + boarding sweep enabled
+ * const wallet = await Wallet.create({
+ *   identity: SingleKey.fromHex('...'),
+ *   arkServerUrl: 'https://ark.example.com',
+ * });
+ *
+ * // Custom threshold
+ * const wallet = await Wallet.create({
+ *   identity: SingleKey.fromHex('...'),
+ *   arkServerUrl: 'https://ark.example.com',
+ *   settlementConfig: {
+ *     vtxoThreshold: 86400, // 24 hours in seconds
+ *   },
+ * });
+ *
+ * // Explicitly disable
+ * const wallet = await Wallet.create({
+ *   identity: SingleKey.fromHex('...'),
+ *   arkServerUrl: 'https://ark.example.com',
+ *   settlementConfig: false,
+ * });
+ * ```
+ */
+export interface SettlementConfig {
+    /**
+     * Seconds before VTXO expiry to trigger renewal.
+     * @default 259200 (3 days)
+     */
+    vtxoThreshold?: number;
+    /**
+     * Sweep expired boarding UTXOs back to a fresh boarding address
+     * via the unilateral exit path (on-chain self-spend to restart the timelock).
+     *
+     * When enabled, expired boarding UTXOs are batched into a single on-chain transaction
+     * with multiple inputs and one output. A dust check ensures the sweep is only
+     * performed when the output after fees is above dust.
+     *
+     * @default true
+     */
+    boardingUtxoSweep?: boolean;
+    /**
+     * Polling interval in milliseconds for checking boarding UTXOs.
+     * The poll loop auto-settles new boarding UTXOs into Ark and
+     * sweeps expired ones (when boardingUtxoSweep is enabled).
+     *
+     * @default 60000 (1 minute)
+     */
+    pollIntervalMs?: number;
+}
 /**
  * Default renewal configuration values
+ * @deprecated Use DEFAULT_SETTLEMENT_CONFIG instead
  */
 export declare const DEFAULT_RENEWAL_CONFIG: Required<Omit<RenewalConfig, "enabled">>;
+/**
+ * Default settlement configuration values
+ */
+export declare const DEFAULT_SETTLEMENT_CONFIG: Required<SettlementConfig>;
 /**
  * Check if a VTXO is expiring soon based on threshold
  *
@@ -75,10 +145,21 @@ export declare function getExpiringAndRecoverableVtxos(vtxos: ExtendedVirtualCoi
  * }
  * ```
  */
-export declare class VtxoManager {
+export declare class VtxoManager implements AsyncDisposable {
     readonly wallet: IWallet;
+    /** @deprecated Use settlementConfig instead */
     readonly renewalConfig?: RenewalConfig | undefined;
-    constructor(wallet: IWallet, renewalConfig?: RenewalConfig | undefined);
+    readonly settlementConfig: SettlementConfig | false;
+    private contractEventsSubscription?;
+    private readonly contractEventsSubscriptionReady;
+    private disposePromise?;
+    private pollIntervalId?;
+    private knownBoardingUtxos;
+    private sweptBoardingUtxos;
+    private pollInProgress;
+    constructor(wallet: IWallet, 
+    /** @deprecated Use settlementConfig instead */
+    renewalConfig?: RenewalConfig | undefined, settlementConfig?: SettlementConfig | false);
     /**
      * Recover swept/expired VTXOs by settling them back to the wallet's Ark address.
      *
@@ -177,4 +258,86 @@ export declare class VtxoManager {
      * ```
      */
     renewVtxos(eventCallback?: (event: SettlementEvent) => void): Promise<string>;
+    /**
+     * Get boarding UTXOs whose timelock has expired.
+     *
+     * These UTXOs 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 UTXOs
+     *
+     * @example
+     * ```typescript
+     * const manager = new VtxoManager(wallet);
+     * const expired = await manager.getExpiredBoardingUtxos();
+     * if (expired.length > 0) {
+     *   console.log(`${expired.length} expired boarding UTXOs to sweep`);
+     * }
+     * ```
+     */
+    getExpiredBoardingUtxos(): Promise<ExtendedCoin[]>;
+    /**
+     * Sweep expired boarding UTXOs back to a fresh boarding address via
+     * the unilateral exit path (on-chain self-spend).
+     *
+     * This builds a raw on-chain transaction that:
+     * - Uses all expired boarding UTXOs 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 UTXOs into one transaction
+     * - Skips the sweep if the output after fees would be below dust
+     *
+     * No Ark server involvement is needed — this is a pure on-chain transaction.
+     *
+     * @returns The broadcast transaction ID
+     * @throws Error if no expired boarding UTXOs found
+     * @throws Error if output after fees is below dust (not economical to sweep)
+     * @throws Error if boarding UTXO sweep is not enabled in settlementConfig
+     *
+     * @example
+     * ```typescript
+     * const manager = new VtxoManager(wallet, undefined, {
+     *   boardingUtxoSweep: true,
+     * });
+     *
+     * try {
+     *   const txid = await manager.sweepExpiredBoardingUtxos();
+     *   console.log('Swept expired boarding UTXOs:', txid);
+     * } catch (e) {
+     *   console.log('No sweep needed or not economical');
+     * }
+     * ```
+     */
+    sweepExpiredBoardingUtxos(): 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 on-chain provider for fee estimation and broadcasting. */
+    private getOnchainProvider;
+    /** Returns the Bitcoin network configuration from the wallet. */
+    private getNetwork;
+    /** Returns the wallet's identity for transaction signing. */
+    private getIdentity;
+    private initializeSubscription;
+    /**
+     * Starts a polling loop that:
+     * 1. Auto-settles new boarding UTXOs into Ark
+     * 2. Sweeps expired boarding UTXOs (when boardingUtxoSweep is enabled)
+     */
+    private startBoardingUtxoPoll;
+    private pollBoardingUtxos;
+    /**
+     * Auto-settle new (unexpired) boarding UTXOs into the Ark.
+     * Skips UTXOs that are already expired (those are handled by sweep).
+     * Only settles UTXOs not already in-flight (tracked in knownBoardingUtxos).
+     * UTXOs are marked as known only after a successful settle, so failed
+     * attempts will be retried on the next poll.
+     */
+    private settleBoardingUtxos;
+    dispose(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
 }

package/dist/types/wallet/wallet.d.ts

@@ -9,6 +9,7 @@ import { SignerSession } from "../tree/signingSession";
 import { Identity, ReadonlyIdentity } from "../identity";
 import { ArkTransaction, Recipient, Coin, ExtendedCoin, ExtendedVirtualCoin, GetVtxosFilter, IReadonlyWallet, IWallet, ReadonlyWalletConfig, SendBitcoinParams, SettleParams, WalletBalance, WalletConfig, IAssetManager, IReadonlyAssetManager } from ".";
 import { CSVMultisigTapscript } from "../script/tapscript";
+import { SettlementConfig, VtxoManager } from "./vtxo-manager";
 import { Intent } from "../intent";
 import { IndexerProvider } from "../providers/indexer";
 import { WalletRepository } from "../repositories/walletRepository";
@@ -122,6 +123,8 @@ export declare class ReadonlyWallet implements IReadonlyWallet {
      */
     getContractManager(): Promise<ContractManager>;
     private initializeContractManager;
+    dispose(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
 }
 /**
  * Main wallet implementation for Bitcoin transactions with Ark protocol support.
@@ -165,13 +168,21 @@ export declare class Wallet extends ReadonlyWallet implements IWallet {
     static MIN_FEE_RATE: number;
     readonly identity: Identity;
     private readonly _delegatorManager?;
+    private _vtxoManager?;
+    private _vtxoManagerInitializing?;
     private _walletAssetManager?;
+    /** @deprecated Use settlementConfig instead */
     readonly renewalConfig: Required<Omit<WalletConfig["renewalConfig"], "enabled">> & {
         enabled: boolean;
         thresholdMs: number;
     };
-    protected constructor(identity: Identity, network: Network, networkName: NetworkName, 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, renewalConfig?: WalletConfig["renewalConfig"], delegatorProvider?: DelegatorProvider, watcherConfig?: WalletConfig["watcherConfig"]);
+    readonly settlementConfig: SettlementConfig | false;
+    protected constructor(identity: Identity, network: Network, networkName: NetworkName, 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, 
+    /** @deprecated Use settlementConfig */
+    renewalConfig?: WalletConfig["renewalConfig"], delegatorProvider?: DelegatorProvider, watcherConfig?: WalletConfig["watcherConfig"], settlementConfig?: WalletConfig["settlementConfig"]);
     get assetManager(): IAssetManager;
+    getVtxoManager(): Promise<VtxoManager>;
+    dispose(): Promise<void>;
     static create(config: WalletConfig): Promise<Wallet>;
     /**
      * Convert this wallet to a readonly wallet.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkade-os/sdk",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "description": "Bitcoin wallet SDK with Taproot and Ark integration",
   "type": "module",
   "main": "./dist/cjs/index.js",