@miradexio/client 0.1.0 → 0.1.2

package/dist/engine/flow-context.js

@@ -1,14 +1,10 @@
-/**
- * Zod-enforced FlowContext schemas.
- *
- * Three strictness levels:
- *   FlowContext          — base, nullable fields (early phases: keygen, creating-swap)
- *   PopulatedFlowContext — snapshot-critical fields non-empty (awaiting-deposit, deposit-detected)
- *   VerifiedFlowContext  — populated + verification non-null (signing, funding, confirming, swapping)
- *
- * Types are inferred from schemas — one source of truth, zero drift.
- * Validation uses safeParse — never throws, returns structured errors.
- */
+// Three strictness levels:
+//   FlowContext          - base, nullable (keygen, creating-swap)
+//   PopulatedFlowContext - snapshot-critical fields non-empty
+//                          (awaiting-deposit, deposit-detected)
+//   VerifiedFlowContext  - populated + verification non-null
+//                          (signing, funding, confirming, swapping)
+// Types are inferred from the schemas; validation uses safeParse.
 import { z } from 'zod';
 const VerificationCheckSchema = z.object({
     name: z.string(),
@@ -26,36 +22,29 @@ const FlowContextExtraSchema = z.object({
     text: z.string().min(1, 'extra.text must not be empty'),
     type: z.enum(EXTRA_TYPES),
 });
-// Used by early phases where data may not be available yet.
-// Every field is nullable — the engine builds it up progressively.
+// Every field nullable; the engine builds it up progressively.
 const FlowContextBaseSchema = z.object({
-    // Addresses
     depositAddr: z.string().nullable(),
     destAddress: z.string().nullable(),
     refundAddress: z.string().nullable(),
     keystoreId: z.string().nullable(),
-    // Amounts
     depositAmount: z.string().nullable(),
     fromToken: z.string().nullable(),
     toToken: z.string().nullable(),
     expectedOut: z.string().nullable(),
     amountInUsd: z.string().nullable(),
     expectedOutUsd: z.string().nullable(),
-    // Display
     qr: z.string().nullable(),
     verification: VerificationResultSchema.nullable(),
     verificationSourceUrl: z.string().nullable(),
     expiresAt: z.string().nullable(),
     depositMemo: z.string().nullable(),
-    // Identity
     provider: z.string().nullable(),
     swapId: z.string().nullable(),
     swapNumber: z.string().nullable(),
-    // Contextual
     extra: FlowContextExtraSchema.nullable(),
 });
-// Used by deposit-ready phases. Critical snapshot fields MUST be
-// non-empty strings — Zod rejects "" and null at runtime.
+// Critical snapshot fields must be non-empty for deposit-ready phases.
 const PopulatedFlowContextSchema = FlowContextBaseSchema.extend({
     depositAddr: z.string().min(1, 'depositAddr is required for this phase'),
     destAddress: z.string().min(1, 'destAddress is required for this phase'),
@@ -63,24 +52,18 @@ const PopulatedFlowContextSchema = FlowContextBaseSchema.extend({
     toToken: z.string().min(1, 'toToken is required for this phase'),
     qr: z.string().min(1, 'qr is required for this phase'),
     provider: z.string().min(1, 'provider is required for this phase'),
-    // `expectedOut` stays nullable here on purpose. It's display-only —
-    // populated from a /quotes round-trip that can legitimately fail
-    // (transient API hiccup, no maker available for the amount, atomicswap
-    // provider not in the quote set). The deposit, swap, and refund paths
-    // do not depend on knowing the exact expected output, so blocking
-    // `deposit-detected` on it would force the SDK to fail a swap that's
-    // otherwise progressing fine. UIs already handle null with a "—".
+    // expectedOut stays nullable: it's display-only, sourced from /quotes which
+    // can fail transiently. Deposit/swap/refund paths don't need it; blocking
+    // here would fail an otherwise-fine swap. UIs render null as "-".
     expectedOut: z.string().nullable(),
 });
-// Used by post-verification phases. Everything populated + verification
-// MUST be a valid VerificationResult (non-null).
+// Post-verification: everything populated + verification non-null.
 const VerifiedFlowContextSchema = PopulatedFlowContextSchema.extend({
     verification: VerificationResultSchema,
 });
-// Re-export schemas for consumers that need them (tests, browser adapter)
+// Re-exported for tests and adapter implementations.
 export { FlowContextBaseSchema, PopulatedFlowContextSchema, VerifiedFlowContextSchema, FlowContextExtraSchema, VerificationResultSchema, VerificationCheckSchema, };
-// Use safeParse — never throw. Return structured error listing every
-// missing/invalid field. The engine calls these before emitting phases.
+// Engine calls these before emitting phases; structured error per failure.
 function buildValidationError(phase, zodError) {
     const fields = zodError.issues.map((issue) => issue.path.join('.'));
     const details = zodError.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`);
@@ -129,18 +112,11 @@ const EMPTY_FLOW_CONTEXT = {
     swapNumber: null,
     extra: null,
 };
-/**
- * Create a new FlowContext with defaults, overriding with provided values.
- * Null values in partial are applied (they mean "not yet known").
- */
+// null in `partial` is a valid override and means "not yet known".
 export function createFlowContext(partial) {
     return { ...EMPTY_FLOW_CONTEXT, ...partial };
 }
-/**
- * Merge an update into an existing FlowContext.
- * Only non-undefined keys in partial overwrite. Null IS a valid value
- * (it means "reset to unknown").
- */
+// Only non-undefined keys overwrite. null means "reset to unknown".
 export function mergeFlowContext(current, partial) {
     return { ...current, ...partial };
 }

package/dist/engine/flow-context.js.map

@@ -1 +1 @@
-{"version":3,"file":"flow-context.js","sourceRoot":"","sources":["../../src/engine/flow-context.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"flow-context.js","sourceRoot":"","sources":["../../src/engine/flow-context.ts"],"names":[],"mappings":"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"}

package/dist/engine/flows/atomic-flow.d.ts

@@ -19,35 +19,13 @@ export declare class AtomicFlow {
     private flowCtx;
     private lastProgressKey;
     private readonly 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'`.
-     */
     private hasReachedTerminal;
-    /**
-     * 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.
-     */
     private variantId;
     constructor(api: ApiClient, platform: PlatformAdapter, config: ResolvedEngineConfig, emitFn: (state: AtomicFlowState) => void, options?: AtomicFlowOptions);
     private get signal();
     private get logger();
     private setFlowContext;
-    /**
-     * Validate FlowContext as PopulatedFlowContext.
-     * On failure, emits a 'failed' phase with structured error and returns null.
-     */
     private requirePopulated;
-    /**
-     * Validate FlowContext as VerifiedFlowContext.
-     * On failure, emits a 'failed' phase with structured error and returns null.
-     */
     private requireVerified;
     private emitError;
     private transition;
@@ -69,12 +47,6 @@ export declare class AtomicFlow {
     private executeSweep;
     private executeRefund;
     private resolveLockAddress;
-    /**
-     * 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.
-     */
     private resolveProtocolParams;
     private cacheProtocolParams;
     private emitRefundAborted;

package/dist/engine/flows/atomic-flow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"atomic-flow.d.ts","sourceRoot":"","sources":["../../../src/engine/flows/atomic-flow.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEpD,OAAO,KAAK,EAAE,eAAe,EAAmB,MAAM,gBAAgB,CAAC;AACvE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,KAAK,EAAE,eAAe,EAAuB,MAAM,wBAAwB,CAAC;AA2EnF,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,qBAAa,UAAU;IA6BnB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IA/BzB,OAAO,CAAC,eAAe,CAAgC;IACvD,OAAO,CAAC,kBAAkB,CAA6B;IACvD,OAAO,CAAC,QAAQ,CAA6B;IAC7C,OAAO,CAAC,OAAO,CAAgC;IAC/C,OAAO,CAAC,UAAU,CAAc;IAChC,OAAO,CAAC,gBAAgB,CAAsD;IAC9E,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,eAAe,CAAuB;IAC9C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC;;;;;;;OAOG;IACH,OAAO,CAAC,kBAAkB,CAAS;IAEnC;;;;;OAKG;IACH,OAAO,CAAC,SAAS,CAAqB;gBAGnB,GAAG,EAAE,SAAS,EACd,QAAQ,EAAE,eAAe,EACzB,MAAM,EAAE,oBAAoB,EAC5B,MAAM,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,EACzD,OAAO,CAAC,EAAE,iBAAiB;IAK7B,OAAO,KAAK,MAAM,GAEjB;IAED,OAAO,KAAK,MAAM,GAEjB;IAED,OAAO,CAAC,cAAc;IAMtB;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAYxB;;;OAGG;IACH,OAAO,CAAC,eAAe;IAYvB,OAAO,CAAC,SAAS;IAQjB,OAAO,CAAC,UAAU;IAWlB,MAAM,IAAI,IAAI;IAMR,KAAK,CAAC,MAAM,EAAE;QAClB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;QAC/B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;KACtC,GAAG,OAAO,CAAC,IAAI,CAAC;IAgLX,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YA6NtE,oBAAoB;YAyBpB,qBAAqB;IA2EnC,OAAO,CAAC,eAAe;IAiLjB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA2C3B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAU3B,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;YAOvB,YAAY;YA6EZ,aAAa;IA8M3B,OAAO,CAAC,kBAAkB;IAU1B;;;;;OAKG;YACW,qBAAqB;YAiCrB,mBAAmB;IAiBjC,OAAO,CAAC,iBAAiB;YAUX,iBAAiB;IA0C/B,OAAO,CAAC,YAAY;IAsBpB,OAAO,CAAC,gBAAgB;IAKxB,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,WAAW;IAenB,OAAO,CAAC,6BAA6B;CAItC"}
+{"version":3,"file":"atomic-flow.d.ts","sourceRoot":"","sources":["../../../src/engine/flows/atomic-flow.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEpD,OAAO,KAAK,EAAE,eAAe,EAAmB,MAAM,gBAAgB,CAAC;AACvE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,KAAK,EAAE,eAAe,EAAuB,MAAM,wBAAwB,CAAC;AAyEnF,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,qBAAa,UAAU;IAqBnB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAvBzB,OAAO,CAAC,eAAe,CAAgC;IACvD,OAAO,CAAC,kBAAkB,CAA6B;IACvD,OAAO,CAAC,QAAQ,CAA6B;IAC7C,OAAO,CAAC,OAAO,CAAgC;IAC/C,OAAO,CAAC,UAAU,CAAc;IAChC,OAAO,CAAC,gBAAgB,CAAsD;IAC9E,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,eAAe,CAAuB;IAC9C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAKhC,OAAO,CAAC,kBAAkB,CAAS;IAInC,OAAO,CAAC,SAAS,CAAqB;gBAGnB,GAAG,EAAE,SAAS,EACd,QAAQ,EAAE,eAAe,EACzB,MAAM,EAAE,oBAAoB,EAC5B,MAAM,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,EACzD,OAAO,CAAC,EAAE,iBAAiB;IAK7B,OAAO,KAAK,MAAM,GAEjB;IAED,OAAO,KAAK,MAAM,GAEjB;IAED,OAAO,CAAC,cAAc;IAOtB,OAAO,CAAC,gBAAgB;IAaxB,OAAO,CAAC,eAAe;IAYvB,OAAO,CAAC,SAAS;IAQjB,OAAO,CAAC,UAAU;IAWlB,MAAM,IAAI,IAAI;IAMR,KAAK,CAAC,MAAM,EAAE;QAClB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;QAC/B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;KACtC,GAAG,OAAO,CAAC,IAAI,CAAC;IAkKX,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAqNtE,oBAAoB;YAyBpB,qBAAqB;IAqEnC,OAAO,CAAC,eAAe;IAyKjB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA2C3B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAU3B,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;YAOvB,YAAY;YA6EZ,aAAa;IA8M3B,OAAO,CAAC,kBAAkB;YAcZ,qBAAqB;YAiCrB,mBAAmB;IAiBjC,OAAO,CAAC,iBAAiB;YAUX,iBAAiB;IAuC/B,OAAO,CAAC,YAAY;IAsBpB,OAAO,CAAC,gBAAgB;IAKxB,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,WAAW;IAenB,OAAO,CAAC,6BAA6B;CAItC"}

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

@@ -27,16 +27,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;
@@ -60,21 +58,13 @@ export class AtomicFlow {
     flowCtx = null;
     lastProgressKey = 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 +84,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 +97,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 +152,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 +197,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 +219,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 +229,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 +304,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 +318,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 +328,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 +342,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 +353,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 +365,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 +484,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 +505,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 +532,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' },
         });
@@ -671,10 +627,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 +663,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 +674,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 +684,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' } });
@@ -1052,12 +1000,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 +1055,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');