@arkade-os/sdk 0.4.15 → 0.4.17

package/dist/cjs/worker/messageBus.js

@@ -10,6 +10,7 @@ const wallet_1 = require("../wallet/wallet");
 const base_1 = require("@scure/base");
 const errors_1 = require("./errors");
 class MessageBus {
+    /** Create the service-worker message bus with repositories and handler configuration. */
     constructor(walletRepository, contractRepository, { messageHandlers, tickIntervalMs = 10000, messageTimeoutMs = 30000, debug = false, buildServices, }) {
         this.walletRepository = walletRepository;
         this.contractRepository = contractRepository;
@@ -25,6 +26,7 @@ class MessageBus {
         this.debug = debug;
         this.buildServicesFn = buildServices ?? this.buildServices.bind(this);
     }
+    /** Start the message bus and attach service-worker event listeners. */
     async start() {
         if (this.running)
             return;
@@ -45,6 +47,7 @@ class MessageBus {
             }
         });
     }
+    /** Stop the message bus, cancel ticks, and stop all registered handlers. */
     async stop() {
         if (this.debug)
             console.log("MessageBus stopping");

package/dist/esm/arkfee/estimator.js

@@ -1,7 +1,7 @@
 import { IntentOffchainInputEnv, IntentOnchainInputEnv, IntentOutputEnv, } from "./celenv.js";
 import { FeeAmount, } from "./types.js";
 /**
- * Estimator evaluates CEL expressions to calculate fees for Ark intents
+ * Estimator evaluates CEL expressions to calculate fees for Arkade intents
  */
 export class Estimator {
     /**

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,48 @@ 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,
- *   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 +56,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 +68,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 +83,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
+        await this.deltaSyncContracts(contracts, undefined, true);
+        // 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 +155,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 +268,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 +287,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 +334,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 +396,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]);
@@ -404,21 +418,39 @@ export class ContractManager {
         if (contracts.length === 0) {
             return new Map();
         }
-        return await this.fetchContractVxosFromIndexer(contracts, false, pageSize);
+        // Deduplicate concurrent callers against an in-flight fetch so we don't
+        // issue redundant round-trips. Once the fetch settles we clear the
+        // reference so the next call triggers a fresh fetch.
+        // TODO: can be removed once we fix the persistence layer (address vs scripts)
+        if (this.syncVtxosCallInflight) {
+            return this.syncVtxosCallInflight;
+        }
+        this.syncVtxosCallInflight = this.fetchContractVxosFromIndexer(contracts, true, pageSize).finally(() => {
+            this.syncVtxosCallInflight = undefined;
+        });
+        return this.syncVtxosCallInflight;
     }
     /**
-     * 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.
      */
-    async deltaSyncContracts(contracts, pageSize) {
+    async deltaSyncContracts(contracts, pageSize, force) {
         if (contracts.length === 0)
             return new Map();
+        // If forced, we are treating all contracts as boostrapped and we clean the VTXO list
+        if (force === true) {
+            await Promise.all(contracts.map((contract) => this.config.walletRepository.deleteVtxos(contract.address)));
+        }
         const cursors = await getAllSyncCursors(this.config.walletRepository);
         // Partition into bootstrap (no cursor) and delta (has cursor) groups.
         const bootstrap = [];
         const delta = [];
         for (const c of contracts) {
+            if (force) {
+                bootstrap.push(c);
+                continue;
+            }
             if (cursors[c.script] !== undefined) {
                 delta.push(c);
             }
@@ -459,8 +491,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 +574,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)