@arkade-os/sdk 0.5.0-rc.3 → 0.5.0-rc.30

package/README.md

@@ -306,6 +306,8 @@ const wallet = await OnchainWallet.create(identity, 'bitcoin', provider)
 await provider.close()
 ```
 
+Where the network is only known at runtime (`Wallet.create`, or a service worker's `MessageBus`), pass a factory instead: `onchainProvider: (network) => new ElectrumOnchainProvider(new ElectrumWS(ELECTRUM_WS_URL[network]), networks[network])`. A `MessageBus` calls it on every init and never closes what it returns, so a worker should hand back one instance per network rather than a new connection each time.
+
 #### Atomic 1P1C package broadcast (TRUC / BIP 431)
 
 Both providers expose `broadcastTransaction(...txs)` that accepts either a single tx or a 1P1C package (parent first, child last). The package path is **atomic** — the parent doesn't have to independently meet mempool minfee, which is the point of TRUC relay.
@@ -591,7 +593,6 @@ Access the `VtxoManager` from the wallet after configuring `settlementConfig`:
 const manager = await wallet.getVtxoManager()
 ```
 
-> **Migration from `renewalConfig`:** Directly initializing a `VtxoManager` with `renewalConfig` is still supported but deprecated. Prefer `settlementConfig` where `vtxoThreshold` is expressed in **seconds** instead of milliseconds.
 
 #### Renewal: Prevent Expiration
 
@@ -799,6 +800,71 @@ const exitTxid = await new Ramps(wallet).offboard(
 service-worker and Expo wallets too. It answers with the server's live `ArkadeInfo`, falling back
 to the snapshot persisted at wallet construction when the server is unreachable.
 
+### Concurrent Spending & Coin Reservations
+
+By default the wallet runs one spend at a time: a `send` issued while a settle or a collaborative
+exit waits for its batch swap queues until that batch swap finalizes, and an exit with an amount
+spends every spendable VTXO. Opt in to let spends overlap on disjoint VTXOs:
+
+```typescript
+const wallet = await Wallet.create({ identity, arkProvider, concurrentSpending: true })
+```
+
+With `concurrentSpending`:
+
+- `send`, `settle` and asset operations hold the wallet lock only while they pick and reserve their
+  inputs; submitting the Arkade transaction and waiting for the batch swap run unlocked.
+- `Ramps.offboard(address, fees, amount)` and `offboardExact` spend only the VTXOs that cover the
+  amount (soonest expiry first, as `send` picks), so the rest of the balance stays spendable. A
+  full exit, and an exit that names its `vtxos`, behave as before.
+- Naming a VTXO that another operation is spending (`send({ selectedVtxos })`,
+  `settle({ inputs })`) throws `VtxoReservedError` before anything is submitted. Exits that pick
+  their own VTXOs retry the pick.
+- Boarding UTXOs a settle is spending stay in `getBoardingUtxos()` and the boarding balance, but
+  a bare `settle()`, `Ramps.onboard` without explicit UTXOs and the boarding poll skip them until
+  that settle finishes, and naming one elsewhere throws `VtxoReservedError`.
+
+Concurrency only helps when the balance sits in more than one VTXO: a wallet holding a single VTXO
+still has one operation at a time. Renewal and a bare `settle()` merge the VTXOs they spend into
+one output.
+
+#### Holding VTXOs for your own use
+
+`reserveVtxos` keeps VTXOs out of every pick the SDK makes for you — `send`, `settle()`, exits,
+renewal, payment-router rails and swap funding — until you release them. You can still spend them
+by naming them. It works with or without `concurrentSpending`.
+
+```typescript
+const hold = wallet.reserveVtxos(coinsForThisOrder)
+try {
+    await wallet.send({ recipients, selectedVtxos: coinsForThisOrder })
+} finally {
+    hold.release()
+}
+```
+
+Held VTXOs stay in `getVtxos()` and in `getBalance().total`, and move from `available` to
+`reserved`. Holding a VTXO that is held or being spent throws `VtxoReservedError`. If the SDK had
+already picked a VTXO when you hold it, that spend throws `VtxoReservedError` (`holder: "held"`)
+instead of spending it; exits and renewal pick again or retry on their own.
+
+Limits:
+
+- Reservations are in memory, per `Wallet` instance. Two processes or two `Wallet` instances on one
+  seed do not see each other's reservations; the operator refuses whichever spend loses.
+- Deprecated-signer migration and recovery name the VTXOs they move, so they can spend a held VTXO.
+- Renewal skips a held VTXO even once it is inside the renewal threshold, since renewing would
+  change the outpoint you are holding. It logs a warning naming each such VTXO; spend or release a
+  long-lived hold before the VTXO expires, or the server sweeps it and it comes back only through
+  recovery.
+- `toReadonly()` views and the service worker's balance reads do not see reservations.
+- `reserveVtxos` is on `Wallet`; the service-worker and Expo wallets accept `concurrentSpending`
+  but do not expose holds yet.
+
+If your app keeps its own reserved-outpoint set, call `reserveVtxos` where you add to it and
+`release()` where you remove, then let the SDK pick: plain `send`, router payments without
+`selectedVtxos`, and exits without `vtxos` all skip what you hold.
+
 ### Talking to the server through the wallet
 
 `getArkadeInfo()` is one of three seams that let a plugin work from a wallet alone, never a
@@ -1092,6 +1158,37 @@ const balance = await wallet.getBalance()
 For watch-only wallets, use `ServiceWorkerReadonlyWallet` with a
 `ReadonlySingleKey` identity instead.
 
+### Faster startup without changing existing reads
+
+Existing `Wallet` and `ReadonlyWallet` reads (`getVtxos`, `getBalance`, and
+`getTransactionHistory`) still synchronize before answering. Retryable provider
+failures retain the existing offline fallback; terminal errors still reject.
+Contract initialization still awaits synchronization and watcher startup by default.
+
+For a returning wallet with persisted contracts, opt into `lazyInitialization: true`
+and use `getStoredVtxos()` or `getStoredBalance()` for the initial display. These
+methods return cached data and request background synchronization. They can return
+empty or stale data, so inspect `(await wallet.getContractManager()).getSyncState()`:
+an absent `lastSyncedAt` means no successful sync this session, `syncing` means work
+is in flight, and `degraded` means refresh failed. Await `manager.whenBooted()` and
+inspect that state again before treating initialization as successful. Refresh the
+display after completion; cached reads do not guarantee a change event.
+
+`getStoredBalance().boarding.loaded` is false until this wallet instance has fetched
+boarding inputs. Call `getBoardingUtxos()` to refresh them. Stored methods are for
+display, not transaction inputs; use the normal reads and spending APIs for actions.
+New contract registration, identity setup, and server-info validation can still
+require provider calls even with lazy initialization enabled.
+
+Service-worker factories expose the same `lazyInitialization` option and a separate
+`lazyBoarding: true` option. Lazy boarding defers the explorer-backed boarding and
+history refresh, reports `boarding.loaded: false`, and broadcasts `UTXO_UPDATE`
+when boarding loading completes. Both options default to false and survive worker
+reinitialization. Existing `GET_BOARDING_UTXOS` requests remain live reads.
+
+Boarding addresses are fetched concurrently in both modes, so wallets with rotated
+addresses benefit without opting into changed initialization timing.
+
 ### Worker Architecture
 
 The _worker_ captures the background processing infrastructure for the SDK.
@@ -1109,78 +1206,50 @@ examples.
 
 ### Repositories (Storage)
 
-The `StorageAdapter` API is deprecated. Use repositories instead. If you omit `storage`, the SDK uses IndexedDB repositories with the default database name.
-
-#### Migration from v1 StorageAdapter
-
-> [!WARNING]
-> If you previously used the v1 `StorageAdapter`-based repositories, migrate
-> data into the new IndexedDB repositories before use:
->
-> ```typescript
-> import {
->   IndexedDBWalletRepository,
->   IndexedDBContractRepository,
->   getMigrationStatus,
->   migrateWalletRepository,
->   rollbackMigration,
-> } from '@arkade-os/sdk'
-> import { IndexedDBStorageAdapter } from '@arkade-os/sdk/adapters/indexedDB'
->
-> const oldStorage = new IndexedDBStorageAdapter('legacy-wallet', 1)
-> const newDbName = 'my-app-db'
-> const walletRepository = new IndexedDBWalletRepository(newDbName)
->
-> // Check migration status before running
-> const status = await getMigrationStatus('wallet', oldStorage)
-> // status: "not-needed" | "pending" | "in-progress" | "done"
->
-> if (status === 'pending' || status === 'in-progress') {
->   try {
->     await migrateWalletRepository(oldStorage, walletRepository, {
->       onchain: [ 'address-1', 'address-2' ],
->       offchain: [ 'onboarding-address-1' ],
->     })
->   } catch (err) {
->     // Reset migration flag so the next attempt starts clean
->     await rollbackMigration('wallet', oldStorage)
->     throw err
->   }
-> }
-> ```
->
-> **Migration status helpers:**
->
-> | Helper | Description |
-> |--------|-------------|
-> | `getMigrationStatus(repoType, adapter)` | Returns `"not-needed"` (no legacy DB), `"pending"`, `"in-progress"` (interrupted), or `"done"` |
-> | `requiresMigration(repoType, adapter)` | Returns `true` if status is `"pending"` or `"in-progress"` |
-> | `rollbackMigration(repoType, adapter)` | Removes the migration flag so migration can re-run from scratch |
-> | `MIGRATION_KEY(repoType)` | Returns the storage key used for the migration flag |
->
-> `migrateWalletRepository` sets an `"in-progress"` flag before copying data.
-> If the process crashes mid-way, the flag remains as `"in-progress"` so the
-> next call to `getMigrationStatus` can detect the partial migration. Old data
-> is never deleted — re-running migration after a rollback is safe.
->
-> Anything related to contract repository migration must be handled by the
-> package that created the contracts. The SDK doesn't manage external contracts
-> in V1; data persisted by other packages remains untouched in its original
-> location.
+Use repository implementations via `StorageConfig`. If you omit `storage`, the
+SDK uses IndexedDB repositories with the default database name.
+
+#### Paged repository reads
+
+Collection repositories expose `getVtxosPage`, `getVtxosForScriptPage`, `getUtxosPage`,
+`getTransactionHistoryPage`, `getContractsPage`, and `getIntentsPage`.
+Each accepts `{ limit, after? }` and returns
+`{ items, nextCursor? }`; pass `nextCursor` as `after` until it is absent.
+Limits must be 1–500. History pages are ordered by `(createdAt, transaction key)`;
+`since` is inclusive Unix milliseconds. Contract and intent pages are ordered
+by their script and intent transaction ID. Filters must stay the same across
+pages. Repository collection reads use pages directly; `collectVtxos`,
+`collectScriptVtxos`, `collectUtxos`, `collectTransactionHistory`, `collectContracts`, and
+`collectIntents` traverse all pages when a complete snapshot is required.
+Wallet spending paths consume every VTXO or UTXO page before coin selection.
+In `@arkade-os/swap`, RFQ page `since` values use Unix seconds instead.
+
+```ts
+let after;
+do {
+  const page = await walletRepo.getTransactionHistoryPage(
+    { address, since: Date.now() - 86_400_000 },
+    { limit: 100, after },
+  );
+  for (const transaction of page.items) handle(transaction);
+  after = page.nextCursor;
+} while (after);
+```
 
 #### Repository Versioning
 
-`WalletRepository`, `ContractRepository`, and `AssetSwapRepository` (in
-`@arkade-os/swap`) each declare a `readonly version` field with a literal
-type. All built-in implementations set this to the current version. If you
-maintain a custom repository implementation, TypeScript will produce a compile
-error when the version is bumped, signaling that a semantic update is required:
+`WalletRepository`, `ContractRepository`, `IntentRepository`,
+`VirtualTxRepository`, and `AssetSwapRepository` (in `@arkade-os/swap`) each
+declare a `readonly version` field with a literal type. All built-in
+implementations set this to the current version. If you maintain a custom
+repository implementation, TypeScript will produce a compile error when the
+version is bumped, signaling that a semantic update is required:
 
 ```typescript
 import { WalletRepository } from '@arkade-os/sdk'
 
 class MyWalletRepository implements WalletRepository {
-  readonly version = 1 // must match the interface's literal type
+  readonly version = 2 // must match the interface's literal type
   // ...
 }
 ```
@@ -1190,17 +1259,21 @@ class MyWalletRepository implements WalletRepository {
 For Node.js or React Native environments, use the SQLite repository with any
 SQLite driver. The SDK accepts a `SQLExecutor` interface — you provide the
 driver, the SDK handles the schema.
+Paged wallet reads require SQLite 3.15.0 or newer because they use
+[row-value comparisons](https://sqlite.org/rowvalue.html#backwards_compatibility).
+The built-in `node:sqlite` module is experimental in Node.js 22.12.x and stable
+from Node.js 22.13.0 onward.
 
 See [examples/node/multiple-wallets.ts](examples/node/multiple-wallets.ts) for
-a full working example using `better-sqlite3`.
+a full working example using `node:sqlite`.
 
 ```typescript
 import { MnemonicIdentity, Wallet } from '@arkade-os/sdk'
 import { SQLiteWalletRepository, SQLiteContractRepository, SQLExecutor } from '@arkade-os/sdk/repositories/sqlite'
-import Database from 'better-sqlite3'
+import { DatabaseSync } from 'node:sqlite'
 
-const db = new Database('my-wallet.sqlite')
-db.pragma('journal_mode = WAL')
+const db = new DatabaseSync('my-wallet.sqlite')
+db.exec('PRAGMA journal_mode = WAL')
 
 const executor: SQLExecutor = {
   run: async (sql, params) => { db.prepare(sql).run(...(params ?? [])) },
@@ -1283,6 +1356,7 @@ const wallet = await Wallet.create({
 })
 ```
 
+### Using with Node.js
 ### Using with Node.js
 
 Node.js does not provide a global `EventSource` implementation (24.x has one behind `--experimental-eventsource`). The SDK relies on `EventSource` for Server-Sent Events during settlement (onboarding/offboarding) and contract watching, so tell it which one to use:
@@ -1402,11 +1476,46 @@ When you call `wallet.notifyIncomingFunds()` or use `waitForIncomingFunds()`, it
 
 `watcherConfig.failsafePollIntervalMs` (default `20_000`) controls how often the watcher replays repository changes into contract events; it does not fetch fresh VTXOs from the indexer.
 
+#### Compiler artifacts
+
+Read compiler format v1 JSON with `arkade.programFromArtifact`, which returns a normalized Program at version 1. `arkade.parseArtifact` reads normalized Program JSON and defaults omitted versions to 1. Only version 1 is supported, with typed `{ name, type }` declarations for every constructor parameter and call argument. Explicit version 0 programs, including persisted contracts, are rejected; there is no automatic migration. Older SDKs reject version 1 programs rather than silently reconstructing a different script. An Arkade function and its same-named Taproot leaf share one call, such as `contract.functions.claim(...)`. Standalone Taproot functions use their own names, such as `contract.functions.unilateral()`. Leaf order in the artifact still determines the Taproot tree. This example assumes a `digest: bytes32` constructor and a `claim` function with one `preimage: bytes32` covenant argument; providers, wallet, artifact JSON and matching digest/preimage values are already available.
+
+Declarations retain the compiler's native scalar names: `pubkey`, `signature`, `bytes`, `bytes20`, `bytes32`, `asset`, `int`, `bool` and `AssetGroup`. There are no `hash` or `sig` type aliases. Byte types take `Uint8Array`; `int`, `bool` and `AssetGroup` take `bigint | number`, with `bool` restricted to `0` or `1`. Fixed widths follow the type itself, without extra width or boolean flags. The SDK requires every `pubkey` to be a 32-byte x-only key, although the language treats it as a bytes alias. Structs and arrays retain the compiler's flattened scalar field names and ordering.
+
+The normalized Program remains an SDK representation: compiler `constructorInputs` become `params`, spend groups and leaves become named `functions`, and covenant `arkade` becomes `arkadeScript`. `parseArtifact` and `stringifyArtifact` read and write that normalized representation; `programFromArtifact` reads the compiler format. Existing deployment and call methods use the same syntax for imported and hand-written programs.
+
+Before upgrading a wallet with persisted v0 contracts, back up its contract rows and retain a compatible SDK. After the upgrade, `manager.getUnsupportedContracts()` lists the v0 rows the wallet still holds: they stay stored, but their VTXOs are not synced and they cannot be spent or exited. To recover a contract in v1, reconstruct its program with typed declarations while preserving the stored constructor values, signer keys, leaf order and emulator position. Compile with the stored keys and compare the resulting `pkScript` with the original; reconnecting to a server with new keys or defaults can change the address. Only after the scripts match, register the reconstructed contract: over a v0 row with the same script, `register()` (like `manager.createContract`) replaces the row's params in place, then syncs its VTXOs. The row keeps its history, and its label and metadata unless you pass new ones. It leaves any other existing row unchanged. If the scripts differ, continue managing the contract with the compatible SDK. Changing the version number alone is not a migration.
+
+```typescript
+import { arkade, ArkAddress } from '@arkade-os/sdk'
+
+const program = arkade.programFromArtifact(artifactJson)
+const client = await arkade.Arkade.connect({
+  arkade: arkProvider,
+  emulator: emulatorProvider,
+  indexer: indexerProvider,
+  identity: wallet.identity,
+  contractManager: await wallet.getContractManager(),
+})
+const contract = client.contract(program, { digest })
+await contract.register({ label: 'Hashlock' })
+await wallet.send({ address: contract.address, amount: 10_000 })
+
+// Call after funding appears in contract.getUtxos().
+const { txid } = await contract.functions.claim(preimage)
+  .to(ArkAddress.decode(recipientAddress).pkScript, 10_000n)
+  .send()
+```
+
+The connected server supplies `<SERVER_KEY>` (the reserved `server` parameter in normalized Programs) and `<SERVER_EXIT_DELAY>`; conflicting overrides fail, and time-based delays that are not multiples of 512 seconds fail rather than changing the advertised delay. Resolved bindings are persisted, so restoring the contract keeps its script through server key or policy changes. A declared constructor named `user` defaults to the connected identity; other constructor keys and flattened struct/array fields remain caller-provided, using names such as `owners.0.key`. Child-output placeholders remain explicit `bytes32` constructor bindings. Leaf call inputs used as script operands cannot produce a fixed address and are rejected; raw CSV operands must be canonical BIP68 encodings.
+
+For compiler-derived programs, call arguments are covenant inputs in declaration order, followed by non-signature leaf inputs in declaration order. Same-named inputs in the two scopes remain separate positional arguments. Leaf signatures are PSBT signatures, not condition arguments: `send()` supports the connected identity and infrastructure signers; additional identities and covenant-tweaked leaf keys require explicit PSBT signing via `build()`. Covenant signature arguments remain caller-provided; transaction-bound Arkade `checkSig` signatures require an Arkade-specific digest helper, which is deferred. CSV leaves require aged onchain outputs and cannot use this offchain builder. Typed call validation and these spending limits apply to every normalized Program. The public `SignerRef` union is unchanged; version 1 programs store emulator signer placement in optional `emulatorIndex` metadata.
+
 #### HD look-ahead window
 
 HD wallets (`walletMode: 'hd'`, or an explicit HD `DescriptorProvider`) also watch a band of *unused* offchain receive scripts around their allocation watermark, so a payment to an address that some other party issued from the same seed — a merchant backend such as BTCPay Server, or the .NET SDK driving the same wallet — arrives without the user calling `restore()`. `lookAheadWindow` (default `20`) is the per-side width of that band: the wallet watches `[watermark - N, watermark + N]`. Speculative entries are subscription-only; they become contract rows, and enter balances, only once funded.
 
-The issuer, not the wallet, picks the contract shape, so each index is watched at *every* variant the wallet could own there: `default` and `delegate`, crossed with the unilateral-exit timelock matrix and the operator's current plus deprecated signers. That is the candidate set `restore()` probes too, so watching and restoring cover identical scripts.
+The issuer, not the wallet, picks the contract shape, so each index is watched at *every* variant the wallet could own there: `default` and `delegate`, crossed with the unilateral-exit timelock matrix and the operator's active plus retired signers. That is the candidate set `restore()` probes too, so watching and restoring cover identical scripts.
 
 ```typescript
 const wallet = await Wallet.create({
@@ -1426,6 +1535,35 @@ const swWallet = await ServiceWorkerWallet.setup({
 
 Raise it when the external issuer is expected to burn more than `N` consecutive addresses without any of them being paid — every index in such a run is a miss, and the funded one sits past the band. When that happens the funds are invisible until a `restore()` whose `gapLimit` is large enough to cross the run (`wallet.restore({ gapLimit: 200 })`); a default restore closes its gap window before reaching the funded index. Keep the value modest: the band adds up to `2N + 1` indices × the candidate matrix (typically 1-4 scripts each) to the wallet's subscription.
 
+#### Restoring plugin state
+
+`wallet.restore()` is the explicit imported-wallet recovery boundary. It first restores the
+wallet's own addresses, contracts, history, and balances, then runs every restore hook registered
+for that wallet instance. `Wallet` and `ServiceWorkerWallet` both follow this ordering, and
+concurrent calls coalesce until the hooks finish.
+
+```typescript
+import { registerWalletRestoreHook } from '@arkade-os/sdk'
+
+const unregister = registerWalletRestoreHook(wallet, {
+  id: 'my-plugin',
+  restore: async (restoredWallet) => {
+    await rebuildPluginState(await restoredWallet.getTransactionHistory())
+  },
+})
+
+await wallet.restore()
+```
+
+Registering the same `id` again replaces that hook without changing its position. A run uses a
+stable snapshot, attempts every hook in registration order, and throws an `AggregateError` after
+all failures have been collected. If core recovery fails, hooks do not run. The returned function
+removes only that exact registration and is safe to call more than once.
+
+Hooks do not run during `Wallet.create()`, `ServiceWorkerWallet.setup()`, or ordinary startup. A
+plugin should register before an application calls `restore()` and keep its normal incremental
+reconciliation for state that arrives later.
+
 For advanced use cases, you can access the ContractManager directly to register external contracts:
 
 ```typescript
@@ -1471,7 +1609,7 @@ const paths = manager.getSpendablePaths({
   contractScript: contract.script,
   vtxo,
   collaborative: true,
-  walletPubKey: myPubKey,
+  walletDescriptor: myDescriptor,
 })
 if (paths.length > 0) {
   console.log('Contract is spendable via:', paths[0].leaf)
@@ -1481,7 +1619,7 @@ if (paths.length > 0) {
 const allPaths = await manager.getAllSpendingPaths({
   contractScript: contract.script,
   collaborative: true,
-  walletPubKey: myPubKey,
+  walletDescriptor: myDescriptor,
 })
 
 // Fetch contracts together with their current virtual outputs
@@ -1523,14 +1661,16 @@ versions keep the coverage they have today.
 Most users don't need to touch repositories directly — `Wallet` reads through them and `ContractManager` owns VTXO/contract synchronization into them. They are documented here for advanced integrations (custom storage backends, offline-first apps, repository inspection).
 
 ```typescript
+import { collectContracts, collectTransactionHistory, collectUtxos, collectVtxos } from '@arkade-os/sdk'
+
 // Wallet repository — VTXOs, UTXOs, transaction history, settings
 const addr = await wallet.getAddress()
-const vtxos = await wallet.walletRepository.getVtxos(addr)
-const utxos = await wallet.walletRepository.getUtxos(addr)
-const history = await wallet.walletRepository.getTransactionHistory(addr)
+const vtxos = await collectVtxos(wallet.walletRepository, addr)
+const utxos = await collectUtxos(wallet.walletRepository, addr)
+const history = await collectTransactionHistory(wallet.walletRepository, addr)
 
 // Contract repository — script-keyed contracts (default address, VHTLCs, etc.)
-const contracts = await wallet.contractRepository.getContracts({ type: 'vhtlc' })
+const contracts = await collectContracts(wallet.contractRepository, { type: 'vhtlc' })
 await wallet.contractRepository.saveContract(myContract)
 await wallet.contractRepository.deleteContract(myContract.script)
 ```
@@ -1544,15 +1684,15 @@ This package is developed inside the [arkade-os/ts-sdk](../..) monorepo. See the
 Common package-local commands (run from the repo root):
 
 ```bash
-pnpm -C packages/ts-sdk run typecheck    # Type-check the SDK
-pnpm -C packages/ts-sdk test:unit        # Unit tests, excluding e2e
-pnpm -C packages/ts-sdk test:watch       # Vitest watch mode
-pnpm -C packages/ts-sdk test:coverage    # Coverage report
-pnpm -C packages/ts-sdk docs:build       # Build TypeDoc API docs
-pnpm -C packages/ts-sdk docs:open        # Open API docs in the browser
+pnpm -C packages/sdk run typecheck    # Type-check the SDK
+pnpm -C packages/sdk test:unit        # Unit tests, excluding e2e
+pnpm -C packages/sdk test:watch       # Vitest watch mode
+pnpm -C packages/sdk test:coverage    # Coverage report
+pnpm -C packages/sdk docs:build       # Build TypeDoc API docs
+pnpm -C packages/sdk docs:open        # Open API docs in the browser
 ```
 
-For integration tests, use the root commands (`pnpm run test:integration:ts-sdk` and the `regtest:*:ts-sdk` family) — see the root README.
+For integration tests, use the root commands (`pnpm run test:integration:sdk` and the `regtest:*:sdk` family) — see the root README.
 
 ### Releasing
 

package/dist/adapters/expo.cjs

@@ -1,19 +1,18 @@
 'use strict';
 
-var chunk43XGA362_cjs = require('../chunk-43XGA362.cjs');
-require('../chunk-L4HZK4KK.cjs');
-require('../chunk-UJTYUYY4.cjs');
-require('../chunk-5BLDMQED.cjs');
+var chunkDLHE4RCH_cjs = require('../chunk-DLHE4RCH.cjs');
+require('../chunk-AICUNREA.cjs');
+require('../chunk-ASKOHVGX.cjs');
 
 
 
 Object.defineProperty(exports, "ExpoArkProvider", {
   enumerable: true,
-  get: function () { return chunk43XGA362_cjs.ExpoArkProvider; }
+  get: function () { return chunkDLHE4RCH_cjs.ExpoArkProvider; }
 });
 Object.defineProperty(exports, "ExpoIndexerProvider", {
   enumerable: true,
-  get: function () { return chunk43XGA362_cjs.ExpoIndexerProvider; }
+  get: function () { return chunkDLHE4RCH_cjs.ExpoIndexerProvider; }
 });
 //# sourceMappingURL=expo.cjs.map
 //# sourceMappingURL=expo.cjs.map

package/dist/adapters/expo.d.cts

@@ -1,9 +1,9 @@
-import { r as RestArkProvider, o as SettlementEvent, T as TxNotificationEvent, s as RestIndexerProvider, t as SubscriptionResponse } from '../index-DnNIOqHS.cjs';
-export { u as ArkProvider, v as IndexerProvider } from '../index-DnNIOqHS.cjs';
+import { r as RestArkProvider, o as SettlementEvent, T as TxNotificationEvent, s as RestIndexerProvider, t as SubscriptionEvent, u as SubscriptionHeartbeat } from '../index-DhP68WBD.cjs';
+export { v as ArkProvider, w as IndexerProvider } from '../index-DhP68WBD.cjs';
 import '@scure/btc-signer/utils.js';
-import '@scure/btc-signer/transaction.js';
-import '@scure/btc-signer';
 import '@scure/btc-signer/psbt.js';
+import '@scure/btc-signer';
+import '@scure/btc-signer/transaction.js';
 
 /**
  * Expo-compatible Arkade provider implementation using expo/fetch for SSE support.
@@ -39,7 +39,7 @@ declare class ExpoArkProvider extends RestArkProvider {
  */
 declare class ExpoIndexerProvider extends RestIndexerProvider {
     constructor(serverUrl?: string);
-    getSubscription(subscriptionId: string, abortSignal: AbortSignal): AsyncIterableIterator<SubscriptionResponse>;
+    protected subscriptionStream(url: string, abortSignal: AbortSignal): AsyncIterableIterator<SubscriptionEvent | SubscriptionHeartbeat>;
 }
 
 export { ExpoArkProvider, ExpoIndexerProvider };

package/dist/adapters/expo.d.ts

@@ -1,9 +1,9 @@
-import { r as RestArkProvider, o as SettlementEvent, T as TxNotificationEvent, s as RestIndexerProvider, t as SubscriptionResponse } from '../index-DnNIOqHS.js';
-export { u as ArkProvider, v as IndexerProvider } from '../index-DnNIOqHS.js';
+import { r as RestArkProvider, o as SettlementEvent, T as TxNotificationEvent, s as RestIndexerProvider, t as SubscriptionEvent, u as SubscriptionHeartbeat } from '../index-DhP68WBD.js';
+export { v as ArkProvider, w as IndexerProvider } from '../index-DhP68WBD.js';
 import '@scure/btc-signer/utils.js';
-import '@scure/btc-signer/transaction.js';
-import '@scure/btc-signer';
 import '@scure/btc-signer/psbt.js';
+import '@scure/btc-signer';
+import '@scure/btc-signer/transaction.js';
 
 /**
  * Expo-compatible Arkade provider implementation using expo/fetch for SSE support.
@@ -39,7 +39,7 @@ declare class ExpoArkProvider extends RestArkProvider {
  */
 declare class ExpoIndexerProvider extends RestIndexerProvider {
     constructor(serverUrl?: string);
-    getSubscription(subscriptionId: string, abortSignal: AbortSignal): AsyncIterableIterator<SubscriptionResponse>;
+    protected subscriptionStream(url: string, abortSignal: AbortSignal): AsyncIterableIterator<SubscriptionEvent | SubscriptionHeartbeat>;
 }
 
 export { ExpoArkProvider, ExpoIndexerProvider };

package/dist/adapters/expo.js

@@ -1,6 +1,5 @@
-export { ExpoArkProvider, ExpoIndexerProvider } from '../chunk-G4UPMCKW.js';
-import '../chunk-ERUAQGYF.js';
-import '../chunk-HSG2GQTM.js';
-import '../chunk-NSBPE2FW.js';
+export { ExpoArkProvider, ExpoIndexerProvider } from '../chunk-KK6GXY4L.js';
+import '../chunk-PY3YQNHP.js';
+import '../chunk-G6ZPX2GL.js';
 //# sourceMappingURL=expo.js.map
 //# sourceMappingURL=expo.js.map

package/dist/{asyncStorageTaskQueue-DAs_n1xr.d.ts → asyncStorageTaskQueue-DAVf4Fyy.d.ts}

@@ -1,4 +1,4 @@
-import { c as TaskQueue, a as TaskItem, b as TaskResult } from './taskRunner-F7wNJcF3.js';
+import { a as TaskQueue, c as TaskItem, d as TaskResult } from './taskRunner-DKtBy8Yo.js';
 
 /**
  * Minimal async key-value storage interface.
@@ -46,4 +46,4 @@ declare class AsyncStorageTaskQueue implements TaskQueue {
     private writeList;
 }
 
-export { type AsyncStorageLike as A, AsyncStorageTaskQueue as a };
+export { AsyncStorageTaskQueue as A, type AsyncStorageLike as a };

package/dist/{asyncStorageTaskQueue-DqGRG66E.d.cts → asyncStorageTaskQueue-fkkUPrhz.d.cts}

@@ -1,4 +1,4 @@
-import { c as TaskQueue, a as TaskItem, b as TaskResult } from './taskRunner-BDb5Ee2J.cjs';
+import { a as TaskQueue, c as TaskItem, d as TaskResult } from './taskRunner-C8H3bSsk.cjs';
 
 /**
  * Minimal async key-value storage interface.
@@ -46,4 +46,4 @@ declare class AsyncStorageTaskQueue implements TaskQueue {
     private writeList;
 }
 
-export { type AsyncStorageLike as A, AsyncStorageTaskQueue as a };
+export { AsyncStorageTaskQueue as A, type AsyncStorageLike as a };