@arkade-os/sdk 0.4.14 → 0.4.16

package/dist/esm/script/base.js

@@ -11,18 +11,35 @@ export function scriptFromTapLeafScript(leaf) {
 }
 /**
  * VtxoScript is a script that contains a list of tapleaf scripts.
- * It is used to create vtxo scripts.
+ * It is used to create virtual output scripts.
+ *
+ * @see ArkAddress
  *
  * @example
  * ```typescript
  * const vtxoScript = new VtxoScript([new Uint8Array(32), new Uint8Array(32)]);
+ * ```
  */
 export class VtxoScript {
+    /**
+     * Decode a virtual output script from an encoded TapTree.
+     *
+     * @param tapTree - Encoded TapTree bytes
+     * @returns Decoded virtual output script
+     * @throws Error if the TapTree cannot be decoded into a valid script set
+     * @see encode
+     */
     static decode(tapTree) {
         const leaves = TapTreeCoder.decode(tapTree);
         const scripts = leaves.map((leaf) => leaf.script);
         return new VtxoScript(scripts);
     }
+    /**
+     * Create a virtual output script from its tapleaf scripts.
+     *
+     * @param scripts - Raw tapscript bytes for each leaf
+     * @throws Error if the provided leaves cannot produce a valid Taproot tree
+     */
     constructor(scripts) {
         this.scripts = scripts;
         // reverse the scripts if the number of scripts is odd
@@ -43,6 +60,12 @@ export class VtxoScript {
         this.leaves = payment.tapLeafScript;
         this.tweakedPublicKey = payment.tweakedPubkey;
     }
+    /**
+     * Encode the virtual output script to a TapTree byte representation.
+     *
+     * @returns Encoded TapTree bytes
+     * @see decode
+     */
     encode() {
         const tapTree = TapTreeCoder.encode(this.scripts.map((script) => ({
             depth: 1,
@@ -51,18 +74,40 @@ export class VtxoScript {
         })));
         return tapTree;
     }
+    /**
+     * Build the Arkade address corresponding to this virtual output script.
+     *
+     * @param prefix - Bech32 human-readable prefix
+     * @param serverPubKey - 32-byte Arkade server public key
+     * @returns Arkade address for this script
+     * @see ArkAddress
+     */
     address(prefix, serverPubKey) {
         return new ArkAddress(serverPubKey, this.tweakedPublicKey, prefix);
     }
     get pkScript() {
         return Script.encode(["OP_1", this.tweakedPublicKey]);
     }
+    /**
+     * Build the Taproot onchain address corresponding to this virtual output script.
+     *
+     * @param network - Bitcoin network descriptor
+     * @returns Taproot onchain address
+     * @see address
+     */
     onchainAddress(network) {
         return Address(network).encode({
             type: "tr",
             pubkey: this.tweakedPublicKey,
         });
     }
+    /**
+     * Look up a tapleaf script by its hex-encoded tapscript body.
+     *
+     * @param scriptHex - Hex-encoded tapscript body without the leaf version byte
+     * @returns Matching tapleaf script
+     * @throws Error if no matching leaf exists
+     */
     findLeaf(scriptHex) {
         const leaf = this.leaves.find((leaf) => hex.encode(scriptFromTapLeafScript(leaf)) === scriptHex);
         if (!leaf) {
@@ -70,6 +115,12 @@ export class VtxoScript {
         }
         return leaf;
     }
+    /**
+     * Return all unilateral exit paths embedded in the virtual output script.
+     *
+     * @returns CSV-based exit paths found in the leaves
+     * @see getSequence
+     */
     exitPaths() {
         const paths = [];
         for (const leaf of this.leaves) {
@@ -91,6 +142,24 @@ export class VtxoScript {
         return paths;
     }
 }
+/**
+ * Extract the timelock value encoded in a timelocked tapleaf, if any.
+ *
+ * The return value is unit-ambiguous: for a CSV leaf it is a BIP-68
+ * nSequence (relative timelock); for a CLTV leaf it is an absolute
+ * nLockTime. Callers must know which leaf shape they are inspecting to
+ * interpret the number correctly, and must not copy a CSV result into
+ * `Transaction.lockTime` (or vice versa).
+ *
+ * @param tapLeafScript - Tapleaf script to inspect
+ * @returns The encoded timelock value, or `undefined` when neither a CSV
+ *          nor CLTV path is present
+ * @see VtxoScript.exitPaths
+ */
+// TODO(next-major): return a discriminated union
+// (`{ kind: "relative", nSequence } | { kind: "absolute", lockTime }`)
+// so callers can't conflate the two. Deferred because changing the
+// return type is a breaking change.
 export function getSequence(tapLeafScript) {
     let sequence = undefined;
     try {

package/dist/esm/script/default.js

@@ -22,6 +22,7 @@ export var DefaultVtxo;
      * ```
      */
     class Script extends VtxoScript {
+        /** Create the default virtual output script with one forfeit path and one exit path. */
         constructor(options) {
             const { pubKey, serverPubKey, csvTimelock = Script.DEFAULT_TIMELOCK, } = options;
             const forfeitScript = MultisigTapscript.encode({
@@ -36,9 +37,11 @@ export var DefaultVtxo;
             this.forfeitScript = hex.encode(forfeitScript);
             this.exitScript = hex.encode(exitScript);
         }
+        /** Return the forfeit tapleaf script. */
         forfeit() {
             return this.findLeaf(this.forfeitScript);
         }
+        /** Return the unilateral exit tapleaf script. */
         exit() {
             return this.findLeaf(this.exitScript);
         }

package/dist/esm/script/delegate.js

@@ -21,6 +21,7 @@ export var DelegateVtxo;
      * ```
      */
     class Script extends VtxoScript {
+        /** Create a delegated virtual output script with forfeit, exit, and delegate paths. */
         constructor(options) {
             const defaultVtxo = new DefaultVtxo.Script(options);
             const { delegatePubKey, pubKey, serverPubKey } = options;
@@ -32,12 +33,15 @@ export var DelegateVtxo;
             this.defaultVtxo = defaultVtxo;
             this.delegateScript = hex.encode(delegateScript);
         }
+        /** Return the forfeit tapleaf script. */
         forfeit() {
             return this.findLeaf(this.defaultVtxo.forfeitScript);
         }
+        /** Return the unilateral exit tapleaf script. */
         exit() {
             return this.findLeaf(this.defaultVtxo.exitScript);
         }
+        /** Return the delegate tapleaf script. */
         delegate() {
             return this.findLeaf(this.delegateScript);
         }

package/dist/esm/script/tapscript.js

@@ -11,9 +11,9 @@ export var TapscriptType;
     TapscriptType["CLTVMultisig"] = "cltv-multisig";
 })(TapscriptType || (TapscriptType = {}));
 /**
- * decodeTapscript is a function that decodes an ark tapsript from a raw script.
+ * decodeTapscript is a function that decodes an Arkade tapscript from a raw script.
  *
- * @throws {Error} if the script is not a valid ark tapscript
+ * @throws {Error} if the script is not a valid Arkade tapscript
  * @example
  * ```typescript
  * const arkTapscript = decodeTapscript(new Uint8Array(32));
@@ -55,6 +55,7 @@ export var MultisigTapscript;
         MultisigType[MultisigType["CHECKSIG"] = 0] = "CHECKSIG";
         MultisigType[MultisigType["CHECKSIGADD"] = 1] = "CHECKSIGADD";
     })(MultisigType = MultisigTapscript.MultisigType || (MultisigTapscript.MultisigType = {}));
+    /** Encode a plain multisig tapscript. */
     function encode(params) {
         if (params.pubkeys.length === 0) {
             throw new Error("At least 1 pubkey is required");
@@ -92,6 +93,7 @@ export var MultisigTapscript;
         };
     }
     MultisigTapscript.encode = encode;
+    /** Decode a plain multisig tapscript from raw script bytes. */
     function decode(script) {
         if (script.length === 0) {
             throw new Error("Failed to decode: script is empty");
@@ -204,6 +206,7 @@ export var MultisigTapscript;
             script,
         };
     }
+    /** Return true when the tapscript is a plain multisig tapscript. */
     function is(tapscript) {
         return tapscript.type === TapscriptType.Multisig;
     }
@@ -224,6 +227,7 @@ export var MultisigTapscript;
  */
 export var CSVMultisigTapscript;
 (function (CSVMultisigTapscript) {
+    /** Encode a CSV multisig tapscript. */
     function encode(params) {
         for (const pubkey of params.pubkeys) {
             if (pubkey.length !== 32) {
@@ -250,6 +254,7 @@ export var CSVMultisigTapscript;
         };
     }
     CSVMultisigTapscript.encode = encode;
+    /** Decode a CSV multisig tapscript from raw script bytes. */
     function decode(script) {
         if (script.length === 0) {
             throw new Error("Failed to decode: script is empty");
@@ -301,6 +306,7 @@ export var CSVMultisigTapscript;
         };
     }
     CSVMultisigTapscript.decode = decode;
+    /** Return true when the tapscript is a CSV multisig tapscript. */
     function is(tapscript) {
         return tapscript.type === TapscriptType.CSVMultisig;
     }
@@ -320,6 +326,7 @@ export var CSVMultisigTapscript;
  */
 export var ConditionCSVMultisigTapscript;
 (function (ConditionCSVMultisigTapscript) {
+    /** Encode a condition + CSV multisig tapscript. */
     function encode(params) {
         const script = new Uint8Array([
             ...params.conditionScript,
@@ -333,6 +340,7 @@ export var ConditionCSVMultisigTapscript;
         };
     }
     ConditionCSVMultisigTapscript.encode = encode;
+    /** Decode a condition + CSV multisig tapscript from raw script bytes. */
     function decode(script) {
         if (script.length === 0) {
             throw new Error("Failed to decode: script is empty");
@@ -376,6 +384,7 @@ export var ConditionCSVMultisigTapscript;
         };
     }
     ConditionCSVMultisigTapscript.decode = decode;
+    /** Return true when the tapscript is a condition + CSV multisig tapscript. */
     function is(tapscript) {
         return tapscript.type === TapscriptType.ConditionCSVMultisig;
     }
@@ -395,6 +404,7 @@ export var ConditionCSVMultisigTapscript;
  */
 export var ConditionMultisigTapscript;
 (function (ConditionMultisigTapscript) {
+    /** Encode a condition + multisig tapscript. */
     function encode(params) {
         const script = new Uint8Array([
             ...params.conditionScript,
@@ -408,6 +418,7 @@ export var ConditionMultisigTapscript;
         };
     }
     ConditionMultisigTapscript.encode = encode;
+    /** Decode a condition + multisig tapscript from raw script bytes. */
     function decode(script) {
         if (script.length === 0) {
             throw new Error("Failed to decode: script is empty");
@@ -451,6 +462,7 @@ export var ConditionMultisigTapscript;
         };
     }
     ConditionMultisigTapscript.decode = decode;
+    /** Return true when the tapscript is a condition + multisig tapscript. */
     function is(tapscript) {
         return tapscript.type === TapscriptType.ConditionMultisig;
     }
@@ -470,6 +482,7 @@ export var ConditionMultisigTapscript;
  */
 export var CLTVMultisigTapscript;
 (function (CLTVMultisigTapscript) {
+    /** Encode a CLTV multisig tapscript. */
     function encode(params) {
         const locktime = MinimalScriptNum.encode(params.absoluteTimelock);
         const asm = [
@@ -489,6 +502,7 @@ export var CLTVMultisigTapscript;
         };
     }
     CLTVMultisigTapscript.encode = encode;
+    /** Decode a CLTV multisig tapscript from raw script bytes. */
     function decode(script) {
         if (script.length === 0) {
             throw new Error("Failed to decode: script is empty");
@@ -498,7 +512,7 @@ export var CLTVMultisigTapscript;
             throw new Error(`Invalid script: too short (expected at least 3)`);
         }
         const locktime = asm[0];
-        if (typeof locktime === "string" || typeof locktime === "number") {
+        if (typeof locktime === "string") {
             throw new Error("Invalid script: expected locktime number");
         }
         if (asm[1] !== "CHECKLOCKTIMEVERIFY" || asm[2] !== "DROP") {
@@ -512,7 +526,13 @@ export var CLTVMultisigTapscript;
         catch (error) {
             throw new Error(`Invalid multisig script: ${error instanceof Error ? error.message : String(error)}`);
         }
-        const absoluteTimelock = MinimalScriptNum.decode(locktime);
+        let absoluteTimelock;
+        if (typeof locktime === "number") {
+            absoluteTimelock = BigInt(locktime);
+        }
+        else {
+            absoluteTimelock = MinimalScriptNum.decode(locktime);
+        }
         const reconstructed = encode({
             absoluteTimelock,
             ...multisig.params,
@@ -530,6 +550,7 @@ export var CLTVMultisigTapscript;
         };
     }
     CLTVMultisigTapscript.decode = decode;
+    /** Return true when the tapscript is a CLTV multisig tapscript. */
     function is(tapscript) {
         return tapscript.type === TapscriptType.CLTVMultisig;
     }

package/dist/esm/script/vhtlc.js

@@ -2,36 +2,38 @@ import { Script } from "@scure/btc-signer";
 import { CLTVMultisigTapscript, ConditionCSVMultisigTapscript, ConditionMultisigTapscript, CSVMultisigTapscript, MultisigTapscript, } from './tapscript.js';
 import { hex } from "@scure/base";
 import { VtxoScript } from './base.js';
-/**
- * Virtual Hash Time Lock Contract (VHTLC) implementation.
- *
- * VHTLC is a contract that enables atomic swaps and conditional payments
- * in the Ark protocol. It provides multiple spending paths:
- *
- * - **claim**: Receiver can claim funds by revealing the preimage
- * - **refund**: Sender and receiver can collaboratively refund
- * - **refundWithoutReceiver**: Sender can refund after locktime expires
- * - **unilateralClaim**: Receiver can claim unilaterally after delay
- * - **unilateralRefund**: Sender and receiver can refund unilaterally after delay
- * - **unilateralRefundWithoutReceiver**: Sender can refund unilaterally after delay
- *
- * @example
- * ```typescript
- * const vhtlc = new VHTLC.Script({
- *   sender: alicePubKey,
- *   receiver: bobPubKey,
- *   server: serverPubKey,
- *   preimageHash: hash160(secret),
- *   refundLocktime: BigInt(chainTip + 10),
- *   unilateralClaimDelay: { type: 'blocks', value: 100n },
- *   unilateralRefundDelay: { type: 'blocks', value: 102n },
- *   unilateralRefundWithoutReceiverDelay: { type: 'blocks', value: 103n }
- * });
- * ```
- */
+/** Virtual Hash Time Lock Contract (VHTLC) namespace. */
 export var VHTLC;
 (function (VHTLC) {
+    /**
+     * Virtual Hash Time Lock Contract (VHTLC) script implementation.
+     *
+     * VHTLC enables atomic swaps and conditional payments in the Arkade protocol.
+     * It provides multiple spending paths:
+     *
+     * - **claim**: Receiver can claim funds by revealing the preimage
+     * - **refund**: Sender and receiver can collaboratively refund
+     * - **refundWithoutReceiver**: Sender can refund after locktime expires
+     * - **unilateralClaim**: Receiver can claim unilaterally after delay
+     * - **unilateralRefund**: Sender and receiver can refund unilaterally after delay
+     * - **unilateralRefundWithoutReceiver**: Sender can refund unilaterally after delay
+     *
+     * @example
+     * ```typescript
+     * const vhtlc = new VHTLC.Script({
+     *   sender: alicePubKey,
+     *   receiver: bobPubKey,
+     *   server: serverPubKey,
+     *   preimageHash: hash160(secret),
+     *   refundLocktime: BigInt(chainTip + 10),
+     *   unilateralClaimDelay: { type: 'blocks', value: 100n },
+     *   unilateralRefundDelay: { type: 'blocks', value: 102n },
+     *   unilateralRefundWithoutReceiverDelay: { type: 'blocks', value: 103n }
+     * });
+     * ```
+     */
     class Script extends VtxoScript {
+        /** Create a VHTLC script from the supplied participant keys, hash, and timelocks. */
         constructor(options) {
             validateOptions(options);
             const { sender, receiver, server, preimageHash, refundLocktime, unilateralClaimDelay, unilateralRefundDelay, unilateralRefundWithoutReceiverDelay, } = options;
@@ -76,21 +78,27 @@ export var VHTLC;
             this.unilateralRefundScript = hex.encode(unilateralRefundScript);
             this.unilateralRefundWithoutReceiverScript = hex.encode(unilateralRefundWithoutReceiverScript);
         }
+        /** Return the collaborative claim tapleaf script. */
         claim() {
             return this.findLeaf(this.claimScript);
         }
+        /** Return the collaborative refund tapleaf script. */
         refund() {
             return this.findLeaf(this.refundScript);
         }
+        /** Return the refund-without-receiver tapleaf script. */
         refundWithoutReceiver() {
             return this.findLeaf(this.refundWithoutReceiverScript);
         }
+        /** Return the unilateral claim tapleaf script. */
         unilateralClaim() {
             return this.findLeaf(this.unilateralClaimScript);
         }
+        /** Return the unilateral refund tapleaf script. */
         unilateralRefund() {
             return this.findLeaf(this.unilateralRefundScript);
         }
+        /** Return the unilateral refund-without-receiver tapleaf script. */
         unilateralRefundWithoutReceiver() {
             return this.findLeaf(this.unilateralRefundWithoutReceiverScript);
         }

package/dist/esm/storage/fileSystem.js

@@ -1,7 +1,7 @@
 import * as fs from "fs/promises";
 import * as path from "path";
 /**
- * @deprecated Use repositories instead
+ * @deprecated Use repository implementations via `StorageConfig` instead.
  */
 export class FileSystemStorageAdapter {
     constructor(dirPath) {

package/dist/esm/storage/inMemory.js

@@ -1,5 +1,5 @@
 /**
- * @deprecated Use repositories instead
+ * @deprecated Use repository implementations via `StorageConfig` instead.
  */
 export class InMemoryStorageAdapter {
     constructor() {

package/dist/esm/storage/indexedDB.js

@@ -1,6 +1,6 @@
 import { DB_VERSION } from '../repositories/indexedDB/db.js';
 /**
- * @deprecated Use repositories instead
+ * @deprecated Use repository implementations via `StorageConfig` instead.
  */
 export class IndexedDBStorageAdapter {
     constructor(dbName, version = DB_VERSION) {

package/dist/esm/storage/localStorage.js

@@ -1,5 +1,5 @@
 /**
- * @deprecated Use repositories instead
+ * @deprecated Use repository implementations via `StorageConfig` instead.
  */
 export class LocalStorageAdapter {
     getSafeLocalStorage() {

package/dist/esm/tree/validation.js

@@ -32,7 +32,7 @@ export function validateConnectorsTxGraph(settlementTxB64, connectorsGraph) {
     if (rootInput.index !== BATCH_OUTPUT_CONNECTORS_INDEX)
         throw ErrWrongSettlementTxid;
 }
-// ValidateVtxoTxGraph checks if the given vtxo graph is valid.
+// ValidateVtxoTxGraph checks if the given virtual output tx graph is valid.
 // The function validates:
 // - the number of nodes
 // - the number of leaves

package/dist/esm/utils/arkTransaction.js

@@ -14,7 +14,7 @@ import { Extension } from '../extension/index.js';
  *
  * 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
@@ -92,9 +92,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 = decodeTapscript(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 VtxoScript([
         serverUnrollScript.script,
         collaborativeClosure.script,
@@ -249,8 +249,8 @@ export 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.
  */
 export function isValidArkAddress(address) {

package/dist/esm/utils/bip21.js

@@ -4,6 +4,12 @@ export var BIP21Error;
     BIP21Error["INVALID_ADDRESS"] = "Invalid address";
 })(BIP21Error || (BIP21Error = {}));
 export 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
@@ -22,7 +28,7 @@ export 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;
@@ -53,11 +59,18 @@ export 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 = {};
@@ -80,7 +93,7 @@ export 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/esm/utils/syncCursors.js

@@ -1,6 +1,6 @@
 /** Lag behind real-time to avoid racing with indexer writes. */
 export const SAFETY_LAG_MS = 30000;
-/** Overlap window so boundary VTXOs are never missed. */
+/** Overlap window so boundary virtual outputs are never missed. */
 export const OVERLAP_MS = 60000;
 /**
  * Per-repository mutex that serializes wallet-state mutations so that
@@ -101,8 +101,8 @@ export 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).
  */
 export function computeSyncWindow(cursor) {
     if (cursor === undefined)
@@ -112,7 +112,7 @@ export 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/esm/utils/transaction.js

@@ -1,7 +1,7 @@
 import { Transaction as BtcSignerTransaction } from "@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.
  */
 export class Transaction extends BtcSignerTransaction {
     constructor(opts) {

package/dist/esm/utils/transactionHistory.js

@@ -45,13 +45,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.
  */
 export async function buildTransactionHistory(vtxos, allBoardingTxs, commitmentsToIgnore, getTxCreatedAt) {
     const fromOldestVtxo = [...vtxos].sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime());
@@ -59,7 +59,7 @@ export async function buildTransactionHistory(vtxos, allBoardingTxs, commitments
     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) {
@@ -79,7 +79,7 @@ export async function buildTransactionHistory(vtxos, allBoardingTxs, commitments
             }
         }
         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({
@@ -92,15 +92,15 @@ export async function buildTransactionHistory(vtxos, allBoardingTxs, commitments
                 ...(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);
@@ -113,7 +113,7 @@ export async function buildTransactionHistory(vtxos, allBoardingTxs, commitments
                 }
                 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)
@@ -130,7 +130,7 @@ export async function buildTransactionHistory(vtxos, allBoardingTxs, commitments
                     ...(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) &&