@arkade-os/sdk 0.4.14 → 0.4.16

package/dist/types/wallet/wallet.d.ts

@@ -65,6 +65,12 @@ export declare class ReadonlyWallet implements IReadonlyWallet {
         info: import("../providers/ark").ArkInfo;
         delegatorProvider: DelegatorProvider | undefined;
     }>;
+    /**
+     * Create a readonly wallet for querying balances, addresses, and history.
+     *
+     * @param config - Readonly wallet configuration
+     * @returns A readonly wallet instance
+     */
     static create(config: ReadonlyWalletConfig): Promise<ReadonlyWallet>;
     get arkAddress(): ArkAddress;
     /**
@@ -72,13 +78,26 @@ export declare class ReadonlyWallet implements IReadonlyWallet {
      * This is the pkScript hex, used to identify the wallet in ContractManager.
      */
     get defaultContractScript(): string;
+    /** Returns the wallet's Arkade address. */
     getAddress(): Promise<string>;
+    /** Returns the onchain boarding address used to move funds into Arkade. */
     getBoardingAddress(): Promise<string>;
+    /**
+     * Return the wallet's combined onchain and offchain balances.
+     */
     getBalance(): Promise<WalletBalance>;
+    /**
+     * Return virtual outputs tracked by the wallet.
+     *
+     * @param filter - Optional flags controlling whether recoverable or unrolled VTXOs are included
+     */
     getVtxos(filter?: GetVtxosFilter): Promise<ExtendedVirtualCoin[]>;
+    /**
+     * Return wallet transaction history derived from Arkade state and boarding transactions.
+     */
     getTransactionHistory(): Promise<ArkTransaction[]>;
     /**
-     * Delta-sync wallet VTXOs: fetch only changed VTXOs since the last
+     * Delta-sync wallet virtual outputs: fetch only changed virtual outputs since the last
      * cursor, or do a full bootstrap when no cursor exists. Upserts
      * the result into the cache and advances the sync cursors.
      *
@@ -89,16 +108,29 @@ export declare class ReadonlyWallet implements IReadonlyWallet {
     private syncVtxos;
     private doSyncVtxos;
     /**
-     * Clear all VTXO sync cursors, forcing a full re-bootstrap on next sync.
+     * Clear all virtual output sync cursors, forcing a full re-bootstrap on next sync.
      * Useful for recovery after indexer reprocessing or debugging.
      */
     clearSyncCursors(): Promise<void>;
+    /**
+     * Build a transaction history view for the wallet's boarding address.
+     */
     getBoardingTxs(): Promise<{
         boardingTxs: ArkTransaction[];
         commitmentsToIgnore: Set<string>;
     }>;
+    /**
+     * Fetch and cache onchain inputs (UTXOs) received at the boarding address.
+     */
     getBoardingUtxos(): Promise<ExtendedCoin[]>;
+    /**
+     * Subscribe to onchain and offchain notifications for newly received funds.
+     *
+     * @param eventCallback - Callback invoked when matching funds are detected
+     * @returns A function that stops the subscriptions
+     */
     notifyIncomingFunds(eventCallback: (coins: IncomingFunds) => void): Promise<() => void>;
+    /** Fetch Arkade transaction ids that are still pending final settlement. */
     fetchPendingTxs(): Promise<string[]>;
     /**
      * Get all pkScript hex strings for the wallet's own addresses
@@ -108,7 +140,7 @@ export declare class ReadonlyWallet implements IReadonlyWallet {
     getWalletScripts(): Promise<string[]>;
     /**
      * Build a map of scriptHex → VtxoScript for all wallet contracts,
-     * so VTXOs can be extended with the correct tapscript per contract.
+     * so virtual outputs can be extended with the correct tapscript per contract.
      */
     getScriptMap(): Promise<Map<string, DefaultVtxo.Script | DelegateVtxo.Script>>;
     /**
@@ -140,28 +172,30 @@ export declare class ReadonlyWallet implements IReadonlyWallet {
      */
     getContractManager(): Promise<ContractManager>;
     private initializeContractManager;
+    /** Dispose wallet-owned managers and release background resources. */
     dispose(): Promise<void>;
+    /** Async-dispose hook that forwards to `dispose()`. */
     [Symbol.asyncDispose](): Promise<void>;
 }
 /**
- * Main wallet implementation for Bitcoin transactions with Ark protocol support.
- * The wallet does not store any data locally and relies on Ark and onchain
- * providers to fetch UTXOs and VTXOs.
+ * Main wallet implementation for Bitcoin transactions with Arkade protocol support.
+ * The wallet does not store any data locally and relies on Arkade and onchain
+ * providers to fetch onchain and virtual outputs.
  *
  * @example
  * ```typescript
  * // Create a wallet with URL configuration
  * const wallet = await Wallet.create({
- *   identity: SingleKey.fromHex('your_private_key'),
- *   arkServerUrl: 'https://ark.example.com',
+ *   identity: MnemonicIdentity.fromMnemonic('abandon abandon...'),
+ *   arkServerUrl: 'https://arkade.computer',
  *   esploraUrl: 'https://mempool.space/api'
  * });
  *
  * // Or with custom provider instances (e.g., for Expo/React Native)
  * const wallet = await Wallet.create({
- *   identity: SingleKey.fromHex('your_private_key'),
- *   arkProvider: new ExpoArkProvider('https://ark.example.com'),
- *   indexerProvider: new ExpoIndexerProvider('https://ark.example.com'),
+ *   identity: MnemonicIdentity.fromMnemonic('abandon abandon...'),
+ *   arkProvider: new ExpoArkProvider('https://arkade.computer'),
+ *   indexerProvider: new ExpoIndexerProvider('https://arkade.computer'),
  *   esploraUrl: 'https://mempool.space/api'
  * });
  *
@@ -170,9 +204,9 @@ export declare class ReadonlyWallet implements IReadonlyWallet {
  * const boardingAddress = await wallet.getBoardingAddress();
  *
  * // Send bitcoin
- * const txid = await wallet.sendBitcoin({
- *   address: 'tb1...',
- *   amount: 50000
+ * const txid = await wallet.send({
+ *   address: 'ark1q...',
+ *   amount: 50000,
  * });
  * ```
  */
@@ -189,7 +223,7 @@ export declare class Wallet extends ReadonlyWallet implements IWallet {
     private _vtxoManagerInitializing?;
     private _walletAssetManager?;
     /**
-     * Async mutex that serializes all operations submitting VTXOs to the Ark
+     * Async mutex that serializes all operations submitting VTXOs to the Arkade
      * server (`settle`, `send`, `sendBitcoin`). This prevents VtxoManager's
      * background renewal from racing with user-initiated transactions for the
      * same VTXO inputs.
@@ -208,6 +242,19 @@ export declare class Wallet extends ReadonlyWallet implements IWallet {
     get assetManager(): IAssetManager;
     getVtxoManager(): Promise<VtxoManager>;
     dispose(): Promise<void>;
+    /**
+     * Create a full wallet and initialize its background managers.
+     *
+     * @param config - Wallet configuration
+     * @returns A wallet ready to query balances and send transactions
+     * @example
+     * ```typescript
+     * const wallet = await Wallet.create({
+     *   identity,
+     *   arkServerUrl: 'https://arkade.computer',
+     * });
+     * ```
+     */
     static create(config: WalletConfig): Promise<Wallet>;
     /**
      * Convert this wallet to a readonly wallet.
@@ -215,7 +262,7 @@ export declare class Wallet extends ReadonlyWallet implements IWallet {
      * @returns A readonly wallet with the same configuration but readonly identity
      * @example
      * ```typescript
-     * const wallet = await Wallet.create({ identity: SingleKey.fromHex('...'), ... });
+     * const wallet = await Wallet.create({ identity: MnemonicIdentity.fromMnemonic('abandon abandon...'), ... });
      * const readonlyWallet = await wallet.toReadonly();
      *
      * // Can query balance and addresses
@@ -223,25 +270,36 @@ export declare class Wallet extends ReadonlyWallet implements IWallet {
      * const address = await readonlyWallet.getAddress();
      *
      * // But cannot send transactions (type error)
-     * // readonlyWallet.sendBitcoin(...); // TypeScript error
+     * // readonlyWallet.send(...); // TypeScript error
      * ```
      */
     toReadonly(): Promise<ReadonlyWallet>;
+    /** Returns the delegator manager when delegation support is configured. */
     getDelegatorManager(): Promise<IDelegatorManager | undefined>;
     /**
-     * @deprecated Use `send`
-     * @param params
+     * Send bitcoin to an Arkade address.
+     *
+     * @deprecated Use `send`.
+     * @param params - Send parameters
      */
     sendBitcoin(params: SendBitcoinParams): Promise<string>;
+    /**
+     * Settle boarding inputs and/or virtual outputs into a finalized mainnet transaction.
+     *
+     * @param params - Optional settlement inputs and outputs. When omitted, the wallet settles all eligible funds.
+     * @param eventCallback - Optional callback invoked for settlement stream events.
+     * @returns The finalized Arkade transaction id
+     */
     settle(params?: SettleParams, eventCallback?: (event: SettlementEvent) => void): Promise<string>;
     private _settleImpl;
     private handleSettlementFinalizationEvent;
     /**
-     * @implements Batch.Handler interface.
+     * Create a batch event handler for settlement flows.
+     *
      * @param intentId - The intent ID.
-     * @param inputs - The inputs of the intent.
-     * @param session - The musig2 signing session, if not provided, the signing will be skipped.
-     * @param expectedRecipients - Expected recipients to validate in the vtxo tree.
+     * @param inputs - Inputs used by the intent.
+     * @param expectedRecipients - Expected recipients to validate in the virtual output tree.
+     * @param session - Optional musig2 signing session. When omitted, signing steps are skipped.
      */
     createBatchHandler(intentId: string, inputs: ExtendedCoin[], expectedRecipients: Recipient[], session?: SignerSession): Batch.Handler;
     safeRegisterIntent(intent: SignedIntent<Intent.RegisterMessage>): Promise<string>;
@@ -251,7 +309,7 @@ export declare class Wallet extends ReadonlyWallet implements IWallet {
     /**
      * Finalizes pending transactions by retrieving them from the server and finalizing each one.
      * Skips the server check entirely when no send was interrupted (no pending tx flag set).
-     * @param vtxos - Optional list of VTXOs to use instead of retrieving them from the server
+     * @param vtxos - Optional list of virtual outputs to use instead of retrieving them from the server
      * @returns Array of transaction IDs that were finalized
      */
     finalizePendingTxs(vtxos?: ExtendedVirtualCoin[]): Promise<{
@@ -263,24 +321,24 @@ export declare class Wallet extends ReadonlyWallet implements IWallet {
     /**
      * Send BTC and/or assets to one or more recipients.
      *
-     * @param recipients - Array of recipients with their addresses, BTC amounts, and assets
-     * @returns Promise resolving to the ark transaction ID
+     * @param args - Recipients with their addresses, BTC amounts, and assets
+     * @returns Promise resolving to the Arkade transaction ID
      *
      * @example
      * ```typescript
      * const txid = await wallet.send({
-     *     address: 'ark1...',
+     *     address: 'ark1q...',
      *     amount: 1000, // (optional, default to dust) btc amount to send to the output
      *     assets: [{ assetId: 'abc123...', amount: 50 }] // (optional) list of assets to send
      * });
      * ```
      */
-    send(...args: Recipient[]): Promise<string>;
+    send(...args: [Recipient, ...Recipient[]]): Promise<string>;
     private _sendImpl;
     /**
      * Build an offchain transaction from the given inputs and outputs,
-     * sign it, submit to the ark provider, and finalize.
-     * @returns The ark transaction id and server-signed checkpoint PSBTs (for bookkeeping)
+     * sign it, submit to the Arkade provider, and finalize.
+     * @returns The Arkade transaction id and server-signed checkpoint PSBTs (for bookkeeping)
      */
     buildAndSubmitOffchainTx(inputs: ExtendedVirtualCoin[], outputs: TransactionOutput[]): Promise<{
         arkTxid: string;
@@ -290,10 +348,10 @@ export declare class Wallet extends ReadonlyWallet implements IWallet {
     private updateDbAfterSettle;
 }
 /**
- * Select virtual coins to reach a target amount, prioritizing those closer to expiry
- * @param coins List of virtual coins to select from
+ * Select virtual outputs to reach a target amount, prioritizing those closer to expiry
+ * @param coins List of virtual outputs to select from
  * @param targetAmount Target amount to reach in satoshis
- * @returns Selected coins and change amount
+ * @returns Selected virtual outputs and change amount
  */
 export declare function selectVirtualCoins(coins: ExtendedVirtualCoin[], targetAmount: number): {
     inputs: ExtendedVirtualCoin[];

package/dist/types/worker/expo/asyncStorageTaskQueue.d.ts

@@ -32,7 +32,7 @@ export declare class AsyncStorageTaskQueue implements TaskQueue {
     acknowledgeResults(ids: string[]): Promise<void>;
     /**
      * Persist a config blob alongside the queue data.
-     * Used by {@link ExpoWallet.setup} to store the wallet parameters
+     * Used by @see ExpoWallet.setup to store the wallet parameters
      * that the background handler needs to reconstruct providers.
      */
     persistConfig(config: Record<string, unknown> | object): Promise<void>;

package/dist/types/worker/expo/processors/contractPollProcessor.d.ts

@@ -4,7 +4,7 @@ export declare const CONTRACT_POLL_TASK_TYPE = "contract-poll";
  * Polls the indexer for the latest VTXO state of every contract and
  * persists the results to the wallet repository.
  *
- * Replicates the polling subset of {@link ContractManager.initialize}:
+ * Replicates the polling subset of @see ContractManager.initialize:
  * 1. Load all contracts from the contract repository.
  * 2. Mark expired active contracts as inactive.
  * 3. Paginated fetch of spendable VTXOs from the indexer.

package/dist/types/worker/expo/taskRunner.d.ts

@@ -20,9 +20,9 @@ export interface TaskDependencies {
  * A stateless unit that handles one type of task item.
  *
  * Processors must not keep in-memory state across invocations —
- * all coordination lives in the {@link TaskQueue} and repositories.
+ * all coordination lives in the @see TaskQueue and repositories.
  *
- * The `TDeps` parameter defaults to {@link TaskDependencies} but
+ * The `TDeps` parameter defaults to @see TaskDependencies but
  * can be overridden for domain-specific processors (e.g. swap processing).
  */
 export interface TaskProcessor<TDeps = TaskDependencies> {
@@ -34,7 +34,7 @@ export interface TaskProcessor<TDeps = TaskDependencies> {
  *
  * For each task in the inbox:
  * 1. Find the processor whose `taskType` matches `task.type`.
- * 2. Execute it, producing a {@link TaskResult}.
+ * 2. Execute it, producing a @see TaskResult.
  * 3. Push the result to the outbox and remove the task from the inbox.
  *
  * Tasks with no matching processor produce a `"noop"` result.
@@ -42,7 +42,7 @@ export interface TaskProcessor<TDeps = TaskDependencies> {
  */
 export declare function runTasks<TDeps = TaskDependencies>(queue: TaskQueue, processors: TaskProcessor<TDeps>[], deps: TDeps): Promise<TaskResult[]>;
 /**
- * Options for {@link createTaskDependencies}.
+ * Options for @see createTaskDependencies.
  */
 export interface CreateTaskDependenciesOptions {
     walletRepository: WalletRepository;
@@ -52,8 +52,8 @@ export interface CreateTaskDependenciesOptions {
     offchainTapscript: ReadonlyWallet["offchainTapscript"];
 }
 /**
- * Build the {@link TaskDependencies} needed by task processors
- * (e.g. {@link import("./processors").contractPollProcessor}).
+ * Build the @see TaskDependencies needed by task processors
+ * (e.g. `src/worker/expo/processors/contractPollProcessor.ts`)
  *
  * This is the same construction that `defineExpoBackgroundTask` does
  * internally, extracted so that consumers with custom schedulers

package/dist/types/worker/messageBus.d.ts

@@ -22,9 +22,8 @@ export interface MessageHandler<REQ extends RequestEnvelope = RequestEnvelope, R
     readonly messageTag: string;
     /**
      * Called once when the SW is starting up
-     * @param opts.arkProvider
-     * @param opts.wallet Wallet with signature cababilities
-     * @param opts.readonlyWallet Read-only Wallet
+     * @param services - Providers and wallet instances available to the handler.
+     * @param repositories - Repositories available to the handler.
      **/
     start(services: {
         arkProvider: ArkProvider;
@@ -91,8 +90,11 @@ export declare class MessageBus {
     private initialized;
     private readonly buildServicesFn;
     private readonly boundOnMessage;
+    /** Create the service-worker message bus with repositories and handler configuration. */
     constructor(walletRepository: WalletRepository, contractRepository: ContractRepository, { messageHandlers, tickIntervalMs, messageTimeoutMs, debug, buildServices, }: Options);
+    /** Start the message bus and attach service-worker event listeners. */
     start(): Promise<void>;
+    /** Stop the message bus, cancel ticks, and stop all registered handlers. */
     stop(): Promise<void>;
     private scheduleNextTick;
     private runTick;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@arkade-os/sdk",
-  "version": "0.4.14",
-  "description": "Bitcoin wallet SDK with Taproot and Ark integration",
+  "version": "0.4.16",
+  "description": "TypeScript SDK for building Bitcoin wallets using the Arkade protocol",
   "type": "module",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",
@@ -130,12 +130,20 @@
     }
   },
   "keywords": [
-    "bitcoin",
-    "wallet",
-    "taproot",
     "ark",
+    "arkade",
+    "bip39",
+    "bitcoin",
+    "btc",
+    "crypto",
+    "lightning",
     "sdk",
-    "arkade"
+    "stablecoin",
+    "taproot",
+    "typescript",
+    "utxo",
+    "vtxo",
+    "wallet"
   ],
   "author": "Ark Labs",
   "license": "MIT",
@@ -159,11 +167,11 @@
     "test:master": "ARK_ENV=master vitest run",
     "test:unit": "vitest run --exclude test/e2e",
     "test:setup": "node test/setup.mjs",
-    "regtest": "pnpm test:down-docker && pnpm test:build-docker && pnpm test:up-docker && pnpm test:setup-docker",
+    "regtest:start": "./regtest/start-env.sh",
+    "regtest:stop": "./regtest/stop-env.sh",
+    "regtest:clean": "./regtest/clean-env.sh",
+    "regtest": "pnpm regtest:clean && pnpm regtest:start && pnpm test:setup-docker",
     "test:setup-docker": "node test/setup.mjs docker",
-    "test:build-docker": "docker compose -f docker-compose.yml build --no-cache",
-    "test:up-docker": "docker compose -f docker-compose.yml up -d",
-    "test:down-docker": "docker compose -f docker-compose.yml down",
     "test:integration": "vitest run test/e2e/**",
     "test:integration-docker": "ARK_ENV=docker vitest run test/e2e/**",
     "test:watch": "vitest",