@arkade-os/sdk 0.4.15 → 0.4.17

package/dist/cjs/wallet/ramps.js

@@ -7,30 +7,50 @@ const base_1 = require("@scure/base");
 const networks_1 = require("../networks");
 const address_1 = require("../script/address");
 /**
- * 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
  * ```
  */
 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 arkfee_1.Estimator(feeInfo?.intentFee ?? {});
         const filteredBoardingUtxos = [];
         let totalAmount = 0n;
@@ -39,7 +59,7 @@ 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);
@@ -87,19 +107,29 @@ 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 arkfee_1.Estimator(feeInfo?.intentFee ?? {});
         const filteredVtxos = [];
         let totalAmount = 0n;
@@ -116,7 +146,7 @@ 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/cjs/wallet/serviceWorker/wallet-message-handler.js

@@ -55,7 +55,7 @@ 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();
@@ -490,7 +490,7 @@ 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) {
@@ -535,9 +535,9 @@ 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.
@@ -568,12 +568,12 @@ 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,
@@ -583,11 +583,11 @@ class WalletMessageHandler {
                 if (funds.type === "utxo") {
                     const utxos = funds.coins.map((utxo) => (0, utils_1.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,
@@ -596,8 +596,8 @@ 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();
@@ -608,7 +608,7 @@ 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.
      */
@@ -616,14 +616,14 @@ 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) => (0, utils_1.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)
@@ -765,7 +765,7 @@ 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() {
@@ -782,7 +782,7 @@ 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) {
@@ -796,15 +796,15 @@ 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) {
@@ -815,8 +815,8 @@ 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/cjs/wallet/serviceWorker/wallet.js

@@ -182,6 +182,13 @@ 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 repositories_1.IndexedDBWalletRepository();
@@ -242,23 +249,17 @@ 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')
      * });
      * ```
      */
@@ -460,6 +461,7 @@ class ServiceWorkerReadonlyWallet {
         });
         return this.reinitPromise;
     }
+    /** Clear cached wallet state from both the page and service worker storage. */
     async clear() {
         const message = {
             id: (0, utils_2.getRandomId)(),
@@ -532,6 +534,11 @@ 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: (0, utils_2.getRandomId)(),
@@ -576,6 +583,11 @@ 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: (0, utils_2.getRandomId)(),
@@ -855,23 +867,15 @@ 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/cjs/wallet/unroll.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Unroll = void 0;
 const base_1 = require("@scure/base");
 const btc_signer_1 = require("@scure/btc-signer");
+const helpers_1 = require("../contracts/handlers/helpers");
 const indexer_1 = require("../providers/indexer");
 const base_2 = require("../script/base");
 const txSizeEstimator_1 = require("../utils/txSizeEstimator");
@@ -18,7 +19,7 @@ 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)
@@ -42,19 +43,21 @@ 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);
@@ -123,7 +126,7 @@ var Unroll;
                 });
             }
             else {
-                // finalize ark transaction
+                // finalize Arkade transaction
                 tx.finalize();
             }
             return {
@@ -153,11 +156,11 @@ 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) {
@@ -187,11 +190,12 @@ var Unroll;
                 throw new Error(`spending leaf not found for vtxo ${vtxo.txid}:${vtxo.vout}`);
             }
             totalAmount += BigInt(vtxo.value);
+            const sequence = (0, helpers_1.timelockToSequence)(exit.params.timelock);
             inputs.push({
                 txid: vtxo.txid,
                 index: vtxo.vout,
                 tapLeafScript: [spendingLeaf],
-                sequence: 0xffffffff - 1,
+                sequence,
                 witnessUtxo: {
                     amount: BigInt(vtxo.value),
                     script: base_2.VtxoScript.decode(vtxo.tapTree).pkScript,

package/dist/cjs/wallet/utils.js

@@ -61,7 +61,7 @@ function validateRecipients(recipients, dustAmount) {
             address = __1.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) {