@arkade-os/sdk 0.4.27 → 0.4.28

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

@@ -1,217 +0,0 @@
-import { IndexerProvider } from "../providers/indexer.js";
-import { WalletRepository } from "../repositories/walletRepository.js";
-import { Contract, ContractEventCallback } from "./types.js";
-/**
- * Configuration for the ContractWatcher.
- *
- * @see ContractWatcher
- *
- * @example
- * ```typescript
- * const watcher = new ContractWatcher({
- *   indexerProvider,
- *   walletRepository,
- * })
- * ```
- */
-export interface ContractWatcherConfig {
-    /** Indexer provider used for subscriptions and queries. */
-    indexerProvider: IndexerProvider;
-    /** 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.
-     *
-     * @defaultValue `60_000` (1 minute)
-     */
-    failsafePollIntervalMs?: number;
-    /**
-     * Initial reconnection delay (ms).
-     * Uses exponential backoff on repeated failures.
-     *
-     * @defaultValue `1_000` (1 second)
-     */
-    reconnectDelayMs?: number;
-    /**
-     * Maximum reconnection delay (ms).
-     *
-     * @defaultValue `30_000` (30 seconds)
-     */
-    maxReconnectDelayMs?: number;
-    /**
-     * Maximum reconnection attempts before giving up.
-     * Set to 0 for unlimited attempts.
-     *
-     * @defaultValue `0` (unlimited)
-     */
-    maxReconnectAttempts?: number;
-}
-/**
- * Connection state for the watcher.
- */
-type ConnectionState = "disconnected" | "connecting" | "connected" | "reconnecting";
-/**
- * Watches multiple contracts for virtual output state changes with resilient connection handling.
- *
- * Features:
- * - Automatic reconnection with exponential backoff
- * - Failsafe polling to catch missed events
- * - Polls immediately after (re)connection to sync state
- * - Graceful handling of subscription failures
- *
- * @example
- * ```typescript
- * const watcher = new ContractWatcher({
- *   indexerProvider: wallet.indexerProvider,
- * });
- *
- * // Add the wallet's default contract
- * await watcher.addContract(defaultContract);
- *
- * // Add additional contracts (swaps, etc.)
- * await watcher.addContract(swapContract);
- *
- * // Start watching for events
- * const stop = await watcher.startWatching((event) => {
- *   console.log(`${event.type} on contract ${event.contractScript}`);
- * });
- *
- * // Later: stop watching
- * stop();
- * ```
- */
-export declare class ContractWatcher {
-    private config;
-    private contracts;
-    private subscriptionId?;
-    private abortController?;
-    private isWatching;
-    private eventCallback?;
-    private connectionState;
-    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 virtual outputs
-     * (which may cause them to be watched even if inactive).
-     */
-    addContract(contract: Contract): Promise<void>;
-    /**
-     * Pre-populate `lastKnownVtxos` from the wallet repository.
-     *
-     * Runs on add (and can be re-run after reconnect) so polling always
-     * compares the indexer's view against what is already persisted,
-     * emitting only genuine deltas.
-     */
-    private seedLastKnownVtxos;
-    /**
-     * Update an existing contract.
-     */
-    updateContract(contract: Contract): Promise<void>;
-    /**
-     * Remove a contract from watching.
-     */
-    removeContract(contractScript: string): Promise<void>;
-    /**
-     * Get all in-memory contracts.
-     */
-    getAllContracts(): Contract[];
-    /**
-     * Contracts the watcher is actually tracking:
-     * - all active contracts, plus
-     * - inactive contracts that still hold known virtual outputs
-     *   (the subscription keeps watching them so `vtxo_spent` events for
-     *   those unspent outputs are still observed).
-     *
-     * This is the single source of truth for "contracts whose VTXO state
-     * we still care about" — callers and the subscription itself fan out
-     * over the same set so nothing is reconciled that isn't also watched.
-     */
-    getWatchedContracts(): Contract[];
-    /**
-     * Get virtual outputs for contracts, grouped by contract script.
-     * @see WalletRepository for `repo`
-     */
-    private getContractVtxos;
-    /**
-     * Start watching for virtual output events across all active contracts.
-     */
-    startWatching(callback: ContractEventCallback): Promise<() => void>;
-    /**
-     * Stop watching for events.
-     */
-    stopWatching(): Promise<void>;
-    /**
-     * Check if currently watching.
-     */
-    isCurrentlyWatching(): boolean;
-    /**
-     * Get current connection state.
-     */
-    getConnectionState(): ConnectionState;
-    /**
-     * Force a poll of all active contracts.
-     * Useful for manual refresh or after app resume.
-     */
-    forcePoll(): Promise<void>;
-    /**
-     * Connect to the subscription.
-     *
-     * @param skipUpdate - Skip the leading `updateSubscription` call when
-     *   the caller has already established `subscriptionId`.
-     */
-    private connect;
-    /**
-     * Schedule a reconnection attempt.
-     */
-    private scheduleReconnect;
-    /**
-     * Start the failsafe polling interval.
-     */
-    private startFailsafePolling;
-    private pollAllContracts;
-    /**
-     * Poll specific contracts and emit events for changes.
-     */
-    private pollContracts;
-    private tryUpdateSubscription;
-    /**
-     * Update the subscription with scripts that should be watched.
-     *
-     * Watches both active contracts and contracts with virtual outputs.
-     */
-    private updateSubscription;
-    /**
-     * Main listening loop for subscription events.
-     */
-    private listenLoop;
-    /**
-     * Handle a subscription update.
-     */
-    private handleSubscriptionUpdate;
-    /**
-     * Process virtual outputs from subscription and route each VTXO to the
-     * single contract that actually locks it via `vtxo.script`. If the script
-     * doesn't match any watched contract, skip the VTXO rather than fan it
-     * out to every matching contract — fan-out produced phantom state in
-     * non-owning contracts that then never reconciled.
-     */
-    private processSubscriptionVtxos;
-    /**
-     * Emit a virtual output event for a contract.
-     */
-    private emitVtxoEvent;
-}
-export {};

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

@@ -1,19 +0,0 @@
-import { DefaultVtxo } from "../../script/default.js";
-import { RelativeTimelock } from "../../script/tapscript.js";
-import { ContractHandler } from "../types.js";
-/**
- * Typed parameters for DefaultVtxo contracts.
- */
-export interface DefaultContractParams {
-    pubKey: Uint8Array;
-    serverPubKey: Uint8Array;
-    csvTimelock: RelativeTimelock;
-}
-/**
- * Handler for default wallet VTXOs.
- *
- * Default contracts use the standard forfeit + exit tapscript:
- * - forfeit: (Alice + Server) multisig for collaborative spending
- * - exit: (Alice) + CSV timelock for unilateral exit
- */
-export declare const DefaultContractHandler: ContractHandler<DefaultContractParams, DefaultVtxo.Script>;

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

@@ -1,21 +0,0 @@
-import { DelegateVtxo } from "../../script/delegate.js";
-import { RelativeTimelock } from "../../script/tapscript.js";
-import { ContractHandler } from "../types.js";
-/**
- * Typed parameters for DelegateVtxo contracts.
- */
-export interface DelegateContractParams {
-    pubKey: Uint8Array;
-    serverPubKey: Uint8Array;
-    delegatePubKey: Uint8Array;
-    csvTimelock: RelativeTimelock;
-}
-/**
- * Handler for delegate wallet virtual outputs.
- *
- * Delegate contracts extend the default tapscript with an additional delegate path:
- * - forfeit: (Alice + Server) multisig for collaborative spending
- * - exit: (Alice) + CSV timelock for unilateral exit
- * - delegate: (Alice + Delegate + Server) multisig for delegated renewal
- */
-export declare const DelegateContractHandler: ContractHandler<DelegateContractParams, DelegateVtxo.Script>;

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

@@ -1,19 +0,0 @@
-import { Contract, PathContext } from "../types.js";
-/**
- * Resolve wallet's role from explicit role or by matching descriptor/pubkey.
- */
-export declare function resolveRole(contract: Contract, context: PathContext): "sender" | "receiver" | undefined;
-/**
- * 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;

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

@@ -1,7 +0,0 @@
-export { contractHandlers } from "./registry.js";
-export { DefaultContractHandler } from "./default.js";
-export type { DefaultContractParams } from "./default.js";
-export { DelegateContractHandler } from "./delegate.js";
-export type { DelegateContractParams } from "./delegate.js";
-export { VHTLCContractHandler } from "./vhtlc.js";
-export type { VHTLCContractParams } from "./vhtlc.js";

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

@@ -1,65 +0,0 @@
-import { ContractHandler } from "../types.js";
-/**
- * Registry for contract handlers.
- *
- * Each contract type ("default", "vhtlc", etc.) has a handler that knows
- * how to create VtxoScripts, serialize params, and select spending paths.
- *
- * @example
- * ```typescript
- * // Register a custom handler
- * contractHandlers.register(myCustomHandler);
- *
- * // Get handler for a type
- * const handler = contractHandlers.get("vhtlc");
- * const script = handler.createScript(contract.params);
- * ```
- */
-declare class ContractHandlerRegistry {
-    private handlers;
-    /**
-     * Register a contract handler.
-     *
-     * @param handler - The handler to register
-     * @throws If a handler for this type is already registered
-     */
-    register(handler: ContractHandler<unknown>): void;
-    /**
-     * Get a handler by type.
-     *
-     * @param type - The contract type
-     * @returns The handler, or undefined if not found
-     */
-    get(type: string): ContractHandler<unknown> | undefined;
-    /**
-     * Get a handler by type, throwing if not found.
-     *
-     * @param type - The contract type
-     * @returns The handler
-     * @throws If no handler is registered for this type
-     */
-    getOrThrow(type: string): ContractHandler<unknown>;
-    /**
-     * Check if a handler is registered.
-     *
-     * @param type - The contract type
-     */
-    has(type: string): boolean;
-    /**
-     * Get all registered types.
-     */
-    getRegisteredTypes(): string[];
-    /**
-     * Unregister a handler (mainly for testing).
-     */
-    unregister(type: string): boolean;
-    /**
-     * Clear all handlers (mainly for testing).
-     */
-    clear(): void;
-}
-/**
- * Global registry of contract handlers.
- */
-export declare const contractHandlers: ContractHandlerRegistry;
-export {};

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

@@ -1,32 +0,0 @@
-import { VHTLC } from "../../script/vhtlc.js";
-import { RelativeTimelock } from "../../script/tapscript.js";
-import { ContractHandler } from "../types.js";
-/**
- * Typed parameters for VHTLC contracts.
- */
-export interface VHTLCContractParams {
-    sender: Uint8Array;
-    receiver: Uint8Array;
-    server: Uint8Array;
-    preimageHash: Uint8Array;
-    refundLocktime: bigint;
-    unilateralClaimDelay: RelativeTimelock;
-    unilateralRefundDelay: RelativeTimelock;
-    unilateralRefundWithoutReceiverDelay: RelativeTimelock;
-}
-/**
- * Handler for Virtual Hash Time Lock Contract (VHTLC).
- *
- * VHTLC supports multiple spending paths:
- *
- * Collaborative paths (with server):
- * - claim: Receiver + Server with preimage
- * - refund: Sender + Receiver + Server
- * - refundWithoutReceiver: Sender + Server after CLTV locktime
- *
- * Unilateral paths (without server):
- * - unilateralClaim: Receiver with preimage after CSV delay
- * - unilateralRefund: Sender + Receiver after CSV delay
- * - unilateralRefundWithoutReceiver: Sender after CSV delay
- */
-export declare const VHTLCContractHandler: ContractHandler<VHTLCContractParams, VHTLC.Script>;

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

@@ -1,14 +0,0 @@
-export * from "./types.js";
-export { contractHandlers } from "./handlers/index.js";
-export { DefaultContractHandler } from "./handlers/index.js";
-export type { DefaultContractParams } from "./handlers/index.js";
-export { DelegateContractHandler } from "./handlers/index.js";
-export type { DelegateContractParams } from "./handlers/index.js";
-export { VHTLCContractHandler } from "./handlers/index.js";
-export type { VHTLCContractParams } from "./handlers/index.js";
-export { encodeArkContract, decodeArkContract, contractFromArkContract, contractFromArkContractWithAddress, isArkContract, } from "./arkcontract.js";
-export type { ParsedArkContract } from "./arkcontract.js";
-export { ContractWatcher } from "./contractWatcher.js";
-export type { ContractWatcherConfig } from "./contractWatcher.js";
-export { ContractManager } from "./contractManager.js";
-export type { ContractManagerConfig, CreateContractParams, RefreshVtxosOptions, } from "./contractManager.js";

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

@@ -1,250 +0,0 @@
-import { Bytes } from "@scure/btc-signer/utils.js";
-import { EncodedVtxoScript, TapLeafScript, VtxoScript } from "../script/base.js";
-import { ExtendedVirtualCoin, VirtualCoin, TapLeaves } from "../wallet/index.js";
-import { ContractFilter } from "../repositories/index.js";
-/**
- * Contract state indicating whether it should be actively monitored.
- */
-export type ContractState = "active" | "inactive";
-/**
- * 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
- * receiving address is itself a contract of type "default".
- *
- * External services (Boltz swaps, atomic swaps, etc.) create additional
- * contracts with their own types and parameters.
- *
- * @example
- * ```typescript
- * const vhtlcContract: Contract = {
- *   type: "vhtlc",
- *   params: {
- *     sender: "ab12...",
- *     receiver: "cd34...",
- *     server: "ef56...",
- *     hash: "1234...",
- *     refundLocktime: "800000",
- *     // ... timelocks
- *   },
- *   script: "5120...",
- *   address: "ark1q...",
- *   state: "active",
- *   createdAt: 1704067200000,
- * };
- * ```
- */
-export interface Contract {
-    /** Human-readable label for display purposes. */
-    label?: string;
-    /**
-     * Contract type identifier.
-     * Built-in types: "default", "vhtlc"
-     * Custom types can be registered via ContractHandler.
-     */
-    type: string;
-    /**
-     * Type-specific parameters for constructing the VtxoScript.
-     * All values are serialized as strings (hex for bytes, string for bigint).
-     * The ContractHandler for this type knows how to interpret these.
-     */
-    params: Record<string, string>;
-    /** The pkScript hex, used as the unique identifier and primary key for contracts. */
-    script: string;
-    /** Address derived from the contract script. */
-    address: string;
-    /** Current state of the contract. */
-    state: ContractState;
-    /** Unix timestamp in milliseconds when this contract was created. */
-    createdAt: number;
-    /**
-     * Optional metadata for external integrations.
-     */
-    metadata?: Record<string, unknown>;
-}
-/**
- * A virtual output that has been associated with a specific contract.
- */
-export type ContractVtxo = VirtualCoin & Partial<TapLeaves & EncodedVtxoScript> & {
-    extraWitness?: Bytes[];
-    contractScript: string;
-};
-/**
- * A {@link ContractVtxo} with all taproot annotation fields required.
- *
- * Mirrors the {@link ExtendedVirtualCoin} / {@link VirtualCoin} split:
- * - {@link ContractVtxo} carries `TapLeaves` and `EncodedVtxoScript` as
- *   `Partial<>` because VTXOs fetched raw from the indexer do not yet have
- *   taproot data.
- * - `ExtendedContractVtxo` narrows those fields to required, guaranteeing
- *   that `annotateVtxos` has run and the taproot leaves are present.
- *
- * Use this type (instead of {@link ContractVtxo}) wherever the compiler
- * should enforce that annotation has happened — e.g. `saveVtxos` and
- * forfeit transaction construction.
- */
-export type ExtendedContractVtxo = ExtendedVirtualCoin & {
-    contractScript: string;
-};
-/**
- * Result of path selection, including the tapleaf to use and any extra witness data.
- */
-export interface PathSelection {
-    /** Tapleaf script to use for spending. */
-    leaf: TapLeafScript;
-    /** Additional witness elements, for example a preimage for HTLC-like paths. */
-    extraWitness?: Bytes[];
-    /**
-     * 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 {
-    /** Whether collaborative spending is available through server cooperation. */
-    collaborative: boolean;
-    /** Current time in milliseconds. */
-    currentTime: number;
-    /** Current block height, when known. */
-    blockHeight?: number;
-    /**
-     * Wallet's descriptor for signing.
-     * Format: tr(pubkey) for static keys, tr([fingerprint/path']xpub/0/{index}) for HD.
-     * Used by handlers to determine wallet's role in multi-party contracts.
-     */
-    walletDescriptor?: string;
-    /**
-     * Wallet's public key (x-only, 32 bytes hex).
-     * @deprecated Use walletDescriptor instead.
-     */
-    walletPubKey?: string;
-    /**
-     * Explicit role override for multi-party contracts such as VHTLC.
-     * If not provided, the handler may derive the role by matching
-     * {@link walletDescriptor} (preferred) — or {@link walletPubKey} as a
-     * fallback — against the contract's sender/receiver params.
-     */
-    role?: string;
-    /** 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:
- * 1. Create the VtxoScript from parameters
- * 2. Serialize/deserialize parameters for storage
- * 3. Select the appropriate spending path based on context
- *
- * @example
- * ```typescript
- * const vhtlcHandler: ContractHandler = {
- *   type: "vhtlc",
- *   createScript(params) {
- *     return new VHTLC.Script(this.deserializeParams(params));
- *   },
- *   selectPath(script, contract, context) {
- *     const vhtlc = script as VHTLC.Script;
- *     const preimage = contract.data?.preimage;
- *     if (context.collaborative && preimage) {
- *       return { leaf: vhtlc.claim(), extraWitness: [hex.decode(preimage)] };
- *     }
- *     // ... other paths
- *   },
- *   // ...
- * };
- * ```
- */
-export interface ContractHandler<P = Record<string, unknown>, S extends VtxoScript = VtxoScript> {
-    /** 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>;
-    /**
-     * Deserialize string key-value pairs to typed parameters.
-     */
-    deserializeParams(params: Record<string, string>): P;
-    /**
-     * Select the preferred spending path based on contract state and context.
-     * Returns the best available path (e.g., collaborative over unilateral).
-     *
-     * @returns PathSelection if a viable path exists, null otherwise
-     */
-    selectPath(script: S, contract: Contract, context: PathContext): PathSelection | null;
-    /**
-     * Get all possible spending paths for the current context.
-     * Returns empty array if no paths are available.
-     *
-     * Useful for showing users which spending options exist regardless of
-     * current spendability.
-     */
-    getAllSpendingPaths(script: S, contract: Contract, context: PathContext): PathSelection[];
-    /**
-     * Get all currently spendable paths.
-     * Returns empty array if no paths are available.
-     */
-    getSpendablePaths(script: S, contract: Contract, context: PathContext): PathSelection[];
-}
-/**
- * Event emitted when contract-related changes occur.
- */
-export type ContractEvent = {
-    type: "vtxo_received";
-    contractScript: string;
-    vtxos: ContractVtxo[];
-    contract: Contract;
-    timestamp: number;
-} | {
-    type: "vtxo_spent";
-    contractScript: string;
-    vtxos: ContractVtxo[];
-    contract: Contract;
-    timestamp: number;
-} | {
-    type: "connection_reset";
-    timestamp: number;
-};
-/**
- * Callback for contract events.
- */
-export type ContractEventCallback = (event: ContractEvent) => void;
-/**
- * Options for retrieving contracts from the Contract Manager.
- * Currently an alias of the repository's filter type but can be extended in the future.
- */
-export type GetContractsFilter = ContractFilter;
-/**
- * Contract with its virtual outputs included.
- */
-export type ContractWithVtxos = {
-    contract: Contract;
-    vtxos: ExtendedContractVtxo[];
-};
-/**
- * Summary of a contract's balance.
- */
-export interface ContractBalance {
-    /** Total balance (settled + pending) in satoshis */
-    total: number;
-    /** Spendable balance in satoshis */
-    spendable: number;
-    /** Number of virtual outputs in this contract */
-    vtxoCount: number;
-}

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

@@ -1,33 +0,0 @@
-import type { ExtendedVirtualCoin, VirtualCoin } from "../wallet/index.js";
-import type { WalletRepository } from "../repositories/walletRepository.js";
-import type { Contract } from "./types.js";
-/**
- * Tier 1 helpers that enforce VTXO ownership at call sites that already know
- * the intended contract script. Address-keyed repositories may still hand back
- * legacy duplicate rows under the wrong bucket; these helpers gate reads and
- * writes so a wrong-script row never wins.
- *
- * `script` is the authoritative ownership key. Equality is strict: a missing
- * or empty `vtxo.script` never matches.
- */
-export declare function vtxoOutpoint(vtxo: Pick<VirtualCoin, "txid" | "vout">): string;
-export declare function isVtxoForScript(vtxo: Pick<VirtualCoin, "script">, script: string): boolean;
-export declare function filterVtxosForScript<T extends Pick<VirtualCoin, "script">>(vtxos: T[], script: string): T[];
-/**
- * Background/indexer sync flavour: drop wrong-script rows and log enough
- * context to identify each rejection. Returns only matching rows so the
- * caller can keep going.
- */
-export declare function warnAndFilterVtxosForScript<T extends Pick<VirtualCoin, "txid" | "vout" | "script">>(vtxos: T[], script: string, context: string): T[];
-/**
- * User-initiated transaction/signing flavour: throw before persisting or
- * signing inconsistent ownership state. Silently skipping here would hide a
- * serious bug in the wallet's spend path.
- */
-export declare function validateVtxosForScript(vtxos: Array<Pick<VirtualCoin, "txid" | "vout" | "script">>, script: string, context: string): void;
-/**
- * Tier 2 dispatch helpers: route to script-scoped repository methods when
- * available, falling back to Tier 1 address-based filtering otherwise.
- */
-export declare function getVtxosForContract(repo: WalletRepository, contract: Pick<Contract, "script" | "address">): Promise<ExtendedVirtualCoin[]>;
-export declare function saveVtxosForContract(repo: WalletRepository, contract: Pick<Contract, "script" | "address">, vtxos: ExtendedVirtualCoin[]): Promise<void>;