Class VtxoManager

constructor

• new VtxoManager(wallet: IWallet, renewalConfig?: RenewalConfig): VtxoManager

  Parameters

  • wallet: IWallet
  • OptionalrenewalConfig: RenewalConfig

  Returns VtxoManager

Optional ReadonlyrenewalConfig

Readonlywallet

getExpiringVtxos

• getExpiringVtxos(thresholdMs?: number): Promise<ExtendedVirtualCoin[]>

  Get VTXOs that are expiring soon based on renewal configuration

  Parameters

  • OptionalthresholdMs: number

    Optional override for threshold in milliseconds

  Returns Promise<ExtendedVirtualCoin[]>

  Array of expiring VTXOs, empty array if renewal is disabled or no VTXOs expiring

  Example

  const manager = new VtxoManager(wallet, { enabled: true, thresholdMs: 86400000 });
  const expiringVtxos = await manager.getExpiringVtxos();
  if (expiringVtxos.length > 0) {
    console.log(`${expiringVtxos.length} VTXOs expiring soon`);
  }
  Copy

getRecoverableBalance

• getRecoverableBalance(): Promise<
      {
          includesSubdust: boolean;
          recoverable: bigint;
          subdust: bigint;
          vtxoCount: number;
      },
  >

  Get information about recoverable balance without executing recovery.

  Useful for displaying to users before they decide to recover funds.

  Returns Promise<
      {
          includesSubdust: boolean;
          recoverable: bigint;
          subdust: bigint;
          vtxoCount: number;
      },
  >

  Object containing recoverable amounts and subdust information

  Example

  const manager = new VtxoManager(wallet);
  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 VTXOs`);
    }
  }
  Copy

recoverVtxos

• recoverVtxos(eventCallback?: (event: SettlementEvent) => void): Promise<string>

  Recover swept/expired VTXOs by settling them back to the wallet's Ark address.

  This method:

  1. Fetches all VTXOs (including recoverable ones)
  2. Filters for swept but still spendable VTXOs and preconfirmed subdust
  3. Includes subdust VTXOs if the total value >= dust threshold
  4. Settles everything back to the wallet's Ark address

  Note: Settled VTXOs with long expiry are NOT recovered to avoid locking liquidity unnecessarily. Only preconfirmed subdust is recovered to consolidate small amounts.

  Parameters

  • OptionaleventCallback: (event: SettlementEvent) => void

    Optional callback to receive settlement events

  Returns Promise<string>

  Settlement transaction ID

  Throws

  Error if no recoverable VTXOs found

  Example

  const manager = new VtxoManager(wallet);
  
  // Simple recovery
  const txid = await manager.recoverVtxos();
  
  // With event callback
  const txid = await manager.recoverVtxos((event) => {
    console.log('Settlement event:', event.type);
  });
  Copy

renewVtxos

• renewVtxos(eventCallback?: (event: SettlementEvent) => void): Promise<string>

  Renew expiring VTXOs by settling them back to the wallet's address

  This method collects all expiring spendable VTXOs (including recoverable ones) and settles them back to the wallet, effectively refreshing their expiration time. This is the primary way to prevent VTXOs from expiring.

  Parameters

  • OptionaleventCallback: (event: SettlementEvent) => void

    Optional callback for settlement events

  Returns Promise<string>

  Settlement transaction ID

  Throws

  Error if no VTXOs available to renew

  Throws

  Error if total amount is below dust threshold

  Example

  const manager = new VtxoManager(wallet);
  
  // Simple renewal
  const txid = await manager.renewVtxos();
  
  // With event callback
  const txid = await manager.renewVtxos((event) => {
    console.log('Settlement event:', event.type);
  });
  Copy