@arkade-os/sdk 0.4.43 → 0.4.44

package/README.md

@@ -797,6 +797,71 @@ await Unroll.completeUnroll(
 - The `completeUnroll` method can only be called after all virtual outputs are fully unrolled and the timelock has expired
 - You need sufficient onchain funds in the `OnchainWallet` to pay for P2A transaction fees
 
+### 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
+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.
+
+> **Note:** Unilateral exit handles **BTC value only** and does not represent any assets a
+> VTXO carries — do not pass asset-bearing VTXOs (those with a non-empty `assets` field).
+
+The flow is **quote → fund → prepare → execute**:
+
+```typescript
+import { UnilateralExit, OnchainWallet, serializeExitPackage } from '@arkade-os/sdk'
+
+const onchainWallet = await OnchainWallet.create(identity, 'mainnet')
+
+// 1. Quote: how many txs, how many sats (no funds needed, nothing signed)
+const quote = await UnilateralExit.estimate({
+  wallet,
+  onchainWallet,
+  sweepAddress: 'bc1p...',      // where the exited funds land
+  // feeRate: 2,                // sat/vB — defaults to the provider estimate
+})
+console.log(quote.totals.txCount, quote.totals.fundingRequiredSats, quote.shortfallSats)
+
+// 2. Deposit quote.shortfallSats to quote.fundingAddress, wait for confirmation
+
+// 3. Prepare: signs everything and broadcasts the fee-funding splitter,
+//    reserving the fee budget onchain
+const pkg = await UnilateralExit.prepare({ wallet, onchainWallet, sweepAddress: 'bc1p...' })
+const json = serializeExitPackage(pkg) // hand this to any executor
+
+// 4. Execute anywhere — here, or on a machine that has only an Esplora URL
+const executor = new UnilateralExit.Executor(pkg, wallet.onchainProvider)
+for await (const event of executor) {
+  console.log(event.stepIndex, event.kind, event.status)
+}
+```
+
+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
+VTXO with a pre-signed sweep, and `totals.recoveredSats` is what arrives at `sweepAddress` after
+the timelocks mature. A VTXO whose sweep cannot be signed — e.g. a contract path that needs
+another party — is dropped from the package rather than left half-exited onchain.
+
+Key properties:
+
+- **Contract-aware**: exit paths are resolved through the contract handler registry, so
+  contract VTXOs (e.g. a VHTLC whose preimage is in the contract params) are pre-signable
+  too — paths needing other parties' signatures are skipped with a reason.
+- **Shared ancestors are paid once**: VTXOs under the same commitment share tree
+  transactions; the package contains one step (and one fee) per unique transaction.
+- **Idempotent execution**: the executor re-checks the chain before every action, so it can
+  be killed, moved, and re-run at any point; already-confirmed steps are skipped.
+- **Per-VTXO isolation**: one sweep per VTXO plus fan-out fee funding means one failed
+  branch never blocks the others.
+- **Confidentiality**: packages contain no key material, but sweeps of condition paths embed
+  the condition witness (e.g. a VHTLC preimage) — treat the file as confidential until
+  broadcast.
+- `validUntil` carries the earliest batch expiry: execute before it, or the operator may
+  sweep the expired batch first.
+
 ### Running the wallet in a service worker
 
 The SDK provides a `MessageBus` orchestrator that runs inside a service worker

package/dist/adapters/expo.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunkPLJZRIFZ_cjs = require('../chunk-PLJZRIFZ.cjs');
-require('../chunk-3AQNLQPM.cjs');
+var chunkX37EKDIH_cjs = require('../chunk-X37EKDIH.cjs');
+require('../chunk-UBYY2TPK.cjs');
 require('../chunk-HXDZ2QTW.cjs');
 require('../chunk-5BLDMQED.cjs');
 
@@ -9,11 +9,11 @@ require('../chunk-5BLDMQED.cjs');
 
 Object.defineProperty(exports, "ExpoArkProvider", {
   enumerable: true,
-  get: function () { return chunkPLJZRIFZ_cjs.ExpoArkProvider; }
+  get: function () { return chunkX37EKDIH_cjs.ExpoArkProvider; }
 });
 Object.defineProperty(exports, "ExpoIndexerProvider", {
   enumerable: true,
-  get: function () { return chunkPLJZRIFZ_cjs.ExpoIndexerProvider; }
+  get: function () { return chunkX37EKDIH_cjs.ExpoIndexerProvider; }
 });
 //# sourceMappingURL=expo.cjs.map
 //# sourceMappingURL=expo.cjs.map

package/dist/adapters/expo.js

@@ -1,5 +1,5 @@
-export { ExpoArkProvider, ExpoIndexerProvider } from '../chunk-VKKLOT2E.js';
-import '../chunk-763XHDAJ.js';
+export { ExpoArkProvider, ExpoIndexerProvider } from '../chunk-V7WIZR2B.js';
+import '../chunk-LJ35HPJW.js';
 import '../chunk-BE5MUB7T.js';
 import '../chunk-NSBPE2FW.js';
 //# sourceMappingURL=expo.js.map

package/dist/adapters/indexedDB.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunkQGNTDGMN_cjs = require('../chunk-QGNTDGMN.cjs');
-require('../chunk-3AQNLQPM.cjs');
+var chunkXIVCG6EP_cjs = require('../chunk-XIVCG6EP.cjs');
+require('../chunk-UBYY2TPK.cjs');
 require('../chunk-32YKLQPS.cjs');
 require('../chunk-HXDZ2QTW.cjs');
 require('../chunk-5BLDMQED.cjs');
@@ -11,7 +11,7 @@ var IndexedDBStorageAdapter = class {
   dbName;
   version;
   db = null;
-  constructor(dbName, version = chunkQGNTDGMN_cjs.DB_VERSION) {
+  constructor(dbName, version = chunkXIVCG6EP_cjs.DB_VERSION) {
     this.dbName = dbName;
     this.version = version;
   }

package/dist/adapters/indexedDB.js

@@ -1,5 +1,5 @@
-import { DB_VERSION } from '../chunk-B4R36PRN.js';
-import '../chunk-763XHDAJ.js';
+import { DB_VERSION } from '../chunk-FMI2GKYO.js';
+import '../chunk-LJ35HPJW.js';
 import '../chunk-YNEDJTX2.js';
 import '../chunk-BE5MUB7T.js';
 import '../chunk-NSBPE2FW.js';

package/dist/{asyncStorageTaskQueue-CjoL-35w.d.ts → asyncStorageTaskQueue-BtSOVZFn.d.ts}

@@ -1,4 +1,4 @@
-import { a as TaskQueue, c as TaskItem, d as TaskResult } from './taskRunner-Djlhfgi1.js';
+import { c as TaskQueue, b as TaskItem, d as TaskResult } from './taskRunner-Bptw9UMa.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-D1FfHfgK.d.cts → asyncStorageTaskQueue-Dap7qUlF.d.cts}

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