@arkade-os/sdk 0.4.14 → 0.4.16

package/dist/esm/worker/expo/asyncStorageTaskQueue.js

@@ -49,7 +49,7 @@ export class AsyncStorageTaskQueue {
     // ── Config persistence (for background handler rehydration) ──────
     /**
      * Persist a config blob alongside the queue data.
-     * Used by {@link ExpoWallet.setup} to store the wallet parameters
+     * Used by @see ExpoWallet.setup to store the wallet parameters
      * that the background handler needs to reconstruct providers.
      */
     async persistConfig(config) {

package/dist/esm/worker/expo/processors/contractPollProcessor.js

@@ -3,7 +3,7 @@ export const CONTRACT_POLL_TASK_TYPE = "contract-poll";
  * Polls the indexer for the latest VTXO state of every contract and
  * persists the results to the wallet repository.
  *
- * Replicates the polling subset of {@link ContractManager.initialize}:
+ * Replicates the polling subset of @see ContractManager.initialize:
  * 1. Load all contracts from the contract repository.
  * 2. Mark expired active contracts as inactive.
  * 3. Paginated fetch of spendable VTXOs from the indexer.
@@ -26,7 +26,7 @@ export const contractPollProcessor = {
                 contract.state = "inactive";
                 await contractRepository.saveContract(contract);
             }
-            // Paginated fetch of spendable VTXOs
+            // Paginated fetch of spendable virtual outputs
             const pageSize = 100;
             let pageIndex = 0;
             let hasMore = true;

package/dist/esm/worker/expo/taskRunner.js

@@ -4,7 +4,7 @@ import { getRandomId, extendVirtualCoin, extendVtxoFromContract, } from '../../w
  *
  * For each task in the inbox:
  * 1. Find the processor whose `taskType` matches `task.type`.
- * 2. Execute it, producing a {@link TaskResult}.
+ * 2. Execute it, producing a @see TaskResult.
  * 3. Push the result to the outbox and remove the task from the inbox.
  *
  * Tasks with no matching processor produce a `"noop"` result.
@@ -53,8 +53,8 @@ export async function runTasks(queue, processors, deps) {
     return results;
 }
 /**
- * Build the {@link TaskDependencies} needed by task processors
- * (e.g. {@link import("./processors").contractPollProcessor}).
+ * Build the @see TaskDependencies needed by task processors
+ * (e.g. `src/worker/expo/processors/contractPollProcessor.ts`)
  *
  * This is the same construction that `defineExpoBackgroundTask` does
  * internally, extracted so that consumers with custom schedulers

package/dist/esm/worker/messageBus.js

@@ -7,6 +7,7 @@ import { ReadonlyWallet, Wallet } from '../wallet/wallet.js';
 import { hex } from "@scure/base";
 import { MessageBusNotInitializedError, ServiceWorkerTimeoutError, } from './errors.js';
 export 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;
@@ -22,6 +23,7 @@ export 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;
@@ -42,6 +44,7 @@ export class MessageBus {
             }
         });
     }
+    /** Stop the message bus, cancel ticks, and stop all registered handlers. */
     async stop() {
         if (this.debug)
             console.log("MessageBus stopping");

package/dist/types/arkfee/estimator.d.ts

@@ -1,6 +1,6 @@
 import { IntentFeeConfig, OffchainInput, OnchainInput, FeeOutput, 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 declare class Estimator {
     readonly config: IntentFeeConfig;

package/dist/types/arkfee/types.d.ts

@@ -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,7 +10,9 @@ export declare class FeeAmount {
     readonly value: number;
     static ZERO: FeeAmount;
     constructor(value: number);
+    /** Returns the fee amount rounded up to whole satoshis. */
     get satoshis(): number;
+    /** Add two fee amounts together. */
     add(other: FeeAmount): FeeAmount;
 }
 export interface IntentFeeConfig {

package/dist/types/arknote/index.d.ts

@@ -2,10 +2,12 @@ import { Bytes } from "@scure/btc-signer/utils.js";
 import { TapLeafScript, VtxoScript } from "../script/base";
 import { ExtendedCoin, Status } from "../wallet";
 /**
- * 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
@@ -29,6 +31,7 @@ export declare class ArkNote implements ExtendedCoin {
     static readonly Length: number;
     static readonly FakeOutpointIndex = 0;
     readonly vtxoScript: VtxoScript;
+    /** Hashlock script backing the note. */
     readonly txid: string;
     readonly vout = 0;
     readonly forfeitTapLeafScript: TapLeafScript;
@@ -36,9 +39,46 @@ export declare class ArkNote implements ExtendedCoin {
     readonly tapTree: Bytes;
     readonly status: Status;
     readonly extraWitness?: Bytes[] | undefined;
+    /**
+     * 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: Uint8Array, value: number, HRP?: string);
+    /**
+     * Encode the note as raw bytes.
+     *
+     * @returns Serialized note bytes
+     * @see decode
+     */
     encode(): Uint8Array;
+    /**
+     * 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: Uint8Array, hrp?: string): ArkNote;
+    /**
+     * 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: string, hrp?: string): ArkNote;
+    /**
+     * Encode the note to its human-readable base58 string form.
+     *
+     * @returns Base58-encoded note string
+     * @see fromString
+     */
     toString(): string;
 }

package/dist/types/bip322/index.d.ts

@@ -8,7 +8,7 @@ import type { Identity } from "../identity";
  *
  * 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/types/contracts/arkcontract.d.ts

@@ -5,7 +5,7 @@ import { Contract } from "./types";
  * 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/types/contracts/contractManager.d.ts

@@ -4,45 +4,6 @@ import { Contract, ContractEventCallback, ContractState, ContractWithVtxos, GetC
 import { ContractWatcherConfig } from "./contractWatcher";
 import { VirtualCoin } from "../wallet";
 import { ContractRepository } from "../repositories";
-/**
- * Contract lifecycle and VTXO orchestration API.
- *
- * Responsibilities:
- * - Create and persist contracts
- * - Query stored contracts (optionally with their VTXOs)
- * - Provide spendable path selection for a contract
- * - Emit contract-related events (VTXO received/spent, expiry, connection reset)
- *
- * Notes:
- * - Implementations typically start watching automatically during initialization
- *   (so `onContractEvent()` is just for subscribing).
- *
- * @example
- * ```typescript
- * const manager = await ContractManager.create({
- *   indexerProvider,
- *   contractRepository,
- *   walletRepository,
- *   getDefaultAddress,
- * });
- *
- * const unsubscribe = manager.onContractEvent((event) => {
- *   console.log(event.type, event.timestamp);
- * });
- *
- * const contract = await manager.createContract({
- *   label: "Lightning Receive",
- *   type: "vhtlc",
- *   params: { sender: "ab12...", receiver: "cd34..." },
- *   script: "5120...",
- *   address: "tark1...",
- * });
- *
- * // Later:
- * unsubscribe();
- * manager.dispose();
- * ```
- */
 export type RefreshVtxosOptions = {
     scripts?: string[];
     after?: number;
@@ -70,9 +31,9 @@ export interface IContractManager extends Disposable {
      */
     getContracts(filter?: GetContractsFilter): Promise<Contract[]>;
     /**
-     * List contracts and include their current VTXOs.
+     * List contracts and their current virtual outputs.
      *
-     * If no filter is provided, returns all contracts with their VTXOs.
+     * If no filter is provided, returns all contracts with their virtual outputs.
      */
     getContractsWithVtxos(filter?: GetContractsFilter): Promise<ContractWithVtxos[]>;
     /**
@@ -108,7 +69,7 @@ export interface IContractManager extends Disposable {
      */
     onContractEvent(callback: ContractEventCallback): () => void;
     /**
-     * Force a VTXO refresh from the indexer.
+     * Force a virtual output refresh from the indexer.
      *
      * Without options, refreshes all contracts from scratch.
      * With options, narrows the refresh to specific scripts and/or a time window.
@@ -129,7 +90,7 @@ export interface IContractManager extends Disposable {
 export type GetSpendablePathsOptions = {
     /** The contract script */
     contractScript: string;
-    /** The specific VTXO being evaluated */
+    /** The specific virtual output being evaluated */
     vtxo: VirtualCoin;
     /** Whether collaborative spending is available (default: true) */
     collaborative?: boolean;
@@ -155,9 +116,9 @@ export interface ContractManagerConfig {
     indexerProvider: IndexerProvider;
     /** The contract repository for persistence */
     contractRepository: ContractRepository;
-    /** The wallet repository for VTXO storage (single source of truth) */
+    /** The wallet repository for virtual output storage (single source of truth) */
     walletRepository: WalletRepository;
-    /** Function to get the wallet's default Ark address */
+    /** Function to get the wallet's default Arkade address */
     getDefaultAddress: () => Promise<string>;
     /** Watcher configuration */
     watcherConfig?: Partial<ContractWatcherConfig>;
@@ -172,38 +133,50 @@ export type CreateContractParams = Omit<Contract, "createdAt" | "state"> & {
 /**
  * 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 declare class ContractManager implements IContractManager {
@@ -218,7 +191,7 @@ export declare class ContractManager implements IContractManager {
      * 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
      */
@@ -279,10 +252,14 @@ export declare class ContractManager implements IContractManager {
     /**
      * Get currently spendable paths for a contract.
      *
-     * @param contractScript - The contract script
      * @param options - Options for getting spendable paths
      */
     getSpendablePaths(options: GetSpendablePathsOptions): Promise<PathSelection[]>;
+    /**
+     * Get every currently valid spending path for a contract.
+     *
+     * @param options - Options for getting spending paths
+     */
     getAllSpendingPaths(options: GetAllSpendingPathsOptions): Promise<PathSelection[]>;
     /**
      * Register a callback for contract events.
@@ -305,7 +282,7 @@ export declare class ContractManager implements IContractManager {
      */
     onContractEvent(callback: ContractEventCallback): () => void;
     /**
-     * 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.
@@ -325,14 +302,14 @@ export declare class ContractManager implements IContractManager {
     private handleContractEvent;
     private getVtxosForContracts;
     /**
-     * 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.
      */
     private deltaSyncContracts;
     /**
-     * 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).
      */
     private reconcilePendingFrontier;

package/dist/types/contracts/contractWatcher.d.ts

@@ -3,33 +3,47 @@ import { WalletRepository } from "../repositories/walletRepository";
 import { Contract, ContractEventCallback } from "./types";
 /**
  * Configuration for the ContractWatcher.
+ *
+ * @see ContractWatcher
+ *
+ * @example
+ * ```typescript
+ * const watcher = new ContractWatcher({
+ *   indexerProvider,
+ *   walletRepository,
+ * })
+ * ```
  */
 export interface ContractWatcherConfig {
-    /** The indexer provider to use for subscriptions and queries */
+    /** Indexer provider used for subscriptions and queries. */
     indexerProvider: IndexerProvider;
-    /** The wallet repository for VTXO persistence (optional) */
+    /** Wallet repository used to store virtual output state between watcher updates. */
     walletRepository: WalletRepository;
     /**
      * Interval for failsafe polling (ms).
      * Polls even when subscription is active to catch missed events.
-     * Default: 60000 (1 minute)
+     *
+     * @defaultValue `60_000` (1 minute)
      */
     failsafePollIntervalMs?: number;
     /**
      * Initial reconnection delay (ms).
      * Uses exponential backoff on repeated failures.
-     * Default: 1000 (1 second)
+     *
+     * @defaultValue `1_000` (1 second)
      */
     reconnectDelayMs?: number;
     /**
      * Maximum reconnection delay (ms).
-     * Default: 30000 (30 seconds)
+     *
+     * @defaultValue `30_000` (30 seconds)
      */
     maxReconnectDelayMs?: number;
     /**
      * Maximum reconnection attempts before giving up.
      * Set to 0 for unlimited attempts.
-     * Default: 0 (unlimited)
+     *
+     * @defaultValue `0` (unlimited)
      */
     maxReconnectAttempts?: number;
 }
@@ -38,7 +52,7 @@ export interface ContractWatcherConfig {
  */
 type ConnectionState = "disconnected" | "connecting" | "connected" | "reconnecting";
 /**
- * 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
@@ -78,13 +92,20 @@ export declare class ContractWatcher {
     private reconnectAttempts;
     private reconnectTimeoutId?;
     private failsafePollIntervalId?;
+    /**
+     * Create a contract watcher with the given providers and polling settings.
+     *
+     * @param config - Contract watcher configuration
+     * @see ContractWatcherConfig
+     */
     constructor(config: ContractWatcherConfig);
     /**
      * 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).
      */
     addContract(contract: Contract): Promise<void>;
     /**
@@ -108,19 +129,19 @@ export declare 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.
      */
     private getScriptsToWatch;
     /**
-     * Get VTXOs for contracts, grouped by contract script.
-     * Uses Repository.
+     * Get virtual outputs for contracts, grouped by contract script.
+     * @see WalletRepository for `repo`
      */
     private getContractVtxos;
     /**
-     * Start watching for VTXO events across all active contracts.
+     * Start watching for virtual output events across all active contracts.
      */
     startWatching(callback: ContractEventCallback): Promise<() => void>;
     /**
@@ -168,7 +189,7 @@ export declare 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.
      */
     private updateSubscription;
     /**
@@ -180,12 +201,12 @@ export declare class ContractWatcher {
      */
     private handleSubscriptionUpdate;
     /**
-     * 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.
      */
     private processSubscriptionVtxos;
     /**
-     * Emit a VTXO event for a contract.
+     * Emit a virtual output event for a contract.
      */
     private emitVtxoEvent;
 }

package/dist/types/contracts/handlers/default.d.ts

@@ -10,7 +10,7 @@ export interface DefaultContractParams {
     csvTimelock: RelativeTimelock;
 }
 /**
- * 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/types/contracts/handlers/delegate.d.ts

@@ -11,7 +11,7 @@ export interface DelegateContractParams {
     csvTimelock: RelativeTimelock;
 }
 /**
- * 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/types/contracts/handlers/helpers.d.ts

@@ -13,6 +13,16 @@ export declare function sequenceToTimelock(sequence: number): RelativeTimelock;
  */
 export declare function resolveRole(contract: Contract, context: PathContext): "sender" | "receiver" | undefined;
 /**
- * Check if a CSV timelock is currently satisfied for the given context/VTXO.
+ * 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.
+ */
+export declare function isCltvSatisfied(context: PathContext, locktime: bigint): boolean;
+/**
+ * Check if a CSV timelock is currently satisfied for the given context/virtual output.
  */
 export declare function isCsvSpendable(context: PathContext, sequence?: number): boolean;