@arkade-os/sdk 0.4.15 → 0.4.16

package/dist/esm/arkfee/types.js

@@ -1,7 +1,6 @@
 /**
  * FeeAmount is a wrapper around a number that represents a fee amount in satoshis floating point.
  * @param value - The fee amount in floating point.
- * @method satoshis - Returns the fee amount in satoshis as a integer.
  * @example
  * const fee = new FeeAmount(1.23456789);
  * console.log(fee.value); // 1.23456789
@@ -11,9 +10,11 @@ export class FeeAmount {
     constructor(value) {
         this.value = value;
     }
+    /** Returns the fee amount rounded up to whole satoshis. */
     get satoshis() {
         return this.value ? Math.ceil(this.value) : 0;
     }
+    /** Add two fee amounts together. */
     add(other) {
         return new FeeAmount(this.value + other.value);
     }

package/dist/esm/arknote/index.js

@@ -3,10 +3,12 @@ import { sha256 } from "@scure/btc-signer/utils.js";
 import { Script } from "@scure/btc-signer";
 import { VtxoScript } from '../script/base.js';
 /**
- * ArkNotes are special virtual coins in the Ark protocol that can be created
- * and spent without requiring any transactions. The server mints them, and they
- * are encoded as base58 strings with a human-readable prefix. It contains a
- * preimage and value.
+ * ArkNotes are special virtual outputs in the Arkade protocol that
+ * can be created and spent without requiring any transactions.
+ * The server mints them, and they are encoded as base58 strings
+ * with a human-readable prefix, a preimage and a value.
+ *
+ * @see VtxoScript
  *
  * @example
  * ```typescript
@@ -21,6 +23,13 @@ import { VtxoScript } from '../script/base.js';
  * ```
  */
 export class ArkNote {
+    /**
+     * Create an ArkNote from a preimage and value.
+     *
+     * @param preimage - 32-byte preimage revealed to spend the note
+     * @param value - Note value in satoshis
+     * @param HRP - Optional human-readable prefix for string encoding
+     */
     constructor(preimage, value, HRP = ArkNote.DefaultHRP) {
         this.preimage = preimage;
         this.value = value;
@@ -37,12 +46,27 @@ export class ArkNote {
         this.status = { confirmed: true };
         this.extraWitness = [this.preimage];
     }
+    /**
+     * Encode the note as raw bytes.
+     *
+     * @returns Serialized note bytes
+     * @see decode
+     */
     encode() {
         const result = new Uint8Array(ArkNote.Length);
         result.set(this.preimage, 0);
         writeUInt32BE(result, this.value, this.preimage.length);
         return result;
     }
+    /**
+     * Decode a note from raw bytes.
+     *
+     * @param data - Serialized note bytes
+     * @param hrp - Human-readable prefix expected for future string encoding
+     * @returns Decoded ArkNote
+     * @throws Error if the payload length is invalid
+     * @see encode
+     */
     static decode(data, hrp = ArkNote.DefaultHRP) {
         if (data.length !== ArkNote.Length) {
             throw new Error(`invalid data length: expected ${ArkNote.Length} bytes, got ${data.length}`);
@@ -51,6 +75,15 @@ export class ArkNote {
         const value = readUInt32BE(data, ArkNote.PreimageLength);
         return new ArkNote(preimage, value, hrp);
     }
+    /**
+     * Decode a note from its base58 string form.
+     *
+     * @param noteStr - Base58-encoded note string
+     * @param hrp - Human-readable prefix expected on the note string
+     * @returns Decoded ArkNote
+     * @throws Error if the prefix or base58 payload is invalid
+     * @see toString
+     */
     static fromString(noteStr, hrp = ArkNote.DefaultHRP) {
         noteStr = noteStr.trim();
         if (!noteStr.startsWith(hrp)) {
@@ -63,6 +96,12 @@ export class ArkNote {
         }
         return ArkNote.decode(decoded, hrp);
     }
+    /**
+     * Encode the note to its human-readable base58 string form.
+     *
+     * @returns Base58-encoded note string
+     * @see fromString
+     */
     toString() {
         return this.HRP + base58.encode(this.encode());
     }

package/dist/esm/bip322/index.js

@@ -14,7 +14,7 @@ const TAG_BIP322 = "BIP0322-signed-message";
  *
  * Reuses the same toSpend/toSign transaction construction as Intent proofs,
  * but with the standard BIP-322 tagged hash ("BIP0322-signed-message")
- * instead of the Ark-specific tag.
+ * instead of the Arkade-specific tag.
  *
  * @see https://github.com/bitcoin/bips/blob/master/bip-0322.mediawiki
  *

package/dist/esm/contracts/arkcontract.js

@@ -10,7 +10,7 @@ const ARKCONTRACT_PREFIX = "arkcontract";
  * Format: arkcontract={type}&{key1}={value1}&{key2}={value2}...
  *
  * This format is compatible with NArk and allows contracts to be
- * shared/imported across different Ark implementations.
+ * shared/imported across different Arkade SDKs.
  *
  * @example
  * ```typescript

package/dist/esm/contracts/contractManager.js

@@ -7,38 +7,50 @@ const DEFAULT_PAGE_SIZE = 500;
 /**
  * Central manager for contract lifecycle and operations.
  *
- * The ContractManager orchestrates:
- * - Contract registration and persistence
- * - Multi-contract watching via ContractWatcher
- * - VTXO queries across contracts
+ * Responsibilities:
+ * - Create and persist contracts
+ * - Query stored contracts (optionally with their virtual outputs)
+ * - Provide spendable path selection for a contract
+ * - Emit contract-related events (virtual output received/spent/expired, connection reset)
+ *
+ * Notes:
+ * - Implementations typically start watching automatically during initialization
+ *   (so `onContractEvent()` is just for subscribing).
  *
  * @example
  * ```typescript
- * const manager = new ContractManager({
+ * const manager = await ContractManager.create({
  *   indexerProvider: wallet.indexerProvider,
  *   contractRepository: wallet.contractRepository,
+ *   walletRepository: wallet.walletRepository,
  *   getDefaultAddress: () => wallet.getAddress(),
  * });
  *
- * // Initialize (loads persisted contracts)
- * await manager.initialize();
- *
  * // Create a new VHTLC contract
  * const contract = await manager.createContract({
  *   label: "Lightning Receive",
  *   type: "vhtlc",
- *   params: { sender: "ab12...", receiver: "cd34...", ... },
+ *   params: { sender: "ark1q...", receiver: "ark1q...", ... },
  *   script: "5120...",
- *   address: "tark1...",
+ *   address: "ark1q...",
  * });
  *
  * // Start watching for events
- * const stop = await manager.startWatching((event) => {
+ * const unsubscribe = manager.onContractEvent((event) => {
  *   console.log(`${event.type} on ${event.contractScript}`);
  * });
  *
+ * // Query contracts together with their current virtual outputs
+ * const contractsWithVtxos = await manager.getContractsWithVtxos();
+ *
  * // Get balance across all contracts
- * const balances = await manager.getAllBalances();
+ * const balances = contractsWithVtxos.flatMap(({vtxos}) => vtxos).reduce((acc, vtxo) => acc + vtxo.value, 0)
+ *
+ * // Later: unsubscribe from events
+ * unsubscribe();
+ *
+ * // Clean up
+ * manager.dispose();
  * ```
  */
 export class ContractManager {
@@ -46,7 +58,7 @@ export class ContractManager {
         this.initialized = false;
         this.eventCallbacks = new Set();
         this.config = config;
-        // Create watcher with wallet repository for VTXO caching
+        // Create watcher with wallet repository for virtual output caching
         this.watcher = new ContractWatcher({
             indexerProvider: config.indexerProvider,
             walletRepository: config.walletRepository,
@@ -58,7 +70,7 @@ export class ContractManager {
      * Initialize the manager by loading persisted contracts and starting to watch.
      *
      * After initialization, the manager automatically watches all active contracts
-     * and contracts with VTXOs. Use `onContractEvent()` to register event callbacks.
+     * and contracts with virtual outputs. Use `onContractEvent()` to register event callbacks.
      *
      * @param config ContractManagerConfig
      */
@@ -73,10 +85,10 @@ export class ContractManager {
         }
         // Load persisted contracts
         const contracts = await this.config.contractRepository.getContracts();
-        // Delta-sync: fetch only VTXOs that changed since the last cursor,
+        // Delta-sync: fetch only virtual outputs that changed since the last cursor,
         // falling back to a full bootstrap for scripts seen for the first time.
         await this.deltaSyncContracts(contracts);
-        // Reconcile the pending frontier: fetch all not-yet-finalized VTXOs
+        // Reconcile the pending frontier: fetch all not-yet-finalized virtual outputs
         // to catch any that the delta window may have missed.
         if (contracts.length > 0) {
             await this.reconcilePendingFrontier(contracts);
@@ -145,7 +157,7 @@ export class ContractManager {
         };
         // Persist
         await this.config.contractRepository.saveContract(contract);
-        // fetch all VTXOs (including spent/swept) for this contract
+        // fetch all virtual outputs (including spent/swept) for this contract
         const requestStartedAt = Date.now();
         await this.fetchContractVxosFromIndexer([contract], true);
         // Advance the sync cursor so that the watcher's vtxo_received
@@ -258,7 +270,6 @@ export class ContractManager {
     /**
      * Get currently spendable paths for a contract.
      *
-     * @param contractScript - The contract script
      * @param options - Options for getting spendable paths
      */
     async getSpendablePaths(options) {
@@ -278,6 +289,11 @@ export class ContractManager {
         };
         return handler.getSpendablePaths(script, contract, context);
     }
+    /**
+     * Get every currently valid spending path for a contract.
+     *
+     * @param options - Options for getting spending paths
+     */
     async getAllSpendingPaths(options) {
         const { contractScript, collaborative = true, walletPubKey } = options;
         const [contract] = await this.getContracts({ script: contractScript });
@@ -320,7 +336,7 @@ export class ContractManager {
         };
     }
     /**
-     * Force a VTXO refresh from the indexer.
+     * Force refresh virtual outputs from the indexer.
      *
      * Without options, clears all sync cursors and re-fetches every contract.
      * With options, narrows the refresh to specific scripts and/or a time window.
@@ -382,7 +398,7 @@ export class ContractManager {
      */
     async handleContractEvent(event) {
         switch (event.type) {
-            // Delta-sync only the changed VTXOs for this contract.
+            // Delta-sync only the changed virtual outputs for this contract.
             case "vtxo_received":
             case "vtxo_spent":
                 await this.deltaSyncContracts([event.contract]);
@@ -407,7 +423,7 @@ export class ContractManager {
         return await this.fetchContractVxosFromIndexer(contracts, false, pageSize);
     }
     /**
-     * Incrementally sync VTXOs for the given contracts.
+     * Incrementally sync virtual outputs for the given contracts.
      * Uses per-script cursors to fetch only what changed since the last sync.
      * Scripts without a cursor are bootstrapped with a full fetch.
      */
@@ -459,8 +475,8 @@ export class ContractManager {
         return result;
     }
     /**
-     * Fetch all pending (not-yet-finalized) VTXOs and upsert them into the
-     * repository. This catches VTXOs whose state changed outside the delta
+     * Fetch all pending (unfinalized) virtual outputs and upsert them into the
+     * repository. This catches virtual outputs whose state changed outside the delta
      * window (e.g. a spend that hasn't settled yet).
      */
     async reconcilePendingFrontier(contracts) {
@@ -542,7 +558,7 @@ export class ContractManager {
                 pageSize,
             });
             for (const vtxo of vtxos) {
-                // Match the VTXO back to its contract via the script field
+                // Match the virtual output back to its contract via the script field
                 // populated by the indexer.
                 if (!vtxo.script)
                     continue;

package/dist/esm/contracts/contractWatcher.js

@@ -1,5 +1,5 @@
 /**
- * Watches multiple contracts for VTXO changes with resilient connection handling.
+ * Watches multiple contracts for virtual output state changes with resilient connection handling.
  *
  * Features:
  * - Automatic reconnection with exponential backoff
@@ -29,6 +29,12 @@
  * ```
  */
 export class ContractWatcher {
+    /**
+     * Create a contract watcher with the given providers and polling settings.
+     *
+     * @param config - Contract watcher configuration
+     * @see ContractWatcherConfig
+     */
     constructor(config) {
         this.contracts = new Map();
         this.isWatching = false;
@@ -45,9 +51,10 @@ export class ContractWatcher {
     /**
      * Add a contract to be watched.
      *
-     * Active contracts are immediately subscribed. All contracts are polled
-     * to discover any existing VTXOs (which may cause them to be watched
-     * even if inactive).
+     * Active contracts are immediately subscribed.
+     *
+     * All contracts are polled to discover any existing virtual outputs
+     * (which may cause them to be watched even if inactive).
      */
     async addContract(contract) {
         const state = {
@@ -55,11 +62,11 @@ export class ContractWatcher {
             lastKnownVtxos: new Map(),
         };
         this.contracts.set(contract.script, state);
-        // If we're already watching, poll to discover VTXOs and update subscription
+        // If we're already watching, poll to discover virtual outputs and update subscription
         if (this.isWatching) {
-            // Poll first to discover VTXOs (may affect whether we watch this contract)
+            // Poll first to discover virtual outputs (may affect whether we watch this contract).
             await this.pollContracts([contract.script]);
-            // Update subscription based on active state and VTXOs
+            // Update subscription based on active state and virtual outputs.
             await this.tryUpdateSubscription();
         }
     }
@@ -105,10 +112,10 @@ export class ContractWatcher {
      *
      * Returns scripts for:
      * - All active contracts
-     * - All contracts with known VTXOs (regardless of state)
+     * - All contracts with known virtual outputs (regardless of state)
      *
      * This ensures we continue monitoring contracts even after they're
-     * deactivated, as long as they have unspent VTXOs.
+     * deactivated, as long as they have unspent virtual outputs.
      */
     getScriptsToWatch() {
         const scripts = new Set();
@@ -118,7 +125,7 @@ export class ContractWatcher {
                 scripts.add(state.contract.script);
                 continue;
             }
-            // Also watch inactive/expired contracts that have VTXOs
+            // Also watch inactive/expired contracts that have virtual outputs.
             if (state.lastKnownVtxos.size > 0) {
                 scripts.add(state.contract.script);
             }
@@ -126,8 +133,8 @@ export class ContractWatcher {
         return Array.from(scripts);
     }
     /**
-     * Get VTXOs for contracts, grouped by contract script.
-     * Uses Repository.
+     * Get virtual outputs for contracts, grouped by contract script.
+     * @see WalletRepository for `repo`
      */
     async getContractVtxos(options) {
         const { contractScripts, includeSpent } = options;
@@ -160,7 +167,7 @@ export class ContractWatcher {
         return new Map(results.flat(1));
     }
     /**
-     * Start watching for VTXO events across all active contracts.
+     * Start watching for virtual output events across all active contracts.
      */
     async startWatching(callback) {
         if (this.isWatching) {
@@ -339,7 +346,7 @@ export class ContractWatcher {
             return;
         const now = Date.now();
         try {
-            // Load all the VTXOs for these contracts, from DB
+            // Load all the virtual outputs for these contracts, from DB
             const vtxosMap = await this.getContractVtxos({
                 contractScripts,
                 includeSpent: false, // only spendable ones!
@@ -350,7 +357,7 @@ export class ContractWatcher {
                     continue;
                 const currentVtxos = vtxosMap.get(contractScript) || [];
                 const currentKeys = new Set(currentVtxos.map((v) => `${v.txid}:${v.vout}`));
-                // Find new VTXOs and add them to the contract's state
+                // Find new virtual outputs and add them to the contract's state
                 const newVtxos = [];
                 for (const vtxo of currentVtxos) {
                     const key = `${vtxo.txid}:${vtxo.vout}`;
@@ -359,7 +366,7 @@ export class ContractWatcher {
                         state.lastKnownVtxos.set(key, vtxo);
                     }
                 }
-                // Find spent VTXOs and remove them from the contract's state
+                // Find spent virtual outputs and remove them from the contract's state
                 const spentVtxos = [];
                 for (const [key, vtxo] of state.lastKnownVtxos) {
                     if (!currentKeys.has(key)) {
@@ -394,7 +401,7 @@ export class ContractWatcher {
     /**
      * Update the subscription with scripts that should be watched.
      *
-     * Watches both active contracts and contracts with VTXOs.
+     * Watches both active contracts and contracts with virtual outputs.
      */
     async updateSubscription() {
         const scriptsToWatch = this.getScriptsToWatch();
@@ -471,11 +478,11 @@ export class ContractWatcher {
         }
     }
     /**
-     * Process VTXOs from subscription and route to correct contracts.
+     * Process virtual outputs from subscription and route to correct contracts.
      * Uses the scripts from the subscription response to determine contract ownership.
      */
     processSubscriptionVtxos(vtxos, scripts, eventType, timestamp) {
-        // If we have exactly one script, all VTXOs belong to that contract
+        // If we have exactly one script, all virtual outputs belong to that contract
         // Otherwise, we can't reliably determine ownership without script in VirtualCoin
         if (scripts.length === 1) {
             const contractScript = scripts[0];
@@ -497,8 +504,8 @@ export class ContractWatcher {
             }
             return;
         }
-        // Multiple scripts - assign VTXOs to all matching contracts
-        // This is a limitation: we can't know which VTXO belongs to which script
+        // Multiple scripts - assign virtual outputs to all matching contracts
+        // This is a limitation: we can't know which virtual output belongs to which script
         // In practice, subscription events usually come with a single script context
         for (const script of scripts) {
             const contractScript = script;
@@ -520,7 +527,7 @@ export class ContractWatcher {
         }
     }
     /**
-     * Emit a VTXO event for a contract.
+     * Emit a virtual output event for a contract.
      */
     emitVtxoEvent(contractScript, vtxos, eventType, timestamp) {
         if (!this.eventCallback)

package/dist/esm/contracts/handlers/default.js

@@ -2,7 +2,7 @@ import { hex } from "@scure/base";
 import { DefaultVtxo } from '../../script/default.js';
 import { isCsvSpendable, sequenceToTimelock, timelockToSequence, } from './helpers.js';
 /**
- * Handler for default wallet VTXOs.
+ * Handler for default wallet virtual outputs.
  *
  * Default contracts use the standard forfeit + exit tapscript:
  * - forfeit: (Alice + Server) multisig for collaborative spending

package/dist/esm/contracts/handlers/delegate.js

@@ -3,7 +3,7 @@ import { DelegateVtxo } from '../../script/delegate.js';
 import { DefaultVtxo } from '../../script/default.js';
 import { isCsvSpendable, sequenceToTimelock, timelockToSequence, } from './helpers.js';
 /**
- * Handler for delegate wallet VTXOs.
+ * Handler for delegate wallet virtual outputs.
  *
  * Delegate contracts extend the default tapscript with an additional delegate path:
  * - forfeit: (Alice + Server) multisig for collaborative spending

package/dist/esm/contracts/handlers/helpers.js

@@ -63,7 +63,7 @@ export function isCltvSatisfied(context, locktime) {
     return currentTimeSec >= locktime;
 }
 /**
- * Check if a CSV timelock is currently satisfied for the given context/VTXO.
+ * Check if a CSV timelock is currently satisfied for the given context/virtual output.
  */
 export function isCsvSpendable(context, sequence) {
     if (sequence === undefined)

package/dist/esm/extension/asset/assetGroup.js

@@ -7,9 +7,25 @@ import { AssetOutputs } from './assetOutput.js';
 import { MetadataList } from './metadata.js';
 import { BufferReader, BufferWriter } from './utils.js';
 /**
- * An asset group contains inputs/outputs and all data related to a given asset id.
+ * An asset group contains inputs, outputs, and all data related to a given asset id.
+ *
+ * @see Packet
+ * @see AssetId
+ * @see AssetRef
+ *
+ * @example
+ * ```typescript
+ * const group = AssetGroup.create(
+ *   null,                              // asset ID: null for new issuance
+ *   null,                              // control asset ID: null when reissuance not needed
+ *   [],                                // asset inputs: empty for new issuance
+ *   [AssetOutput.create(0, 1000)],     // asset outputs: 1000 units at vout index 0
+ *   []                                 // metadata: can be empty
+ * )
+ * ```
  */
 export class AssetGroup {
+    /** @see create */
     constructor(assetId, controlAsset, inputs, outputs, metadata) {
         this.assetId = assetId;
         this.controlAsset = controlAsset;
@@ -17,12 +33,31 @@ export class AssetGroup {
         this.outputs = outputs;
         this.metadataList = new MetadataList(metadata);
     }
+    /**
+     * Create and validate an asset group.
+     *
+     * @param assetId - Asset id for this group, or `null` for fresh issuance
+     * @param controlAsset - Optional control asset reference for (re) issuance
+     * @param inputs - Asset inputs in the group
+     * @param outputs - Asset outputs in the group
+     * @param metadata - Metadata entries associated with the group
+     * @returns A validated asset group
+     * @throws Error if the group fails validation
+     * @see validate
+     */
     static create(assetId, controlAsset, inputs, outputs, metadata) {
         const ag = new AssetGroup(assetId, controlAsset, inputs, outputs, metadata);
         ag.validate();
         return ag;
     }
-    // from hex encoded
+    /**
+     * Decode an asset group from its hex string form.
+     *
+     * @param s - Hex-encoded asset group
+     * @returns Decoded asset group
+     * @throws Error if the string is not valid hex or does not encode a valid asset group
+     * @see toString
+     */
     static fromString(s) {
         let buf;
         try {
@@ -33,6 +68,13 @@ export class AssetGroup {
         }
         return AssetGroup.fromBytes(buf);
     }
+    /**
+     * Decode an asset group from its serialized bytes.
+     *
+     * @param buf - Serialized asset group bytes
+     * @returns Decoded asset group
+     * @throws Error if the buffer is empty or malformed
+     */
     static fromBytes(buf) {
         if (!buf || buf.length === 0) {
             throw new Error("missing asset group");
@@ -40,12 +82,21 @@ export class AssetGroup {
         const reader = new BufferReader(buf);
         return AssetGroup.fromReader(reader);
     }
-    // an issuance is a group with null assetId
+    /**
+     * Return true when the group represents an issuance.
+     *
+     * @returns `true` when the group has no asset id
+     */
     isIssuance() {
         return this.assetId === null;
     }
-    // a reissuance is a group that is not an issuance
-    // but where the sum of the outputs is greater than the sum of the inputs
+    /**
+     * Return true when the group represents a reissuance.
+     *
+     * @returns `true` when the group has an asset id and outputs exceed local inputs
+     * @remarks
+     * Only local inputs contribute to the comparison; intent-backed inputs contribute `0` here.
+     */
     isReissuance() {
         const sumReducer = (s, { amount }) => s + amount;
         const sumOutputs = this.outputs.reduce(sumReducer, 0n);
@@ -56,12 +107,23 @@ export class AssetGroup {
             .reduce(sumReducer, 0n);
         return !this.isIssuance() && sumInputs < sumOutputs;
     }
+    /**
+     * Serialize the asset group to raw bytes.
+     *
+     * @returns Serialized asset group bytes
+     * @see fromBytes
+     */
     serialize() {
         this.validate();
         const writer = new BufferWriter();
         this.serializeTo(writer);
         return writer.toBytes();
     }
+    /**
+     * Validate the asset group and its child structures.
+     *
+     * @throws Error if the group is empty or violates issuance invariants
+     */
     validate() {
         if (this.inputs.length === 0 && this.outputs.length === 0) {
             throw new Error("empty asset group");
@@ -77,13 +139,33 @@ export class AssetGroup {
             }
         }
     }
+    /**
+     * Convert the group into its batch-leaf representation for the given intent txid.
+     *
+     * @param intentTxid - Intent transaction id used to build the leaf input reference
+     * @returns Batch-leaf asset group
+     * @see AssetInput.createIntent
+     */
     toBatchLeafAssetGroup(intentTxid) {
         const leafInput = AssetInput.createIntent(hex.encode(intentTxid), 0, 0);
         return new AssetGroup(this.assetId, this.controlAsset, [leafInput], this.outputs, this.metadataList.items);
     }
+    /**
+     * Encode the asset group to a hex string.
+     *
+     * @returns Hex-encoded asset group
+     * @see fromString
+     */
     toString() {
         return hex.encode(this.serialize());
     }
+    /**
+     * Decode an asset group from a binary reader.
+     *
+     * @param reader - Reader positioned at an asset group
+     * @returns Decoded asset group
+     * @throws Error if the encoded group is malformed
+     */
     static fromReader(reader) {
         const presence = reader.readByte();
         let assetId = null;
@@ -104,6 +186,11 @@ export class AssetGroup {
         ag.validate();
         return ag;
     }
+    /**
+     * Serialize the asset group into an existing binary writer.
+     *
+     * @param writer - Writer to append the asset group to
+     */
     serializeTo(writer) {
         let presence = 0;
         if (this.assetId !== null) {