@miradexio/client 0.1.1 → 0.1.3

package/dist/engine/flows/atomic-flow.js

@@ -1,5 +1,6 @@
 import { ApiError, NetworkError } from '../../api/index.js';
 import { TERMINAL_STATUSES, ProtocolError } from '../../types/index.js';
+import { routeError } from './error-routing.js';
 import { createFlowContext, mergeFlowContext, validatePopulated, validateVerified, } from '../flow-context.js';
 import { resumeAtomicSwap as coreResumeAtomicSwap, SwapCancelledError, } from '../../atomic-swap/index.js';
 import { generateMnemonicKeys } from '../../lib/crypto/mnemonic.js';
@@ -16,6 +17,15 @@ import { buildMultisigWitnessScript } from '../../atomic-swap/presign.js';
 import { extractProtocolData } from '../../atomic-swap/extract.js';
 const DEFAULT_POLL_MS = 5_000;
 const MAX_TRANSIENT_RETRIES = 5;
+const SWAP_STATUS_STAGES = new Set([
+    'pending',
+    'awaiting_funding',
+    'initializing',
+    'deposited',
+    'swapping',
+    'sending',
+    'punished',
+]);
 function isTransientError(err) {
     if (err instanceof NetworkError)
         return true;
@@ -27,16 +37,14 @@ function isTransientError(err) {
     }
     return false;
 }
-/**
- * True iff the protocol params carry enough material for the client to
- * construct a refund without sidecar cooperation. Two valid shapes:
- *  - Legacy/Full: `tx_full_refund_encsig` alone is enough — the client
- *    builds and broadcasts TxFullRefund spending TxCancel.
- *  - Partial (amnesty): `tx_partial_refund_encsig` plus the amnesty
- *    triple (`amnesty_amount_sats`, `tx_partial_refund_fee_sats`) drive
- *    the partial-refund branch. The amnesty output stays at multisig
- *    until a separate TxReclaim phase (not yet implemented client-side).
- */
+// True if the params carry enough material to refund without the sidecar.
+// Two valid shapes:
+//   Legacy/Full: tx_full_refund_encsig alone (client builds + broadcasts
+//                TxFullRefund spending TxCancel).
+//   Partial:     tx_partial_refund_encsig + amnesty triple
+//                (amnesty_amount_sats, tx_partial_refund_fee_sats). Amnesty
+//                output stays at multisig pending TxReclaim (not implemented
+//                client-side yet).
 function hasRefundEscapeHatch(params) {
     if (params.tx_full_refund_encsig)
         return true;
@@ -59,22 +67,15 @@ export class AtomicFlow {
     lastEmittedState = { phase: 'idle', snapshot: null };
     flowCtx = null;
     lastProgressKey = null;
+    lastSeenStatus = null;
     pollMs;
-    /**
-     * True once the driver has emitted a terminal phase (`completed`,
-     * `failed`, `refunded`, etc.). Used to suppress the post-driver
-     * `requiredAction` re-check that would otherwise trigger a phantom
-     * second sweep — the server has no scanner for the on-chain XMR sweep,
-     * so a fresh `getSwapDetail` right after the driver completes still
-     * reports `requiredAction.type === 'sweep'`.
-     */
+    // Set once the driver emits a terminal phase. Suppresses the post-driver
+    // requiredAction re-check that would otherwise trigger a phantom second
+    // sweep — the server has no scanner for the on-chain XMR sweep so a fresh
+    // getSwapDetail still reports requiredAction.type === 'sweep'.
     hasReachedTerminal = false;
-    /**
-     * Optional maker pin forwarded to `coreResumeAtomicSwap` via
-     * `params.variantId`. Set by `start()` from `StartAtomicSwapParams`;
-     * unused (and irrelevant) on the resume path because the maker is
-     * already chosen at that point.
-     */
+    // Forwarded to coreResumeAtomicSwap as params.variantId. Set by start();
+    // ignored on resume (maker already chosen).
     variantId;
     constructor(api, platform, config, emitFn, options) {
         this.api = api;
@@ -94,10 +95,7 @@ export class AtomicFlow {
             ? mergeFlowContext(this.flowCtx, partial)
             : createFlowContext(partial);
     }
-    /**
-     * Validate FlowContext as PopulatedFlowContext.
-     * On failure, emits a 'failed' phase with structured error and returns null.
-     */
+    // On failure, emits 'failed' with a structured error and returns null.
     requirePopulated(phase) {
         if (!this.flowCtx) {
             this.emitError(phase, 'FlowContext not initialized');
@@ -110,10 +108,7 @@ export class AtomicFlow {
         this.emitError(phase, result.error.message);
         return null;
     }
-    /**
-     * Validate FlowContext as VerifiedFlowContext.
-     * On failure, emits a 'failed' phase with structured error and returns null.
-     */
+    // On failure, emits 'failed' with a structured error and returns null.
     requireVerified(phase) {
         if (!this.flowCtx) {
             this.emitError(phase, 'FlowContext not initialized');
@@ -168,17 +163,14 @@ export class AtomicFlow {
             this.transition({ phase: 'keygen', snapshot: this.flowCtx, message: 'Initializing keygen...' });
             await ensureWasm();
             const network = this.config.network;
-            // Either reuse an existing keystore (re-quote-after-failure path) or
-            // generate a fresh one (default path). In both cases the rest of the
-            // flow is identical from this point forward — same deposit polling,
-            // same swap creation, same drive loop.
+            // Reuse an existing keystore (re-quote-after-failure) or generate a
+            // fresh one. Flow is identical past this point.
             let wallet;
             if (params.existingKeystoreId !== undefined) {
                 this.setFlowContext({ extra: { text: 'Loading keystore...', type: 'message' } });
                 this.transition({ phase: 'keygen', snapshot: this.flowCtx, message: 'Loading keystore...' });
-                // Trust: the keystore was created here originally and its keys
-                // already passed `verifyKeys`. Skipping the API call avoids
-                // doubling the call's transient-failure surface for a no-op check.
+                // Trust the keystore: it was created here and its keys already
+                // passed verifyKeys. Re-checking adds a transient-failure surface.
                 this.keystore = await this.platform.loadKeystore(params.existingKeystoreId);
                 this.keystoreId = params.existingKeystoreId;
                 wallet = walletFromWif(this.keystore.btc.wif, network);
@@ -216,16 +208,10 @@ export class AtomicFlow {
                 this.keystoreId = saveResult.id;
                 this.logger.info({ keystoreId: this.keystoreId }, 'Keystore saved');
             }
-            // Emit `keystoreId` to engine state IMMEDIATELY, before the slow
-            // pre-deposit prep work (`estimateFee` → mempool.space, `getQuotes`
-            // → swap-engine, `generateQr` → wasm). The web app's
-            // EngineRegistry races a 30 s timeout against `state.atomic.
-            // snapshot.keystoreId` to decide whether to keep this engine; if
-            // the slow chain below blows the budget the engine is destroyed
-            // mid-flight and the user has to retry. Emitting a placeholder
-            // keystore-saved transition here guarantees the registry binds
-            // the engine on first save, regardless of subsequent network
-            // latency.
+            // Emit keystoreId before the slow pre-deposit chain (estimateFee,
+            // getQuotes, generateQr). EngineRegistry races a 30s timeout against
+            // state.atomic.snapshot.keystoreId — without this early emit the
+            // engine gets destroyed mid-flight on slow networks.
             this.setFlowContext({ keystoreId: this.keystoreId });
             this.transition({
                 phase: 'keystore-saved',
@@ -244,12 +230,8 @@ export class AtomicFlow {
             }
             catch { /* non-fatal */ }
             const qr = await this.platform.generateQr(wallet.address);
-            // Now that the slow chain has finished, populate the full
-            // FlowContext with the deposit address, expected XMR amount, and
-            // QR. The first `keystore-saved` transition above was the bare-
-            // bones state emit needed to keep the registry from destroying
-            // this engine; this second `setFlowContext` enriches it before
-            // `awaiting-deposit` validates against `PopulatedFlowContext`.
+            // Slow chain done: enrich FlowContext before awaiting-deposit validates
+            // against PopulatedFlowContext.
             this.setFlowContext({
                 depositAddr: wallet.address,
                 depositAmount: requiredBtc,
@@ -258,7 +240,6 @@ export class AtomicFlow {
                 extra: { text: `Send ${requiredBtc} BTC to the address above.`, type: 'message' },
             });
             this.checkAborted();
-            // Validate before emitting awaiting-deposit
             const populated = this.requirePopulated('awaiting-deposit');
             if (!populated)
                 return;
@@ -334,15 +315,10 @@ export class AtomicFlow {
                     this.emitTerminal(existingSwapId, detail.status, detail);
                     return;
                 }
-                // Funding-address UTXO is only meaningful pre-broadcast — once the
-                // swap is `deposited` or beyond, the BTC has already been swept
-                // into TxLock at the lock address and the funding address is
-                // empty. Re-querying it on every resume costs 2-15 s on
-                // testnet/stagenet electrs (cold TLS, multi-server fallback,
-                // flaky public endpoints) and the result feeds nothing
-                // downstream once the protocol is past funding. Skip it for
-                // post-funding statuses so resume settles immediately on the
-                // current state instead of stalling on a useless network probe.
+                // Funding-address UTXO is only meaningful pre-broadcast; once the
+                // swap is 'deposited' or past, BTC is in TxLock and the funding
+                // address is empty. Re-querying costs 2-15s on flaky public
+                // electrs and feeds nothing downstream — skip for post-funding.
                 const PRE_FUNDING_STATUSES = new Set([
                     'initializing',
                     'pending',
@@ -353,7 +329,6 @@ export class AtomicFlow {
                     : null;
                 if (deposit)
                     this.deposit = deposit;
-                // Verify the contract for the resumed swap
                 let verification = null;
                 if (detail.depositAddress && detail.verification) {
                     const { verifyDepositAddress } = await import('../../verification/index.js');
@@ -364,8 +339,7 @@ export class AtomicFlow {
                         refundAddress: this.keystore.swap.refundAddress,
                         toToken: 'XMR',
                         amount: '',
-                        // Lock address lives at the top level of SwapDetail; timelock
-                        // blocks come from the typed atomicswap params when present.
+                        // lock_address = SwapDetail.depositAddress; timelock from typed params.
                         protocol: detail.depositAddress &&
                             detail.protocolData?.type === 'atomicswap' &&
                             detail.protocolData.params
@@ -379,7 +353,7 @@ export class AtomicFlow {
                         fetchFn: this.config.fetchFn,
                     });
                 }
-                // Fallback: if server has progressed past verification, trust it
+                // Server is past the verification gate; trust it.
                 if (!verification) {
                     verification = { verified: true, provider: 'atomicswap', checks: [], timestamp: Date.now() };
                 }
@@ -390,8 +364,8 @@ export class AtomicFlow {
                     depositAmount: deposit ? (deposit.value / 1e8).toFixed(8) : this.flowCtx?.depositAmount ?? null,
                     extra: { text: `Resuming swap (${detail.status})...`, type: 'message' },
                 });
-                // For resumed swaps the core will provide verification via progress callbacks.
-                // Emit as swapping (base FlowContext is sufficient for resume entry).
+                // Core supplies verification via progress callbacks on resume; base
+                // FlowContext is enough for the entry transition.
                 this.transition({
                     phase: 'creating-swap',
                     snapshot: this.flowCtx,
@@ -402,10 +376,9 @@ export class AtomicFlow {
             }
             this.logger.info({ btcAddress }, 'Resume Path B: local keystore');
             const deposit = await this.platform.fetchUtxo(btcAddress, network);
-            // Fetch expected XMR output for both branches (required for PopulatedFlowContext).
-            // Pre-funding resume: there's no deposit yet, so we can't derive the
-            // amount from on-chain. Read the original amount the swap was started
-            // with from the keystore metadata (saved by saveKeystore as `label`).
+            // expectedOut is required for PopulatedFlowContext. Pre-funding resume
+            // has no on-chain deposit, so pull the original amount from the
+            // keystore metadata (saveKeystore stores it as `label`).
             let amountForQuote;
             if (deposit) {
                 amountForQuote = (deposit.value / 1e8).toFixed(8);
@@ -522,9 +495,8 @@ export class AtomicFlow {
             throw new Error('keystore must be set before driving swap');
         }
         const network = (this.keystore.btc?.network ?? 'mainnet');
-        // Provide a blockchain provider so the resume path can reconstruct the
-        // TxLock from on-chain data when recomputing the redeem digest (Fix 1
-        // on resume). The provider is shared across the driver's lifetime.
+        // AV-B.2 (resume): the driver reconstructs TxLock via this provider when
+        // recomputing the redeem digest. Shared across the driver's lifetime.
         const blockchain = await this.platform.createBlockchainProvider(network);
         const result = await coreResumeAtomicSwap({
             api: this.api,
@@ -544,13 +516,10 @@ export class AtomicFlow {
             saveProtocolSnapshot: this.platform.saveProtocolSnapshot,
             loadProtocolSnapshot: this.platform.loadProtocolSnapshot,
         });
-        // If the driver already reached a terminal phase via mapCoreProgress
-        // (sweep complete, refunded, cancelled, failed, punished), the post-driver
-        // server re-check is meaningless — the server has no scanner for the
-        // on-chain XMR sweep, so it still reports requiredAction=sweep /
-        // status=sending right after the client broadcast its sweep tx. Treating
-        // that as actionable triggers a phantom second executeSweep that emits a
-        // spurious `completed → sweeping` transition.
+        // Skip the server re-check if mapCoreProgress already emitted terminal:
+        // the server has no on-chain XMR scanner so it still reports
+        // requiredAction=sweep right after our broadcast, which would trigger a
+        // phantom second executeSweep and a spurious completed -> sweeping flicker.
         if (this.hasReachedTerminal)
             return;
         let finalStatus = 'completed';
@@ -574,11 +543,9 @@ export class AtomicFlow {
             this.emitTerminal(result.swapId, finalStatus, undefined);
             return;
         }
-        // Non-terminal status with no immediately-actionable requiredAction
-        // (e.g., server is still broadcasting TxCancel, or waiting for cancel
-        // confirmation). Sidecar handles TxCancel automatically; the client just
-        // needs to watch for the requiredAction to flip to 'refund' (or the
-        // swap to reach terminal). pollUntilTerminal does both.
+        // Non-terminal with no actionable requiredAction (e.g. server still
+        // broadcasting TxCancel). Sidecar handles cancel; we wait for the
+        // action to flip to 'refund' or the swap to reach terminal.
         this.setFlowContext({
             extra: { text: requiredAction?.message ?? 'Waiting for server...', type: 'message' },
         });
@@ -596,6 +563,9 @@ export class AtomicFlow {
             this.setFlowContext({ swapNumber: p.swapNumber });
         if (p.verification)
             this.setFlowContext({ verification: p.verification });
+        if (SWAP_STATUS_STAGES.has(p.stage)) {
+            this.lastSeenStatus = p.stage;
+        }
         switch (p.stage) {
             case 'keygen':
             case 'keystore_saved':
@@ -671,10 +641,9 @@ export class AtomicFlow {
                     phase: 'completed',
                     snapshot: this.flowCtx,
                     outputTxHash: p.txHash ?? null,
-                    // Atomic swaps have no slippage — the buyer receives exactly the
-                    // negotiated rate × deposit amount. Default to the snapshot's
-                    // expectedOut so the receipt shows the actual amount the user got
-                    // even when the in-flight progress event doesn't carry it.
+                    // Atomic swaps have no slippage; buyer receives exactly rate * deposit.
+                    // Fall back to expectedOut so the receipt shows the right number even
+                    // when the progress event doesn't carry it.
                     actualOut: this.flowCtx?.expectedOut ?? '',
                     durationSec: null,
                 });
@@ -708,9 +677,8 @@ export class AtomicFlow {
                 });
                 break;
             case 'cancelling':
-                // Intermediate: BTC TxCancel is in flight, the refund will follow.
-                // Stay in a watching phase so the driver keeps polling until the row
-                // settles in `refunded` (or `failed` if the refund never lands).
+                // TxCancel in flight; refund follows. Stay watching until the row
+                // settles in 'refunded' (or 'failed' if the refund never lands).
                 this.setFlowContext({ extra: { text: p.message, type: 'warning' } });
                 this.transition({
                     phase: 'creating-swap',
@@ -720,11 +688,8 @@ export class AtomicFlow {
                 break;
             case 'withheld':
             case 'expired':
-                // Terminal: the deposit window closed (`expired`) or the maker
-                // refused to release funds (`withheld`). Both are user-visible
-                // terminal statuses in `TerminalStatus`. Emit a `failed` phase so
-                // poll consumers (engine driver, TUI exec state) observe a terminal
-                // transition and resolve.
+                // Both are terminal in TerminalStatus. Emit 'failed' so poll
+                // consumers see a terminal transition and resolve.
                 this.transition({
                     phase: 'failed',
                     snapshot: this.flowCtx,
@@ -733,12 +698,9 @@ export class AtomicFlow {
                 break;
             case 'punished': {
                 // Not terminal. Alice published TxPunish (Bob missed the refund
-                // window), but the sidecar autonomously runs
-                // `cooperative_xmr_redeem_after_punish` to recover s_a — once Alice
-                // cooperates, the server flips `requiredAction.type` to `sweep` and
-                // the driver finishes the swap with an XMR sweep that lands the row
-                // in `completed`. Stay in a watching phase so `drive.ts`'s existing
-                // sweep branch can pick up the action transition.
+                // window), but the sidecar runs cooperative_xmr_redeem_after_punish
+                // to recover s_a; the server then flips requiredAction to 'sweep'
+                // and drive.ts finishes via the sweep branch.
                 const reason = p.message ||
                     'BTC punished — recovering XMR via cooperative_xmr_redeem_after_punish...';
                 this.setFlowContext({ extra: { text: reason, type: 'warning' } });
@@ -836,6 +798,7 @@ export class AtomicFlow {
                 receiveAddress: this.keystore.swap.receiveAddress,
                 expectedSAMonero: pp.S_a_monero,
                 monerodNodes: this.config.monerodNodes,
+                signal: this.signal,
                 onProgress: (stage) => {
                     const sweepStep = stage.includes('key') ? 'key-images'
                         : stage.includes('submit') || stage.includes('broadcast') ? 'broadcasting'
@@ -1052,12 +1015,10 @@ export class AtomicFlow {
         }
         return '';
     }
-    /**
-     * Read protocol params from the server response; fall back to the platform
-     * adapter's optional write-through cache when the server didn't return the
-     * refund encsig. On success from the server, populate the cache so later
-     * refunds survive a briefly-unreachable backend.
-     */
+    // Server response first; fall back to the platform adapter's optional
+    // write-through cache when the server omitted the refund encsig. On a
+    // good server response, prime the cache so later refunds survive a brief
+    // backend outage.
     async resolveProtocolParams(swapId, detail) {
         const fromServer = extractProtocolData(detail).params;
         if (fromServer && hasRefundEscapeHatch(fromServer)) {
@@ -1109,17 +1070,14 @@ export class AtomicFlow {
                     this.emitTerminal(swapId, detail.status, detail);
                     return;
                 }
-                // Opportunistically prime the protocol cache while the server is
-                // reachable. The refund path will use this cache if the server is
-                // briefly unreachable later.
+                // Prime the protocol cache while the server is up; the refund path
+                // falls back to it if the server goes down later.
                 const polledParams = extractProtocolData(detail).params;
                 if (polledParams?.tx_full_refund_encsig) {
                     await this.cacheProtocolParams(swapId, polledParams);
                 }
-                // Server flipped the required action to 'refund' — TxCancel has
-                // confirmed on-chain and Bob's refund window is open. Auto-trigger
-                // the client-side refund so we don't drift toward the punish
-                // deadline while idly polling.
+                // 'refund' flip means TxCancel confirmed and the refund window is
+                // open. Auto-trigger so we don't drift toward the punish deadline.
                 const action = detail.requiredAction ?? null;
                 if (action?.type === 'refund') {
                     this.logger.info({ swapId, blocksRemaining: action.blocksRemaining ?? null }, 'Required action flipped to refund — auto-triggering client-side refund');
@@ -1170,17 +1128,29 @@ export class AtomicFlow {
             throw new SwapCancelledError();
     }
     handleError(err) {
-        if (err instanceof SwapCancelledError || this.signal.aborted) {
-            this.logger.info({ swapId: this.flowCtx?.swapId ?? null }, 'AtomicFlow cancelled');
+        const route = routeError(err, this.signal.aborted, this.lastSeenStatus);
+        const swapId = this.flowCtx?.swapId ?? null;
+        if (route.kind === 'cancelled') {
+            this.logger.info({ swapId }, 'AtomicFlow cancelled');
             this.transition({ phase: 'cancelled', snapshot: this.flowCtx, swapId: null, txCancelTxid: null });
             return;
         }
-        const message = err instanceof Error ? err.message : String(err);
-        this.logger.error({ swapId: this.flowCtx?.swapId ?? null, error: message }, 'AtomicFlow error');
-        this.setFlowContext({ extra: { text: message, type: 'error' } });
+        this.logger.error({ swapId, error: route.message, kind: route.kind }, 'AtomicFlow error');
+        this.setFlowContext({ extra: { text: route.message, type: 'error' } });
+        if (route.kind === 'stalled') {
+            this.transition({
+                phase: 'stalled',
+                snapshot: this.flowCtx,
+                error: route.message,
+                swapId,
+                keystoreId: this.keystoreId.length > 0 ? this.keystoreId : null,
+            });
+            return;
+        }
         this.transition({
-            phase: 'failed', snapshot: this.flowCtx,
-            error: message,
+            phase: 'failed',
+            snapshot: this.flowCtx,
+            error: route.message,
         });
     }
     getCurrentAwaitingActionState() {