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

    Class ReadonlyWallet

    Readonly wallet interface for Bitcoin transactions with Arkade protocol support.

    This interface defines the contract that all wallet implementations must follow. It provides methods for address management, balance checking, virtual output operations, and transaction management including sending, settling, and unrolling.

    IWallet

    Hierarchy (View Summary)

    Implements

    Index

    Properties

    activity contractRepository delegateProvider? dustAmount exitDataCapture? identity indexerProvider intentRepository? network onchainProvider virtualTxRepository? walletContractTimelocks walletRepository

    Accessors

    arkAddress arkServerPublicKey assetManager boardingTapscript defaultContractScript offchainTapscript serverInfoSource

    Methods

    [asyncDispose] clear clearSyncCursor dispose fetchPendingTxs getActivityHistory getAddress getArkadeInfo getArkadeReader getBalance getBoardingAddress getBoardingAddresses getBoardingTxs getBoardingUtxos getBoardingUtxosForSigners getContractManager getContractSyncState getProviderConnectionState getScriptMap getSpendableVtxos getTransactionHistory getVtxos getWalletScripts logUngatedInputs notifyIncomingFunds pendingRecoveryOutpoints pendingRecoveryOutpointsIn refreshDeprecatedSigners create

    Properties

    activity: ActivityRegistry = ...

    Activity resolvers consumed by getActivityHistory.

    contractRepository: ContractRepository
    delegateProvider?: DelegateProvider
    dustAmount: bigint
    exitDataCapture?: {
        minExitWorthSats?: number;
        mode?: ExitCaptureMode;
        sources?: ExitDataSource[];
    }

    Opt-in exit-data capture settings; see StorageConfig.exitDataCapture.

    identity: ReadonlyIdentity

    Readonly identity associated with the wallet.

    indexerProvider: IndexerProvider
    intentRepository?: IntentRepository

    Opt-in intent-lifecycle repository. Assigned by the create() factories from config.storage.intentRepository; undefined ⇒ all intent-persistence code paths are no-ops (default behaviour unchanged).

    network: Network
    onchainProvider: OnchainProvider
    virtualTxRepository?: VirtualTxRepository

    Experimental / inert. Opt-in virtual-tx / exit-branch repository, exposed so callers can pass it to Unroll.Session.create as a best-effort raw-tx cache. Assigned by create() from config.storage.virtualTxRepository. Normal sync never writes it (ContractManager isn't given it); undefined ⇒ no-op.

    walletContractTimelocks: RelativeTimelock[]
    walletRepository: WalletRepository

    Accessors

    • get defaultContractScript(): string

      Get the pkScript hex for the wallet's primary offchain address. For the full wallet-owned script set registered in ContractManager, use getWalletScripts().

      Returns string

    Methods

    • Clear the global VTXO sync cursor, forcing a full re-bootstrap on next sync. Useful for recovery after indexer reprocessing or debugging.

      Returns Promise<void>

    • Server info for the Arkade server this wallet is connected to, resolved exactly as construction resolves it: live wins, a retryable failure falls back to the snapshot persisted at boot, a terminal one propagates.

      Live rather than the pinned boot snapshot because the fields callers come here for — signerPubkey, checkpointTapscript, fees — are the ones a mid-session rotation moves, and a covenant built against a superseded signer is unspendable.

      One rotation caveat: reading does NOT re-pin the wallet — arkServerPublicKey, dustAmount and the tapscripts move only through handleServerInfoChanged/rotateServerSigner — so inside a rotation window this can report epoch N+1 while the wallet still spends on N. The window closes on its own: a read that observes a moved digest makes the provider emit onServerInfoChanged, which is what drives that rotation. A caller about to bind the answer into a covenant passes { requireLive: true } and fails closed instead of receiving the boot snapshot.

      Parameters

      Returns Promise<ArkadeInfo>

      The Arkade server's info

      ArkadeInfo

    • Chain reads against this wallet's server for scripts it does not own.

      Binds the wallet's own indexerProvider — which may be an Expo or injected one that a caller's hand-built RestIndexerProvider would silently bypass. getVtxos goes through getNormalizedVtxos, which is what makes every VTXO leaving the seam carry its canonical facts.

      A bound object rather than the provider itself, so an IReadonlyWallet holder gets getVtxos/getVirtualTxs and nothing else at runtime. (indexerProvider is still public on the concrete classes, unlike arkProvider, so this narrows the interface rather than the field.)

      Returns Promise<ArkadeReader>

    • The on-chain (P2TR) addresses of every boarding tapscript this wallet uses — the current address plus any historical rotated boarding addresses. The aggregating boarding readers (history, notifications) fan out over this set so deposits at previous boarding addresses are still surfaced (plan §6-IV); getBoardingAddress stays single-valued.

      Returns Promise<string[]>

    • Build a transaction history view across the wallet's boarding addresses (current + historical rotated; plan §6-IV.1).

      Returns Promise<{ boardingTxs: ArkTransaction[]; commitmentsToIgnore: Set<string> }>

    • Fetch and cache onchain inputs (UTXOs) received at the wallet's boarding addresses — the current address plus any historical rotated boarding addresses that still hold unspent UTXOs (plan §6-III.1). Each UTXO is annotated with the tapscript of the address it actually sits on, so the spending path forfeits / exits it with the correct per-index leaves.

      Current-signer only: a flatten of getBoardingUtxosForSigners over the wallet's current signer, so the two paths cannot drift. Old-signer boarding recovery goes through the deprecated-signer migration API instead (it would otherwise pull EXPIRED-signer inputs into a plain settle() that the server must reject).

      Returns Promise<ExtendedCoin[]>

    • Fetch and cache onchain inputs (UTXOs) received at the boarding addresses of the given signer set, grouped per boarding address so the caller keeps the address↔signer association that ExtendedCoin cannot carry (it retains only the encoded leaves/tapTree the spend needs, not the DefaultVtxo.Script and its serverPubKey/CSV delay).

      Per group it does exactly what getBoardingUtxos does per tapscript: getCoins → extendCoinWithTapscript → saveUtxos. Offline-first: it does not call getInfo(); the caller supplies the allowed signer set, so the only network calls are the per-address getCoins.

      Parameters

      • allowedSigners: Set<string>

        x-only-hex server keys whose boarding addresses to fetch (passed through to getBoardingTapscripts).

      Returns Promise<BoardingUtxoGroup[]>

    • Get the ContractManager for managing contracts including the wallet's default address.

      The ContractManager handles:

      • The wallet's default receiving address (as a "default" contract)
      • External contracts (Boltz swaps, HTLCs, etc.)
      • Multi-contract watching with resilient connections

      Returns Promise<ContractManager>

      const manager = await wallet.getContractManager();

      // Create a contract for a Boltz swap
      const contract = await manager.createContract({
        label: "Boltz Swap",
        type: "vhtlc",
        params: { ... },
        script: swapScript,
        address: swapAddress,
      });

      // Start watching for events (includes wallet's default address)
      const stop = await manager.onContractEvent((event) => {
        console.log(`${event.type} on ${event.contractScript}`);
      });

    • Composed provider-connection freshness: the LATEST server-info resolution (boot, or any later getArkadeInfo read) combined with the contract-manager's indexer-sync health, if the manager has been initialized. Reads no live provider state — it never forces a ContractManager to construct — so it is safe for readonly callers that only use address/balance APIs.

      • Latest resolution fell back to the cached snapshot → degraded on arkade (cache).
      • Otherwise, if the contract manager has degraded to repository data → degraded on indexer (repository).
      • Otherwise online.

      This only describes sync freshness; wallet balances/VTXOs are always read from the repository regardless of this state.

      Returns ProviderConnectionState

    • Get all pkScript hex strings for the wallet's own addresses (both delegate and non-delegate, current and historical).

      Returns Promise<string[]>

    • Debug-log any explicit input generic selection would have excluded, for each of the three reasons it excludes on. Explicit-input APIs stay ungated on purpose (naming an outpoint is the intent the gate protects, and it is how an escrowed deposit is recovered once generic selection stops covering it), so this only makes the crossing visible — notably settle({ inputs: await wallet.getVtxos() }), which launders the raw read into a spend. Never throws into a spend path.

      Public so the worker handler and plugins can report their own explicit-input crossings through the same three checks.

      Parameters

      • source: string
      • inputs: readonly { script?: string; txid: string; vout: number }[]

      Returns Promise<void>

    • Subscribe to onchain and offchain notifications for newly received funds.

      The onchain watcher tracks the full boarding-address set (current + historical rotated). When boarding rotates after subscribing — e.g. rotate-on-board allocates a fresh address via getNewBoardingAddress — the watcher automatically re-subscribes to widen its set, so a deposit to the new address fires a notification within the same session (no watcher re-init required). The re-subscribe is driven by onBoardingRotation; static / auto / readonly wallets never rotate boarding, so it never fires for them.

      Parameters

      • eventCallback: (coins: IncomingFunds) => void

        Callback invoked when matching funds are detected

      Returns Promise<() => void>

      A function that stops the subscriptions

    • Outpoints of VTXOs whose deprecated signer is past its cutoff (EXPIRED) and which have not yet been swept — unspendable until they recover. Offline: classifies the repo's contracts against the cached signer set (active + _deprecatedSigners, cutoffs included). Empty fast-path when no signer is deprecated. Consumed by getBalance (the pendingRecovery bucket) and by getSpendableVtxos so neither counts nor spends them.

      Takes a fresh contractSnapshot, which syncs against the indexer. Callers that already hold a snapshot — or that must not sync at all, like the worker's balance read — pass it to pendingRecoveryOutpointsIn instead.

      Returns Promise<Set<string>>

    • pendingRecoveryOutpoints over a snapshot the caller already has: pure classification against the cached signer set, no repository or network read of its own.

      Parameters

      • snapshot: readonly {
            contract: { params: { serverPubKey?: string } };
            vtxos: readonly VirtualCoin[];
        }[]

      Returns Set<string>

    • Refresh the cached deprecated-signer set from a fresh server-info snapshot. Called by the create() factories at construction, by the server-info-change handler mid-session, and by the deprecated-signer migration pass (VtxoManager.migrateDeprecatedSignerVtxos). This set feeds pendingRecoveryOutpoints, which drops EXPIRED (past-cutoff) deprecated-signer VTXOs from the wallet's own coin selection. Lenient: a malformed deprecated entry is skipped, never fatal to wallet creation.

      Parameters

      • info: { deprecatedSigners?: readonly { cutoffDate?: bigint; pubkey?: string }[] }

      Returns void

    Settings

    Member Visibility

    On This Page

    Properties
    Accessors
    Methods