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

    Class Wallet

    Main wallet implementation for Bitcoin transactions with Arkade protocol support. The wallet does not store any data locally and relies on Arkade and onchain providers to fetch onchain and virtual outputs.

    // Create a wallet with providers
    const wallet = await Wallet.create({
      identity: MnemonicIdentity.fromMnemonic('abandon abandon...'),
      arkProvider: new RestArkProvider(),
      onchainProvider: new EsploraProvider()
    });

    // Use custom providers and/or URLs (e.g., for Expo/React Native)
    const wallet = await Wallet.create({
      identity: MnemonicIdentity.fromMnemonic('abandon abandon...'),
      arkProvider: new ExpoArkProvider('https://arkade.computer'),
      indexerProvider: new ExpoIndexerProvider('https://arkade.computer'),
      onchainProvider: new EsploraProvider('https://mempool.space/api')
    });

    // Get addresses
    const arkAddress = await wallet.getAddress();
    const boardingAddress = await wallet.getBoardingAddress();

    // Send bitcoin
    const txid = await wallet.send({
      address: 'ark1q...',
      amount: 50000,
    });

    Hierarchy (View Summary)

    Implements

    Index

    Properties

    arkProvider contractRepository delegateProvider? dustAmount forfeitOutputScript forfeitPubkey identity indexerProvider network onchainProvider renewalConfig settlementConfig walletContractTimelocks walletRepository MIN_FEE_RATE

    Accessors

    arkAddress arkServerPublicKey assetManager boardingTapscript defaultContractScript offchainTapscript serverUnrollScript

    Methods

    [asyncDispose] buildAndSubmitOffchainTx clearSyncCursor createBatchHandler dispose fetchPendingTxs finalizePendingTxs getAddress getBalance getBoardingAddress getBoardingAddresses getBoardingTxs getBoardingUtxos getBoardingUtxosForSigners getContractManager getDelegateManager getDelegatorManager getNewBoardingAddress getScriptMap getTransactionHistory getVtxoManager getVtxos getWalletScripts makeDeleteIntentSignature makeGetPendingTxIntentSignature makeRegisterIntentSignature notifyIncomingFunds pendingRecoveryOutpoints refreshDeprecatedSigners restore rotateServerSigner safeRegisterIntent send sendBitcoin sendSelectedVtxosToSelf setArkServerPublicKeyForRotation setBoardingTapscriptForRotation setOffchainTapscriptForRotation setServerUnrollScriptForRotation settle signOnchainBoardingTx toReadonly create

    Properties

    arkProvider: ArkProvider
    contractRepository: ContractRepository
    delegateProvider?: DelegateProvider
    dustAmount: bigint
    forfeitOutputScript: Bytes
    forfeitPubkey: Bytes
    identity: Identity

    Signing identity associated with the wallet.

    indexerProvider: IndexerProvider
    network: Network
    onchainProvider: OnchainProvider
    renewalConfig: Required<Omit<RenewalConfig | undefined, "enabled">> & {
        enabled: boolean;
        thresholdMs: number;
    }

    Use settlementConfig instead

    settlementConfig: false | SettlementConfig
    walletContractTimelocks: RelativeTimelock[]
    walletRepository: WalletRepository
    MIN_FEE_RATE: number = 1

    Accessors

    • get arkServerPublicKey(): Bytes

      The wallet's current active server signer (x-only, 32 bytes). Read-only from the outside; mutated only via Wallet.setArkServerPublicKeyForRotation during mid-session server-signer rotation (plan §4). Single-valued for wallets that never span a rotation.

      Returns Bytes

    • 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

    • Build an offchain transaction from the given inputs and outputs, sign it, submit to the Arkade provider, and finalize.

      Parameters

      Returns Promise<{ arkTxid: string; signedCheckpointTxs: string[] }>

      The Arkade transaction id and server-signed checkpoint PSBTs (for bookkeeping)

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

    • Create a batch event handler for settlement flows.

      Parameters

      • intentId: string

        The intent ID.

      • inputs: ExtendedCoin[]

        Inputs used by the intent.

      • expectedRecipients: Recipient[]

        Expected recipients to validate in the virtual output tree.

      • Optionalsession: SignerSession

        Optional musig2 signing session. When omitted, signing steps are skipped.

      Returns Handler

    • Finalizes pending transactions by retrieving them from the server and finalizing each one. Skips the server check entirely when no send was interrupted (no pending tx flag set).

      Parameters

      • Optionalvtxos: ExtendedVirtualCoin[]

        Optional list of virtual outputs to use instead of retrieving them from the server

      Returns Promise<{ finalized: string[]; pending: string[] }>

      Array of transaction IDs that were finalized

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

    • Allocate and return a fresh on-chain boarding address, rotating the wallet's current boarding tapscript to a new HD index.

      This is the explicit boarding allocator — the analogue of dotnet's GetNextContract(NextContractPurpose.Boarding). Unlike getBoardingAddress (a stable read of the current display address that never burns an index), each call here:

      • allocates the next index from the shared HD stream (so boarding and L2 receive interleave on one monotonic index);
      • builds the boarding tapscript at that index with the boarding-exit CSV;
      • persists an active boarding contract tagged WALLET_RECEIVE_SOURCE (with its signingDescriptor) so the ContractWatcher monitors it, boot can restore it as the current boarding address, and descriptor-aware signing can recover the per-index key;
      • swaps the wallet's current boardingTapscript.

      Gated by walletMode: a static / auto wallet has no descriptor provider and keeps a single index-0 boarding address for its lifetime, so this returns the existing getBoardingAddress unchanged (no rotation, no index burned).

      Returns Promise<string>

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

      Returns Promise<string[]>

    • 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 the send coin-selection path so neither counts nor spends them.

      Returns Promise<Set<string>>

    • Refresh the cached deprecated-signer set from a fresh server-info snapshot. Called by the create() factories at construction and by the server-info-change handler mid-session. Lenient: a malformed deprecated entry is skipped, never fatal to wallet creation.

      Parameters

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

      Returns void

    • Explicitly recover this wallet's contracts and balance on a fresh repo. HD wallets run a gap-limit scan across the index range; static / non-HD wallets restore based on the single default pubkey. Never throws because of identity/mode (a static identity is a valid, narrower restore); throws on operational failure (so a truncated restore is loud, not silent — the gap window may have closed early). Idempotent and safe to call concurrently (calls coalesce into one scan).

      Ordering is deliberate (spec §3.B / §4): scan → advance the HD watermark → inline VTXO pull → only THEN surface aggregated handler errors, so safely-discovered funds are always recovered even when one discovery handler failed.

      Parameters

      • Optionalopts: { gapLimit?: number }
        • OptionalgapLimit?: number

          Consecutive-unused-index window. Default 20. A non-positive / non-integer value is a programmer error and throws synchronously (distinct from operational failure).

      Returns Promise<void>

      Concurrent calls coalesce: if a restore is already in flight, subsequent callers receive the same promise and their gapLimit is ignored — the first caller's value governs the running scan.

    • Internal

      Mid-session server-signer rotation (plan §4). When arkd rotates its active signer mid-session — the case the long-lived service worker and Expo background processes that own automatic migration must handle — a wallet constructed before the rotation keeps deriving old-signer receive addresses. Building a migration output to such an address would produce a VTXO the server must reject, so the wallet must first re-derive its own receive state under the new active signer.

      Follows the WalletReceiveRotator.rotate write-path pattern with the server key swapped instead of the user key: build the new offchain and boarding tapscripts locally (preserving every other option), register the matching default/delegate and boarding contract rows through ContractManager.createContract, and only then commit the new tapscripts and server key to the wallet's visible state. The signing metadata of the current receive/boarding rows is carried onto the new rows so a rotated (descriptor-backed) receive pubkey can still sign.

      The old-signer contract rows are intentionally left active and watched — they are exactly the deprecated-signer contracts the migration pass drains. Idempotent: a no-op when the wallet already tracks xonly.

      Serialized against HD receive rotation so the two paths (both of which rebuild and swap offchainTapscript) cannot interleave.

      Invoked by the VtxoManager migration pass; not part of the stable public API.

      Parameters

      • newServerPubKey: Bytes
      • checkpointTapscript: string

      Returns Promise<void>

    • Send BTC and/or assets to one or more recipients.

      Parameters

      • ...args: [Recipient, ...Recipient[]]

        Recipients with their addresses, BTC amounts, and assets

      Returns Promise<string>

      Promise resolving to the Arkade transaction ID

      const txid = await wallet.send({
          address: 'ark1q...',
          amount: 1000, // (optional, default to dust) btc amount to send to the output
          assets: [{ assetId: 'abc123...', amount: 50n }] // (optional) list of assets to send
      });
    • Internal

      Migration primitive (deprecated-signer plan, step 1). Spend an explicit set of the wallet's own deprecated-signer VTXOs into a single full-value output on the wallet's active signer, through the Ark send path (not settle) so arkd builds checkpoints against the active server epoch. Consumed in-process by VtxoManager's migration pass; not part of the public IWallet API and never accepts boarding ExtendedCoin inputs.

      The caller (migrateCore) must have already moved the wallet onto the active signer (ensureReceiveOnActiveSigner) and sized the batch (caps + dust floor); this method validates the inputs, preserves all input assets on the self output, and persists the new active-signer VTXO even though there is no separate change output. It records no TxSent history — the funds never leave the wallet.

      Parameters

      Returns Promise<string>

    • Internal

      Sole write path for arkServerPublicKey after construction. Called by Wallet.rotateServerSigner once the rotated offchain and boarding contract rows have been persisted. External code must treat arkServerPublicKey as read-only.

      Parameters

      • serverPubKey: Bytes

      Returns void

    • Internal

      Sole write path for serverUnrollScript after construction. Called by Wallet._doRotateServerSigner with the checkpoint script sourced from the fresh ArkInfo that triggered the rotation, so the send path builds checkpoints against the new server epoch. External code must treat serverUnrollScript as read-only.

      Parameters

      Returns void

    • Settle boarding inputs and/or virtual outputs into a finalized mainnet transaction.

      Parameters

      • Optionalparams: SettleParams

        Optional settlement inputs and outputs. When omitted, the wallet settles all eligible funds.

      • OptionaleventCallback: (event: SettlementEvent) => void

        Optional callback invoked for settlement stream events.

      Returns Promise<string>

      The finalized Arkade transaction id

    • Internal

      Sign an on-chain boarding exit / sweep transaction, routing each input to the correct key by its witnessUtxo.script: the identity for index-0 / static boarding, the per-index descriptor for a rotated boarding UTXO (plan §6-III.3). Used by VtxoManager.sweepExpiredBoardingUtxos; without it, the unilateral exit of a rotated boarding UTXO would be signed with the wrong (index-0) key and rejected.

      Parameters

      • tx: Transaction

      Returns Promise<Transaction>

    • Convert this wallet to a readonly wallet.

      Returns Promise<ReadonlyWallet>

      A readonly wallet with the same configuration but readonly identity

      const wallet = await Wallet.create({ identity: MnemonicIdentity.fromMnemonic('abandon abandon...'), ... });
      const readonlyWallet = await wallet.toReadonly();

      // Can query balance and addresses
      const balance = await readonlyWallet.getBalance();
      const address = await readonlyWallet.getAddress();

      // But cannot send transactions (type error)
      // readonlyWallet.send(...); // TypeScript error

    • Create a full wallet and initialize its background managers.

      Parameters

      Returns Promise<Wallet>

      A wallet ready to query balances and send transactions

      const wallet = await Wallet.create({
        identity,
        arkProvider: new RestArkProvider(),
      });

    Settings

    Member Visibility

    On This Page

    Properties
    Accessors
    Methods