@arkade-os/sdk 0.4.14 → 0.4.16

package/dist/cjs/arkfee/estimator.js

@@ -4,7 +4,7 @@ exports.Estimator = void 0;
 const celenv_js_1 = require("./celenv.js");
 const types_js_1 = require("./types.js");
 /**
- * Estimator evaluates CEL expressions to calculate fees for Ark intents
+ * Estimator evaluates CEL expressions to calculate fees for Arkade intents
  */
 class Estimator {
     /**

package/dist/cjs/arkfee/types.js

@@ -4,7 +4,6 @@ exports.FeeAmount = void 0;
 /**
  * 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
@@ -14,9 +13,11 @@ 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/cjs/arknote/index.js

@@ -6,10 +6,12 @@ const utils_js_1 = require("@scure/btc-signer/utils.js");
 const btc_signer_1 = require("@scure/btc-signer");
 const base_2 = require("../script/base");
 /**
- * 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
@@ -24,6 +26,13 @@ const base_2 = require("../script/base");
  * ```
  */
 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;
@@ -40,12 +49,27 @@ 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}`);
@@ -54,6 +78,15 @@ 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)) {
@@ -66,6 +99,12 @@ 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 + base_1.base58.encode(this.encode());
     }

package/dist/cjs/bip322/index.js

@@ -17,7 +17,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/cjs/contracts/arkcontract.js

@@ -17,7 +17,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/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

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.timelockToSequence = timelockToSequence;
 exports.sequenceToTimelock = sequenceToTimelock;
 exports.resolveRole = resolveRole;
+exports.isCltvSatisfied = isCltvSatisfied;
 exports.isCsvSpendable = isCsvSpendable;
 const bip68 = __importStar(require("bip68"));
 /**
@@ -79,7 +80,30 @@ function resolveRole(contract, context) {
     return undefined;
 }
 /**
- * Check if a CSV timelock is currently satisfied for the given context/VTXO.
+ * BIP65 threshold: locktime values below this are interpreted as block heights,
+ * values at or above are interpreted as Unix timestamps (seconds).
+ */
+const CLTV_HEIGHT_THRESHOLD = 500000000n;
+/**
+ * Check if an absolute (CLTV) locktime is currently satisfied.
+ *
+ * Following the BIP65 convention:
+ * - locktime < 500_000_000  → interpreted as a block height; compared against `context.blockHeight`
+ * - locktime >= 500_000_000 → interpreted as a Unix timestamp (seconds); compared against `context.currentTime`
+ *
+ * Returns false if the relevant context field is missing.
+ */
+function isCltvSatisfied(context, locktime) {
+    if (locktime < CLTV_HEIGHT_THRESHOLD) {
+        if (context.blockHeight === undefined)
+            return false;
+        return BigInt(context.blockHeight) >= locktime;
+    }
+    const currentTimeSec = BigInt(Math.floor(context.currentTime / 1000));
+    return currentTimeSec >= locktime;
+}
+/**
+ * Check if a CSV timelock is currently satisfied for the given context/virtual output.
  */
 function isCsvSpendable(context, sequence) {
     if (sequence === undefined)

package/dist/cjs/contracts/handlers/vhtlc.js

@@ -59,7 +59,6 @@ exports.VHTLCContractHandler = {
         const role = (0, helpers_1.resolveRole)(contract, context);
         const preimage = contract.params?.preimage;
         const refundLocktime = BigInt(contract.params.refundLocktime);
-        const currentTimeSec = Math.floor(context.currentTime / 1000);
         if (!role) {
             return null;
         }
@@ -70,7 +69,7 @@ exports.VHTLCContractHandler = {
                     extraWitness: [base_1.hex.decode(preimage)],
                 };
             }
-            if (role === "sender" && BigInt(currentTimeSec) >= refundLocktime) {
+            if (role === "sender" && (0, helpers_1.isCltvSatisfied)(context, refundLocktime)) {
                 return {
                     leaf: script.refundWithoutReceiver(),
                 };
@@ -154,7 +153,6 @@ exports.VHTLCContractHandler = {
         }
         const preimage = contract.params?.preimage;
         const refundLocktime = BigInt(contract.params.refundLocktime);
-        const currentTimeSec = Math.floor(context.currentTime / 1000);
         if (context.collaborative) {
             if (role === "receiver" && preimage) {
                 paths.push({
@@ -162,7 +160,7 @@ exports.VHTLCContractHandler = {
                     extraWitness: [base_1.hex.decode(preimage)],
                 });
             }
-            if (role === "sender" && BigInt(currentTimeSec) >= refundLocktime) {
+            if (role === "sender" && (0, helpers_1.isCltvSatisfied)(context, refundLocktime)) {
                 paths.push({
                     leaf: script.refundWithoutReceiver(),
                 });