@arkade-os/sdk 0.4.15 → 0.4.16

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

@@ -3,8 +3,11 @@ import { TreeNonces, TreePartialSigs } from "../tree/signingSession";
 import { Vtxo } from "./indexer";
 import type { IntentFeeConfig } from "../arkfee";
 import { Intent } from "../intent";
+/** Output requested during settlement or transaction submission. */
 export type Output = {
+    /** Destination address, either onchain or Arkade (offchain). */
     address: string;
+    /** Amount to send in satoshis. */
     amount: bigint;
 };
 export declare enum SettlementEventType {
@@ -44,6 +47,7 @@ export type TreeNoncesEvent = {
     id: string;
     topic: string[];
     txid: string;
+    /** Musig2 public nonces keyed by cosigner public key. */
     nonces: TreeNonces;
 };
 export type BatchStartedEvent = {
@@ -108,53 +112,87 @@ export interface ArkInfo {
     sessionDuration: bigint;
     signerPubkey: string;
     unilateralExitDelay: bigint;
+    /**
+     * Maximum boarding input amount.
+     *
+     * @remarks
+     * `-1` means unlimited, while `0` disables boarding.
+     */
     utxoMaxAmount: bigint;
     utxoMinAmount: bigint;
     version: string;
+    /**
+     * Maximum virtual output amount.
+     *
+     * @remarks
+     * `-1` means unlimited.
+     */
     vtxoMaxAmount: bigint;
     vtxoMinAmount: bigint;
 }
+/** Signed intent payload sent to the Arkade server. */
 export interface SignedIntent<T extends Intent.Message> {
+    /** Base64-encoded signed proof transaction. */
     proof: string;
+    /** Intent message payload associated with the proof. */
     message: T;
 }
+/** Transaction notification emitted by the Arkade server stream. */
 export interface TxNotification {
+    /** Transaction id. */
     txid: string;
+    /** Raw transaction payload. */
     tx: string;
+    /** Virtual outputs spent by the transaction. */
     spentVtxos: Vtxo[];
+    /** Virtual outputs made spendable by the transaction. */
     spendableVtxos: Vtxo[];
+    /** Optional checkpoint transactions associated with the notification. */
     checkpointTxs?: Record<string, {
         txid: string;
         tx: string;
     }>;
 }
 export interface ArkProvider {
+    /** Fetch Arkade server configuration and fee settings. */
     getInfo(): Promise<ArkInfo>;
+    /** Submit a signed Arkade transaction and its checkpoint transactions. */
     submitTx(signedArkTx: string, checkpointTxs: string[]): Promise<{
         arkTxid: string;
         finalArkTx: string;
         signedCheckpointTxs: string[];
     }>;
+    /** Finalize a previously submitted Arkade transaction. */
     finalizeTx(arkTxid: string, finalCheckpointTxs: string[]): Promise<void>;
+    /** Register a signed intent with the Arkade server. */
     registerIntent(intent: SignedIntent<Intent.RegisterMessage>): Promise<string>;
+    /** Delete a previously registered intent. */
     deleteIntent(intent: SignedIntent<Intent.DeleteMessage>): Promise<void>;
+    /** Confirm an already registered intent id. */
     confirmRegistration(intentId: string): Promise<void>;
+    /** Submit musig2 tree nonces for a batch signing session. */
     submitTreeNonces(batchId: string, pubkey: string, nonces: TreeNonces): Promise<void>;
+    /** Submit musig2 partial signatures for a batch signing session. */
     submitTreeSignatures(batchId: string, pubkey: string, signatures: TreePartialSigs): Promise<void>;
+    /** Submit signed forfeit transactions for cooperative settlement. */
     submitSignedForfeitTxs(signedForfeitTxs: string[], signedCommitmentTx?: string): Promise<void>;
+    /** Open the settlement event stream for the given topics. */
     getEventStream(signal: AbortSignal, topics: string[]): AsyncIterableIterator<SettlementEvent>;
+    /** Stream transaction notifications emitted by the Arkade server. */
     getTransactionsStream(signal: AbortSignal): AsyncIterableIterator<{
         commitmentTx?: TxNotification;
         arkTx?: TxNotification;
     }>;
+    /** Fetch pending transactions for a signed get-pending-tx intent. */
     getPendingTxs(intent: SignedIntent<Intent.GetPendingTxMessage>): Promise<PendingTx[]>;
 }
 /**
- * REST-based Ark provider implementation.
+ * REST-based Arkade provider implementation.
+ *
  * @see https://buf.build/arkade-os/arkd/docs/main:ark.v1#ark.v1.ArkService
  * @example
  * ```typescript
- * const provider = new RestArkProvider('https://ark.example.com');
+ * const provider = new RestArkProvider('https://arkade.computer');
  * const info = await provider.getInfo();
  * ```
  */

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

@@ -1,19 +1,53 @@
 import { Intent } from "../intent";
 import { SignedIntent } from "./ark";
+/**
+ * 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 Delegator provider implementation.
+ * REST-based delegation provider implementation.
  * @example
  * ```typescript
  * const provider = new RestDelegatorProvider('https://delegator.example.com');
@@ -23,7 +57,26 @@ export interface DelegatorProvider {
  */
 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/expoArk.d.ts

@@ -1,6 +1,6 @@
 import { RestArkProvider, SettlementEvent, TxNotification } from "./ark";
 /**
- * Expo-compatible Ark provider implementation using expo/fetch for SSE support.
+ * 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.
  *
@@ -8,7 +8,7 @@ import { RestArkProvider, SettlementEvent, TxNotification } from "./ark";
  * ```typescript
  * import { ExpoArkProvider } from '@arkade-os/sdk/providers/expo';
  *
- * const provider = new ExpoArkProvider('https://ark.example.com');
+ * const provider = new ExpoArkProvider('https://arkade.computer');
  * const info = await provider.getInfo();
  * ```
  */

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

@@ -33,6 +33,7 @@ export interface ChainTx {
     txid: string;
     expiresAt: string;
     type: ChainTxType;
+    /** IDs of the transactions in the chain used as input of the current transaction. */
     spends: string[];
 }
 export interface CommitmentTx {
@@ -101,61 +102,163 @@ export interface SubscriptionHeartbeat {
 export interface SubscriptionEvent extends SubscriptionResponse {
     type: "event";
 }
+/**
+ * Filters accepted by `IndexerProvider.getVtxos`.
+ *
+ * @remarks
+ * Exactly one of `scripts` or `outpoints` must be supplied.
+ *
+ * @see IndexerProvider.getVtxos
+ */
 export type GetVtxosOptions = PaginationOptions & {
+    /** Only return spendable virtual outputs. */
     spendableOnly?: boolean;
+    /** Only return spent virtual outputs. */
     spentOnly?: boolean;
+    /** Only return recoverable virtual outputs. */
     recoverableOnly?: boolean;
+    /** Only return pending/preconfirmed virtual outputs. */
     pendingOnly?: boolean;
+    /** Only return virtual outputs created after this timestamp. */
     after?: number;
+    /** Only return virtual outputs created before this timestamp. */
     before?: number;
 } & ({
+    /** Scripts to search for matching virtual outputs. */
     scripts: string[];
     outpoints?: never;
 } | {
+    /** Explicit outpoints to fetch. */
     outpoints: Outpoint[];
     scripts?: never;
 });
 export interface IndexerProvider {
+    /**
+     * Fetch the virtual output tree for a batch outpoint.
+     *
+     * @param batchOutpoint - Batch outpoint whose tree should be fetched
+     * @param opts - Optional pagination settings
+     * @returns virtual output tree nodes and optional pagination state
+     */
     getVtxoTree(batchOutpoint: Outpoint, opts?: PaginationOptions): Promise<{
         vtxoTree: Tx[];
         page?: PageResponse;
     }>;
+    /**
+     * Fetch the leaf outpoints for a batch virtual output tree.
+     *
+     * @param batchOutpoint - Batch outpoint whose leaf outpoints should be fetched
+     * @param opts - Optional pagination settings
+     * @returns Leaf outpoints and optional pagination state
+     */
     getVtxoTreeLeaves(batchOutpoint: Outpoint, opts?: PaginationOptions): Promise<{
         leaves: Outpoint[];
         page?: PageResponse;
     }>;
+    /**
+     * Fetch sweep transactions that spent a batch.
+     *
+     * @param batchOutpoint - Batch outpoint to inspect
+     * @returns Sweep transaction ids
+     */
     getBatchSweepTransactions(batchOutpoint: Outpoint): Promise<{
         sweptBy: string[];
     }>;
+    /**
+     * Fetch a commitment transaction by txid.
+     *
+     * @param txid - Commitment transaction id
+     * @returns Commitment transaction details
+     */
     getCommitmentTx(txid: string): Promise<CommitmentTx>;
+    /**
+     * Fetch connector transactions for a commitment transaction.
+     *
+     * @param txid - Commitment transaction id
+     * @param opts - Optional pagination settings
+     * @returns Connector transactions and optional pagination state
+     */
     getCommitmentTxConnectors(txid: string, opts?: PaginationOptions): Promise<{
         connectors: Tx[];
         page?: PageResponse;
     }>;
+    /**
+     * Fetch forfeit transaction ids for a commitment transaction.
+     *
+     * @param txid - Commitment transaction id
+     * @param opts - Optional pagination settings
+     * @returns Forfeit transaction ids and optional pagination state
+     */
     getCommitmentTxForfeitTxs(txid: string, opts?: PaginationOptions): Promise<{
         txids: string[];
         page?: PageResponse;
     }>;
+    /**
+     * Open a streamed subscription for a previously created subscription id.
+     *
+     * @param subscriptionId - Subscription identifier returned by `subscribeForScripts`
+     * @param abortSignal - Signal used to terminate the stream
+     * @returns Async iterator of subscription responses
+     */
     getSubscription(subscriptionId: string, abortSignal: AbortSignal): AsyncIterableIterator<SubscriptionResponse>;
+    /**
+     * Fetch raw virtual transactions by txid.
+     *
+     * @param txids - Virtual transaction ids to fetch
+     * @param opts - Optional pagination settings
+     * @returns Raw virtual transactions and optional pagination state
+     */
     getVirtualTxs(txids: string[], opts?: PaginationOptions): Promise<{
         txs: string[];
         page?: PageResponse;
     }>;
+    /**
+     * Fetch the ancestry chain for a virtual output.
+     *
+     * @param vtxoOutpoint - Virtual output outpoint to inspect
+     * @param opts - Optional pagination settings
+     * @returns Chain data and optional pagination state
+     */
     getVtxoChain(vtxoOutpoint: Outpoint, opts?: PaginationOptions): Promise<VtxoChain>;
+    /**
+     * Fetch virtual outputs by script set or outpoints.
+     *
+     * @param opts - Virtual output filters and pagination settings
+     * @returns Virtual outputs and optional pagination state
+     */
     getVtxos(opts?: GetVtxosOptions): Promise<{
         vtxos: VirtualCoin[];
         page?: PageResponse;
     }>;
+    /**
+     * Fetch metadata for a specific asset id.
+     *
+     * @param assetId - Asset identifier
+     * @returns Asset details
+     */
     getAssetDetails(assetId: string): Promise<AssetDetails>;
+    /**
+     * Create or extend a subscription for a set of scripts.
+     *
+     * @param scripts - Scripts to monitor
+     * @param subscriptionId - Existing subscription id to extend
+     * @returns Subscription id
+     */
     subscribeForScripts(scripts: string[], subscriptionId?: string): Promise<string>;
+    /**
+     * Remove some or all scripts from an existing subscription.
+     *
+     * @param subscriptionId - Subscription identifier to update
+     * @param scripts - Scripts to remove, or omit to remove all
+     */
     unsubscribeForScripts(subscriptionId: string, scripts?: string[]): Promise<void>;
 }
 /**
- * REST-based Indexer provider implementation.
+ * REST-based indexer provider implementation.
  * @see https://buf.build/arkade-os/arkd/docs/main:ark.v1#ark.v1.IndexerService
  * @example
  * ```typescript
- * const provider = new RestIndexerProvider('https://ark.indexer.example.com');
+ * const provider = new RestIndexerProvider('https://arkade.computer');
  * const commitmentTx = await provider.getCommitmentTx("6686af8f3be3517880821f62e6c3d749b9d6713736a1d8e229a55daa659446b2");
  * ```
  */

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

@@ -16,14 +16,57 @@ export type ExplorerTransaction = {
     };
 };
 export interface OnchainProvider {
+    /**
+     * Fetch spendable onchain outputs for an address.
+     *
+     * @param address - Bitcoin address to query
+     * @returns Spendable onchain outputs for the address
+     * @see Coin
+     */
     getCoins(address: string): Promise<Coin[]>;
+    /**
+     * Fetch the current fastest fee rate estimate.
+     *
+     * @returns Fee rate in sats/vB, if available
+     * @remarks
+     * Implementations may return `undefined` when the backing service does not expose
+     * a usable fee estimate.
+     */
     getFeeRate(): Promise<number | undefined>;
+    /**
+     * Broadcast a single transaction or a 1P1C package.
+     *
+     * @param txs - One or more raw transaction hex strings
+     * @returns Broadcast transaction id
+     * @throws Error if the broadcast request fails or the package shape is invalid
+     */
     broadcastTransaction(...txs: string[]): Promise<string>;
+    /**
+     * Fetch outspend information for every output in a transaction.
+     *
+     * @param txid - Transaction id to inspect
+     * @returns Per-output spend status information
+     * @see getTxStatus
+     */
     getTxOutspends(txid: string): Promise<{
         spent: boolean;
         txid: string;
     }[]>;
+    /**
+     * Fetch transactions associated with an address.
+     *
+     * @param address - Bitcoin address to query
+     * @returns Transactions involving the address
+     * @see ExplorerTransaction
+     */
     getTransactions(address: string): Promise<ExplorerTransaction[]>;
+    /**
+     * Fetch confirmation status for a transaction.
+     *
+     * @param txid - Transaction id to inspect
+     * @returns Confirmation status and block metadata when confirmed
+     * @see getTxOutspends
+     */
     getTxStatus(txid: string): Promise<{
         confirmed: false;
     } | {
@@ -31,20 +74,36 @@ export interface OnchainProvider {
         blockTime: number;
         blockHeight: number;
     }>;
+    /**
+     * Fetch the current chain tip.
+     *
+     * @returns Current chain height, block time, and block hash
+     */
     getChainTip(): Promise<{
         height: number;
         time: number;
         hash: string;
     }>;
+    /**
+     * Watch a set of addresses and invoke the callback when transactions are observed.
+     *
+     * @param addresses - Addresses to monitor
+     * @param eventCallback - Callback invoked when matching transactions are seen
+     * @returns Stop function that cancels the watch
+     * @remarks
+     * Implementations may use websockets, server-sent events, polling, or a hybrid strategy.
+     * @see getTransactions
+     */
     watchAddresses(addresses: string[], eventCallback: (txs: ExplorerTransaction[]) => void): Promise<() => void>;
 }
 /**
  * Implementation of the onchain provider interface for esplora REST API.
+ *
  * @see https://mempool.space/docs/api/rest
  * @example
  * ```typescript
  * const provider = new EsploraProvider("https://mempool.space/api");
- * const utxos = await provider.getCoins("bcrt1q679zsd45msawvr7782r0twvmukns3drlstjt77");
+ * const outputs = await provider.getCoins("bcrt1q679zsd45msawvr7782r0twvmukns3drlstjt77");
  * ```
  */
 export declare class EsploraProvider implements OnchainProvider {
@@ -52,7 +111,9 @@ export declare class EsploraProvider implements OnchainProvider {
     readonly pollingInterval: number;
     readonly forcePolling: boolean;
     constructor(baseUrl: string, opts?: {
+        /** Polling interval in milliseconds. */
         pollingInterval?: number;
+        /** Force polling even when websocket transport is available. */
         forcePolling?: boolean;
     });
     getCoins(address: string): Promise<Coin[]>;

package/dist/types/repositories/realm/schemas.d.ts

@@ -1,5 +1,5 @@
 /**
- * Realm object schemas for the Ark wallet.
+ * Realm object schemas for the Arkade wallet.
  *
  * All schema names are prefixed with "Ark" to avoid collisions with
  * other Realm schemas in the consuming application.
@@ -108,7 +108,7 @@ export declare const ArkContractSchema: {
     };
 };
 /**
- * All Realm schemas needed by the Ark wallet repositories.
+ * All Realm schemas needed by the Arkade wallet repositories.
  * Pass this array to your Realm configuration's `schema` property.
  */
 export declare const ArkRealmSchemas: ({

package/dist/types/repositories/realm/types.d.ts

@@ -1,13 +1,13 @@
 /**
  * Minimal interface for the subset of the Realm API used by the
- * Ark repositories.  Consumers pass their real Realm instance and
+ * Arkade repositories. Consumers pass their real Realm instance and
  * the compiler validates it satisfies this shape.
  */
 /** Result set returned by `realm.objects()`. */
 export interface RealmResults<T = Record<string, unknown>> extends Iterable<T> {
     filtered(query: string, ...args: unknown[]): RealmResults<T>;
 }
-/** The Realm API surface used by Ark repositories. */
+/** The Realm API surface used by Arkade repositories. */
 export interface RealmLike {
     write(callback: () => void): void;
     objects<T = Record<string, unknown>>(schemaName: string): RealmResults<T>;

package/dist/types/repositories/walletRepository.d.ts

@@ -1,10 +1,15 @@
 import { ArkTransaction, ExtendedCoin, ExtendedVirtualCoin } from "../wallet";
 export interface WalletState {
+    /** Timestamp of the last successful wallet sync, in milliseconds. */
     lastSyncTime?: number;
+    /** Arbitrary stored wallet settings. */
     settings?: Record<string, any>;
 }
+/** Stored commitment transaction metadata. */
 export type CommitmentTxRecord = {
+    /** Commitment transaction id. */
     txid: string;
+    /** Creation timestamp in milliseconds. */
     createdAt: number;
 };
 export interface WalletRepository extends AsyncDisposable {
@@ -13,15 +18,26 @@ export interface WalletRepository extends AsyncDisposable {
      * Clear all data from storage.
      */
     clear(): Promise<void>;
+    /** Fetch stored virtual outputs for an address. */
     getVtxos(address: string): Promise<ExtendedVirtualCoin[]>;
+    /** Save virtual outputs for an address. */
     saveVtxos(address: string, vtxos: ExtendedVirtualCoin[]): Promise<void>;
+    /** Delete stored virtual outputs for an address. */
     deleteVtxos(address: string): Promise<void>;
+    /** Fetch stored boarding inputs for an address. */
     getUtxos(address: string): Promise<ExtendedCoin[]>;
+    /** Save boarding inputs for an address. */
     saveUtxos(address: string, utxos: ExtendedCoin[]): Promise<void>;
+    /** Delete stored boarding inputs for an address. */
     deleteUtxos(address: string): Promise<void>;
+    /** Fetch stored transaction history for an address. */
     getTransactionHistory(address: string): Promise<ArkTransaction[]>;
+    /** Save transaction history for an address. */
     saveTransactions(address: string, txs: ArkTransaction[]): Promise<void>;
+    /** Delete stored transaction history for an address. */
     deleteTransactions(address: string): Promise<void>;
+    /** Fetch stored wallet state. */
     getWalletState(): Promise<WalletState | null>;
+    /** Save wallet state. */
     saveWalletState(state: WalletState): Promise<void>;
 }

package/dist/types/script/address.d.ts

@@ -1,12 +1,19 @@
 import { Bytes } from "@scure/btc-signer/utils.js";
 /**
- * ArkAddress allows to create and decode bech32m encoded ark address.
- * An ark address is composed of:
+ * ArkAddress allows creating and decoding bech32m-encoded Arkade addresses.
+ *
+ * An Arkade address is composed of:
  * - a human readable prefix (hrp)
  * - a version byte (1 byte)
  * - a server public key (32 bytes)
  * - a vtxo taproot public key (32 bytes)
  *
+ * @remarks
+ * This is an Arkade-specific address format.
+ * It is distinct from the Taproot onchain address returned by `VtxoScript.onchainAddress`.
+ *
+ * @see VtxoScript
+ *
  * @example
  * ```typescript
  * const address = new ArkAddress(
@@ -26,9 +33,35 @@ export declare class ArkAddress {
     readonly vtxoTaprootKey: Bytes;
     readonly hrp: string;
     readonly version: number;
+    /**
+     * Create an Arkade address from its server key, vtxo taproot public key, and prefix.
+     *
+     * @param serverPubKey - 32-byte Arkade server public key
+     * @param vtxoTaprootKey - 32-byte tweaked vtxo taproot public key
+     * @param hrp - Bech32 human-readable prefix
+     * @param version - Address version byte
+     * @defaultValue `version = 0`
+     * @throws Error if either public key is not 32 bytes long
+     */
     constructor(serverPubKey: Bytes, vtxoTaprootKey: Bytes, hrp: string, version?: number);
+    /**
+     * Decode an Arkade address from its bech32m string form.
+     *
+     * @param address - Bech32m-encoded Arkade address
+     * @returns Decoded Arkade address
+     * @throws Error if the address is malformed or has an invalid payload length
+     * @see encode
+     */
     static decode(address: string): ArkAddress;
+    /**
+     * Encode the address to its bech32m string form.
+     *
+     * @returns Bech32m-encoded Arkade address
+     * @see decode
+     */
     encode(): string;
+    /** ScriptPubKey used to send non-dust funds to the address. */
     get pkScript(): Bytes;
+    /** ScriptPubKey used to send sub-dust funds to the address. */
     get subdustPkScript(): Bytes;
 }