@arkade-os/sdk 0.4.14 → 0.4.16

package/dist/types/wallet/onchain.d.ts

@@ -9,7 +9,7 @@ import { Transaction } from "../utils/transaction";
  * Onchain Bitcoin wallet implementation for traditional Bitcoin transactions.
  *
  * This wallet handles regular Bitcoin transactions on the blockchain without
- * using the Ark protocol. It supports P2TR (Pay-to-Taproot) addresses and
+ * using the Arkade protocol. It supports P2TR (Pay-to-Taproot) addresses and
  * provides basic Bitcoin wallet functionality.
  *
  * @example
@@ -29,16 +29,38 @@ export declare class OnchainWallet implements AnchorBumper {
     readonly provider: OnchainProvider;
     readonly network: Network;
     private constructor();
+    /**
+     * Create an onchain wallet for the given identity and Bitcoin network.
+     *
+     * @param identity - Identity used to derive the Taproot key and sign transactions
+     * @param networkName - Bitcoin network name, @see NetworkName
+     * @param provider - Optional onchain provider override, @see OnchainProvider
+     * @returns Configured onchain wallet
+     * @defaultValue `provider = new EsploraProvider('https://mempool.space/api')`
+     * @throws Error if the configured identity cannot produce a valid x-only public key
+     */
     static create(identity: Identity, networkName: NetworkName, provider?: OnchainProvider): Promise<OnchainWallet>;
     get address(): string;
+    /**
+     * Fetch spendable onchain outputs for the wallet address.
+     *
+     * @returns Spendable onchain outputs for the wallet address
+     * @see getBalance
+     */
     getCoins(): Promise<Coin[]>;
+    /**
+     * Return the wallet's total onchain balance in satoshis.
+     *
+     * @returns Confirmed plus unconfirmed onchain balance
+     * @see getCoins
+     */
     getBalance(): Promise<number>;
     /**
      * Iteratively selects coins and estimates transaction fees until convergence.
      *
-     * This method handles the circular dependency between coin selection and fee
+     * This method handles the circular dependency between output selection and fee
      * estimation: the fee depends on transaction size, which depends on the number
-     * of inputs (selected coins) and whether a change output is needed.
+     * of inputs (selected outputs) and whether a change output is needed.
      *
      * The algorithm iterates up to 10 times, refining the fee estimate based on
      * the actual transaction structure. It resolves dust oscillation loops that
@@ -47,7 +69,7 @@ export declare class OnchainWallet implements AnchorBumper {
      * When a lower fee is computed (indicating the change output was dropped),
      * the function accepts this state to guarantee termination.
      *
-     * @param coins - Available coins to select from
+     * @param coins - Available onchain outputs to select from
      * @param amount - Target send amount in satoshis
      * @param feeRate - Fee rate in sat/vbyte
      * @param recipientAddress - Destination address for size estimation
@@ -55,7 +77,23 @@ export declare class OnchainWallet implements AnchorBumper {
      * @throws Error if fee estimation fails to converge within max iterations
      */
     private estimateFeesAndSelectCoins;
+    /**
+     * Send bitcoin to a single onchain address.
+     *
+     * @param params - destination `address`, `amount` (in satoshis), and optional `feeRate` override (other fields ignored)
+     * @returns Broadcast transaction id
+     * @throws Error if the amount is non-positive, below dust, or cannot be funded
+     * @see SendBitcoinParams
+     */
     send(params: SendBitcoinParams): Promise<string>;
+    /**
+     * CPFP-bump a parent transaction that contains a pay-to-anchor output.
+     *
+     * @param parent - Parent transaction containing a pay-to-anchor output
+     * @returns Tuple of parent transaction id and child transaction id
+     * @throws Error if the parent transaction has no pay-to-anchor output or bumping cannot be funded
+     * @see send
+     */
     bumpP2A(parent: Transaction): Promise<[string, string]>;
 }
 /**

package/dist/types/wallet/ramps.d.ts

@@ -1,34 +1,64 @@
 import { ExtendedCoin, IWallet } from ".";
 import { FeeInfo, SettlementEvent } from "../providers/ark";
 /**
- * Ramps is a class wrapping IWallet.settle method to provide a more convenient interface for onboarding and offboarding operations.
+ * Ramps is a class wrapping `settle` method to provide a more convenient interface for onboarding and offboarding operations.
+ *
+ * @see IWallet.settle
+ * @see onboard
+ * @see offboard
  *
  * @example
  * ```typescript
  * const ramps = new Ramps(wallet);
- * await ramps.onboard(); // onboard all boarding utxos
- * await ramps.offboard(myOnchainAddress); // collaborative exit all vtxos to onchain address
+ * const feeInfo = { intentFee: {}, txFeeRate: '1' };
+ * await ramps.onboard(feeInfo); // onboard all boarding inputs
+ * await ramps.offboard('bc1q...', feeInfo); // collaboratively exit all virtual outputs to an onchain address
  * ```
  */
 export declare class Ramps {
     readonly wallet: IWallet;
+    /**
+     * Create convenience wrappers for onboarding and offboarding flows.
+     *
+     * @param wallet - Wallet used to query funds and execute settlement transactions
+     */
     constructor(wallet: IWallet);
     /**
-     * Onboard boarding utxos.
+     * Onboard boarding inputs.
      *
      * @param feeInfo - The fee info to deduct from the onboard amount.
-     * @param boardingUtxos - The boarding utxos to onboard. If not provided, all boarding utxos will be used.
-     * @param amount - The amount to onboard. If not provided, the total amount of boarding utxos will be onboarded.
-     * @param eventCallback - The callback to receive settlement events. optional.
+     * @param boardingUtxos - Specific boarding inputs to onboard. If not provided, all boarding inputs will be used.
+     * @param amount - Amount to onboard. If not provided, the total amount of boarding inputs will be onboarded.
+     * @param eventCallback - Optional callback that receives settlement events
+     * @returns The Arkade transaction id created by settlement
+     * @throws Error if no boarding inputs remain after fee deduction or if `amount` exceeds available value
+     * @see IWallet.getBoardingUtxos
+     * @see IWallet.settle
+     * @example
+     * ```typescript
+     * const feeInfo = { intentFee: {}, txFeeRate: '1' };
+     * const ramps = new Ramps(wallet);
+     * await ramps.onboard(feeInfo);
+     * ```
      */
     onboard(feeInfo: FeeInfo, boardingUtxos?: ExtendedCoin[], amount?: bigint, eventCallback?: (event: SettlementEvent) => void): ReturnType<IWallet["settle"]>;
     /**
-     * Offboard vtxos, or "collaborative exit" vtxos to onchain address.
+     * Offboard virtual outputs, or collaboratively exit them to an onchain address.
      *
      * @param destinationAddress - The destination address to offboard to.
      * @param feeInfo - The fee info to deduct from the offboard amount.
-     * @param amount - The amount to offboard. If not provided, the total amount of vtxos will be offboarded.
-     * @param eventCallback - The callback to receive settlement events. optional.
+     * @param amount - The amount to offboard. If not provided, the total amount of virtual outputs will be offboarded.
+     * @param eventCallback - Optional callback that receives settlement events
+     * @returns The Arkade transaction id created by settlement
+     * @throws Error if no virtual outputs remain after fee deduction or the destination address cannot be decoded
+     * @see IWallet.getVtxos
+     * @see IWallet.settle
+     * @example
+     * ```typescript
+     * const feeInfo = { intentFee: {}, txFeeRate: '1' };
+     * const ramps = new Ramps(wallet);
+     * await ramps.offboard('bc1q...', feeInfo);
+     * ```
      */
     offboard(destinationAddress: string, feeInfo: FeeInfo, amount?: bigint, eventCallback?: (event: SettlementEvent) => void): ReturnType<IWallet["settle"]>;
 }

package/dist/types/wallet/serviceWorker/wallet-message-handler.d.ts

@@ -290,7 +290,7 @@ export type ResponseContractEvent = ResponseEnvelope & {
 export type RequestSend = RequestEnvelope & {
     type: "SEND";
     payload: {
-        recipients: Recipient[];
+        recipients: [Recipient, ...Recipient[]];
     };
 };
 export type ResponseSend = ResponseEnvelope & {
@@ -479,7 +479,7 @@ export declare class WalletMessageHandler implements MessageHandler<WalletUpdate
     private getSpendableVtxos;
     private onWalletInitialized;
     /**
-     * Refresh VTXOs, boarding UTXOs, and transaction history from cache.
+     * Refresh virtual outputs, boarding inputs, and transaction history from cache.
      * Shared by onWalletInitialized (full bootstrap) and reloadWallet
      * (post-refresh), avoiding duplicate subscriptions and VtxoManager restarts.
      */
@@ -497,12 +497,12 @@ export declare class WalletMessageHandler implements MessageHandler<WalletUpdate
     private handleGetVtxos;
     private clear;
     /**
-     * Read all VTXOs from the repository, aggregated across all contract
+     * Read all virtual outputs from the repository, aggregated across all contract
      * addresses and the wallet's primary address, with deduplication.
      */
     private getVtxosFromRepo;
     /**
-     * Build transaction history from cached VTXOs without hitting the indexer.
+     * Build transaction history from cached virtual outputs without hitting the indexer.
      * Falls back to indexer only for uncached transaction timestamps.
      */
     private buildTransactionHistoryFromCache;

package/dist/types/wallet/serviceWorker/wallet.d.ts

@@ -25,20 +25,18 @@ type PrivateKeyIdentity = Identity & {
  * @example
  * ```typescript
  * // SIMPLE: Recommended approach
- * const identity = SingleKey.fromHex('your_private_key_hex');
  * const wallet = await ServiceWorkerWallet.setup({
  *   serviceWorkerPath: '/service-worker.js',
- *   arkServerUrl: 'https://mutinynet.arkade.sh',
- *   identity
+ *   arkServerUrl: 'https://arkade.computer',
+ *   identity: MnemonicIdentity.fromMnemonic('abandon abandon...')
  * });
  *
  * // ADVANCED: Manual setup with service worker control
- * const worker = await setupServiceWorker("/service-worker.js");
- * const identity = SingleKey.fromHex('your_private_key_hex');
+ * const serviceWorker = await setupServiceWorker("/service-worker.js");
  * const wallet = await ServiceWorkerWallet.create({
- *   worker,
- *   identity,
- *   arkServerUrl: 'https://mutinynet.arkade.sh'
+ *   serviceWorker,
+ *   arkServerUrl: 'https://arkade.computer',
+ *   identity: MnemonicIdentity.fromMnemonic('abandon abandon...')
  * });
  *
  * // Use like any other wallet
@@ -47,24 +45,60 @@ type PrivateKeyIdentity = Identity & {
  * ```
  */
 interface ServiceWorkerWalletOptions {
+    /** Optional Arkade server public key used to construct and validate Arkade addresses. */
     arkServerPublicKey?: string;
+    /** Base URL of the Arkade server. */
     arkServerUrl: string;
+    /** Optional override for the indexer URL. */
     indexerUrl?: string;
+    /** Optional override for the Esplora API URL. */
     esploraUrl?: string;
+    /**
+     * Repository-backed storage configuration overrides.
+     * Defaults to IndexedDB if unset.
+     */
     storage?: StorageConfig;
+    /** Identity used to derive addresses and optionally sign operations. */
     identity: ReadonlyIdentity | Identity;
+    /** Optional delegation service URL. */
     delegatorUrl?: string;
+    /**
+     * Override the default tag used for messages sent to and received from the service worker.
+     * @see DEFAULT_MESSAGE_TAG
+     */
     walletUpdaterTag?: string;
+    /** Timeout used while bootstrapping the message bus inside the service worker. */
     messageBusTimeoutMs?: number;
+    /** Optional settlement configuration forwarded to the worker wallet. */
     settlementConfig?: SettlementConfig | false;
+    /** Optional contract watcher configuration forwarded to the worker wallet. */
     watcherConfig?: Partial<Omit<ContractWatcherConfig, "indexerProvider">>;
+    /**
+     * Per-request timeout overrides for wallet-updater messages.
+     * @see DEFAULT_MESSAGE_TIMEOUTS
+     */
     messageTimeouts?: MessageTimeouts;
 }
+/**
+ * Options for creating a service-worker wallet with an existing worker instance.
+ *
+ * @see ServiceWorkerReadonlyWallet.create
+ * @see ServiceWorkerWallet.create
+ */
 export type ServiceWorkerWalletCreateOptions = ServiceWorkerWalletOptions & {
+    /** Existing service worker instance used for messaging. */
     serviceWorker: ServiceWorker;
 };
+/**
+ * Options for registering a service worker and then creating a wallet around it.
+ *
+ * @see ServiceWorkerReadonlyWallet.setup
+ * @see ServiceWorkerWallet.setup
+ */
 export type ServiceWorkerWalletSetupOptions = ServiceWorkerWalletOptions & {
+    /** Path to the service worker script to register. */
     serviceWorkerPath: string;
+    /** Timeout while waiting for the service worker to activate. */
     serviceWorkerActivationTimeoutMs?: number;
 };
 type MessageBusInitConfig = {
@@ -101,25 +135,26 @@ export declare class ServiceWorkerReadonlyWallet implements IReadonlyWallet {
     get assetManager(): IReadonlyAssetManager;
     protected constructor(serviceWorker: ServiceWorker, identity: ReadonlyIdentity, walletRepository: WalletRepository, contractRepository: ContractRepository, messageTag: string);
     private getTimeoutForRequest;
+    /**
+     * Create a readonly service-worker wallet bound to an already-registered worker.
+     *
+     * @param options - Service worker, identity, and backend configuration
+     * @returns Initialized readonly service-worker wallet
+     * @throws Error if service-worker initialization fails
+     */
     static create(options: ServiceWorkerWalletCreateOptions): Promise<ServiceWorkerReadonlyWallet>;
     /**
-     * Simplified setup method that handles service worker registration,
-     * identity creation, and wallet initialization automatically.
+     * Simplified setup method that handles service worker registration
+     * and wallet initialization automatically.
+     *
+     * @see ServiceWorkerReadonlyWallet.create
      *
      * @example
      * ```typescript
-     * // One-liner setup - handles everything automatically!
-     * const wallet = await ServiceWorkerReadonlyWallet.setup({
-     *   serviceWorkerPath: '/service-worker.js',
-     *   arkServerUrl: 'https://mutinynet.arkade.sh'
-     * });
-     *
-     * // With custom readonly identity
-     * const identity = ReadonlySingleKey.fromPublicKey('your_public_key_hex');
      * const wallet = await ServiceWorkerReadonlyWallet.setup({
      *   serviceWorkerPath: '/service-worker.js',
-     *   arkServerUrl: 'https://mutinynet.arkade.sh',
-     *   identity
+     *   arkServerUrl: 'https://arkade.computer',
+     *   identity: ReadonlySingleKey.fromPublicKey('your_public_key_hex')
      * });
      * ```
      */
@@ -131,14 +166,25 @@ export declare class ServiceWorkerReadonlyWallet implements IReadonlyWallet {
     private sendMessageWithRetry;
     protected sendMessageWithEvents(request: WalletUpdaterRequest, onEvent: (response: WalletUpdaterResponse) => void, isComplete: (response: WalletUpdaterResponse) => boolean): Promise<WalletUpdaterResponse>;
     private reinitialize;
+    /** Clear cached wallet state from both the page and service worker storage. */
     clear(): Promise<void>;
     getAddress(): Promise<string>;
     getBoardingAddress(): Promise<string>;
     getBalance(): Promise<WalletBalance>;
     getBoardingUtxos(): Promise<ExtendedCoin[]>;
+    /**
+     * Return service-worker wallet status, including connectivity and sync state.
+     *
+     * @returns Current service-worker wallet status payload including `walletInitalized` and `xOnlyPublicKey`
+     */
     getStatus(): Promise<ResponseGetStatus["payload"]>;
     getTransactionHistory(): Promise<ArkTransaction[]>;
     getVtxos(filter?: GetVtxosFilter): Promise<ExtendedVirtualCoin[]>;
+    /**
+     * Trigger a wallet reload inside the service worker.
+     *
+     * @returns `true` when the wallet was reloaded
+     */
     reload(): Promise<boolean>;
     getContractManager(): Promise<IContractManager>;
 }
@@ -153,30 +199,22 @@ export declare class ServiceWorkerWallet extends ServiceWorkerReadonlyWallet imp
     get assetManager(): IAssetManager;
     static create(options: ServiceWorkerWalletCreateOptions): Promise<ServiceWorkerWallet>;
     /**
-     * Simplified setup method that handles service worker registration,
-     * identity creation, and wallet initialization automatically.
+     * Simplified setup method that handles service worker registration
+     * and wallet initialization automatically.
      *
      * @example
      * ```typescript
-     * // One-liner setup - handles everything automatically!
-     * const wallet = await ServiceWorkerWallet.setup({
-     *   serviceWorkerPath: '/service-worker.js',
-     *   arkServerUrl: 'https://mutinynet.arkade.sh'
-     * });
-     *
-     * // With custom identity
-     * const identity = SingleKey.fromHex('your_private_key_hex');
      * const wallet = await ServiceWorkerWallet.setup({
      *   serviceWorkerPath: '/service-worker.js',
-     *   arkServerUrl: 'https://mutinynet.arkade.sh',
-     *   identity
+     *   arkServerUrl: 'https://arkade.computer',
+     *   identity: MnemonicIdentity.fromMnemonic('abandon abandon...')
      * });
      * ```
      */
     static setup(options: ServiceWorkerWalletSetupOptions): Promise<ServiceWorkerWallet>;
     sendBitcoin(params: SendBitcoinParams): Promise<string>;
     settle(params?: SettleParams, callback?: (event: SettlementEvent) => void): Promise<string>;
-    send(...recipients: Recipient[]): Promise<string>;
+    send(...recipients: [Recipient, ...Recipient[]]): Promise<string>;
     getDelegatorManager(): Promise<IDelegatorManager | undefined>;
     getVtxoManager(): Promise<IVtxoManager>;
 }

package/dist/types/wallet/unroll.d.ts

@@ -36,7 +36,7 @@ export declare namespace Unroll {
         type: StepType.WAIT;
     } & WaitStep);
     /**
-     * Manages the unrolling process of a VTXO back to the Bitcoin blockchain.
+     * Manages the unrolling process of a virtual output back to the Bitcoin blockchain.
      *
      * The Session class implements an async iterator that processes the unrolling steps:
      * 1. **WAIT**: Waits for a transaction to be confirmed onchain (if it's in mempool)
@@ -60,7 +60,7 @@ export declare namespace Unroll {
      *       console.log(`Broadcasting transaction ${doneStep.tx.id}`);
      *       break;
      *     case Unroll.StepType.DONE:
-     *       console.log(`Unrolling complete for VTXO ${doneStep.vtxoTxid}`);
+     *       console.log(`Unrolling complete for virtual output ${doneStep.vtxoTxid}`);
      *       break;
      *   }
      * }
@@ -73,9 +73,11 @@ export declare namespace Unroll {
         readonly bumper: AnchorBumper;
         readonly explorer: OnchainProvider;
         readonly indexer: IndexerProvider;
+        /** Create an unroll session from a virtual output outpoint and its dependency chain. */
         constructor(toUnroll: Outpoint & {
             chain: ChainTx[];
         }, bumper: AnchorBumper, explorer: OnchainProvider, indexer: IndexerProvider);
+        /** Create an unroll session by loading the virtual output chain from the indexer. */
         static create(toUnroll: Outpoint, bumper: AnchorBumper, explorer: OnchainProvider, indexer: IndexerProvider): Promise<Session>;
         /**
          * Get the next step to be executed
@@ -91,11 +93,11 @@ export declare namespace Unroll {
         [Symbol.asyncIterator](): AsyncIterator<Step>;
     }
     /**
-     * Complete the unroll of a VTXO by broadcasting the transaction that spends the CSV path.
-     * @param wallet the wallet owning the VTXO(s)
-     * @param vtxoTxids the txids of the VTXO(s) to complete unroll
+     * Complete the unroll of a virtual output by broadcasting the transaction that spends the CSV path.
+     * @param wallet the wallet owning the virtual output(s)
+     * @param vtxoTxids the txids of the virtual output(s) to complete unroll
      * @param outputAddress the address to send the unrolled funds to
-     * @throws if the VTXO(s) are not fully unrolled, if the txids are not found, if the tx is not confirmed, if no exit path is found or not available
+     * @throws if the virtual output(s) are not fully unrolled, if the txids are not found, if the tx is not confirmed, if no exit path is found or not available
      * @returns the txid of the transaction spending the unrolled funds
      */
     function completeUnroll(wallet: Wallet, vtxoTxids: string[], outputAddress: string): Promise<string>;