@arkade-os/sdk 0.4.15 → 0.4.16

package/dist/cjs/contracts/contractManager.js

@@ -10,38 +10,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();
  * ```
  */
 class ContractManager {
@@ -49,7 +61,7 @@ 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_1.ContractWatcher({
             indexerProvider: config.indexerProvider,
             walletRepository: config.walletRepository,
@@ -61,7 +73,7 @@ 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
      */
@@ -76,10 +88,10 @@ 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);
@@ -148,7 +160,7 @@ 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
@@ -261,7 +273,6 @@ class ContractManager {
     /**
      * Get currently spendable paths for a contract.
      *
-     * @param contractScript - The contract script
      * @param options - Options for getting spendable paths
      */
     async getSpendablePaths(options) {
@@ -281,6 +292,11 @@ 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 });
@@ -323,7 +339,7 @@ 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.
@@ -385,7 +401,7 @@ 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]);
@@ -410,7 +426,7 @@ 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.
      */
@@ -462,8 +478,8 @@ 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) {
@@ -545,7 +561,7 @@ 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/cjs/contracts/contractWatcher.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ContractWatcher = void 0;
 /**
- * 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
@@ -32,6 +32,12 @@ exports.ContractWatcher = void 0;
  * ```
  */
 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;
@@ -48,9 +54,10 @@ 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 = {
@@ -58,11 +65,11 @@ 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();
         }
     }
@@ -108,10 +115,10 @@ 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();
@@ -121,7 +128,7 @@ 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);
             }
@@ -129,8 +136,8 @@ 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;
@@ -163,7 +170,7 @@ 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) {
@@ -342,7 +349,7 @@ 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!
@@ -353,7 +360,7 @@ 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}`;
@@ -362,7 +369,7 @@ 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)) {
@@ -397,7 +404,7 @@ 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();
@@ -474,11 +481,11 @@ 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];
@@ -500,8 +507,8 @@ 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;
@@ -523,7 +530,7 @@ 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/cjs/contracts/handlers/default.js

@@ -5,7 +5,7 @@ const base_1 = require("@scure/base");
 const default_1 = require("../../script/default");
 const helpers_1 = require("./helpers");
 /**
- * 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/cjs/contracts/handlers/delegate.js

@@ -6,7 +6,7 @@ const delegate_1 = require("../../script/delegate");
 const default_1 = require("../../script/default");
 const helpers_1 = require("./helpers");
 /**
- * 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/cjs/contracts/handlers/helpers.js

@@ -103,7 +103,7 @@ 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.
  */
 function isCsvSpendable(context, sequence) {
     if (sequence === undefined)

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

@@ -10,9 +10,25 @@ const assetOutput_1 = require("./assetOutput");
 const metadata_1 = require("./metadata");
 const utils_1 = require("./utils");
 /**
- * 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
+ * )
+ * ```
  */
 class AssetGroup {
+    /** @see create */
     constructor(assetId, controlAsset, inputs, outputs, metadata) {
         this.assetId = assetId;
         this.controlAsset = controlAsset;
@@ -20,12 +36,31 @@ class AssetGroup {
         this.outputs = outputs;
         this.metadataList = new metadata_1.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 {
@@ -36,6 +71,13 @@ 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");
@@ -43,12 +85,21 @@ class AssetGroup {
         const reader = new utils_1.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);
@@ -59,12 +110,23 @@ 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 utils_1.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");
@@ -80,13 +142,33 @@ 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_1.AssetInput.createIntent(base_1.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 base_1.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;
@@ -107,6 +189,11 @@ 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) {

package/dist/cjs/extension/asset/assetId.js

@@ -5,15 +5,34 @@ const base_1 = require("@scure/base");
 const types_1 = require("./types");
 const utils_1 = require("./utils");
 /**
- * AssetId represents the id of an asset.
- * @param txid - the genesis transaction id (decoded from hex)
- * @param groupIndex - the asset group index in the genesis transaction
+ * AssetId identifies a specific asset.
+ *
+ * @remarks
+ * Asset ids are derived from the genesis transaction id plus the asset group index.
+ *
+ * @see AssetRef
+ *
+ * @example
+ * ```typescript
+ * const assetId = AssetId.create('00'.repeat(32), 0)
+ * const encoded = assetId.toString()
+ * const decoded = AssetId.fromString(encoded)
+ * ```
  */
 class AssetId {
     constructor(txid, groupIndex) {
         this.txid = txid;
         this.groupIndex = groupIndex;
     }
+    /**
+     * Create an asset id from a genesis transaction id and group index.
+     *
+     * @param txid - Hex-encoded genesis transaction id
+     * @param groupIndex - Asset group index within the genesis transaction
+     * @returns A validated asset id
+     * @throws Error if the txid is missing, malformed, or not 32 bytes long
+     * @see fromString
+     */
     static create(txid, groupIndex) {
         if (!txid) {
             throw new Error("missing txid");
@@ -32,6 +51,14 @@ class AssetId {
         assetId.validate();
         return assetId;
     }
+    /**
+     * Decode an asset id from its hex string representation.
+     *
+     * @param s - Hex-encoded asset id
+     * @returns Decoded asset id
+     * @throws Error if the string is not valid hex or does not encode a valid asset id
+     * @see toString
+     */
     static fromString(s) {
         let buf;
         try {
@@ -42,6 +69,13 @@ class AssetId {
         }
         return AssetId.fromBytes(buf);
     }
+    /**
+     * Decode an asset id from its serialized bytes.
+     *
+     * @param buf - Serialized asset id bytes
+     * @returns Decoded asset id
+     * @throws Error if the buffer length is invalid
+     */
     static fromBytes(buf) {
         if (!buf || buf.length === 0) {
             throw new Error("missing asset id");
@@ -52,14 +86,31 @@ class AssetId {
         const reader = new utils_1.BufferReader(buf);
         return AssetId.fromReader(reader);
     }
+    /**
+     * Serialize the asset id to raw bytes.
+     *
+     * @returns Serialized asset id bytes
+     * @see fromBytes
+     */
     serialize() {
         const writer = new utils_1.BufferWriter();
         this.serializeTo(writer);
         return writer.toBytes();
     }
+    /**
+     * Encode the asset id to a hex string.
+     *
+     * @returns Hex-encoded asset id
+     * @see fromString
+     */
     toString() {
         return base_1.hex.encode(this.serialize());
     }
+    /**
+     * Validate the asset id fields.
+     *
+     * @throws Error if the txid is empty or the group index is out of range
+     */
     validate() {
         if ((0, utils_1.isZeroBytes)(this.txid)) {
             throw new Error("empty txid");
@@ -70,6 +121,13 @@ class AssetId {
             throw new Error(`invalid group index: ${this.groupIndex}, must be in range [0, 65535]`);
         }
     }
+    /**
+     * Decode an asset id from a binary reader.
+     *
+     * @param reader - Reader positioned at an asset id
+     * @returns Decoded asset id
+     * @throws Error if the reader does not contain enough bytes
+     */
     static fromReader(reader) {
         if (reader.remaining() < types_1.ASSET_ID_SIZE) {
             throw new Error(`invalid asset id length: got ${reader.remaining()}, want ${types_1.ASSET_ID_SIZE}`);
@@ -80,6 +138,12 @@ class AssetId {
         assetId.validate();
         return assetId;
     }
+    /**
+     * Serialize the asset id into an existing binary writer.
+     *
+     * @param writer - Writer to append the asset id to
+     * @see serialize
+     */
     serializeTo(writer) {
         writer.write(this.txid);
         writer.writeUint16LE(this.groupIndex);