@arkade-os/sdk 0.4.15 → 0.4.16

package/dist/cjs/utils/arkTransaction.js

@@ -21,7 +21,7 @@ const extension_1 = require("../extension");
  *
  * Creates one checkpoint transaction per input and a virtual transaction that
  * combines all the checkpoints, sending to the specified outputs. This is the
- * core function for creating Ark transactions.
+ * core function for creating Arkade transactions.
  *
  * @param inputs - Array of virtual transaction inputs
  * @param outputs - Array of transaction outputs
@@ -99,9 +99,9 @@ function buildVirtualTx(inputs, outputs) {
     return tx;
 }
 function buildCheckpointTx(vtxo, serverUnrollScript) {
-    // create the checkpoint vtxo script from collaborative closure
+    // create the checkpoint virtual output script from collaborative closure
     const collaborativeClosure = (0, tapscript_1.decodeTapscript)((0, base_2.scriptFromTapLeafScript)(vtxo.tapLeafScript));
-    // create the checkpoint vtxo script combining collaborative closure and server unroll script
+    // create the checkpoint virtual output script combining collaborative closure and server unroll script
     const checkpointVtxoScript = new base_2.VtxoScript([
         serverUnrollScript.script,
         collaborativeClosure.script,
@@ -256,8 +256,8 @@ function combineTapscriptSigs(signedTx, originalTx) {
     return originalTx;
 }
 /**
- * Validates if a given string is a valid Ark address by attempting to decode it.
- * @param address The Ark address to validate.
+ * Validates if a given string is a valid Arkade address by attempting to decode it.
+ * @param address The Arkade address to validate.
  * @returns True if the address is valid, false otherwise.
  */
 function isValidArkAddress(address) {

package/dist/cjs/utils/bip21.js

@@ -7,6 +7,12 @@ var BIP21Error;
     BIP21Error["INVALID_ADDRESS"] = "Invalid address";
 })(BIP21Error || (exports.BIP21Error = BIP21Error = {}));
 class BIP21 {
+    /**
+     * Create a BIP21 URI from the provided parameters.
+     *
+     * @param params - BIP21 parameters to encode
+     * @returns Encoded BIP21 URI
+     */
     static create(params) {
         const { address, ...options } = params;
         // Build query string
@@ -25,7 +31,7 @@ class BIP21 {
                 queryParams[key] = value;
             }
             else if (key === "ark") {
-                // Validate ARK address format
+                // Validate Arkade address format
                 if (typeof value === "string" &&
                     (value.startsWith("ark") || value.startsWith("tark"))) {
                     queryParams[key] = value;
@@ -56,11 +62,18 @@ class BIP21 {
             : "";
         return `bitcoin:${address ? address.toLowerCase() : ""}${query}`;
     }
+    /**
+     * Parse a BIP21 URI and return its decoded parameters.
+     *
+     * @param uri - BIP21 URI to parse
+     * @returns Parsed BIP21 URI data
+     * @throws Error if the URI does not start with the `bitcoin:` scheme
+     */
     static parse(uri) {
         if (!uri.toLowerCase().startsWith("bitcoin:")) {
             throw new Error(BIP21Error.INVALID_URI);
         }
-        // Remove bitcoin: prefix, preserving case of the rest
+        // Remove the `bitcoin:` prefix while preserving the case of the rest.
         const withoutPrefix = uri.slice(uri.toLowerCase().indexOf("bitcoin:") + 8);
         const [address, query] = withoutPrefix.split("?");
         const params = {};
@@ -83,7 +96,7 @@ class BIP21 {
                     params[key] = amount;
                 }
                 else if (key === "ark") {
-                    // Validate ARK address format
+                    // Validate Arkade address format
                     if (value.startsWith("ark") || value.startsWith("tark")) {
                         params[key] = value;
                     }

package/dist/cjs/utils/syncCursors.js

@@ -11,7 +11,7 @@ exports.computeSyncWindow = computeSyncWindow;
 exports.cursorCutoff = cursorCutoff;
 /** Lag behind real-time to avoid racing with indexer writes. */
 exports.SAFETY_LAG_MS = 30000;
-/** Overlap window so boundary VTXOs are never missed. */
+/** Overlap window so boundary virtual outputs are never missed. */
 exports.OVERLAP_MS = 60000;
 /**
  * Per-repository mutex that serializes wallet-state mutations so that
@@ -112,8 +112,8 @@ async function clearSyncCursors(repo, scripts) {
  * Returns `undefined` when the script has no cursor (bootstrap needed).
  *
  * No upper bound (`before`) is applied to the query so that freshly
- * created VTXOs are never excluded. The safety lag is applied only
- * when advancing the cursor (see {@link cursorCutoff}).
+ * created virtual outputs are never excluded. The safety lag is applied only
+ * when advancing the cursor (see @see cursorCutoff).
  */
 function computeSyncWindow(cursor) {
     if (cursor === undefined)
@@ -123,7 +123,7 @@ function computeSyncWindow(cursor) {
 }
 /**
  * The safe high-water mark for cursor advancement.
- * Lags behind real-time by {@link SAFETY_LAG_MS} so that VTXOs still
+ * Lags behind real-time by @see SAFETY_LAG_MS so that virtual outputs still
  * being indexed are re-queried on the next sync.
  *
  * When `requestStartedAt` is provided the cutoff is frozen to the

package/dist/cjs/utils/transaction.js

@@ -4,7 +4,7 @@ exports.Transaction = void 0;
 const btc_signer_1 = require("@scure/btc-signer");
 /**
  * Transaction is a wrapper around the @scure/btc-signer Transaction class.
- * It adds the Ark protocol specific options to the transaction.
+ * It adds the Arkade protocol specific options to the transaction.
  */
 class Transaction extends btc_signer_1.Transaction {
     constructor(opts) {

package/dist/cjs/utils/transactionHistory.js

@@ -48,13 +48,13 @@ function subtractAssets(spent, change) {
     return Array.from(map, ([assetId, amount]) => ({ assetId, amount }));
 }
 /**
- * Builds the transaction history by analyzing virtual coins (VTXOs), boarding transactions, and ignored commitments.
+ * Builds the transaction history by analyzing virtual outputs, boarding transactions, and ignored commitments.
  * History is sorted from newest to oldest and is composed only of SENT and RECEIVED transactions.
  *
- * @param {VirtualCoin[]} vtxos - An array of virtual coins representing the user's transactions and balances.
+ * @param {VirtualCoin[]} vtxos - An array of virtual outputs representing the user's transactions and balances.
  * @param {ArkTransaction[]} allBoardingTxs - An array of boarding transactions to include in the history.
  * @param {Set<string>} commitmentsToIgnore - A set of commitment IDs that should be excluded from processing.
- * @return {ExtendedArkTransaction[]} A sorted array of extended Ark transactions, representing the transaction history.
+ * @return {ExtendedArkTransaction[]} A sorted array of extended Arkade transactions, representing the transaction history.
  */
 async function buildTransactionHistory(vtxos, allBoardingTxs, commitmentsToIgnore, getTxCreatedAt) {
     const fromOldestVtxo = [...vtxos].sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime());
@@ -62,7 +62,7 @@ async function buildTransactionHistory(vtxos, allBoardingTxs, commitmentsToIgnor
     let received = [];
     for (const vtxo of fromOldestVtxo) {
         if (vtxo.status.isLeaf) {
-            // If this vtxo is a leaf and it's not the settlement of a boarding or there's no vtxo refreshed by it,
+            // If this virtual output is a leaf and it's not the settlement of a boarding or there's no virtual output refreshed by it,
             // it's translated into a received batch transaction
             if (!commitmentsToIgnore.has(vtxo.virtualStatus.commitmentTxIds[0]) &&
                 fromOldestVtxo.filter((v) => v.settledBy === vtxo.virtualStatus.commitmentTxIds[0]).length === 0) {
@@ -82,7 +82,7 @@ async function buildTransactionHistory(vtxos, allBoardingTxs, commitmentsToIgnor
             }
         }
         else if (fromOldestVtxo.filter((v) => v.arkTxId === vtxo.txid).length === 0) {
-            // If this vtxo is preconfirmed and does not spend any other vtxos,
+            // If this virtual output is preconfirmed and does not spend any other virtual outputs,
             // it's translated into a received offchain transaction
             const assets = collectAssets([vtxo]);
             received.push({
@@ -95,15 +95,15 @@ async function buildTransactionHistory(vtxos, allBoardingTxs, commitmentsToIgnor
                 ...(assets && { assets }),
             });
         }
-        // If the vtxo is spent, it's translated into a sent transaction unless:
+        // If the virtual output is spent, it's translated into a sent transaction unless:
         // - it's been refreshed (we don't want to add any record in this case)
-        // - a sent transaction has been already added to avoid duplicates (can happen if many vtxos have been spent in the same tx or forfeited in the same batch)
+        // - a sent transaction has been already added to avoid duplicates (can happen if many virtual outputs have been spent in the same tx or forfeited in the same batch)
         if (vtxo.isSpent) {
-            // If the vtxo is spent offchain, it's translated into offchain sent tx
+            // If the virtual output is spent offchain, it's translated into an offchain sent tx
             if (vtxo.arkTxId &&
                 !sent.some((s) => s.key.arkTxid === vtxo.arkTxId)) {
                 const changes = fromOldestVtxo.filter((_) => _.txid === vtxo.arkTxId);
-                // We want to find all the other VTXOs spent by the same transaction to
+                // We want to find all the other virtual outputs spent by the same transaction to
                 // calculate the full amount of the change.
                 const allSpent = fromOldestVtxo.filter((v) => v.arkTxId === vtxo.arkTxId);
                 const spentAmount = allSpent.reduce((acc, v) => acc + v.value, 0);
@@ -116,7 +116,7 @@ async function buildTransactionHistory(vtxos, allBoardingTxs, commitmentsToIgnor
                 }
                 else {
                     txAmount = spentAmount;
-                    // TODO: fetch the vtxo with /v1/indexer/vtxos?outpoints=<vtxo.arkTxid:0> to know when the tx was made
+                    // TODO: fetch the virtual output with /v1/indexer/vtxos?outpoints=<vtxo.arkTxid:0> to know when the tx was made
                     txTime = getTxCreatedAt
                         ? ((await getTxCreatedAt(vtxo.arkTxId)) ??
                             vtxo.createdAt.getTime() + 1)
@@ -133,7 +133,7 @@ async function buildTransactionHistory(vtxos, allBoardingTxs, commitmentsToIgnor
                     ...(assets && { assets }),
                 });
             }
-            // If the vtxo is forfeited in a batch and the total sum of forfeited vtxos is bigger than the sum of new vtxos,
+            // If the virtual output is forfeited in a batch and the total sum of forfeited virtual outputs is bigger than the sum of new virtual outputs,
             // it's translated into an exit sent tx
             if (vtxo.settledBy &&
                 !commitmentsToIgnore.has(vtxo.settledBy) &&

package/dist/cjs/utils/unknownFields.js

@@ -40,7 +40,7 @@ const bip68 = __importStar(require("bip68"));
 const btc_signer_1 = require("@scure/btc-signer");
 const base_1 = require("@scure/base");
 /**
- * ArkPsbtFieldKey is the key values for ark psbt fields.
+ * ArkPsbtFieldKey are the available key names for the Arkade PSBT custom fields.
  */
 var ArkPsbtFieldKey;
 (function (ArkPsbtFieldKey) {
@@ -50,8 +50,8 @@ var ArkPsbtFieldKey;
     ArkPsbtFieldKey["ConditionWitness"] = "condition";
 })(ArkPsbtFieldKey || (exports.ArkPsbtFieldKey = ArkPsbtFieldKey = {}));
 /**
- * ArkPsbtFieldKeyType is the type of the ark psbt field key.
- * Every ark psbt field has key type 222.
+ * ArkPsbtFieldKeyType is the key type of the Arkade PSBT custom field.
+ * Every Arkade PSBT field has key type 222.
  */
 exports.ArkPsbtFieldKeyType = 222;
 /**

package/dist/cjs/wallet/asset-manager.js

@@ -27,7 +27,7 @@ class AssetManager extends ReadonlyAssetManager {
      * @param params.amount - Amount of asset units to issue
      * @param params.controlAssetId - Optional control asset ID (for reissuable assets)
      * @param params.metadata - Optional metadata to attach to the asset
-     * @returns Promise resolving to the ark transaction ID and asset ID
+     * @returns Promise resolving to the Arkade transaction ID and asset ID
      *
      * @example
      * ```typescript
@@ -112,7 +112,7 @@ class AssetManager extends ReadonlyAssetManager {
      * @param params - Parameters for asset reissuance
      * @param params.assetId - The asset ID to reissue (control asset ID is resolved via getAssetDetails)
      * @param params.amount - Amount of additional units to issue
-     * @returns Promise resolving to the ark transaction ID
+     * @returns Promise resolving to the Arkade transaction ID
      *
      * @example
      * ```typescript
@@ -219,7 +219,7 @@ class AssetManager extends ReadonlyAssetManager {
      * @param params - Parameters for burning
      * @param params.assetId - The asset ID to burn
      * @param params.amount - Amount of units to burn
-     * @returns Promise resolving to the ark transaction ID
+     * @returns Promise resolving to the Arkade transaction ID
      *
      * @example
      * ```typescript
@@ -237,7 +237,7 @@ class AssetManager extends ReadonlyAssetManager {
             withRecoverable: false,
         });
         const assetChanges = new Map();
-        // select vtxos with the asset to burn
+        // select virtual outputs with the asset to burn
         const { selected: assetCoins } = (0, asset_2.selectCoinsWithAsset)(virtualCoins, params.assetId, BigInt(params.amount));
         const selectedCoins = [...assetCoins];
         let totalBtcSelected = 0;

package/dist/cjs/wallet/batch.js

@@ -14,7 +14,7 @@ const base_1 = require("@scure/base");
  * const handler = wallet.createBatchHandler(intentId, inputs, expectedRecipients, musig2session);
  *
  * const abortController = new AbortController();
- * // Get event stream from Ark provider
+ * // Get event stream from the Arkade provider
  * const eventStream = arkProvider.getEventStream(
  *   abortController.signal,
  *   ['your-topic-1', 'your-topic-2']
@@ -99,7 +99,7 @@ var Batch;
                         step !== Step.TreeNoncesAggregated) {
                         continue;
                     }
-                    // batchIndex 0 = vtxo tree, batchIndex 1 = connector tree
+                    // batchIndex 0 = virtual output tree, batchIndex 1 = connector tree
                     if (event.batchIndex === 0) {
                         flatVtxoTree.push(event.chunk);
                     }
@@ -118,7 +118,7 @@ var Batch;
                     if (!vtxoTree) {
                         throw new Error("vtxo tree not initialized");
                     }
-                    // push signature to the vtxo tree
+                    // push signature to the virtual output tree
                     const tapKeySig = base_1.hex.decode(event.signature);
                     vtxoTree.update(event.txid, (tx) => {
                         tx.updateInput(0, {
@@ -134,7 +134,7 @@ var Batch;
                     if (step !== Step.BatchStarted) {
                         continue;
                     }
-                    // create vtxo tree from collected chunks
+                    // create virtual output tree from collected chunks
                     vtxoTree = txTree_1.TxTree.create(flatVtxoTree);
                     const { skip } = await handler.onTreeSigningStarted(event, vtxoTree);
                     if (!skip) {
@@ -156,7 +156,7 @@ var Batch;
                     if (step !== Step.TreeNoncesAggregated) {
                         continue;
                     }
-                    // Build vtxo tree if it hasn't been built yet
+                    // Build virtual output tree if it hasn't been built yet
                     if (!vtxoTree && flatVtxoTree.length > 0) {
                         vtxoTree = txTree_1.TxTree.create(flatVtxoTree);
                     }

package/dist/cjs/wallet/delegator.js

@@ -12,6 +12,7 @@ const networks_1 = require("../networks");
 const asset_1 = require("./asset");
 const extension_1 = require("../extension");
 class DelegatorManagerImpl {
+    /** Create a delegator manager from the configured provider, Arkade info source, and wallet identity. */
     constructor(delegatorProvider, arkInfoProvider, identity) {
         this.delegatorProvider = delegatorProvider;
         this.arkInfoProvider = arkInfoProvider;
@@ -28,7 +29,7 @@ class DelegatorManagerImpl {
         // fetch server and delegator info once, shared across all groups
         const arkInfo = await this.arkInfoProvider.getInfo();
         const delegateInfo = await this.delegatorProvider.getDelegateInfo();
-        // if explicit delegateAt is provided, delegate all vtxos at once without sorting
+        // if explicit delegateAt is provided, delegate all virtual outputs at once without sorting
         if (delegateAt) {
             try {
                 await delegate(this.identity, this.delegatorProvider, arkInfo, delegateInfo, vtxos, destinationScript, delegateAt);
@@ -38,7 +39,7 @@ class DelegatorManagerImpl {
             }
             return { delegated: vtxos, failed: [] };
         }
-        // if no explicit delegateAt is provided, sort vtxos by expiry and delegate in groups of the same expiry day
+        // if no explicit delegateAt is provided, sort virtual outputs by expiry and delegate in groups of the same expiry day
         const groupByExpiry = new Map();
         let recoverableVtxos = [];
         for (const vtxo of vtxos) {
@@ -55,7 +56,7 @@ class DelegatorManagerImpl {
                 vtxo,
             ]);
         }
-        // if no groups, it means we only need to delegate the recoverable vtxos
+        // if no groups, it means we only need to delegate the recoverable virtual outputs
         if (groupByExpiry.size === 0) {
             try {
                 await delegate(this.identity, this.delegatorProvider, arkInfo, delegateInfo, recoverableVtxos, destinationScript, delegateAt);
@@ -68,7 +69,7 @@ class DelegatorManagerImpl {
             }
             return { delegated: recoverableVtxos, failed: [] };
         }
-        // search for the earliest group, include recoverable vtxos into it
+        // search for the earliest group, include recoverable virtual outputs into it
         const earliestGroup = Math.min(...groupByExpiry.keys());
         groupByExpiry.set(earliestGroup, [
             ...(groupByExpiry.get(earliestGroup) ?? []),
@@ -91,9 +92,9 @@ class DelegatorManagerImpl {
 }
 exports.DelegatorManagerImpl = DelegatorManagerImpl;
 /**
- * Delegates virtual coins to a delegator provider, allowing them to manage the coins renewal
- * on behalf of the wallet.
- * @param vtxos - Array of extended virtual coins to delegate. Must not be empty.
+ * Delegates virtual outputs to a delegation service, allowing them to manage their renewal
+ * on behalf of the wallet owner.
+ * @param vtxos - Array of extended virtual outputs to delegate. Must not be empty.
  * @param delegateAt - Optional Date specifying when the delegation
  *                     should occur. If not provided, defaults to 12 hours before the earliest
  *                     expiry time of the provided vtxos.
@@ -110,7 +111,7 @@ async function delegate(identity, delegatorProvider, arkInfo, delegateInfo, vtxo
             .filter((coin) => !(0, __1.isRecoverable)(coin) && coin.virtualStatus.batchExpiry)
             .reduce((min, coin) => Math.min(min, coin.virtualStatus.batchExpiry), Number.MAX_SAFE_INTEGER);
         if (!expiryTimestamp || expiryTimestamp === Number.MAX_SAFE_INTEGER) {
-            // if no expiry (recoverable vtxos), delegate 1 minute from now
+            // if no expiry (recoverable virtual outputs), delegate 1 minute from now
             delegateAt = new Date(Date.now() + 1 * 60 * 1000);
         }
         else {

package/dist/cjs/wallet/expo/background.js

@@ -65,7 +65,7 @@ function defineExpoBackgroundTask(taskName, options) {
             const indexerProvider = new expoIndexer_1.ExpoIndexerProvider(config.arkServerUrl);
             const arkProvider = new expoArk_1.ExpoArkProvider(config.arkServerUrl);
             // Reconstruct default offchainTapscript as fallback
-            // for VTXOs not associated with a contract.
+            // for virtual outputs not associated with a contract.
             const offchainTapscript = new default_1.DefaultVtxo.Script({
                 pubKey: base_1.hex.decode(config.pubkeyHex),
                 serverPubKey: base_1.hex.decode(config.serverPubKeyHex),
@@ -109,8 +109,8 @@ function defineExpoBackgroundTask(taskName, options) {
 /**
  * Activate the OS-level background task scheduler.
  *
- * Call this after {@link defineExpoBackgroundTask} (typically inside
- * {@link ExpoWallet.setup} or in a React component after wallet init).
+ * Call this after @see defineExpoBackgroundTask (typically inside
+ * @see ExpoWallet.setup or in a React component after wallet init).
  *
  * @param minimumInterval - Minimum interval in minutes (default 15).
  */

package/dist/cjs/wallet/expo/wallet.js

@@ -44,7 +44,7 @@ const default_1 = require("../../script/default");
 /**
  * Expo/React Native wallet with built-in background task processing.
  *
- * Wraps a standard {@link Wallet} and adds a lightweight task queue
+ * Wraps a standard @see Wallet and adds a lightweight task queue
  * for keeping contract/VTXO state fresh while the app is active and
  * across Expo BackgroundTask wakes.
  *
@@ -54,10 +54,10 @@ const default_1 = require("../../script/default");
  * import { AsyncStorageTaskQueue } from "@arkade-os/sdk/worker/expo";
  *
  * const wallet = await ExpoWallet.setup({
- *     identity: SingleKey.fromHex(privateKey),
- *     arkServerUrl,
- *     esploraUrl,
- *     storage: { walletRepository, contractRepository },
+ *     identity: MnemonicIdentity.fromMnemonic('abandon abandon...'),
+ *     arkServerUrl: 'https://arkade.computer',
+ *     esploraUrl: 'https://mempool.space/api',
+ *     storage: { ... },
  *     background: {
  *         taskName: "ark-background-poll",
  *         taskQueue: new AsyncStorageTaskQueue(AsyncStorage),
@@ -86,8 +86,8 @@ class ExpoWallet {
     /**
      * Create an ExpoWallet with background task support.
      *
-     * 1. Creates the inner {@link Wallet} via `Wallet.create()`.
-     * 2. Wires up processors (defaults to {@link contractPollProcessor}).
+     * 1. Creates the inner @see Wallet via `Wallet.create()`.
+     * 2. Wires up processors (defaults to @see contractPollProcessor).
      * 3. Persists background config for the background handler (if the queue supports it).
      * 4. Seeds the task queue with a `contract-poll` task.
      * 5. Registers the background task with the OS scheduler (if `minimumBackgroundInterval` is set).

package/dist/cjs/wallet/index.js

@@ -5,17 +5,51 @@ exports.isSpendable = isSpendable;
 exports.isRecoverable = isRecoverable;
 exports.isExpired = isExpired;
 exports.isSubdust = isSubdust;
+/** Wallet transaction direction. */
 var TxType;
 (function (TxType) {
     TxType["TxSent"] = "SENT";
     TxType["TxReceived"] = "RECEIVED";
 })(TxType || (exports.TxType = TxType = {}));
+/**
+ * Return whether a virtual output is still spendable.
+ *
+ * @param vtxo - virtual output to inspect
+ * @returns `true` when the virtual output is not marked as spent
+ *
+ * @see isRecoverable
+ * @see isExpired
+ */
 function isSpendable(vtxo) {
     return !vtxo.isSpent;
 }
+/**
+ * Return whether a virtual output is recoverable.
+ *
+ * @param vtxo - virtual output to inspect
+ * @returns `true` when the virtual output is swept but still spendable
+ *
+ * @remarks
+ * Recoverable virtual outputs are typically re-settled into fresh virtual outputs by the virtual output manager.
+ *
+ * @see isSpendable
+ * @see isExpired
+ */
 function isRecoverable(vtxo) {
     return vtxo.virtualStatus.state === "swept" && isSpendable(vtxo);
 }
+/**
+ * Return whether a virtual output should be treated as expired.
+ *
+ * @param vtxo - virtual output to inspect
+ * @returns `true` when the virtual output is swept or its batch expiry has passed
+ * @remarks
+ * On regtest-like environments the upstream expiry value may be expressed as a block
+ * height instead of a timestamp. This helper intentionally ignores obviously non-time
+ * values to avoid false positives.
+ *
+ * @see VirtualStatus.batchExpiry
+ */
 function isExpired(vtxo) {
     if (vtxo.virtualStatus.state === "swept")
         return true; // swept by server = expired
@@ -30,6 +64,15 @@ function isExpired(vtxo) {
         return false;
     return expiry <= Date.now();
 }
+/**
+ * Return whether a virtual output is below the dust threshold.
+ *
+ * @param vtxo - virtual output to inspect
+ * @param dust - dust threshold in satoshis
+ * @returns `true` when the virtual output value is below `dust`
+ *
+ * @see isRecoverable
+ */
 function isSubdust(vtxo, dust) {
     return vtxo.value < dust;
 }

package/dist/cjs/wallet/onchain.js

@@ -13,7 +13,7 @@ const utils_1 = require("./utils");
  * 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
@@ -33,6 +33,16 @@ 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) {
@@ -46,9 +56,21 @@ 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
@@ -63,9 +85,9 @@ 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
@@ -74,7 +96,7 @@ 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
@@ -107,6 +129,14 @@ 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");
@@ -152,6 +182,14 @@ 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_1.Transaction({
@@ -173,7 +211,7 @@ 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) {