@arkade-os/sdk 0.4.15 → 0.4.16

package/dist/esm/wallet/onchain.js

@@ -9,7 +9,7 @@ import { DUST_AMOUNT } from './utils.js';
  * 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,6 +29,16 @@ export class OnchainWallet {
         this.onchainP2TR = onchainP2TR;
         this.provider = provider;
     }
+    /**
+     * 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 async create(identity, networkName, provider) {
         const pubkey = await identity.xOnlyPublicKey();
         if (!pubkey) {
@@ -42,9 +52,21 @@ export class OnchainWallet {
     get address() {
         return this.onchainP2TR.address || "";
     }
+    /**
+     * Fetch spendable onchain outputs for the wallet address.
+     *
+     * @returns Spendable onchain outputs for the wallet address
+     * @see getBalance
+     */
     async getCoins() {
         return this.provider.getCoins(this.address);
     }
+    /**
+     * Return the wallet's total onchain balance in satoshis.
+     *
+     * @returns Confirmed plus unconfirmed onchain balance
+     * @see getCoins
+     */
     async getBalance() {
         const coins = await this.getCoins();
         const onchainConfirmed = coins
@@ -59,9 +81,9 @@ export class OnchainWallet {
     /**
      * 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
@@ -70,7 +92,7 @@ export class OnchainWallet {
      * 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
@@ -103,6 +125,14 @@ export class OnchainWallet {
         }
         throw new Error("Fee estimation failed: could not converge");
     }
+    /**
+     * 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
+     */
     async send(params) {
         if (params.amount <= 0) {
             throw new Error("Amount must be positive");
@@ -148,6 +178,14 @@ export class OnchainWallet {
         const txid = await this.provider.broadcastTransaction(tx.hex);
         return txid;
     }
+    /**
+     * 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
+     */
     async bumpP2A(parent) {
         const parentVsize = parent.vsize;
         let child = new Transaction({
@@ -169,7 +207,7 @@ export class OnchainWallet {
         if (!fee) {
             throw new Error(`invalid fee, got ${fee} with vsize ${packageVSize}, feeRate ${feeRate}`);
         }
-        // Select coins
+        // Select onchain outputs
         const coins = await this.getCoins();
         const selected = selectCoins(coins, fee, true);
         for (const input of selected.inputs) {

package/dist/esm/wallet/ramps.js

@@ -4,30 +4,50 @@ import { hex } from "@scure/base";
 import { networks } from '../networks.js';
 import { ArkAddress } from '../script/address.js';
 /**
- * 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 class Ramps {
+    /**
+     * Create convenience wrappers for onboarding and offboarding flows.
+     *
+     * @param wallet - Wallet used to query funds and execute settlement transactions
+     */
     constructor(wallet) {
         this.wallet = wallet;
     }
     /**
-     * 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);
+     * ```
      */
     async onboard(feeInfo, boardingUtxos, amount, eventCallback) {
         boardingUtxos = boardingUtxos ?? (await this.wallet.getBoardingUtxos());
-        // Calculate input fees and filter out utxos where fee >= value
+        // Calculate input fees and filter out boarding inputs where fee >= value.
         const estimator = new Estimator(feeInfo?.intentFee ?? {});
         const filteredBoardingUtxos = [];
         let totalAmount = 0n;
@@ -36,7 +56,7 @@ export class Ramps {
                 amount: BigInt(utxo.value),
             });
             if (inputFee.satoshis >= utxo.value) {
-                // skip if fees are greater than or equal to the utxo value
+                // Skip boarding inputs where spending fees are greater than or equal to the input value.
                 continue;
             }
             filteredBoardingUtxos.push(utxo);
@@ -84,19 +104,29 @@ export class Ramps {
         }, eventCallback);
     }
     /**
-     * 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);
+     * ```
      */
     async offboard(destinationAddress, feeInfo, amount, eventCallback) {
         const vtxos = await this.wallet.getVtxos({
             withRecoverable: true,
             withUnrolled: false,
         });
-        // Calculate input fees and filter out vtxos where fee >= value
+        // Calculate input fees and filter out virtual outputs where fee >= value.
         const estimator = new Estimator(feeInfo?.intentFee ?? {});
         const filteredVtxos = [];
         let totalAmount = 0n;
@@ -113,7 +143,7 @@ export class Ramps {
                     : undefined,
             });
             if (inputFee.satoshis >= vtxo.value) {
-                // skip if fees are greater than or equal to the vtxo value
+                // Skip virtual outputs where spending fees are greater than or equal to the output value.
                 continue;
             }
             filteredVtxos.push(vtxo);

package/dist/esm/wallet/serviceWorker/wallet-message-handler.js

@@ -49,7 +49,7 @@ export class WalletMessageHandler {
             this.contractEventsSubscription = undefined;
         }
         // Dispose the wallet to stop VtxoManager background tasks
-        // (auto-renewal, boarding UTXO polling) and ContractWatcher.
+        // (auto-renewal, boarding input polling) and ContractWatcher.
         try {
             if (this.wallet) {
                 await this.wallet.dispose();
@@ -484,7 +484,7 @@ export class WalletMessageHandler {
         }
         const totalBoarding = confirmed + unconfirmed;
         const totalOffchain = settled + preconfirmed + recoverable;
-        // aggregate asset balances from spendable vtxos
+        // aggregate asset balances from spendable virtual outputs
         const assetBalances = new Map();
         for (const vtxo of spendableVtxos) {
             if (vtxo.assets) {
@@ -529,9 +529,9 @@ export class WalletMessageHandler {
             return;
         }
         // Initialize contract manager FIRST — this populates the repository
-        // with full VTXO history for all contracts (one indexer call per contract)
+        // with full virtual output history for all contracts (one indexer call per contract)
         await this.ensureContractEventBroadcasting();
-        // Refresh cached data (VTXOs, boarding UTXOs, tx history)
+        // Refresh cached data (virtual outputs, boarding inputs, tx history)
         await this.refreshCachedData();
         // Recover pending transactions (init-only, not on reload).
         // Pending txs only exist if a send was interrupted mid-finalization.
@@ -562,12 +562,12 @@ export class WalletMessageHandler {
                         : [];
                     if ([...newVtxos, ...spentVtxos].length === 0)
                         return;
-                    // save vtxos using unified repository
+                    // save virtual outputs using unified repository
                     await this.walletRepository?.saveVtxos(address, [
                         ...newVtxos,
                         ...spentVtxos,
                     ]);
-                    // notify all clients about the vtxo update
+                    // notify all clients about the virtual output state update
                     this.scheduleForNextTick(() => this.tagged({
                         type: "VTXO_UPDATE",
                         broadcast: true,
@@ -577,11 +577,11 @@ export class WalletMessageHandler {
                 if (funds.type === "utxo") {
                     const utxos = funds.coins.map((utxo) => extendCoin(this.readonlyWallet, utxo));
                     const boardingAddress = await this.readonlyWallet.getBoardingAddress();
-                    // save utxos using unified repository
-                    // TODO: remove UTXOS by address
+                    // save boarding inputs using unified repository
+                    // TODO: remove UTXOs by address
                     //  await this.walletRepository.clearUtxos(boardingAddress);
                     await this.walletRepository?.saveUtxos(boardingAddress, utxos);
-                    // notify all clients about the utxo update
+                    // notify all clients about the boarding input state update
                     this.scheduleForNextTick(() => this.tagged({
                         type: "UTXO_UPDATE",
                         broadcast: true,
@@ -590,8 +590,8 @@ export class WalletMessageHandler {
                 }
             });
         // Eagerly start the VtxoManager so its background tasks (auto-renewal,
-        // boarding UTXO polling/sweep) run inside the service worker without
-        // waiting for a client to send a vtxo-manager message first.
+        // boarding input polling/sweep) run inside the service worker without
+        // waiting for a client to send a VtxoManager message first.
         if (this.wallet) {
             try {
                 await this.wallet.getVtxoManager();
@@ -602,7 +602,7 @@ export class WalletMessageHandler {
         }
     }
     /**
-     * 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.
      */
@@ -610,14 +610,14 @@ export class WalletMessageHandler {
         if (!this.readonlyWallet || !this.walletRepository) {
             return;
         }
-        // Read VTXOs from repository (now populated by contract manager)
+        // Read virtual outputs from repository (now populated by contract manager)
         const vtxos = await this.getVtxosFromRepo();
-        // Fetch boarding utxos and save using unified repository
+        // Fetch boarding inputs and save using unified repository
         const boardingAddress = await this.readonlyWallet.getBoardingAddress();
         const coins = await this.readonlyWallet.onchainProvider.getCoins(boardingAddress);
         await this.walletRepository.deleteUtxos(boardingAddress);
         await this.walletRepository.saveUtxos(boardingAddress, coins.map((utxo) => extendCoin(this.readonlyWallet, utxo)));
-        // Build transaction history from cached VTXOs (no indexer call)
+        // Build transaction history from cached virtual outputs (no indexer call)
         const address = await this.readonlyWallet.getAddress();
         const txs = await this.buildTransactionHistoryFromCache(vtxos);
         if (txs)
@@ -759,7 +759,7 @@ export class WalletMessageHandler {
         this.indexerProvider = undefined;
     }
     /**
-     * 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.
      */
     async getVtxosFromRepo() {
@@ -776,7 +776,7 @@ export class WalletMessageHandler {
                 }
             }
         };
-        // Aggregate VTXOs from all contract addresses
+        // Aggregate virtual outputs from all contract addresses
         const manager = await this.readonlyWallet.getContractManager();
         const contracts = await manager.getContracts();
         for (const contract of contracts) {
@@ -790,15 +790,15 @@ export class WalletMessageHandler {
         return allVtxos;
     }
     /**
-     * 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.
      */
     async buildTransactionHistoryFromCache(vtxos) {
         if (!this.readonlyWallet)
             return null;
         const { boardingTxs, commitmentsToIgnore } = await this.readonlyWallet.getBoardingTxs();
-        // Build a lookup for cached VTXO timestamps, keyed by txid.
-        // Multiple VTXOs can share a txid (different vouts) — we keep the
+        // Build a lookup for cached virtual output timestamps, keyed by txid.
+        // Multiple virtual outputs can share a txid (different vouts) — we keep the
         // earliest createdAt so the history ordering is stable.
         const vtxoCreatedAt = new Map();
         for (const vtxo of vtxos) {
@@ -809,8 +809,8 @@ export class WalletMessageHandler {
             }
         }
         // Pre-fetch uncached timestamps in a single batched indexer call.
-        // buildTransactionHistory needs these for spent-offchain VTXOs with
-        // no change outputs (i.e. arkTxId is set but no VTXO has txid === arkTxId).
+        // buildTransactionHistory needs these for spent-offchain virtual outputs with
+        // no change outputs (i.e. arkTxId is set but no virtual output has txid === arkTxId).
         if (this.indexerProvider) {
             const uncachedTxids = new Set();
             for (const vtxo of vtxos) {

package/dist/esm/wallet/serviceWorker/wallet.js

@@ -179,6 +179,13 @@ export class ServiceWorkerReadonlyWallet {
     getTimeoutForRequest(request) {
         return this.messageTimeouts[request.type] ?? 30000;
     }
+    /**
+     * 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 async create(options) {
         const walletRepository = options.storage?.walletRepository ??
             new IndexedDBWalletRepository();
@@ -239,23 +246,17 @@ export class ServiceWorkerReadonlyWallet {
         return wallet;
     }
     /**
-     * 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')
      * });
      * ```
      */
@@ -457,6 +458,7 @@ export class ServiceWorkerReadonlyWallet {
         });
         return this.reinitPromise;
     }
+    /** Clear cached wallet state from both the page and service worker storage. */
     async clear() {
         const message = {
             id: getRandomId(),
@@ -529,6 +531,11 @@ export class ServiceWorkerReadonlyWallet {
             throw new Error(`Failed to get boarding UTXOs: ${error}`);
         }
     }
+    /**
+     * Return service-worker wallet status, including connectivity and sync state.
+     *
+     * @returns Current service-worker wallet status payload including `walletInitalized` and `xOnlyPublicKey`
+     */
     async getStatus() {
         const message = {
             id: getRandomId(),
@@ -573,6 +580,11 @@ export class ServiceWorkerReadonlyWallet {
             throw new Error(`Failed to get vtxos: ${error}`);
         }
     }
+    /**
+     * Trigger a wallet reload inside the service worker.
+     *
+     * @returns `true` when the wallet was reloaded
+     */
     async reload() {
         const message = {
             id: getRandomId(),
@@ -851,23 +863,15 @@ export class ServiceWorkerWallet extends ServiceWorkerReadonlyWallet {
         return wallet;
     }
     /**
-     * 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...')
      * });
      * ```
      */

package/dist/esm/wallet/unroll.js

@@ -1,5 +1,6 @@
 import { base64, hex } from "@scure/base";
 import { SigHash, TaprootControlBlock } from "@scure/btc-signer";
+import { timelockToSequence } from '../contracts/handlers/helpers.js';
 import { ChainTxType } from '../providers/indexer.js';
 import { VtxoScript } from '../script/base.js';
 import { TxWeightEstimator } from '../utils/txSizeEstimator.js';
@@ -15,7 +16,7 @@ export var Unroll;
         StepType[StepType["DONE"] = 2] = "DONE";
     })(StepType = Unroll.StepType || (Unroll.StepType = {}));
     /**
-     * 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)
@@ -39,19 +40,21 @@ export var 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;
      *   }
      * }
      * ```
      **/
     class Session {
+        /** Create an unroll session from a virtual output outpoint and its dependency chain. */
         constructor(toUnroll, bumper, explorer, indexer) {
             this.toUnroll = toUnroll;
             this.bumper = bumper;
             this.explorer = explorer;
             this.indexer = indexer;
         }
+        /** Create an unroll session by loading the virtual output chain from the indexer. */
         static async create(toUnroll, bumper, explorer, indexer) {
             const { chain } = await indexer.getVtxoChain(toUnroll);
             return new Session({ ...toUnroll, chain }, bumper, explorer, indexer);
@@ -120,7 +123,7 @@ export var Unroll;
                 });
             }
             else {
-                // finalize ark transaction
+                // finalize Arkade transaction
                 tx.finalize();
             }
             return {
@@ -150,11 +153,11 @@ export var Unroll;
     }
     Unroll.Session = Session;
     /**
-     * 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
      */
     async function completeUnroll(wallet, vtxoTxids, outputAddress) {
@@ -184,11 +187,12 @@ export var Unroll;
                 throw new Error(`spending leaf not found for vtxo ${vtxo.txid}:${vtxo.vout}`);
             }
             totalAmount += BigInt(vtxo.value);
+            const sequence = timelockToSequence(exit.params.timelock);
             inputs.push({
                 txid: vtxo.txid,
                 index: vtxo.vout,
                 tapLeafScript: [spendingLeaf],
-                sequence: 0xffffffff - 1,
+                sequence,
                 witnessUtxo: {
                     amount: BigInt(vtxo.value),
                     script: VtxoScript.decode(vtxo.tapTree).pkScript,

package/dist/esm/wallet/utils.js

@@ -52,7 +52,7 @@ export function validateRecipients(recipients, dustAmount) {
             address = ArkAddress.decode(recipient.address);
         }
         catch (e) {
-            throw new Error(`Invalid Ark address: ${recipient.address}`);
+            throw new Error(`Invalid Arkade address: ${recipient.address}`);
         }
         const amount = recipient.amount || dustAmount;
         if (amount <= 0) {