@arkade-os/sdk Documentation - v0.5.0-rc.11
    Preparing search index...

    Class VtxoManager

    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 (isSwept) and they remain spendable
    • They are preconfirmed subdust (to consolidate small amounts without locking liquidity on settled virtual outputs)
    const wallet = await Wallet.create({
      identity,
      arkProvider: new RestArkProvider(),
      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();
    }

    Implements

    Index

    Constructors

    constructor

    Properties

    settlementConfig wallet

    Methods

    [asyncDispose] dispose getDeprecatedSignerStatus getExpiredBoardingUtxos getExpiringVtxos getRecoverableBalance migrateDeprecatedSignerVtxos recoverVtxos renewVtxos sweepExpiredBoardingUtxos

    Constructors

    Properties

    settlementConfig: false | SettlementConfig
    wallet: IWallet

    Methods

    • 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.

      Parameters

      Returns Promise<ExtendedCoin[]>

      Array of expired boarding inputs

      const manager = await wallet.getVtxoManager();
      const expired = await manager.getExpiredBoardingUtxos();
      if (expired.length > 0) {
        console.log(`${expired.length} expired boarding inputs to sweep`);
      }

    • Get virtual outputs that are expiring soon based on renewal configuration

      Parameters

      • OptionalthresholdMs: number

        Optional override for threshold in milliseconds

      Returns Promise<NormalizedExtendedVirtualCoin[]>

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

      const wallet = await Wallet.create({
       identity,
       arkProvider: new RestArkProvider(),
       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`);
      }

    • Get information about recoverable balance without executing recovery.

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

      Both amounts are net of the operator's intent fees, so recoverable is what recoverVtxos would actually hand back rather than the gross sum of the inputs. subdust is net of the per-input fees only — the output fee is charged on the batch as a whole and is not attributed per coin — so it reports what the subdust coins are worth once each has paid its own way, and is not strictly a slice of recoverable. It can exceed recoverable where a flat output fee meets a wholly subdust wallet.

      The batch size caps are not applied here: they defer the overflow to the next cycle rather than reducing what is recoverable.

      Inputs a contract refuses right now are excluded, so this and recoverVtxos answer over the same set. Balance.recoverable still counts them: that field reports what the wallet owns, this one what a batch would hand back today.

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

      Object containing recoverable amounts and subdust information

      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`);
        }
      }

    • 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.

      Inputs whose contract refuses a spend right now — an immature VHTLC refund path — are skipped rather than failing the batch that holds them, and getRecoverableBalance skips the same set. See unspendableNow for which rows that reaches.

      Parameters

      • OptionaleventCallback: (event: SettlementEvent) => void

        Optional callback to receive settlement events

      Returns Promise<string>

      Settlement transaction ID

      Error if no recoverable virtual outputs found

      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);
      });

    • 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.

      Parameters

      Returns Promise<string>

      Settlement transaction ID

      Error if no virtual outputs available to renew

      Error if total amount is below dust threshold

      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);
      });

      // Renew only VTXOs that expire within 6 hours
      const txid = await manager.renewVtxos(undefined, { thresholdSeconds: 6 * 60 * 60 });

    • 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.

      Parameters

      Returns Promise<string>

      The broadcast transaction ID

      Error if no expired boarding inputs are found

      Error if output after fees is below dust (not economical to sweep)

      Error if boarding input sweep is not enabled in settlementConfig

      const wallet = await Wallet.create({
        identity,
        arkProvider: new RestArkProvider(),
        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');
      }

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Methods