@arkade-os/sdk 0.4.66 → 0.4.68

package/README.md

@@ -215,6 +215,29 @@ await wallet.send({ address: 'ark1q...', amount: 1000 })
 
 Identities without `signMultiple` continue to work unchanged — each checkpoint is signed individually via `sign()`.
 
+### Ark Provider Caching
+
+`RestArkProvider.getInfo()` fetches current Arkade server parameters on every call. Wrap it
+with `CachingArkProvider` when you reuse that response for fee, signer, or limit lookups:
+
+```typescript
+import { CachingArkProvider, RestArkProvider, Wallet } from '@arkade-os/sdk'
+
+const arkProvider = new CachingArkProvider(
+  new RestArkProvider('https://arkade.computer'),
+  60_000, // optional TTL in milliseconds; defaults to 60 seconds
+)
+
+const wallet = await Wallet.create({ identity, arkProvider })
+```
+
+Only `getInfo()` is cached; all other Ark provider methods pass through. The cache expires
+after the TTL and updates when the inner provider reports server-info changes, including
+signer rotation. Wrapping `RestArkProvider` preserves its `serverUrl`, so `Wallet.create`
+can still derive the default indexer URL. Expired refresh failures propagate;
+wallet boot fallback lives in the persisted ArkInfo snapshot. Call `dispose()` if the
+inner provider outlives the wrapper, to drop its server-info subscription.
+
 ### Onchain Providers
 
 Wallets read onchain state (UTXOs, transactions, fee rates, chain tip) through an `OnchainProvider`. The SDK ships with two implementations and a single transport-agnostic interface so you can swap them without touching wallet code.
@@ -226,6 +249,8 @@ 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.
+
 #### Default URLs
 
 The SDK ships with reachable defaults for each network — bitcoin, signet, and mutinynet point at Ark Labs–operated deployments; testnet falls back to mempool.space; regtest assumes a local [arkade-regtest](https://github.com/ArkLabsHQ/arkade-regtest) stack (esplora API on `http://localhost:3000/api`).
@@ -345,21 +370,27 @@ 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` and `pendingRecovery` 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:
+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:
 
 ```text
 settled + preconfirmed === available + gated + intentLocked
 ```
 
+`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`.
+
 To show "your money, minus what is tied up", subtract from `settled + preconfirmed`
-— **not from `total`**, which also contains `boarding.total`, `recoverable` and
-`pendingRecovery`. Those are still your funds, so subtracting a bucket from `total`
-silently drops them from the figure.
+— **not from `total`**, which also contains `boarding.total`, `recoverable`,
+`pendingRecovery` and `unrolled`. Those are still your funds, so subtracting a bucket
+from `total` silently drops them from the figure.
 
 ```typescript
 
@@ -543,6 +574,11 @@ const expiringVtxos = await manager.getExpiringVtxos()
 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`.
+
 #### Boarding Input Sweep
 
 When a boarding input's CSV timelock expires, it can no longer be onboarded into Arkade cooperatively. The sweep feature detects these expired UTXOs and builds a raw onchain transaction that spends them via the unilateral exit path back to a fresh boarding address, restarting the timelock.
@@ -747,12 +783,7 @@ const onchainWallet = await OnchainWallet.create(onchainIdentity, 'regtest');
 
 // Unroll a specific virtual output
 const vtxo = { txid: 'your_vtxo_txid', vout: 0 };
-const session = await Unroll.Session.create(
-  vtxo,
-  onchainWallet,
-  onchainWallet.provider,
-  wallet.indexerProvider
-);
+const session = await Unroll.sessionFor(wallet, vtxo, onchainWallet);
 
 // Iterate through the unrolling steps
 for await (const step of session) {
@@ -770,6 +801,24 @@ for await (const step of session) {
 }
 ```
 
+`Unroll.sessionFor` is `Session.create` with the wallet's explorer, indexer and
+virtual-tx cache filled in, plus the exit observer wired: at `StepType.DONE` it re-reads
+the outpoint from the indexer, so the value moves into the `unrolled` balance bucket
+without waiting for a sync that would never bring it. Nothing else would tell the wallet
+— delta sync filters on creation time, so it never sees a status change on an older
+virtual output.
+
+That re-read is a prompt rather than a guarantee: `StepType.DONE` means your Esplora
+endpoint saw the exit confirm, and the Arkade indexer may not have marked the output
+`isUnrolled` yet. The session fires once, so a re-read that lands early simply leaves the
+wallet where it would have been anyway, and the next thing to refresh that outpoint picks
+the exit up. `UnilateralExit` fires twice per virtual output — branch-confirmed and
+sweep-confirmed — and by the sweep the exit has been onchain for at least the CSV delay.
+
+If you hold no `Wallet` — driving an exit from providers alone — build the session with
+the lower-level `Unroll.Session.create(vtxo, bumper, explorer, indexer,
+virtualTxRepository?, onExitObserved?)`, whose last two parameters are optional.
+
 The unrolling process works by:
 
 - Traversing the transaction chain from the root (most recent) to the leaf (oldest)
@@ -819,9 +868,10 @@ await Unroll.completeUnroll(
 
 ### Unilateral Exit Packages (pre-signed)
 
-`Unroll.Session` requires the wallet (keys + indexer access) to stay online for the whole
-multi-day exit. `UnilateralExit` removes that requirement: it pre-signs **every** transaction
-needed to unroll a VTXO's offchain transaction chain onchain **and** sweep each matured output
+`Unroll.sessionFor` (and the `Unroll.Session` it builds) requires the wallet — keys plus
+indexer access — to stay online for the whole multi-day exit. `UnilateralExit` removes that
+requirement: it pre-signs **every** transaction needed to unroll a VTXO's offchain
+transaction chain onchain **and** sweep each matured output
 to an address you solely control, then emits a versioned JSON package that anything with an
 Esplora-compatible endpoint can execute — no keys, no Arkade infrastructure.
 
@@ -858,6 +908,12 @@ for await (const event of executor) {
 }
 ```
 
+Where the executing machine does hold the `Wallet`, `UnilateralExit.execute(wallet, pkg, opts?)`
+returns the same executor with the exit observer already wired, so the repository re-reads each
+branch as it confirms and again as its sweep does — picking the exit up as it lands, indexer lag
+permitting. The same prompt-not-guarantee caveat as `Unroll.sessionFor` above applies, with the
+sweep-confirm re-read as its own retry.
+
 Every exit terminates in a **sweep**. Unrolling only lands a VTXO back onchain still encumbered
 by its Arkade script; the funds become yours unilaterally only once a sweep spends that output
 through the CSV-timelocked exit path to `sweepAddress`. So the package always pairs each exited

package/dist/adapters/expo.cjs

@@ -1,19 +1,19 @@
 'use strict';
 
-var chunkIM6IKNSL_cjs = require('../chunk-IM6IKNSL.cjs');
-require('../chunk-3S3JZUEN.cjs');
-require('../chunk-ZIRFXBKL.cjs');
+var chunkJGMSZIE4_cjs = require('../chunk-JGMSZIE4.cjs');
+require('../chunk-PJR63FTK.cjs');
+require('../chunk-EJOFL5WH.cjs');
 require('../chunk-5BLDMQED.cjs');
 
 
 
 Object.defineProperty(exports, "ExpoArkProvider", {
   enumerable: true,
-  get: function () { return chunkIM6IKNSL_cjs.ExpoArkProvider; }
+  get: function () { return chunkJGMSZIE4_cjs.ExpoArkProvider; }
 });
 Object.defineProperty(exports, "ExpoIndexerProvider", {
   enumerable: true,
-  get: function () { return chunkIM6IKNSL_cjs.ExpoIndexerProvider; }
+  get: function () { return chunkJGMSZIE4_cjs.ExpoIndexerProvider; }
 });
 //# sourceMappingURL=expo.cjs.map
 //# sourceMappingURL=expo.cjs.map

package/dist/adapters/expo.d.cts

@@ -1,5 +1,5 @@
-import { l as RestArkProvider, i as SettlementEvent, T as TxNotificationEvent, m as RestIndexerProvider, n as SubscriptionResponse } from '../index-uUE_uQPn.cjs';
-export { o as ArkProvider, p as IndexerProvider } from '../index-uUE_uQPn.cjs';
+import { n as RestArkProvider, k as SettlementEvent, T as TxNotificationEvent, o as RestIndexerProvider, p as SubscriptionResponse } from '../index-C7RZCfoY.cjs';
+export { q as ArkProvider, r as IndexerProvider } from '../index-C7RZCfoY.cjs';
 import '@scure/btc-signer/utils.js';
 import '@scure/btc-signer/transaction.js';
 import '@scure/btc-signer';

package/dist/adapters/expo.d.ts

@@ -1,5 +1,5 @@
-import { l as RestArkProvider, i as SettlementEvent, T as TxNotificationEvent, m as RestIndexerProvider, n as SubscriptionResponse } from '../index-uUE_uQPn.js';
-export { o as ArkProvider, p as IndexerProvider } from '../index-uUE_uQPn.js';
+import { n as RestArkProvider, k as SettlementEvent, T as TxNotificationEvent, o as RestIndexerProvider, p as SubscriptionResponse } from '../index-C7RZCfoY.js';
+export { q as ArkProvider, r as IndexerProvider } from '../index-C7RZCfoY.js';
 import '@scure/btc-signer/utils.js';
 import '@scure/btc-signer/transaction.js';
 import '@scure/btc-signer';

package/dist/adapters/expo.js

@@ -1,6 +1,6 @@
-export { ExpoArkProvider, ExpoIndexerProvider } from '../chunk-R5POS3RS.js';
-import '../chunk-2JZGPXU4.js';
-import '../chunk-J33ZEM3A.js';
+export { ExpoArkProvider, ExpoIndexerProvider } from '../chunk-G4I6PU5H.js';
+import '../chunk-33Q2RFET.js';
+import '../chunk-4CMXV5SF.js';
 import '../chunk-NSBPE2FW.js';
 //# sourceMappingURL=expo.js.map
 //# sourceMappingURL=expo.js.map

package/dist/adapters/indexedDB.cjs

@@ -1,9 +1,9 @@
 'use strict';
 
-var chunk5E6IZNRG_cjs = require('../chunk-5E6IZNRG.cjs');
-require('../chunk-3S3JZUEN.cjs');
-require('../chunk-PXPPZF5K.cjs');
-require('../chunk-ZIRFXBKL.cjs');
+var chunkWCJVKFAP_cjs = require('../chunk-WCJVKFAP.cjs');
+require('../chunk-PJR63FTK.cjs');
+require('../chunk-6YUACVX4.cjs');
+require('../chunk-EJOFL5WH.cjs');
 require('../chunk-5BLDMQED.cjs');
 
 // src/storage/indexedDB.ts
@@ -11,7 +11,7 @@ var IndexedDBStorageAdapter = class {
   dbName;
   version;
   db = null;
-  constructor(dbName, version = chunk5E6IZNRG_cjs.DB_VERSION) {
+  constructor(dbName, version = chunkWCJVKFAP_cjs.DB_VERSION) {
     this.dbName = dbName;
     this.version = version;
   }

package/dist/adapters/indexedDB.js

@@ -1,7 +1,7 @@
-import { DB_VERSION } from '../chunk-DSC3G6QZ.js';
-import '../chunk-2JZGPXU4.js';
-import '../chunk-CYOI4PEA.js';
-import '../chunk-J33ZEM3A.js';
+import { DB_VERSION } from '../chunk-VBHXBI7F.js';
+import '../chunk-33Q2RFET.js';
+import '../chunk-45FKMOJH.js';
+import '../chunk-4CMXV5SF.js';
 import '../chunk-NSBPE2FW.js';
 
 // src/storage/indexedDB.ts

package/dist/{asyncStorageTaskQueue-BZcIN7sA.d.cts → asyncStorageTaskQueue-B2CcXIHU.d.cts}

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

package/dist/{asyncStorageTaskQueue-B6SijMi3.d.ts → asyncStorageTaskQueue-DaZlVTbM.d.ts}

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

package/dist/{chunk-2JZGPXU4.js → chunk-33Q2RFET.js}

@@ -1,4 +1,4 @@
-import { DEFAULT_ARKADE_SERVER_URL, eventSourceIterator, resolveEventSource, convertVtxo, isFetchTimeoutError, isEventSourceError, isEventSourceUnavailableError, rateGate, baseFetch, toProviderUnavailable, ProviderUnavailableError, throwIfHttpUnavailable } from './chunk-J33ZEM3A.js';
+import { DEFAULT_ARKADE_SERVER_URL, eventSourceIterator, resolveEventSource, convertVtxo, isFetchTimeoutError, isEventSourceError, isEventSourceUnavailableError, rateGate, baseFetch, toProviderUnavailable, ProviderUnavailableError, throwIfHttpUnavailable } from './chunk-4CMXV5SF.js';
 import { __export } from './chunk-NSBPE2FW.js';
 import { hex } from '@scure/base';
 import { schnorr } from '@noble/curves/secp256k1.js';
@@ -1954,5 +1954,5 @@ var Response;
 })(Response || (Response = {}));
 
 export { AssetGroup, AssetId, AssetInput, AssetOutput, AssetRef, BufferReader, BufferWriter, ChainTxType, DEFAULT_VTXO_PAGE_SIZE, IndexerTxType, Metadata, Packet, RestIndexerProvider, asset_exports };
-//# sourceMappingURL=chunk-2JZGPXU4.js.map
-//# sourceMappingURL=chunk-2JZGPXU4.js.map
+//# sourceMappingURL=chunk-33Q2RFET.js.map
+//# sourceMappingURL=chunk-33Q2RFET.js.map