@arkade-os/sdk 0.4.15 → 0.4.16

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

@@ -23,6 +23,6 @@ export declare function resolveRole(contract: Contract, context: PathContext): "
  */
 export declare function isCltvSatisfied(context: PathContext, locktime: bigint): boolean;
 /**
- * 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 declare function isCsvSpendable(context: PathContext, sequence?: number): boolean;

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

@@ -7,7 +7,7 @@ import { ContractFilter } from "../repositories";
  */
 export type ContractState = "active" | "inactive";
 /**
- * Represents a contract that can receive and manage VTXOs.
+ * Represents a contract that can receive and manage virtual outputs.
  *
  * A contract is defined by its type and parameters, which together
  * determine the VtxoScript (spending paths). The wallet's default
@@ -29,14 +29,14 @@ export type ContractState = "active" | "inactive";
  *     // ... timelocks
  *   },
  *   script: "5120...",
- *   address: "tark1...",
+ *   address: "ark1q...",
  *   state: "active",
  *   createdAt: 1704067200000,
  * };
  * ```
  */
 export interface Contract {
-    /** Human-readable label for display purposes */
+    /** Human-readable label for display purposes. */
     label?: string;
     /**
      * Contract type identifier.
@@ -50,15 +50,15 @@ export interface Contract {
      * The ContractHandler for this type knows how to interpret these.
      */
     params: Record<string, string>;
-    /** The pkScript hex - unique identifier and primary key for contracts */
+    /** The pkScript hex, used as the unique identifier and primary key for contracts. */
     script: string;
-    /** The address derived from the script */
+    /** Address derived from the contract script. */
     address: string;
-    /** Current state of the contract */
+    /** Current state of the contract. */
     state: ContractState;
-    /** Unix timestamp (ms) when this contract was created */
+    /** Unix timestamp in milliseconds when this contract was created. */
     createdAt: number;
-    /** Unix timestamp (ms) when this contract expires (optional) */
+    /** Unix timestamp in milliseconds when this contract expires. */
     expiresAt?: number;
     /**
      * Optional metadata for external integrations.
@@ -66,50 +66,54 @@ export interface Contract {
     metadata?: Record<string, unknown>;
 }
 /**
- * A VTXO that has been associated with a specific contract.
+ * A virtual output that has been associated with a specific contract.
  */
 export interface ContractVtxo extends ExtendedVirtualCoin {
-    /** The contract script this VTXO belongs to */
+    /** The contract script this virtual output belongs to. */
     contractScript: string;
 }
 /**
- * Result of path selection - which tapleaf to use and extra witness data.
+ * Result of path selection, including the tapleaf to use and any extra witness data.
  */
 export interface PathSelection {
-    /** The tapleaf script to use for spending */
+    /** Tapleaf script to use for spending. */
     leaf: TapLeafScript;
-    /** Additional witness elements (e.g., preimage for HTLC) */
+    /** Additional witness elements, for example a preimage for HTLC-like paths. */
     extraWitness?: Bytes[];
-    /** Sequence number override (for CSV timelocks) */
+    /**
+     * nSequence for the spending input, BIP-68 encoded when the leaf
+     * uses CSV. Decode with `sequenceToTimelock`; do NOT use as an
+     * absolute `Transaction.lockTime`.
+     */
     sequence?: number;
 }
 /**
  * Context for path selection decisions.
  */
 export interface PathContext {
-    /** Is collaborative spending available (server cooperation)? */
+    /** Whether collaborative spending is available through server cooperation. */
     collaborative: boolean;
-    /** Current time in milliseconds */
+    /** Current time in milliseconds. */
     currentTime: number;
-    /** Current block height (optional) */
+    /** Current block height, when known. */
     blockHeight?: number;
     /**
-     * Wallet's public key (x-only, 32 bytes hex).
-     * Used by handlers to determine wallet's role in multi-party contracts.
+     * Wallet public key encoded as 32-byte x-only hex.
+     * Used by handlers to determine the wallet's role in multi-party contracts.
      */
     walletPubKey?: string;
     /**
-     * Explicit role override (for multi-party contracts like VHTLC).
-     * If not provided, handler may derive role from walletPubKey.
+     * Explicit role override for multi-party contracts such as VHTLC.
+     * If not provided, the handler may derive the role from `walletPubKey`.
      */
     role?: string;
-    /** The specific VTXO being evaluated */
+    /** The specific virtual output being evaluated. */
     vtxo?: VirtualCoin;
 }
 /**
  * Handler for a specific contract type.
  *
- * Each contract type (default, vhtlc, etc.) has a handler that knows how to:
+ * Each contract type (`default`, `vhtlc`, etc.) has a handler that knows how to:
  * 1. Create the VtxoScript from parameters
  * 2. Serialize/deserialize parameters for storage
  * 3. Select the appropriate spending path based on context
@@ -134,14 +138,20 @@ export interface PathContext {
  * ```
  */
 export interface ContractHandler<P = Record<string, unknown>, S extends VtxoScript = VtxoScript> {
-    /** The contract type this handler manages */
+    /** Contract type managed by this handler. */
     readonly type: string;
     /**
      * Create the VtxoScript from serialized parameters.
+     *
+     * @param params - Serialized contract parameters
+     * @returns Contract script instance
      */
     createScript(params: Record<string, string>): S;
     /**
      * Serialize typed parameters to string key-value pairs.
+     *
+     * @param params - Typed contract parameters
+     * @returns Serialized key-value representation
      */
     serializeParams(params: P): Record<string, string>;
     /**
@@ -203,7 +213,7 @@ export type ContractEventCallback = (event: ContractEvent) => void;
  */
 export type GetContractsFilter = ContractFilter;
 /**
- * Contract with its VTXOs included.
+ * Contract with its virtual outputs included.
  */
 export type ContractWithVtxos = {
     contract: Contract;
@@ -217,6 +227,6 @@ export interface ContractBalance {
     total: number;
     /** Spendable balance in satoshis */
     spendable: number;
-    /** Number of VTXOs in this contract */
+    /** Number of virtual outputs in this contract */
     vtxoCount: number;
 }