@arkade-os/sdk 0.5.0-rc.8 → 0.5.0

package/README.md

@@ -31,6 +31,10 @@ const identity = MnemonicIdentity.fromMnemonic(mnemonic)
 const wallet = await Wallet.create({ identity })  // defaults to mainnet
 ```
 
+`Wallet.create` also accepts short spellings: `service` in place of the
+`arkProvider`/`indexerProvider`/`onchainProvider` trio, `mode` for `walletMode` and
+`settlement` for `settlementConfig`. Setting both spellings of one field throws.
+
 ### Read-Only Wallets (Watch-Only)
 
 The SDK supports read-only wallets that allow you to query wallet state without exposing private keys. This is useful for:
@@ -188,6 +192,7 @@ import {
   BatchSignableIdentity,
   SignRequest,
   isBatchSignable,
+  Transaction,
   Wallet
 } from '@arkade-os/sdk'
 
@@ -249,7 +254,7 @@ Wallets read onchain state (UTXOs, transactions, fee rates, chain tip) through a
 
 If you don't pass a provider explicitly, `OnchainWallet` and `Wallet.create({ ... })` both default to `EsploraProvider` pointing at the URL in `ESPLORA_URL[networkName]`.
 
-> **New:** the interface also requires `getRawTransaction(txid): Promise<Uint8Array>`, the raw wire bytes of a transaction. Emulator v0.0.7+ demands the previous transaction of every input a covenant spend or intent proof carries, and a boarding or commitment parent has no off-chain source. Both shipped providers implement it; a custom `OnchainProvider` has to add it.
+> **Note:** the interface requires `getRawTransaction(txid): Promise<Uint8Array>`, the raw wire bytes of a transaction. Emulator v0.0.7+ demands the previous transaction of every input a covenant spend or intent proof carries, and a boarding or commitment parent has no off-chain source. Both shipped providers implement it; a custom `OnchainProvider` has to add it.
 
 #### Default URLs
 
@@ -306,6 +311,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.
@@ -334,7 +341,7 @@ import { waitForIncomingFunds } from '@arkade-os/sdk'
 const arkadeAddress = await wallet.getAddress()
 const boardingAddress = await wallet.getBoardingAddress()
 console.log('Arkade Address:', arkadeAddress)
-console.log('Boarding (Mainnet) Address:', boardingAddress)
+console.log('Boarding (onchain) Address:', boardingAddress)
 
 const incomingFunds = await waitForIncomingFunds(wallet)
 if (incomingFunds.type === "vtxo") {
@@ -392,33 +399,37 @@ const boardingTxId = await new Ramps(wallet).onboard();
 ### Checking Balance
 
 ```typescript
-// Get detailed balance information
 const balance = await wallet.getBalance()
-console.log('Total Balance:', balance.total)
-console.log('Boarding Total:', balance.boarding.total)
-console.log('Offchain Available:', balance.available)
-console.log('Offchain Settled:', balance.settled)
-console.log('Offchain Preconfirmed:', balance.preconfirmed)
-console.log('Gated by a contract:', balance.gated) // swap escrow, chiefly
-console.log('Locked by an in-flight intent:', balance.intentLocked)
-console.log('Recoverable:', balance.recoverable)
-console.log('Awaiting recovery:', balance.pendingRecovery)
-console.log('Unilaterally exited:', balance.unrolled)
-```
-
-`settled` and `preconfirmed` are the owned offchain buckets this relationship is
-about — `recoverable`, `pendingRecovery` and `unrolled` are the wallet's funds
-too, just held under a different predicate. `available` is what generic spending
-will actually pick, and the difference between the two is accounted for exactly:
+```
+
+| Field | What it holds |
+| --- | --- |
+| `boarding.confirmed` | Confirmed onchain [boarding](#onboarding) funds, ready to settle into virtual outputs. |
+| `boarding.unconfirmed` | Boarding funds still waiting for an onchain confirmation. |
+| `boarding.total` | `confirmed + unconfirmed`. |
+| `boarding.loaded` | Set on cached and service-worker balances: `false` until this instance has fetched boarding inputs, so a zero may only mean "not loaded" ([Faster startup](#faster-startup-without-changing-existing-reads)). |
+| `settled` | Finalized offchain funds the wallet owns, spendable or not. |
+| `preconfirmed` | Owned offchain funds not yet finalized in a batch. |
+| `available` | What `send` and every other automatic coin selection can spend now. |
+| `gated` | Held by a contract that generic spending refuses (chiefly swap escrow); only that contract can spend it ([Contract Management](#contract-management)). |
+| `pendingSettlement` | Committed to an in-flight settlement intent; back in `available` when the intent ends. Always `0` without `storage.intentRepository`. |
+| `reserved` | Held by [`reserveVtxos`](#holding-vtxos-for-your-own-use) until released. |
+| `recoverable` | Swept or subdust virtual outputs that [`recoverVtxos`](#recovery-reclaim-swept-vtxos) can reclaim; `getRecoverableBalance()` gives what a batch would return today. |
+| `pendingRecovery` | Under a server signer past its cutoff, which the operator no longer co-signs; recovers once swept and re-settled. |
+| `unrolled` | Already [unilaterally exited](#unilateral-exit): onchain behind its CSV timelock, movable only by `Unroll.completeUnroll`. |
+| `total` | Everything the wallet owns: `boarding.total + settled + preconfirmed + recoverable + pendingRecovery + unrolled`. |
+| `assets` | Every [asset](#assets-issue-reissue-burn-send) balance the wallet owns. |
+| `availableAssets` | The subset of `assets` generic spending can move: the asset counterpart of `available`. |
+
+`available` is what remains of the owned offchain funds once everything held for a
+cause is taken out:
 
 ```text
-settled + preconfirmed === available + gated + intentLocked
+settled + preconfirmed === available + gated + pendingSettlement + reserved
 ```
 
-`unrolled` holds virtual outputs whose unilateral exit already happened: they sit
-onchain behind their CSV timelock, so nothing offchain can move them and
-`Unroll.completeUnroll` is the only thing that will. They are never `available` and
-never `recoverable` — but they are still your money, so they still count in `total`.
+plus one dust carrier when the wallet holds available assets, since an asset moves
+only with the output that carries it.
 
 To show "your money, minus what is tied up", subtract from `settled + preconfirmed`
 — **not from `total`**, which also contains `boarding.total`, `recoverable`,
@@ -426,10 +437,12 @@ To show "your money, minus what is tied up", subtract from `settled + preconfirm
 from `total` silently drops them from the figure.
 
 ```typescript
-
-// Get virtual outputs (available for offchain spending)
+// Every virtual output the wallet tracks, spendable or not
 const vtxos = await wallet.getVtxos()
 
+// Only those automatic coin selection may pick
+const spendable = await wallet.getSpendableVtxos()
+
 // Get boarding inputs
 const boardingInputs = await wallet.getBoardingUtxos()
 ```
@@ -527,7 +540,7 @@ const [vtxos, boardingInputs] = await Promise.all([
 // For settling transactions
 const settlementTxId = await wallet.settle({
   inputs: [...vtxos, ...boardingInputs],
-  // Optional: specify a mainnet output
+  // Optional: specify an onchain output
   outputs: [{
     address: "bc1p...",
     amount: 100_000n
@@ -609,7 +622,7 @@ const urgentlyExpiring = await manager.getExpiringVtxos(60_000)
 A virtual output whose unilateral exit already happened is never offered for renewal, and the
 exported `isVtxoExpiringSoon` answers `false` for it regardless of its batch expiry: "expiring
 soon" is a renewal signal, and no batch can take an output that already lives onchain. Its remedy
-is `Unroll.completeUnroll`, and its value shows up in `balance.unrolled`.
+is `Unroll.completeUnroll`, and its value shows up in [`balance.unrolled`](#checking-balance).
 
 #### Boarding Input Sweep
 
@@ -798,6 +811,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`](#checking-balance). 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
@@ -901,7 +979,7 @@ switch (step.type) {
     const [parent, child] = step.pkg;
     console.log(`Parent: ${parent}`)
     console.log(`Child: ${child}`)
-    await step.do(); // broadcast the 1C1P package
+    await step.do(); // broadcast the 1P1C package
     break;
   case Unroll.StepType.DONE:
     console.log(`Unrolling complete for VTXO ${step.vtxoTxid}`);
@@ -946,7 +1024,7 @@ The flow is **quote → fund → prepare → execute**:
 ```typescript
 import { UnilateralExit, OnchainWallet, serializeExitPackage } from '@arkade-os/sdk'
 
-const onchainWallet = await OnchainWallet.create(identity, 'mainnet')
+const onchainWallet = await OnchainWallet.create(identity, 'bitcoin')
 
 // 1. Quote: how many txs, how many sats (no funds needed, nothing signed)
 const quote = await UnilateralExit.estimate({
@@ -1064,7 +1142,8 @@ const bus = new MessageBus(walletRepo, contractRepo, {
   tickIntervalMs: 10_000, // default 10s
   // Optional, same opt-in as `storage.intentRepository` on a main-thread
   // wallet. Omit it and the worker persists no settlement intent, reconciles
-  // none on restart, and counts intent-locked VTXOs as available.
+  // none on restart, and counts intent-locked VTXOs as available
+  // (`pendingSettlement` stays 0).
   intentRepository: new IndexedDBIntentRepository(),
 })
 
@@ -1091,6 +1170,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()` (same [fields](#checking-balance) as `getBalance()`) 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.
@@ -1111,6 +1221,33 @@ examples.
 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`, `IntentRepository`,
@@ -1124,7 +1261,7 @@ version is bumped, signaling that a semantic update is required:
 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
   // ...
 }
 ```
@@ -1134,17 +1271,19 @@ 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).
 
 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 ?? [])) },
@@ -1227,7 +1366,6 @@ 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:
@@ -1347,6 +1485,47 @@ 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.
 
+To watch transactions at scripts you don't know in advance (extension packets at someone else's offer, say), `indexerProvider.getFilteredSubscription(filter, signal)` streams what a server-side CEL filter matches. It yields `SubscriptionEvent | SubscriptionHeartbeat`, so check `type === "event"` before reading `tx`. A custom `IndexerProvider` must implement it.
+
+#### 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; 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, Arkade, ArkAddress } from '@arkade-os/sdk'
+
+const program = arkade.programFromArtifact(artifactJson)
+const client = await Arkade.connect({
+  service: { network: 'bitcoin' }, // operator, indexer, esplora and covenant co-signer
+  identity: wallet.identity,
+  contractManager: await wallet.getContractManager(),
+})
+const contract = client.contract(program, { digest })
+await contract.register({ label: 'Hashlock' })
+
+const funded = await contract.on('vtxo_received', async () => {
+  funded.off()
+  const { txid } = await contract.functions.claim(preimage)
+    .to(ArkAddress.decode(recipientAddress).pkScript, 10_000n)
+    .send()
+})
+await wallet.send({ address: contract.address, amount: 10_000 })
+```
+
+`service` takes `{ network }` for the reference deployment or `{ operatorUrl, emulatorUrl? }` for a custom one, whose covenant paths stay disabled without `emulatorUrl`; passing the `arkade`/`emulator`/`indexer` providers yourself still works. Without a wallet, pass `storage: { contractRepository }` instead of `contractManager`: the client then owns a session-scoped manager, which `client.dispose()` stops.
+
+`contract.on('vtxo_received' | 'vtxo_spent' | 'connection_reset', cb)` reports activity from subscription on and returns a handle with `off()`. Coins that predate it are not replayed and a reconnect re-syncs silently, so read `contract.getVtxos()` (every stored VTXO, spent ones included) after subscribing and on each `connection_reset`.
+
+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.
@@ -1424,7 +1603,7 @@ const contract = await manager.createContract({
 })
 
 // Listen for all contracts events (wallet address + external contracts)
-const unsubscribe = await manager.onContractEvent((event) => {
+const unsubscribe = manager.onContractEvent((event) => {
   switch (event.type) {
     case 'vtxo_received':
       console.log(`Received ${event.vtxos.length} virtual outputs to ${event.contractScript}`)
@@ -1441,7 +1620,7 @@ await manager.updateContractParams(contract.script, { preimage: revealedPreimage
 // Check spendable paths (requires a specific virtual output)
 const [withVtxos] = await manager.getContractsWithVtxos({ script: contract.script })
 const vtxo = withVtxos.vtxos[0]
-const paths = manager.getSpendablePaths({
+const paths = await manager.getSpendablePaths({
   contractScript: contract.script,
   vtxo,
   collaborative: true,
@@ -1497,14 +1676,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)
 ```
@@ -1518,15 +1699,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 [CONTRIBUTING.md](../../CONTRIBUTING.md).
 
 ### Releasing
 

package/dist/adapters/expo.cjs

@@ -1,18 +1,18 @@
 'use strict';
 
-var chunk56RCBKNF_cjs = require('../chunk-56RCBKNF.cjs');
-require('../chunk-2AWDPVZI.cjs');
-require('../chunk-NY5FN4VV.cjs');
+var chunkJT5YVMCJ_cjs = require('../chunk-JT5YVMCJ.cjs');
+require('../chunk-IQWLFYT2.cjs');
+require('../chunk-UUSKJOSX.cjs');
 
 
 
 Object.defineProperty(exports, "ExpoArkProvider", {
   enumerable: true,
-  get: function () { return chunk56RCBKNF_cjs.ExpoArkProvider; }
+  get: function () { return chunkJT5YVMCJ_cjs.ExpoArkProvider; }
 });
 Object.defineProperty(exports, "ExpoIndexerProvider", {
   enumerable: true,
-  get: function () { return chunk56RCBKNF_cjs.ExpoIndexerProvider; }
+  get: function () { return chunkJT5YVMCJ_cjs.ExpoIndexerProvider; }
 });
 //# sourceMappingURL=expo.cjs.map
 //# sourceMappingURL=expo.cjs.map

package/dist/adapters/expo.d.cts

@@ -1,9 +1,9 @@
-import { q as RestArkProvider, n as SettlementEvent, T as TxNotificationEvent, r as RestIndexerProvider, s as SubscriptionResponse } from '../index-BIL9boGL.cjs';
-export { t as ArkProvider, u as IndexerProvider } from '../index-BIL9boGL.cjs';
+import { r as RestArkProvider, o as SettlementEvent, T as TxNotificationEvent, s as RestIndexerProvider, t as SubscriptionEvent, u as SubscriptionHeartbeat } from '../index-CZw-MMfY.cjs';
+export { v as ArkProvider, w as IndexerProvider } from '../index-CZw-MMfY.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 { q as RestArkProvider, n as SettlementEvent, T as TxNotificationEvent, r as RestIndexerProvider, s as SubscriptionResponse } from '../index-BIL9boGL.js';
-export { t as ArkProvider, u as IndexerProvider } from '../index-BIL9boGL.js';
+import { r as RestArkProvider, o as SettlementEvent, T as TxNotificationEvent, s as RestIndexerProvider, t as SubscriptionEvent, u as SubscriptionHeartbeat } from '../index-CZw-MMfY.js';
+export { v as ArkProvider, w as IndexerProvider } from '../index-CZw-MMfY.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,5 +1,5 @@
-export { ExpoArkProvider, ExpoIndexerProvider } from '../chunk-INTEA7D3.js';
-import '../chunk-G6S4XSFI.js';
-import '../chunk-MTYQXZ2T.js';
+export { ExpoArkProvider, ExpoIndexerProvider } from '../chunk-K2E6X6JT.js';
+import '../chunk-HABGVRLF.js';
+import '../chunk-ZOEB53NQ.js';
 //# sourceMappingURL=expo.js.map
 //# sourceMappingURL=expo.js.map

package/dist/{asyncStorageTaskQueue-CeYTmuGU.d.ts → asyncStorageTaskQueue-BFv2O1y1.d.ts}

@@ -1,4 +1,4 @@
-import { c as TaskQueue, b as TaskItem, d as TaskResult } from './taskRunner-CRbuzUXR.js';
+import { c as TaskQueue, b as TaskItem, d as TaskResult } from './taskRunner-wm1bhmtP.js';
 
 /**
  * Minimal async key-value storage interface.

package/dist/{asyncStorageTaskQueue-Bn3FoNkc.d.cts → asyncStorageTaskQueue-qRRQUOE8.d.cts}

@@ -1,4 +1,4 @@
-import { c as TaskQueue, b as TaskItem, d as TaskResult } from './taskRunner-z_BGID85.cjs';
+import { c as TaskQueue, b as TaskItem, d as TaskResult } from './taskRunner-B3SLvUfL.cjs';
 
 /**
  * Minimal async key-value storage interface.