@arkade-os/sdk 0.4.27 → 0.4.28

package/dist/types/providers/delegator.d.ts

@@ -1,82 +0,0 @@
-import { Intent } from "../intent/index.js";
-import { SignedIntent } from "./ark.js";
-/**
- * Delegate identity and fee information returned by `getDelegateInfo`.
- */
-export interface DelegateInfo {
-    /** Delegate public key. */
-    pubkey: string;
-    /** Delegate fee amount or expression returned by the delegation service. */
-    fee: string;
-    /**
-     * Address controlled by the delegation service.
-     * Naming is confusing: should be thought of as a "delegate address".
-     */
-    delegatorAddress: string;
-}
-/**
- * Optional delegate behavior flags.
- */
-export interface DelegateOptions {
-    /**
-     * Instruct the delegate not to replace an existing delegation
-     * (meaning a signed register intent and its forfeit transactions)
-     * that already includes at least one virtual output from this request.
-     *
-     * @defaultValue `false`
-     */
-    rejectReplace?: boolean;
-}
-/**
- * Provider interface for remote delegation services.
- */
-export interface DelegatorProvider {
-    /**
-     * Request delegation for a signed register intent and its forfeit transactions.
-     *
-     * @param intent - Signed register intent to delegate
-     * @param forfeitTxs - Forfeit transactions associated with the delegation request
-     * @param options - Optional delegate behavior flags
-     */
-    delegate(intent: SignedIntent<Intent.RegisterMessage>, forfeitTxs: string[], options?: DelegateOptions): Promise<void>;
-    /**
-     * Fetch delegate metadata such as pubkey, fee, and delegate address.
-     *
-     * @returns Delegate identity and fee information
-     */
-    getDelegateInfo(): Promise<DelegateInfo>;
-}
-/**
- * REST-based delegation provider implementation.
- * @example
- * ```typescript
- * const provider = new RestDelegatorProvider('https://delegator.example.com');
- * const info = await provider.getDelegateInfo();
- * await provider.delegate(intent, forfeitTxs);
- * ```
- */
-export declare class RestDelegatorProvider implements DelegatorProvider {
-    url: string;
-    /**
-     * Create a REST delegation provider targeting the given base URL.
-     *
-     * @param url - Base URL of the delegation service
-     */
-    constructor(url: string);
-    /**
-     * Submit a delegation request to the remote delegation service.
-     *
-     * @param intent - Signed register intent to delegate
-     * @param forfeitTxs - Forfeit transactions associated with the delegation request
-     * @param options - Optional delegate behavior flags
-     * @throws Error if the remote service rejects the request
-     */
-    delegate(intent: SignedIntent<Intent.RegisterMessage>, forfeitTxs: string[], options?: DelegateOptions): Promise<void>;
-    /**
-     * Fetch delegate metadata exposed by the remote delegation service.
-     *
-     * @returns Delegate identity and fee information
-     * @throws Error if the remote service returns invalid data
-     */
-    getDelegateInfo(): Promise<DelegateInfo>;
-}

package/dist/types/providers/electrum.d.ts

@@ -1,312 +0,0 @@
-import type { ElectrumWS } from "ws-electrumx-client";
-import type { Network, NetworkName } from "../networks.js";
-import type { Coin } from "../wallet/index.js";
-import type { ExplorerTransaction, OnchainProvider } from "./onchain.js";
-/**
- * Default WebSocket Electrum endpoints. Mainnet, mutinynet, and signet
- * point at Ark Labs–operated Fulcrum 2.1 deployments (which support
- * `blockchain.transaction.broadcast_package` for atomic 1P1C TRUC
- * relay; see `ElectrumOnchainProvider.broadcastTransaction`). Testnet
- * defaults to Blockstream's public Fulcrum because Ark doesn't host
- * it. Regtest assumes the `electrum-ws` websocat bridge from
- * `vulpemventures/nigiri`.
- *
- * @example
- * ```typescript
- * import { ElectrumWS } from "ws-electrumx-client";
- * import { ELECTRUM_WS_URL, ElectrumOnchainProvider, networks } from "@arkade-os/sdk";
- *
- * const ws = new ElectrumWS(ELECTRUM_WS_URL.bitcoin);
- * const provider = new ElectrumOnchainProvider(ws, networks.bitcoin);
- * ```
- */
-export declare const ELECTRUM_WS_URL: Record<NetworkName, string>;
-/**
- * Hostnames for Electrum endpoints reachable over raw TCP. Provided as
- * a reference for Node-side consumers — the SDK's
- * {@link ElectrumOnchainProvider} only speaks WebSocket because it has
- * to run in browsers, so this map is informational only and not
- * consumed by any built-in provider.
- *
- * Public Ark Labs Fulcrum instances expose:
- *   - port 50001 — plain TCP (Electrum protocol)
- *   - port 50002 — TCP + TLS (Electrum protocol)
- *   - port 50003 — WebSocket (Electrum-over-WS, see {@link ELECTRUM_WS_URL})
- */
-export declare const ELECTRUM_TCP_HOST: Record<NetworkName, string | null>;
-export type TransactionHistory = {
-    tx_hash: string;
-    height: number;
-    fee?: number;
-};
-export type BlockHeader = {
-    height: number;
-    hex: string;
-};
-export type Unspent = {
-    txid: string;
-    vout: number;
-    witnessUtxo: {
-        script: Uint8Array;
-        value: bigint;
-    };
-};
-type VerboseTransaction = {
-    txid: string;
-    confirmations: number;
-    blockhash?: string;
-    blocktime?: number;
-    time?: number;
-    /** Raw transaction hex. Bitcoin Core's getrawtransaction <tx> 1 always
-     *  includes this; we use it to derive exact satoshi amounts instead of
-     *  multiplying the floating-point `value` field by 1e8. */
-    hex?: string;
-    vout: {
-        n: number;
-        value: number;
-        scriptPubKey: {
-            addresses?: string[];
-            address?: string;
-            hex: string;
-        };
-    }[];
-    vin: {
-        txid: string;
-        vout: number;
-    }[];
-};
-type HeaderSubscribeResult = {
-    height: number;
-    hex: string;
-};
-/**
- * WebSocket-based Electrum chain source using ws-electrumx-client.
- * Provides low-level methods for the Electrum protocol.
- *
- * @example
- * ```typescript
- * import { ElectrumWS } from "ws-electrumx-client";
- * import { WsElectrumChainSource } from "./providers/electrum.js";
- * import { networks } from "./networks.js";
- *
- * const ws = new ElectrumWS("wss://electrum.blockstream.info:50004");
- * const chain = new WsElectrumChainSource(ws, networks.bitcoin);
- *
- * const history = await chain.fetchHistories([script]);
- * await chain.close();
- * ```
- */
-export declare class WsElectrumChainSource {
-    private ws;
-    private network;
-    private cachedTip;
-    private headersSubscribePromise;
-    constructor(ws: ElectrumWS, network: Network);
-    /**
-     * Send N requests in parallel and aggregate the results, replacement
-     * for `ws.batchRequest`. The library's batchRequest is implemented as
-     * `Promise.all` over individual request promises — when one element
-     * rejects, the others remain pending. When their (often error)
-     * responses arrive later, the library rejects them too, and nobody is
-     * awaiting them: the rejections become unhandled and crash the test
-     * runner / pollute production logs.
-     *
-     * `safeBatchRequest` issues each request through `ws.request` (so each
-     * has its own request-promise lifecycle), waits for all of them via
-     * `Promise.allSettled` (every promise gets an explicit handler), and
-     * then surfaces the first error if any failed. Same wall-clock cost
-     * as the library's batch (parallel send), no orphan rejections.
-     *
-     * Use this in place of `ws.batchRequest` for any call where one or
-     * more elements may legitimately error (e.g. electrs index lag
-     * surfacing as `missingheight` for a subset of heights/txids).
-     */
-    safeBatchRequest<T>(requests: {
-        method: string;
-        params: unknown[];
-    }[]): Promise<T[]>;
-    fetchTransactions(txids: string[]): Promise<{
-        txID: string;
-        hex: string;
-    }[]>;
-    fetchVerboseTransaction(txid: string): Promise<VerboseTransaction>;
-    fetchVerboseTransactions(txids: string[]): Promise<VerboseTransaction[]>;
-    /**
-     * Look up the block height of a confirmed transaction without relying
-     * on the verbose-tx endpoint. `blockchain.transaction.get_merkle` is
-     * part of the standard SPV protocol and is supported by both Fulcrum
-     * and electrs (whereas `blockchain.transaction.get` with verbose=true
-     * is Fulcrum-only). Returns `null` when the tx is in the mempool —
-     * electrs in that case rejects with a "not yet in a block" error.
-     */
-    fetchTxMerkle(txid: string): Promise<{
-        blockHeight: number;
-    } | null>;
-    unsubscribeScriptStatus(script: Uint8Array): Promise<void>;
-    subscribeScriptStatus(script: Uint8Array, callback: (scripthash: string, status: string | null) => void): Promise<void>;
-    fetchHistories(scripts: Uint8Array[]): Promise<TransactionHistory[][]>;
-    fetchHistory(script: Uint8Array): Promise<TransactionHistory[]>;
-    fetchBlockHeaders(heights: number[]): Promise<BlockHeader[]>;
-    fetchBlockHeader(height: number): Promise<BlockHeader>;
-    /**
-     * Returns the current chain tip and keeps it fresh via a single
-     * server-side subscription. Subsequent calls return the cached tip
-     * (updated by background notifications) without round-tripping to the
-     * server. Previously each call issued `blockchain.headers.subscribe` as
-     * a regular request, leaving a stale subscription on the server every
-     * time — under polling that adds up. ws-electrumx-client deduplicates
-     * `subscribe()` by method+params, so registering once is enough.
-     */
-    subscribeHeaders(): Promise<HeaderSubscribeResult>;
-    estimateFees(targetNumberBlocks: number): Promise<number>;
-    broadcastTransaction(txHex: string): Promise<string>;
-    /**
-     * Submit a package of raw transactions atomically via Fulcrum's
-     * `blockchain.transaction.broadcast_package` method, the on-the-wire
-     * equivalent of bitcoind's `submitpackage` RPC.
-     *
-     * Required for TRUC (BIP 431) 1P1C relay where the parent has zero
-     * (or below-minfee) fee and depends on the child to pay for both via
-     * CPFP — sequential broadcast cannot work in that case because the
-     * parent would be rejected from the mempool on its own.
-     *
-     * @param txHexes - Topologically sorted raw transactions; child must
-     *                  be the last element. Currently must be a 1P1C pair
-     *                  (length 2). Parents may not depend on each other.
-     * @returns The child transaction id (the last entry in the array),
-     *          computed locally — `broadcast_package` itself returns
-     *          `{success, errors}` rather than a txid.
-     * @throws If the server does not implement `broadcast_package` (e.g.
-     *         ElectrumX, or older Fulcrum, or Fulcrum backed by bitcoind
-     *         < v28.0.0). Callers must surface this clearly to users —
-     *         this method does NOT silently fall back to sequential
-     *         broadcasts because doing so would let TRUC packages fail
-     *         in subtle ways.
-     * @throws If the server returns `success=false`, surfacing the
-     *         underlying mempool rejection in the error message.
-     */
-    broadcastPackage(txHexes: string[]): Promise<string>;
-    getRelayFee(): Promise<number>;
-    close(): Promise<void>;
-    waitForAddressReceivesTx(addr: string): Promise<void>;
-    listUnspents(addr: string): Promise<Unspent[]>;
-    /**
-     * Get the address string for a script output, if decodable.
-     */
-    addressForScript(scriptHex: string): string | undefined;
-}
-/**
- * Electrum-based implementation of the {@link OnchainProvider} interface.
- *
- * Built around the subset of the Electrum protocol that both **Fulcrum**
- * and **electrs** support — listunspent, get_history, transaction.get
- * (non-verbose), transaction.get_merkle, block.header,
- * headers.subscribe, scripthash.subscribe, estimatefee, relayfee, and
- * broadcast. The verbose form of `transaction.get` is **not** used (it's
- * Fulcrum-only and rejected by electrs); confirmation status is derived
- * from `transaction.get_merkle` plus parsed block headers.
- *
- * Output amounts are derived from parsed raw transaction bytes (exact
- * bigints), never the floating-point `value` fields some servers return.
- *
- * Atomic 1P1C package broadcast (TRUC / BIP 431) is supported via
- * Fulcrum's `blockchain.transaction.broadcast_package`. There is **no
- * fallback** to sequential parent-then-child broadcasts — TRUC packages
- * with a zero-fee parent would silently fail, so the call surfaces an
- * error against servers that don't support the method.
- *
- * @example Default URL via {@link ELECTRUM_WS_URL}
- * ```typescript
- * import { ElectrumWS } from "ws-electrumx-client";
- * import {
- *   ElectrumOnchainProvider,
- *   ELECTRUM_WS_URL,
- *   networks,
- * } from "@arkade-os/sdk";
- *
- * const ws = new ElectrumWS(ELECTRUM_WS_URL.bitcoin);
- * const provider = new ElectrumOnchainProvider(ws, networks.bitcoin);
- *
- * const coins = await provider.getCoins("bc1q...");
- * await provider.close();
- * ```
- *
- * @example Custom server
- * ```typescript
- * const ws = new ElectrumWS("wss://my-fulcrum.example:50004");
- * const provider = new ElectrumOnchainProvider(ws, networks.bitcoin);
- * ```
- */
-export declare class ElectrumOnchainProvider implements OnchainProvider {
-    private ws;
-    private network;
-    private chain;
-    constructor(ws: ElectrumWS, network: Network);
-    getCoins(address: string): Promise<Coin[]>;
-    getFeeRate(): Promise<number | undefined>;
-    /**
-     * Broadcast a single transaction or a TRUC (BIP 431) 1P1C package
-     * atomically.
-     *
-     * **Server requirements for 1P1C packages:** the backing Electrum
-     * server must implement `blockchain.transaction.broadcast_package`
-     * (Fulcrum ≥ 1.10) and be backed by bitcoind ≥ v28.0.0. ElectrumX
-     * does not implement this method. There is **no fallback** to
-     * sequential parent-then-child broadcast: TRUC packages typically
-     * have a zero-fee parent and would be rejected from the mempool on
-     * their own, so a fallback would silently fail in subtle ways.
-     * Callers receiving a "method not found" error here should route
-     * through a different provider for that submission.
-     *
-     * @param txs - One transaction (single broadcast) or two
-     *              topologically-sorted transactions (parent first,
-     *              child last) for 1P1C package relay.
-     * @returns The broadcast txid (or the child txid for 1P1C packages).
-     */
-    broadcastTransaction(...txs: string[]): Promise<string>;
-    getTxOutspends(txid: string): Promise<{
-        spent: boolean;
-        txid: string;
-    }[]>;
-    getTransactions(address: string): Promise<ExplorerTransaction[]>;
-    /**
-     * Resolve a list of `{tx_hash, height}` entries (as returned by the
-     * scripthash history endpoint) into ExplorerTransaction shape **without
-     * using the verbose-tx endpoint**, which only Fulcrum implements. We
-     * reconstruct everything the verbose response would have given us:
-     *   - vouts ← parse the raw tx (exact sat amounts, no float precision risk)
-     *   - block_time ← batch-fetch the block headers for the heights present
-     *   - addresses ← decode each output's scriptPubKey via @scure/btc-signer
-     */
-    private historyToExplorerTxs;
-    /**
-     * Build an ExplorerTransaction from a history entry plus the raw tx hex
-     * (when known) and a height→block_time map. Parse errors propagate —
-     * silently returning an empty vout would hide real outputs (e.g. a
-     * deposit) and is far worse for protocol-level money handling than
-     * failing the whole batch.
-     */
-    private buildExplorerTx;
-    /**
-     * Decode `address` into its scriptPubKey, throwing a clear error if the
-     * input is malformed. @scure/btc-signer raises a generic decode error
-     * which is hard to map back to user input — this wraps it.
-     */
-    private encodeAddress;
-    getTxStatus(txid: string): Promise<{
-        confirmed: false;
-    } | {
-        confirmed: true;
-        blockTime: number;
-        blockHeight: number;
-    }>;
-    getChainTip(): Promise<{
-        height: number;
-        time: number;
-        hash: string;
-    }>;
-    watchAddresses(addresses: string[], eventCallback: (txs: ExplorerTransaction[]) => void): Promise<() => void>;
-    /** Close the underlying WebSocket connection. */
-    close(): Promise<void>;
-}
-export {};

package/dist/types/providers/errors.d.ts

@@ -1,13 +0,0 @@
-export declare class ArkError extends Error {
-    readonly code: number;
-    readonly message: string;
-    readonly name: string;
-    readonly metadata?: Record<string, string> | undefined;
-    constructor(code: number, message: string, name: string, metadata?: Record<string, string> | undefined);
-}
-/**
- * Try to convert an error to an ArkError class, returning undefined if the error is not an ArkError
- * @param error - The error to parse
- * @returns The parsed ArkError, or undefined if the error is not an ArkError
- */
-export declare function maybeArkError(error: any): ArkError | undefined;

package/dist/types/providers/expoArk.d.ts

@@ -1,22 +0,0 @@
-import { RestArkProvider, SettlementEvent, TxNotification } from "./ark.js";
-/**
- * Expo-compatible Arkade provider implementation using expo/fetch for SSE support.
- * This provider works specifically in React Native/Expo environments where
- * standard EventSource is not available but expo/fetch provides SSE capabilities.
- *
- * @example
- * ```typescript
- * import { ExpoArkProvider } from '@arkade-os/sdk/providers/expo';
- *
- * const provider = new ExpoArkProvider('https://arkade.computer');
- * const info = await provider.getInfo();
- * ```
- */
-export declare class ExpoArkProvider extends RestArkProvider {
-    constructor(serverUrl: string);
-    getEventStream(signal: AbortSignal, topics: string[]): AsyncIterableIterator<SettlementEvent>;
-    getTransactionsStream(signal: AbortSignal): AsyncIterableIterator<{
-        commitmentTx?: TxNotification;
-        arkTx?: TxNotification;
-    }>;
-}

package/dist/types/providers/expoIndexer.d.ts

@@ -1,18 +0,0 @@
-import { RestIndexerProvider, SubscriptionResponse } from "./indexer.js";
-/**
- * Expo-compatible Indexer provider implementation using expo/fetch for streaming support.
- * This provider works specifically in React Native/Expo environments where
- * standard fetch streaming may not work properly but expo/fetch provides streaming capabilities.
- *
- * @example
- * ```typescript
- * import { ExpoIndexerProvider } from '@arkade-os/sdk/adapters/expo';
- *
- * const provider = new ExpoIndexerProvider('https://indexer.example.com');
- * const vtxos = await provider.getVtxos({ scripts: ['script1'] });
- * ```
- */
-export declare class ExpoIndexerProvider extends RestIndexerProvider {
-    constructor(serverUrl: string);
-    getSubscription(subscriptionId: string, abortSignal: AbortSignal): AsyncIterableIterator<SubscriptionResponse>;
-}

package/dist/types/providers/expoUtils.d.ts

@@ -1,18 +0,0 @@
-/**
- * Dynamically imports expo/fetch with fallback to standard fetch.
- * @returns A fetch function suitable for SSE streaming
- */
-export declare function getExpoFetch(options?: {
-    requireExpo?: boolean;
-}): Promise<typeof fetch>;
-/**
- * Generic SSE stream processor using fetch API with ReadableStream.
- * Handles SSE format parsing, buffer management, and abort signals.
- *
- * @param url - The SSE endpoint URL
- * @param abortSignal - Signal to abort the stream
- * @param fetchFn - Fetch function to use (defaults to standard fetch)
- * @param headers - Additional headers to send
- * @param parseData - Function to parse and yield data from SSE events
- */
-export declare function sseStreamIterator<T>(url: string, abortSignal: AbortSignal, fetchFn: typeof fetch, headers: Record<string, string>, parseData: (data: any) => T | null): AsyncGenerator<T, void, unknown>;