@arkade-os/sdk 0.4.65 → 0.4.67

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
 
@@ -747,12 +778,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 +796,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 +863,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 +903,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 chunkSJQM5AVB_cjs = require('../chunk-SJQM5AVB.cjs');
-require('../chunk-XN55B6EP.cjs');
-require('../chunk-G552MISJ.cjs');
+var chunkR2YAMONM_cjs = require('../chunk-R2YAMONM.cjs');
+require('../chunk-CO3KKSWM.cjs');
+require('../chunk-2JV4VQ7C.cjs');
 require('../chunk-5BLDMQED.cjs');
 
 
 
 Object.defineProperty(exports, "ExpoArkProvider", {
   enumerable: true,
-  get: function () { return chunkSJQM5AVB_cjs.ExpoArkProvider; }
+  get: function () { return chunkR2YAMONM_cjs.ExpoArkProvider; }
 });
 Object.defineProperty(exports, "ExpoIndexerProvider", {
   enumerable: true,
-  get: function () { return chunkSJQM5AVB_cjs.ExpoIndexerProvider; }
+  get: function () { return chunkR2YAMONM_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 TxNotification, m as RestIndexerProvider, n as SubscriptionResponse } from '../index-CFOMyVMt.cjs';
-export { o as ArkProvider, p as IndexerProvider } from '../index-CFOMyVMt.cjs';
+import { n as RestArkProvider, k as SettlementEvent, T as TxNotificationEvent, o as RestIndexerProvider, p as SubscriptionResponse } from '../index-DU5o_hz7.cjs';
+export { q as ArkProvider, r as IndexerProvider } from '../index-DU5o_hz7.cjs';
 import '@scure/btc-signer/utils.js';
 import '@scure/btc-signer/transaction.js';
 import '@scure/btc-signer';
@@ -21,10 +21,7 @@ import '@scure/btc-signer/psbt.js';
 declare class ExpoArkProvider extends RestArkProvider {
     constructor(serverUrl?: string);
     getEventStream(signal: AbortSignal, topics: string[]): AsyncIterableIterator<SettlementEvent>;
-    getTransactionsStream(signal: AbortSignal): AsyncIterableIterator<{
-        commitmentTx?: TxNotification;
-        arkTx?: TxNotification;
-    }>;
+    getTransactionsStream(signal: AbortSignal): AsyncIterableIterator<TxNotificationEvent>;
 }
 
 /**

package/dist/adapters/expo.d.ts

@@ -1,5 +1,5 @@
-import { l as RestArkProvider, i as SettlementEvent, T as TxNotification, m as RestIndexerProvider, n as SubscriptionResponse } from '../index-CFOMyVMt.js';
-export { o as ArkProvider, p as IndexerProvider } from '../index-CFOMyVMt.js';
+import { n as RestArkProvider, k as SettlementEvent, T as TxNotificationEvent, o as RestIndexerProvider, p as SubscriptionResponse } from '../index-DU5o_hz7.js';
+export { q as ArkProvider, r as IndexerProvider } from '../index-DU5o_hz7.js';
 import '@scure/btc-signer/utils.js';
 import '@scure/btc-signer/transaction.js';
 import '@scure/btc-signer';
@@ -21,10 +21,7 @@ import '@scure/btc-signer/psbt.js';
 declare class ExpoArkProvider extends RestArkProvider {
     constructor(serverUrl?: string);
     getEventStream(signal: AbortSignal, topics: string[]): AsyncIterableIterator<SettlementEvent>;
-    getTransactionsStream(signal: AbortSignal): AsyncIterableIterator<{
-        commitmentTx?: TxNotification;
-        arkTx?: TxNotification;
-    }>;
+    getTransactionsStream(signal: AbortSignal): AsyncIterableIterator<TxNotificationEvent>;
 }
 
 /**

package/dist/adapters/expo.js

@@ -1,6 +1,6 @@
-export { ExpoArkProvider, ExpoIndexerProvider } from '../chunk-TYTPVPKD.js';
-import '../chunk-3G5V564P.js';
-import '../chunk-TFSVXMTM.js';
+export { ExpoArkProvider, ExpoIndexerProvider } from '../chunk-MZFUZUTQ.js';
+import '../chunk-X3VEMUVV.js';
+import '../chunk-3WIWNE4P.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 chunkGFZNEMGL_cjs = require('../chunk-GFZNEMGL.cjs');
-require('../chunk-XN55B6EP.cjs');
-require('../chunk-BABJ77NG.cjs');
-require('../chunk-G552MISJ.cjs');
+var chunkMJUTO3PY_cjs = require('../chunk-MJUTO3PY.cjs');
+require('../chunk-CO3KKSWM.cjs');
+require('../chunk-OIZ2V2VD.cjs');
+require('../chunk-2JV4VQ7C.cjs');
 require('../chunk-5BLDMQED.cjs');
 
 // src/storage/indexedDB.ts
@@ -11,7 +11,7 @@ var IndexedDBStorageAdapter = class {
   dbName;
   version;
   db = null;
-  constructor(dbName, version = chunkGFZNEMGL_cjs.DB_VERSION) {
+  constructor(dbName, version = chunkMJUTO3PY_cjs.DB_VERSION) {
     this.dbName = dbName;
     this.version = version;
   }

package/dist/adapters/indexedDB.js

@@ -1,7 +1,7 @@
-import { DB_VERSION } from '../chunk-5YTSQSLE.js';
-import '../chunk-3G5V564P.js';
-import '../chunk-XMOIRDLF.js';
-import '../chunk-TFSVXMTM.js';
+import { DB_VERSION } from '../chunk-AEWJU6NZ.js';
+import '../chunk-X3VEMUVV.js';
+import '../chunk-6TAQF6EV.js';
+import '../chunk-3WIWNE4P.js';
 import '../chunk-NSBPE2FW.js';
 
 // src/storage/indexedDB.ts

package/dist/{asyncStorageTaskQueue-Chwe60Ce.d.cts → asyncStorageTaskQueue-LTpeXYaD.d.cts}

@@ -1,4 +1,4 @@
-import { a as TaskQueue, c as TaskItem, d as TaskResult } from './taskRunner-CIKOS2OO.cjs';
+import { c as TaskQueue, b as TaskItem, d as TaskResult } from './taskRunner-BZJMLQ6g.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 };

package/dist/{asyncStorageTaskQueue-Dq_UcvDx.d.ts → asyncStorageTaskQueue-Za-e_zMk.d.ts}

@@ -1,4 +1,4 @@
-import { a as TaskQueue, c as TaskItem, d as TaskResult } from './taskRunner-BDzWbpct.js';
+import { c as TaskQueue, b as TaskItem, d as TaskResult } from './taskRunner-DATaRQus.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/{chunk-G552MISJ.cjs → chunk-2JV4VQ7C.cjs}

@@ -1032,7 +1032,7 @@ function resolveEventSource(override) {
 }
 
 // package.json
-var version = "0.4.65";
+var version = "0.4.67";
 
 // src/utils/fetch.ts
 var buildVersion = "0.9.9";
@@ -1349,6 +1349,9 @@ function prepareCoinAsIntentProofInput(coin) {
   if (coin.extraWitness) {
     unknown.push(ConditionWitness.encode(coin.extraWitness));
   }
+  if (coin.prevTx) {
+    unknown.push(PrevArkTxField.encode(coin.prevTx));
+  }
   return {
     txid: base.hex.decode(coin.txid),
     index: coin.vout,
@@ -1613,6 +1616,11 @@ var SettlementEventType = /* @__PURE__ */ ((SettlementEventType2) => {
   SettlementEventType2["StreamStarted"] = "stream_started";
   return SettlementEventType2;
 })(SettlementEventType || {});
+function advertisedLimit(fromServer) {
+  if (fromServer == null) return void 0;
+  const limit = BigInt(fromServer);
+  return limit > 0n ? limit : void 0;
+}
 var RestArkProvider = class {
   constructor(serverUrl = DEFAULT_ARKADE_SERVER_URL, options = {}) {
     this.serverUrl = serverUrl;
@@ -1622,17 +1630,17 @@ var RestArkProvider = class {
   /** Overrides {@link configureEventSource} for this provider's streams. */
   eventSource;
   /**
-   * Last server-info digest seen (from {@link getInfo}). Sent as `X-Digest`
-   * on outgoing requests so arkd can reject a client whose cached info is
-   * stale. Empty until the first {@link getInfo}.
+   * Last server-info digest seen from {@link getInfo}. Sent as `X-Digest`
+   * so arkd can reject stale client configuration.
    */
   _digest = "";
+  _hasServerInfo = false;
+  _suppressNextGetInfoChangeEmit = false;
   _serverInfoListeners = /* @__PURE__ */ new Set();
   /**
-   * Subscribe to server-info changes. Fired when a request is rejected with
-   * `DIGEST_MISMATCH` and fresh info is re-fetched, so consumers (the wallet)
-   * can re-derive signer-dependent state mid-session without polling. Returns
-   * an unsubscribe function.
+   * Subscribe to server-info changes. Fired after a stale-info
+   * `DIGEST_MISMATCH` refresh or when {@link getInfo} observes a changed digest.
+   * Returns an unsubscribe function.
    */
   onServerInfoChanged(listener) {
     this._serverInfoListeners.add(listener);
@@ -1687,7 +1695,13 @@ var RestArkProvider = class {
     if (!arkError) throwIfHttpUnavailable(response, "arkade");
     if (!isArkError(arkError, ArkErrorName.DIGEST_MISMATCH)) return response;
     this._digest = "";
-    const info = await this.getInfo();
+    this._suppressNextGetInfoChangeEmit = true;
+    let info;
+    try {
+      info = await this.getInfo();
+    } finally {
+      this._suppressNextGetInfoChangeEmit = false;
+    }
     this.emitServerInfoChanged(info);
     throw new DigestMismatchError(
       "Arkade server reported a configuration digest mismatch; server info was refreshed. Rebuild and retry the request under the new server info."
@@ -1736,13 +1750,21 @@ var RestArkProvider = class {
       signerPubkey: fromServer.signerPubkey ?? "",
       unilateralExitDelay: BigInt(fromServer.unilateralExitDelay ?? 0),
       vtxoTreeExpiry: fromServer.vtxoTreeExpiry != null ? BigInt(fromServer.vtxoTreeExpiry) : void 0,
+      maxTxWeight: advertisedLimit(fromServer.maxTxWeight),
+      maxOpReturnOutputs: advertisedLimit(fromServer.maxOpReturnOutputs),
       utxoMaxAmount: BigInt(fromServer.utxoMaxAmount ?? -1),
       utxoMinAmount: BigInt(fromServer.utxoMinAmount ?? 0),
       version: fromServer.version ?? "",
       vtxoMaxAmount: BigInt(fromServer.vtxoMaxAmount ?? -1),
       vtxoMinAmount: BigInt(fromServer.vtxoMinAmount ?? 0)
     };
+    const previousDigest = this._digest;
+    const hadServerInfo = this._hasServerInfo;
     this._digest = info.digest;
+    this._hasServerInfo = true;
+    if (hadServerInfo && previousDigest !== info.digest && !this._suppressNextGetInfoChangeEmit) {
+      this.emitServerInfoChanged(info);
+    }
     return info;
   }
   async submitTx(signedArkTx, checkpointTxs) {
@@ -2127,24 +2149,16 @@ var RestArkProvider = class {
   }
   parseTransactionNotification(data) {
     if (data.commitmentTx) {
-      return {
-        commitmentTx: {
-          txid: data.commitmentTx.txid,
-          tx: data.commitmentTx.tx,
-          spentVtxos: data.commitmentTx.spentVtxos.map(mapVtxo),
-          spendableVtxos: data.commitmentTx.spendableVtxos.map(mapVtxo),
-          checkpointTxs: data.commitmentTx.checkpointTxs
-        }
-      };
+      return { commitmentTx: mapTxNotification(data.commitmentTx) };
     }
     if (data.arkTx) {
+      return { arkTx: mapTxNotification(data.arkTx) };
+    }
+    if (data.sweepTx) {
       return {
-        arkTx: {
-          txid: data.arkTx.txid,
-          tx: data.arkTx.tx,
-          spentVtxos: data.arkTx.spentVtxos.map(mapVtxo),
-          spendableVtxos: data.arkTx.spendableVtxos.map(mapVtxo),
-          checkpointTxs: data.arkTx.checkpointTxs
+        sweepTx: {
+          ...mapTxNotification(data.sweepTx),
+          sweptVtxos: data.sweepTx.sweptVtxos ?? []
         }
       };
     }
@@ -2187,6 +2201,15 @@ function isFetchTimeoutError(err) {
   };
   return checkError(err) || checkError(err.cause);
 }
+function mapTxNotification(data) {
+  return {
+    txid: data.txid,
+    tx: data.tx,
+    spentVtxos: data.spentVtxos.map(mapVtxo),
+    spendableVtxos: data.spendableVtxos.map(mapVtxo),
+    checkpointTxs: data.checkpointTxs
+  };
+}
 function mapVtxo(vtxo) {
   return {
     outpoint: {
@@ -2376,11 +2399,15 @@ function isPastExpiry(vtxo, now) {
 }
 function canSpendOffchain(vtxo, now) {
   const n = normalizeVtxo(vtxo);
-  return !hasTerminalSpend(n) && !(n.isSwept || isPastExpiry(n, now));
+  return !hasTerminalSpend(n) && !n.isUnrolled && !(n.isSwept || isPastExpiry(n, now));
 }
 function canRecoverOnchain(vtxo, now) {
   const n = normalizeVtxo(vtxo);
-  return !hasTerminalSpend(n) && (n.isSwept || isPastExpiry(n, now));
+  return !hasTerminalSpend(n) && !n.isUnrolled && (n.isSwept || isPastExpiry(n, now));
+}
+function canSweepOnchain(vtxo) {
+  const n = normalizeVtxo(vtxo);
+  return !hasTerminalSpend(n) && !!n.isUnrolled;
 }
 function toOffchainInputFeeParams(vtxo) {
   const batchExpiry = toBatchExpiry(vtxo);
@@ -2442,6 +2469,7 @@ exports.baseFetch = baseFetch;
 exports.buildVersion = buildVersion;
 exports.canRecoverOnchain = canRecoverOnchain;
 exports.canSpendOffchain = canSpendOffchain;
+exports.canSweepOnchain = canSweepOnchain;
 exports.configureEventSource = configureEventSource;
 exports.convertVtxo = convertVtxo;
 exports.craftToSpendTx = craftToSpendTx;
@@ -2485,5 +2513,5 @@ exports.toBatchExpiry = toBatchExpiry;
 exports.toOffchainInputFeeParams = toOffchainInputFeeParams;
 exports.toProviderUnavailable = toProviderUnavailable;
 exports.toVirtualStatus = toVirtualStatus;
-//# sourceMappingURL=chunk-G552MISJ.cjs.map
-//# sourceMappingURL=chunk-G552MISJ.cjs.map
+//# sourceMappingURL=chunk-2JV4VQ7C.cjs.map
+//# sourceMappingURL=chunk-2JV4VQ7C.cjs.map