Class ReadonlyWallet

Readonlyactivity

ReadonlycontractRepository

Optional ReadonlydelegateProvider

ReadonlydustAmount

OptionalexitDataCapture

Readonlyidentity

ReadonlyindexerProvider

OptionalintentRepository

Readonlynetwork

ReadonlyonchainProvider

OptionalvirtualTxRepository

ReadonlywalletContractTimelocks

ReadonlywalletRepository

arkAddress

• get arkAddress(): ArkAddress

  Returns ArkAddress

arkServerPublicKey

• 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

assetManager

• get assetManager(): IReadonlyAssetManager

  Readonly asset manager bound to this wallet instance.

  Returns IReadonlyAssetManager

boardingTapscript

• get boardingTapscript(): DefaultVtxo.Script

  The wallet's current boarding tapscript (the on-chain onboarding target). Read-only from the outside; mutated only via Wallet.setBoardingTapscriptForRotation when a fresh boarding address is explicitly allocated. Single-valued for static / auto wallets.

  Returns DefaultVtxo.Script

defaultContractScript

• 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

offchainTapscript

• get offchainTapscript(): DefaultVtxo.Script | DelegateVtxo.Script

  Currently-active receive tapscript. Read-only from the outside; mutated only via Wallet.setOffchainTapscriptForRotation by WalletReceiveRotator.rotate.

  Returns DefaultVtxo.Script | DelegateVtxo.Script

serverInfoSource

• get serverInfoSource(): ServerInfoSource

  Returns ServerInfoSource

  See

  _serverInfoSource

[asyncDispose]

• "[asyncDispose]"(): Promise<void>

  Async-dispose hook that forwards to dispose().

  Returns Promise<void>

clear

• clear(): Promise<void>

  Wipe all locally persisted wallet data (VTXOs, UTXOs, history, sync cursor, contracts). Create a fresh wallet instance afterward.

  Returns Promise<void>

clearSyncCursor

• clearSyncCursor(): Promise<void>

  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>

dispose

• dispose(): Promise<void>

  Dispose wallet-owned managers and release background resources.

  Returns Promise<void>

fetchPendingTxs

• fetchPendingTxs(): Promise<string[]>

  Fetch Arkade transaction ids that are still pending final settlement.

  Returns Promise<string[]>

getActivityHistory

• getActivityHistory(): Promise<Activity[]>

  Wallet history grouped by registered activity resolvers. With no resolver match, rows bucket by transaction key so send/change pairs stay together.

  Returns Promise<Activity[]>

getAddress

• getAddress(): Promise<string>

  Returns the wallet's Arkade address.

  Returns Promise<string>

getBalance

• getBalance(): Promise<WalletBalance>

  Return the wallet's combined onchain and offchain balances.

  Returns Promise<WalletBalance>

getBoardingAddress

• getBoardingAddress(): Promise<string>

  Returns the onchain boarding address used to move funds into Arkade.

  Returns Promise<string>

getBoardingAddresses

• getBoardingAddresses(): Promise<string[]>

  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[]>

getBoardingTxs

• getBoardingTxs(): Promise<
      { boardingTxs: ArkTransaction[]; commitmentsToIgnore: Set<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> }>

getBoardingUtxos

• getBoardingUtxos(): Promise<ExtendedCoin[]>

  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[]>

getBoardingUtxosForSigners

• getBoardingUtxosForSigners(
      allowedSigners: Set<string>,
  ): Promise<BoardingUtxoGroup[]>

  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[]>

getContractManager

• getContractManager(): Promise<ContractManager>

  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>

  Example

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

getContractSyncState

• getContractSyncState(): ContractSyncState

  The contract-manager's current provider-sync health without forcing it to initialize — reads the already-constructed manager, or reports online when none exists yet. Unlike getContractManager, this never triggers a remote sync, so it is safe on a pure diagnostics path (e.g. the service-worker sync-state message).

  Returns ContractSyncState

getProviderConnectionState

• getProviderConnectionState(): ProviderConnectionState

  Composed provider-connection freshness: the boot server-info source (Arkade) 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.

  • Boot fell back to a 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

getScriptMap

• getScriptMap(): Promise<Map<string, DefaultVtxo.Script | DelegateVtxo.Script>>

  Build a map of scriptHex → VtxoScript for all wallet contracts, so virtual outputs can be extended with the correct tapscript per contract.

  Returns Promise<Map<string, DefaultVtxo.Script | DelegateVtxo.Script>>

getTransactionHistory

• getTransactionHistory(): Promise<ArkTransaction[]>

  Return wallet transaction history derived from Arkade state and boarding transactions.

  Returns Promise<ArkTransaction[]>

getVtxos

• getVtxos(filter?: GetVtxosFilter): Promise<NormalizedExtendedVirtualCoin[]>

  Return virtual outputs tracked by the wallet.

  Parameters

  • Optionalfilter: GetVtxosFilter

    Optional flags controlling whether recoverable or unrolled VTXOs are included

  Returns Promise<NormalizedExtendedVirtualCoin[]>

getWalletScripts

• getWalletScripts(): Promise<string[]>

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

  Returns Promise<string[]>

notifyIncomingFunds

• notifyIncomingFunds(
      eventCallback: (coins: IncomingFunds) => void,
  ): 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

pendingRecoveryOutpoints

• pendingRecoveryOutpoints(): Promise<Set<string>>

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

refreshDeprecatedSigners

• refreshDeprecatedSigners(
      info: {
          deprecatedSigners?: readonly { cutoffDate?: bigint; pubkey?: string }[];
      },
  ): void

  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

Staticcreate

• create(config: ReadonlyWalletConfig): Promise<ReadonlyWallet>

  Create a readonly wallet for querying balances, addresses, and history.

  Parameters

  • config: ReadonlyWalletConfig

    Readonly wallet configuration

  Returns Promise<ReadonlyWallet>

  A readonly wallet instance