@arkade-os/sdk 0.4.27 → 0.4.28

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

@@ -1,84 +0,0 @@
-import { Bytes } from "@scure/btc-signer/utils.js";
-import { TapLeafScript, VtxoScript } from "../script/base.js";
-import { ExtendedCoin, Status } from "../wallet/index.js";
-/**
- * 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
- * // Create an ArkNote
- * const note = new ArkNote(preimage, 50000);
- *
- * // Encode to string
- * const noteString = note.toString();
- *
- * // Decode from string
- * const decodedNote = ArkNote.fromString(noteString);
- * ```
- */
-export declare class ArkNote implements ExtendedCoin {
-    preimage: Uint8Array;
-    value: number;
-    HRP: string;
-    static readonly DefaultHRP = "arknote";
-    static readonly PreimageLength = 32;
-    static readonly ValueLength = 4;
-    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;
-    readonly intentTapLeafScript: TapLeafScript;
-    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

@@ -1,55 +0,0 @@
-import { type BTC_NETWORK } from "@scure/btc-signer/utils.js";
-import type { Identity } from "../identity/index.js";
-/**
- * BIP-322 simple message signing and verification.
- *
- * Supports P2TR (Taproot) signing and verification, P2WPKH verification,
- * and legacy P2PKH verification (Bitcoin Core signmessage format).
- *
- * Reuses the same toSpend/toSign transaction construction as Intent proofs,
- * but with the standard BIP-322 tagged hash ("BIP0322-signed-message")
- * instead of the Arkade-specific tag.
- *
- * @see https://github.com/bitcoin/bips/blob/master/bip-0322.mediawiki
- *
- * @example
- * ```typescript
- * // Sign a message (P2TR)
- * const signature = await BIP322.sign("Hello Bitcoin!", identity);
- *
- * // Verify a signature (P2TR or P2WPKH)
- * const valid = BIP322.verify("Hello Bitcoin!", signature, "bc1p...");
- * const valid2 = BIP322.verify("Hello Bitcoin!", signature, "bc1q...");
- * ```
- */
-export declare namespace BIP322 {
-    /**
-     * Sign a message using the BIP-322 simple signature scheme.
-     *
-     * Constructs the standard BIP-322 toSpend and toSign transactions,
-     * signs via the Identity interface, and returns the base64-encoded
-     * witness stack.
-     *
-     * @param message - The message to sign
-     * @param identity - Identity instance (holds the private key internally)
-     * @param network - Optional Bitcoin network for P2TR address derivation
-     * @returns Base64-encoded BIP-322 simple signature (witness stack)
-     */
-    function sign(message: string, identity: Identity, network?: BTC_NETWORK): Promise<string>;
-    /**
-     * Verify a BIP-322 signature for a P2TR, P2WPKH, or legacy P2PKH address.
-     *
-     * For segwit addresses (P2TR, P2WPKH), reconstructs the BIP-322
-     * toSpend/toSign transactions and verifies the witness signature.
-     *
-     * For P2PKH addresses, verifies using the Bitcoin Core legacy
-     * `signmessage` format (compact recoverable ECDSA signature).
-     *
-     * @param message - The original message that was signed
-     * @param signature - Base64-encoded signature (BIP-322 witness or legacy compact)
-     * @param address - P2TR, P2WPKH, or P2PKH address of the signer
-     * @param network - Optional Bitcoin network for address decoding
-     * @returns true if the signature is valid
-     */
-    function verify(message: string, signature: string, address: string, network?: BTC_NETWORK): boolean;
-}

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

@@ -1,99 +0,0 @@
-import { Contract } from "./types.js";
-/**
- * Encode a contract to the arkcontract string format.
- *
- * Format: arkcontract={type}&{key1}={value1}&{key2}={value2}...
- *
- * This format is compatible with NArk and allows contracts to be
- * shared/imported across different Arkade SDKs.
- *
- * @example
- * ```typescript
- * const contract: Contract = {
- *   type: "vhtlc",
- *   params: { sender: "ab12...", receiver: "cd34...", ... },
- *   // ...
- * };
- *
- * const encoded = encodeArkContract(contract);
- * // "arkcontract=vhtlc&sender=ab12...&receiver=cd34...&..."
- * ```
- */
-export declare function encodeArkContract(contract: Contract): string;
-/**
- * Parsed result from decoding an arkcontract string.
- *
- * This is a low-level representation. For type-safe contract creation,
- * use `contractFromArkContract` or `contractFromArkContractWithAddress`
- * which validate params through the handler system.
- */
-export interface ParsedArkContract {
-    /** Contract type (e.g., "vhtlc", "default") */
-    type: string;
-    /** All key-value pairs from the string */
-    data: Record<string, string>;
-}
-/**
- * Decode an arkcontract string into raw type and data.
- *
- * This is a low-level function that parses the URL-encoded format.
- * For creating typed Contract objects, use `contractFromArkContract`
- * or `contractFromArkContractWithAddress` instead.
- *
- * @param encoded - The arkcontract string
- * @returns Parsed type and key-value data
- * @throws If the string is not a valid arkcontract
- *
- * @example
- * ```typescript
- * const parsed = decodeArkContract("arkcontract=vhtlc&sender=ab12...");
- * // { type: "vhtlc", data: { sender: "ab12...", ... } }
- * ```
- */
-export declare function decodeArkContract(encoded: string): ParsedArkContract;
-/**
- * Create a Contract from an arkcontract string.
- *
- * This requires a handler to be registered for the contract type.
- *
- * @param encoded - The arkcontract string
- * @param options - Additional options for the contract
- * @returns A Contract object
- * @throws If the string is invalid or no handler exists for the type
- *
- * @example
- * ```typescript
- * const contract = contractFromArkContract(
- *   "arkcontract=vhtlc&sender=ab12...",
- *   {
- *     label: "Lightning Receive",
- *   }
- * );
- * ```
- */
-export declare function contractFromArkContract(encoded: string, options?: {
-    label?: string;
-    state?: "active" | "inactive";
-    metadata?: Record<string, unknown>;
-}): Omit<Contract, "script" | "address"> & {
-    script?: string;
-    address?: string;
-};
-/**
- * Create a full Contract with derived script and address.
- *
- * @param encoded - The arkcontract string
- * @param serverPubKey - Server public key (for address derivation)
- * @param addressPrefix - Address prefix (e.g., "tark" for testnet)
- * @param options - Additional options
- * @returns A complete Contract object
- */
-export declare function contractFromArkContractWithAddress(encoded: string, serverPubKey: Uint8Array, addressPrefix?: string, options?: {
-    label?: string;
-    state?: "active" | "inactive";
-    metadata?: Record<string, unknown>;
-}): Contract;
-/**
- * Check if a string is an arkcontract.
- */
-export declare function isArkContract(str: string): boolean;

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

@@ -1,411 +0,0 @@
-import { IndexerProvider } from "../providers/indexer.js";
-import { WalletRepository } from "../repositories/walletRepository.js";
-import { Contract, ContractEventCallback, ContractState, ContractWithVtxos, GetContractsFilter, PathSelection } from "./types.js";
-import { ContractWatcherConfig } from "./contractWatcher.js";
-import { ExtendedVirtualCoin, Outpoint, VirtualCoin } from "../wallet/index.js";
-import { ContractRepository } from "../repositories/index.js";
-export type RefreshVtxosOptions = {
-    scripts?: string[];
-    after?: number;
-    before?: number;
-    /**
-     * When true and `scripts` is not set, refresh every contract in
-     * the repository — including those marked `inactive` and those
-     * that have dropped out of the watcher's active set. Useful for
-     * "did anyone send funds to a stale rotated display address?"
-     * audits.
-     *
-     * Because this is a *superset* of the watcher's watched set, the
-     * cursor invariant still holds and the cursor advances normally
-     * (unless an explicit `after` / `before` window is also supplied).
-     *
-     * Ignored when `scripts` is set (the explicit list already
-     * specifies what to refresh, regardless of contract state).
-     *
-     * @defaultValue `false`
-     */
-    includeInactive?: boolean;
-};
-export interface IContractManager extends Disposable {
-    /**
-     * Create and register a new contract.
-     *
-     * Implementations may validate that:
-     * - A handler exists for `params.type`
-     * - `params.script` matches the script derived from `params.params`
-     *
-     * The contract script is used as the unique identifier.
-     */
-    createContract(params: CreateContractParams): Promise<Contract>;
-    /**
-     * List contracts with optional filters.
-     *
-     * @example
-     * ```typescript
-     * const vhtlcs = await manager.getContracts({ type: "vhtlc" });
-     * const active = await manager.getContracts({ state: "active" });
-     * ```
-     */
-    getContracts(filter?: GetContractsFilter): Promise<Contract[]>;
-    /**
-     * List contracts and their current virtual outputs.
-     *
-     * If no filter is provided, returns all contracts with their virtual outputs.
-     */
-    getContractsWithVtxos(filter?: GetContractsFilter): Promise<ContractWithVtxos[]>;
-    /**
-     * Stamp raw virtual outputs with the correct per-contract tapscripts
-     * (forfeit, intent, tap tree).
-     *
-     * Resolves each vtxo's `script` to its owning contract via the contract
-     * repository and attaches the matching tapscripts. Throws when any vtxo
-     * references a script with no registered contract — callers are expected
-     * to register the contract before asking for annotation. This is the
-     * single shared path that replaces scattered `extendVirtualCoin*` calls
-     * in wallet/handler code, and keeps the wallet from silently stamping the
-     * default tapscript onto a non-default vtxo.
-     */
-    annotateVtxos(vtxos: VirtualCoin[]): Promise<ExtendedVirtualCoin[]>;
-    /**
-     * Update mutable contract fields.
-     *
-     * `script` and `createdAt` are immutable.
-     */
-    updateContract(script: string, updates: Partial<Omit<Contract, "script" | "createdAt">>): Promise<Contract>;
-    /**
-     * Convenience helper to update only the contract state.
-     */
-    setContractState(script: string, state: ContractState): Promise<void>;
-    /**
-     * Delete a contract by script and stop watching it (if applicable).
-     */
-    deleteContract(script: string): Promise<void>;
-    /**
-     * Get all currently spendable paths for a contract.
-     *
-     * Returns an empty array if the contract or its handler cannot be found.
-     */
-    getSpendablePaths(options: GetSpendablePathsOptions): Promise<PathSelection[]>;
-    /**
-     * Get all possible spending paths for a contract.
-     *
-     * Returns an empty array if the contract or its handler cannot be found.
-     */
-    getAllSpendingPaths(options: GetAllSpendingPathsOptions): Promise<PathSelection[]>;
-    /**
-     * Subscribe to contract events.
-     *
-     * @returns Unsubscribe function
-     */
-    onContractEvent(callback: ContractEventCallback): () => void;
-    /**
-     * 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.
-     */
-    refreshVtxos(opts?: RefreshVtxosOptions): Promise<void>;
-    /**
-     * Reconcile specific outpoints with the indexer's authoritative state and
-     * upsert the result into the wallet repository.
-     *
-     * The cursor-derived delta sync filters by `created_at`, so a VTXO that
-     * was created before the cursor but spent recently won't surface in a
-     * standard `refreshVtxos()` call. This method is the surgical recovery
-     * path for that case: when something hands us a stale outpoint (e.g. the
-     * server returns `VTXO_ALREADY_SPENT` with a `vtxo_outpoint` in its
-     * error metadata), call this to pull the latest state and unblock the
-     * caller — no full re-scan, no cursor change.
-     *
-     * Outpoints not owned by any tracked contract are silently dropped.
-     */
-    refreshOutpoints(outpoints: Outpoint[]): Promise<void>;
-    /**
-     * Whether the underlying watcher is currently active.
-     */
-    isWatching(): Promise<boolean>;
-    /**
-     * Release resources (stop watching, clear listeners).
-     */
-    dispose(): void;
-}
-/**
- * Options for getting spendable paths.
- */
-export type GetSpendablePathsOptions = {
-    /** The contract script */
-    contractScript: string;
-    /** The specific virtual output being evaluated */
-    vtxo: VirtualCoin;
-    /** Whether collaborative spending is available (default: true) */
-    collaborative?: boolean;
-    /** Wallet's public key (hex) to determine role */
-    walletPubKey?: string;
-};
-/**
- * Options for getting all possible spending paths.
- */
-export type GetAllSpendingPathsOptions = {
-    /** The contract script */
-    contractScript: string;
-    /** Whether collaborative spending is available (default: true) */
-    collaborative?: boolean;
-    /** Wallet's public key (hex) to determine role */
-    walletPubKey?: string;
-};
-/**
- * Configuration for the ContractManager.
- */
-export interface ContractManagerConfig {
-    /** The indexer provider */
-    indexerProvider: IndexerProvider;
-    /** The contract repository for persistence */
-    contractRepository: ContractRepository;
-    /** The wallet repository for virtual output storage (single source of truth) */
-    walletRepository: WalletRepository;
-    /** Watcher configuration */
-    watcherConfig?: Partial<ContractWatcherConfig>;
-}
-/**
- * Parameters for creating a new contract.
- */
-export type CreateContractParams = Omit<Contract, "createdAt" | "state"> & {
-    /** Initial state (defaults to "active") */
-    state?: ContractState;
-};
-/**
- * Central manager for contract lifecycle and operations.
- *
- * 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, connection reset)
- *
- * Notes:
- * - Implementations typically start watching automatically during initialization
- *   (so `onContractEvent()` is just for subscribing).
- *
- * @example
- * ```typescript
- * const manager = await ContractManager.create({
- *   indexerProvider: wallet.indexerProvider,
- *   contractRepository: wallet.contractRepository,
- * });
- *
- * // Create a new VHTLC contract
- * const contract = await manager.createContract({
- *   label: "Lightning Receive",
- *   type: "vhtlc",
- *   params: { sender: "ark1q...", receiver: "ark1q...", ... },
- *   script: "5120...",
- *   address: "ark1q...",
- * });
- *
- * // Start watching for events
- * 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 = 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 {
-    private config;
-    private watcher;
-    private initialized;
-    private eventCallbacks;
-    private stopWatcherFn?;
-    private constructor();
-    /**
-     * Static factory method for creating a new ContractManager.
-     * Initialize the manager by loading persisted contracts and starting to watch.
-     *
-     * After initialization, the manager automatically watches all active contracts
-     * and contracts with virtual outputs. Use `onContractEvent()` to register event callbacks.
-     *
-     * @param config ContractManagerConfig
-     */
-    static create(config: ContractManagerConfig): Promise<ContractManager>;
-    private initialize;
-    /**
-     * Delta-sync the full watched set and reconcile the pending frontier.
-     *
-     * Shared recovery path used on initial boot and after a subscription
-     * reconnect. `syncContracts({})` scopes to the current watched set
-     * (see {@link ContractWatcher.getWatchedContracts}), uses the
-     * cursor-derived delta window, and advances the cursor on success.
-     * `reconcilePendingFrontier` catches not-yet-finalized virtual
-     * outputs that could sit outside any delta window.
-     */
-    private reconcileWatched;
-    /**
-     * Create and register a new contract.
-     *
-     * @param params - Contract parameters
-     * @returns The created contract
-     */
-    createContract(params: CreateContractParams): Promise<Contract>;
-    /**
-     * Get contracts with optional filters.
-     *
-     * @param filter - Optional filter criteria
-     * @returns Filtered contracts TODO: filter spent/unspent
-     *
-     * @example
-     * ```typescript
-     * // Get all VHTLC contracts
-     * const vhtlcs = await manager.getContracts({ type: 'vhtlc' });
-     *
-     * // Get all active contracts
-     * const active = await manager.getContracts({ state: 'active' });
-     * ```
-     */
-    getContracts(filter?: GetContractsFilter): Promise<Contract[]>;
-    getContractsWithVtxos(filter?: GetContractsFilter, pageSize?: number): Promise<ContractWithVtxos[]>;
-    annotateVtxos(vtxos: VirtualCoin[]): Promise<ExtendedVirtualCoin[]>;
-    private buildContractsDbFilter;
-    /**
-     * Update a contract.
-     * Nested fields like `params` and `metadata` are replaced with the provided values.
-     * If you need to preserve existing fields, merge them manually.
-     *
-     * @param script - Contract script
-     * @param updates - Fields to update
-     */
-    updateContract(script: string, updates: Partial<Omit<Contract, "script" | "createdAt">>): Promise<Contract>;
-    /**
-     * Update a contract's params.
-     * This method preserves existing params by merging the provided values.
-     *
-     * @param script - Contract script
-     * @param updates - The new values to merge with existing params
-     */
-    updateContractParams(script: string, updates: Contract["params"]): Promise<Contract>;
-    /**
-     * Set a contract's state.
-     */
-    setContractState(script: string, state: ContractState): Promise<void>;
-    /**
-     * Delete a contract.
-     *
-     * @param script - Contract script
-     */
-    deleteContract(script: string): Promise<void>;
-    /**
-     * Get currently spendable paths for a contract.
-     *
-     * @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.
-     *
-     * The manager automatically watches after `initialize()`. This method
-     * allows registering callbacks to receive events.
-     *
-     * @param callback - Event callback
-     * @returns Unsubscribe function to remove this callback
-     *
-     * @example
-     * ```typescript
-     * const unsubscribe = manager.onContractEvent((event) => {
-     *   console.log(`${event.type} on ${event.contractScript}`);
-     * });
-     *
-     * // Later: stop receiving events
-     * unsubscribe();
-     * ```
-     */
-    onContractEvent(callback: ContractEventCallback): () => void;
-    /**
-     * Force refresh virtual outputs from the indexer.
-     *
-     * Without options, re-fetches every contract in the watcher's
-     * watched set and advances the global cursor.
-     *
-     * `scripts` narrows the refresh to a specific list (subset query —
-     * cursor is not advanced because contracts outside the list may
-     * have data we'd skip).
-     *
-     * `includeInactive: true` (and no `scripts`) widens the refresh to
-     * every contract in the repository, including ones marked
-     * `inactive` and ones that have dropped out of the watcher's
-     * active set. This is a *superset* of the watched set, so the
-     * cursor invariant still holds and the cursor advances normally.
-     *
-     * `after` / `before` apply a caller-supplied time window. The
-     * cursor never advances on a windowed query because the window
-     * may skip data outside its bounds.
-     */
-    refreshVtxos(opts?: RefreshVtxosOptions): Promise<void>;
-    refreshOutpoints(outpoints: Outpoint[]): Promise<void>;
-    /**
-     * Check if currently watching.
-     */
-    isWatching(): Promise<boolean>;
-    /**
-     * Emit an event to all registered callbacks.
-     */
-    private emitEvent;
-    /**
-     * Handle events from the watcher.
-     */
-    private handleContractEvent;
-    private getVtxosForContracts;
-    /**
-     * Sync virtual outputs for the given contracts against the indexer.
-     *
-     * When `options.contracts` is omitted the sync covers the full
-     * watched set (active contracts plus any inactive contracts still
-     * holding cached VTXOs) and the global cursor is advanced on
-     * success. Passing an explicit subset leaves the cursor alone so a
-     * narrow poll can't hide data that other contracts still need to
-     * pick up.
-     */
-    private syncContracts;
-    /**
-     * 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;
-    private fetchContractVxosFromIndexer;
-    private fetchContractVtxosBulk;
-    /**
-     * Dispose of the ContractManager and release all resources.
-     *
-     * Stops the watcher, clears callbacks, and marks
-     * the manager as uninitialized.
-     *
-     * Implements the disposable pattern for cleanup.
-     */
-    dispose(): void;
-    /**
-     * Symbol.dispose implementation for using with `using` keyword.
-     * @example
-     * ```typescript
-     * {
-     *   using manager = await wallet.getContractManager();
-     *   // ... use manager
-     * } // automatically disposed
-     * ```
-     */
-    [Symbol.dispose](): void;
-}