@arkade-os/sdk 0.3.13 → 0.4.0-next.1

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

@@ -0,0 +1,192 @@
+import { IndexerProvider } from "../providers/indexer";
+import { WalletRepository } from "../repositories/walletRepository";
+import { Contract, ContractEventCallback } from "./types";
+/**
+ * Configuration for the ContractWatcher.
+ */
+export interface ContractWatcherConfig {
+    /** The indexer provider to use for subscriptions and queries */
+    indexerProvider: IndexerProvider;
+    /** The wallet repository for VTXO persistence (optional) */
+    walletRepository: WalletRepository;
+    /**
+     * Interval for failsafe polling (ms).
+     * Polls even when subscription is active to catch missed events.
+     * Default: 60000 (1 minute)
+     */
+    failsafePollIntervalMs?: number;
+    /**
+     * Initial reconnection delay (ms).
+     * Uses exponential backoff on repeated failures.
+     * Default: 1000 (1 second)
+     */
+    reconnectDelayMs?: number;
+    /**
+     * Maximum reconnection delay (ms).
+     * Default: 30000 (30 seconds)
+     */
+    maxReconnectDelayMs?: number;
+    /**
+     * Maximum reconnection attempts before giving up.
+     * Set to 0 for unlimited attempts.
+     * Default: 0 (unlimited)
+     */
+    maxReconnectAttempts?: number;
+}
+/**
+ * Connection state for the watcher.
+ */
+type ConnectionState = "disconnected" | "connecting" | "connected" | "reconnecting";
+/**
+ * Watches multiple contracts for VTXO 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?;
+    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).
+     */
+    addContract(contract: Contract): Promise<void>;
+    /**
+     * 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[];
+    /**
+     * Get all active in-memory contracts.
+     */
+    getActiveContracts(): Contract[];
+    /**
+     * Get scripts that should be watched.
+     *
+     * Returns scripts for:
+     * - All active contracts
+     * - All contracts with known VTXOs (regardless of state)
+     *
+     * This ensures we continue monitoring contracts even after they're
+     * deactivated, as long as they have unspent VTXOs.
+     */
+    private getScriptsToWatch;
+    /**
+     * Get VTXOs for contracts, grouped by contract script.
+     * Uses Repository.
+     */
+    private getContractVtxos;
+    /**
+     * Start watching for VTXO 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>;
+    /**
+     * Check for expired contracts, update their state, and emit events.
+     */
+    private checkExpiredContracts;
+    /**
+     * Connect to the subscription.
+     */
+    private connect;
+    /**
+     * Schedule a reconnection attempt.
+     */
+    private scheduleReconnect;
+    /**
+     * Start the failsafe polling interval.
+     */
+    private startFailsafePolling;
+    /**
+     * Poll all active contracts for current state.
+     */
+    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 VTXOs.
+     */
+    private updateSubscription;
+    /**
+     * Main listening loop for subscription events.
+     */
+    private listenLoop;
+    /**
+     * Handle a subscription update.
+     */
+    private handleSubscriptionUpdate;
+    /**
+     * Process VTXOs 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.
+     */
+    private emitVtxoEvent;
+}
+export {};

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

@@ -0,0 +1,19 @@
+import { DefaultVtxo } from "../../script/default";
+import { RelativeTimelock } from "../../script/tapscript";
+import { ContractHandler } from "../types";
+/**
+ * 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

@@ -0,0 +1,21 @@
+import { DelegateVtxo } from "../../script/delegate";
+import { RelativeTimelock } from "../../script/tapscript";
+import { ContractHandler } from "../types";
+/**
+ * Typed parameters for DelegateVtxo contracts.
+ */
+export interface DelegateContractParams {
+    pubKey: Uint8Array;
+    serverPubKey: Uint8Array;
+    delegatePubKey: Uint8Array;
+    csvTimelock: RelativeTimelock;
+}
+/**
+ * Handler for delegate wallet VTXOs.
+ *
+ * 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

@@ -0,0 +1,18 @@
+import { RelativeTimelock } from "../../script/tapscript";
+import { Contract, PathContext } from "../types";
+/**
+ * Convert RelativeTimelock to BIP68 sequence number.
+ */
+export declare function timelockToSequence(timelock: RelativeTimelock): number;
+/**
+ * Convert BIP68 sequence number back to RelativeTimelock.
+ */
+export declare function sequenceToTimelock(sequence: number): RelativeTimelock;
+/**
+ * Resolve wallet's role from explicit role or by matching pubkey.
+ */
+export declare function resolveRole(contract: Contract, context: PathContext): "sender" | "receiver" | undefined;
+/**
+ * Check if a CSV timelock is currently satisfied for the given context/VTXO.
+ */
+export declare function isCsvSpendable(context: PathContext, sequence?: number): boolean;

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

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

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

@@ -0,0 +1,65 @@
+import { ContractHandler } from "../types";
+/**
+ * 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

@@ -0,0 +1,32 @@
+import { VHTLC } from "../../script/vhtlc";
+import { RelativeTimelock } from "../../script/tapscript";
+import { ContractHandler } from "../types";
+/**
+ * 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

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

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

@@ -0,0 +1,222 @@
+import { Bytes } from "@scure/btc-signer/utils.js";
+import { TapLeafScript, VtxoScript } from "../script/base";
+import { VirtualCoin, ExtendedVirtualCoin } from "../wallet";
+import { ContractFilter } from "../repositories";
+/**
+ * Contract state indicating whether it should be actively monitored.
+ */
+export type ContractState = "active" | "inactive";
+/**
+ * Represents a contract that can receive and manage VTXOs.
+ *
+ * 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: "tark1...",
+ *   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 - unique identifier and primary key for contracts */
+    script: string;
+    /** The address derived from the script */
+    address: string;
+    /** Current state of the contract */
+    state: ContractState;
+    /** Unix timestamp (ms) when this contract was created */
+    createdAt: number;
+    /** Unix timestamp (ms) when this contract expires (optional) */
+    expiresAt?: number;
+    /**
+     * Optional metadata for external integrations.
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * A VTXO that has been associated with a specific contract.
+ */
+export interface ContractVtxo extends ExtendedVirtualCoin {
+    /** The contract script this VTXO belongs to */
+    contractScript: string;
+}
+/**
+ * Result of path selection - which tapleaf to use and extra witness data.
+ */
+export interface PathSelection {
+    /** The tapleaf script to use for spending */
+    leaf: TapLeafScript;
+    /** Additional witness elements (e.g., preimage for HTLC) */
+    extraWitness?: Bytes[];
+    /** Sequence number override (for CSV timelocks) */
+    sequence?: number;
+}
+/**
+ * Context for path selection decisions.
+ */
+export interface PathContext {
+    /** Is collaborative spending available (server cooperation)? */
+    collaborative: boolean;
+    /** Current time in milliseconds */
+    currentTime: number;
+    /** Current block height (optional) */
+    blockHeight?: number;
+    /**
+     * Wallet's public key (x-only, 32 bytes hex).
+     * Used by handlers to determine 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.
+     */
+    role?: string;
+    /** The specific VTXO 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> {
+    /** The contract type this handler manages */
+    readonly type: string;
+    /**
+     * Create the VtxoScript from serialized parameters.
+     */
+    createScript(params: Record<string, string>): S;
+    /**
+     * Serialize typed parameters to string key-value pairs.
+     */
+    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: "contract_expired";
+    contractScript: string;
+    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 VTXOs included.
+ */
+export type ContractWithVtxos = {
+    contract: Contract;
+    vtxos: ContractVtxo[];
+};
+/**
+ * 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 VTXOs in this contract */
+    vtxoCount: number;
+}

package/dist/types/forfeit.d.ts

@@ -1,3 +1,4 @@
 import { Transaction } from "./utils/transaction";
-import { TransactionInputUpdate } from "@scure/btc-signer/psbt.js";
+import { TransactionInputUpdate, TransactionOutput } from "@scure/btc-signer/psbt.js";
 export declare function buildForfeitTx(inputs: TransactionInputUpdate[], forfeitPkScript: Uint8Array, txLocktime?: number): Transaction;
+export declare function buildForfeitTxWithOutput(inputs: TransactionInputUpdate[], output: TransactionOutput, txLocktime?: number): Transaction;

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

@@ -10,3 +10,4 @@ export interface ReadonlyIdentity {
     compressedPublicKey(): Promise<Uint8Array>;
 }
 export * from "./singleKey";
+export * from "./seedIdentity";