@arkade-os/sdk 0.5.0-rc.2 → 0.5.0-rc.20

package/README.md

@@ -591,7 +591,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
 
@@ -1109,78 +1108,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 +1161,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 +1258,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:
@@ -1406,7 +1382,7 @@ When you call `wallet.notifyIncomingFunds()` or use `waitForIncomingFunds()`, it
 
 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 +1402,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 +1476,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 +1486,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 +1528,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 +1551,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 chunkHLCGYOIH_cjs = require('../chunk-HLCGYOIH.cjs');
-require('../chunk-NVZJSKZS.cjs');
-require('../chunk-JZWLXNHV.cjs');
-require('../chunk-5BLDMQED.cjs');
+var chunk6YVGWOLG_cjs = require('../chunk-6YVGWOLG.cjs');
+require('../chunk-P42MGA4K.cjs');
+require('../chunk-T6N6B7HK.cjs');
 
 
 
 Object.defineProperty(exports, "ExpoArkProvider", {
   enumerable: true,
-  get: function () { return chunkHLCGYOIH_cjs.ExpoArkProvider; }
+  get: function () { return chunk6YVGWOLG_cjs.ExpoArkProvider; }
 });
 Object.defineProperty(exports, "ExpoIndexerProvider", {
   enumerable: true,
-  get: function () { return chunkHLCGYOIH_cjs.ExpoIndexerProvider; }
+  get: function () { return chunk6YVGWOLG_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-DUxufw76.cjs';
-export { u as ArkProvider, v as IndexerProvider } from '../index-DUxufw76.cjs';
+import { r as RestArkProvider, o as SettlementEvent, T as TxNotificationEvent, s as RestIndexerProvider, t as SubscriptionResponse } from '../index-CK5QbTmZ.cjs';
+export { u as ArkProvider, v as IndexerProvider } from '../index-CK5QbTmZ.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.

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-DUxufw76.js';
-export { u as ArkProvider, v as IndexerProvider } from '../index-DUxufw76.js';
+import { r as RestArkProvider, o as SettlementEvent, T as TxNotificationEvent, s as RestIndexerProvider, t as SubscriptionResponse } from '../index-CK5QbTmZ.js';
+export { u as ArkProvider, v as IndexerProvider } from '../index-CK5QbTmZ.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.

package/dist/adapters/expo.js

@@ -1,6 +1,5 @@
-export { ExpoArkProvider, ExpoIndexerProvider } from '../chunk-ZOTXDOS5.js';
-import '../chunk-4PKLULWT.js';
-import '../chunk-ISO4TI5J.js';
-import '../chunk-NSBPE2FW.js';
+export { ExpoArkProvider, ExpoIndexerProvider } from '../chunk-P267BXL7.js';
+import '../chunk-AARSVV3S.js';
+import '../chunk-NR4XYTN3.js';
 //# sourceMappingURL=expo.js.map
 //# sourceMappingURL=expo.js.map

package/dist/{asyncStorageTaskQueue-C5rBYlru.d.ts → asyncStorageTaskQueue-aL7K14e4.d.ts}

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

package/dist/{asyncStorageTaskQueue-BuDvgWh6.d.cts → asyncStorageTaskQueue-x8ok3tJy.d.cts}

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