@arkade-os/sdk Documentation - v0.4.36
    Preparing search index...

    Interface IVtxoManager

    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)
    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();
    }
    interface IVtxoManager {
        dispose(): Promise<void>;
        getDeprecatedSignerStatus(): Promise<DeprecatedSignerReport[]>;
        getExpiredBoardingUtxos(): Promise<ExtendedCoin[]>;
        getExpiringVtxos(thresholdMs?: number): Promise<ExtendedVirtualCoin[]>;
        getRecoverableBalance(): Promise<
            {
                includesSubdust: boolean;
                recoverable: bigint;
                subdust: bigint;
                vtxoCount: number;
            },
        >;
        migrateDeprecatedSignerVtxos(
            options?: MigrateDeprecatedSignerOptions,
        ): Promise<DeprecatedSignerMigrationReport>;
        recoverVtxos(
            eventCallback?: (event: SettlementEvent) => void,
        ): Promise<string>;
        renewVtxos(
            eventCallback?: (event: SettlementEvent) => void,
            options?: RenewVtxosOptions,
        ): Promise<string>;
        sweepExpiredBoardingUtxos(): Promise<string>;
    }

    Implemented by

    Index

    Methods

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

    • Cooperatively migrate VTXOs minted under a now-deprecated server signer to the wallet's active-signer address (planned arkd key rotation).

      Applies a mid-session server-signer rotation first when the wallet's own snapshot signer has been deprecated, so the migration output commits to the active signer. Selects spendable VTXOs under deprecated-signer contracts, prioritizing those closest to their cutoff, and settles them back to the (rotated) Ark address. VTXOs whose cutoff has already passed are reported as expired rather than migrated.

      Available regardless of the deprecatedSignerMigration config flag (that flag only gates the automatic poll-loop pass).

      Parameters

      Returns Promise<DeprecatedSignerMigrationReport>

      A report of what was migrated, skipped, expired, or failed.