@invisible-labs/sdk 0.6.0-devnet.4 → 0.6.0-devnet.5

package/dist/user.js

@@ -1,12 +1,13 @@
-import { scheduledPayoutWindowSeconds } from './chunk-E4DCEDAG.js';
-import { validatePayoutPolicyShape, formatAjvErrors, createSession, createExponentialBackoff } from './chunk-5NNEO7IK.js';
+import { scheduledPayoutWindowSeconds } from './chunk-3TGQ4CZ3.js';
+import { validatePayoutPolicyShape, formatAjvErrors, persistTransferStatus, createSession, disabledClientPersistence, readPersistedTransferForResume, persistTransferReady, createExponentialBackoff, persistTransferTerminal, persistTransferRecoveryCode, persistTransferAllocation, persistTransferDkgMetadata } from './chunk-Y7AK6RBV.js';
+export { getPersistedTransfer, listPersistedTransfers, purgePersistedTransfers, removePersistedTransfer } from './chunk-Y7AK6RBV.js';
 import { PRODUCT_MAX_ENTRY_LAMPORTS, PRODUCT_MIN_ENTRY_LAMPORTS } from './chunk-4X5OCCQW.js';
-import { assertAttested, publicKey, solanaAddressFromPublicKeyBytes } from './chunk-NHEHCUS5.js';
-import { requestEnvelope, CoordinatorMessageType, onEnvelope, closeProtocolRuntime, EnvelopeKind } from './chunk-UADJCUPK.js';
-import { getSessionState } from './chunk-V5HXJRBW.js';
-import './chunk-DIA6U2CV.js';
-import { PolicyValidationError, CommandError, TransportError, InvalidDepositAmountError, normalizeError, AttestationError, RoutingError } from './chunk-GHBQF3A7.js';
-export { InvalidDepositAmountError } from './chunk-GHBQF3A7.js';
+import { assertAttested, publicKey, solanaAddressFromPublicKeyBytes } from './chunk-EBWTAXNT.js';
+import { requestEnvelope, CoordinatorMessageType, onEnvelope, closeProtocolRuntime, EnvelopeKind } from './chunk-3MDHAS4D.js';
+import { getSessionState } from './chunk-HJFMDMPY.js';
+import './chunk-DCTYBUY3.js';
+import { PolicyValidationError, CommandError, StorageError, TransportError, normalizeError, InvalidDepositAmountError, AttestationError, RoutingError } from './chunk-QRN46R3F.js';
+export { InvalidDepositAmountError } from './chunk-QRN46R3F.js';
 import './chunk-VR6T6OJS.js';
 
 // src/validation/payoutPolicy.ts
@@ -171,7 +172,7 @@ function recoveryCodeFromUserInput(input) {
 var protocolPromise = null;
 var frostRuntimePromise = null;
 function loadProtocol() {
-  protocolPromise ??= import('./coordinator-ZNLGAYXD.js');
+  protocolPromise ??= import('./coordinator-PEWHNZ7I.js');
   return protocolPromise;
 }
 function loadFrostRuntime() {
@@ -212,6 +213,16 @@ function readDkgComplete(protocol, envelope) {
     coordinatorTimestampMs: envelope.timestamp_ms
   };
 }
+function assertDepositConfirmedAmount(protocol, envelope, expectedAmountLamports) {
+  const payload = protocol.asDepositConfirmedPayload(envelope);
+  if (payload.amount_lamports !== expectedAmountLamports) {
+    throw new InvalidDepositAmountError(
+      BigInt(payload.amount_lamports),
+      BigInt(expectedAmountLamports)
+    );
+  }
+  return payload;
+}
 function tagBenignTransportDrop(err) {
   err[BENIGN_TRANSPORT_DROP] = true;
   return err;
@@ -241,9 +252,12 @@ var UserCoordinatorSession = class {
     this.refundExecutedListeners = /* @__PURE__ */ new Set();
     this.normalUserActorSyncListeners = /* @__PURE__ */ new Set();
     this.coordinatorErrorListeners = /* @__PURE__ */ new Set();
+    this.storageErrorListeners = /* @__PURE__ */ new Set();
     this.emittedPayoutKeys = /* @__PURE__ */ new Set();
     this.emittedRefundKeys = /* @__PURE__ */ new Set();
     this.statusReconciliationStops = /* @__PURE__ */ new Map();
+    this.pushProcessing = /* @__PURE__ */ new Map();
+    this.terminalOutcomes = /* @__PURE__ */ new Map();
     this.coordinator = options.coordinator;
     this.createSessionImpl = options.createSession ?? createSession;
     this.closeSessionAfterOperationFailure = closeSessionAfterRefund;
@@ -272,6 +286,10 @@ var UserCoordinatorSession = class {
     this.coordinatorErrorListeners.add(listener);
     return () => this.coordinatorErrorListeners.delete(listener);
   }
+  onStorageError(listener) {
+    this.storageErrorListeners.add(listener);
+    return () => this.storageErrorListeners.delete(listener);
+  }
   get currentSwapState() {
     return this.swapState;
   }
@@ -282,6 +300,9 @@ var UserCoordinatorSession = class {
   get currentSwapId() {
     return this.swapId;
   }
+  clientPersistenceState() {
+    return this.session ? getSessionState(this.session).clientPersistence : disabledClientPersistence();
+  }
   beginOperation() {
     this.activeOperations += 1;
     if (this.activeOperations === 1) this.setSessionStatus("connecting");
@@ -297,6 +318,7 @@ var UserCoordinatorSession = class {
     if (!context) {
       context = {
         swapId,
+        requestedAmountLamports: null,
         swapState: this.swapId === swapId ? this.swapState : "new",
         syncSecret: this.swapId === swapId && this.syncSecret ? new Uint8Array(this.syncSecret) : null,
         resumeSecret: this.swapId === swapId && this.resumeSecret ? new Uint8Array(this.resumeSecret) : null,
@@ -321,16 +343,19 @@ var UserCoordinatorSession = class {
     if (this.swapId === context.swapId) {
       this.swapState = state;
     }
-    this.emitStateChange(context.swapId, state);
     if (TERMINAL_SWAP_STATES.has(state)) {
       this.evictSwapContext(context.swapId);
     }
+    this.emitStateChange(context.swapId, state);
   }
   evictSwapContext(swapId) {
     this.statusReconciliationStops.get(swapId)?.();
     this.statusReconciliationStops.delete(swapId);
     const context = this.swapContexts.get(swapId);
     if (context) {
+      if (isTerminalSwapState(context.swapState)) {
+        this.rememberTerminalOutcome(swapId, context.swapState);
+      }
       context.syncSecret?.fill(0);
       context.resumeSecret?.fill(0);
       context.bufferedDepositConfirmed = null;
@@ -347,9 +372,26 @@ var UserCoordinatorSession = class {
   clearSwapContexts() {
     for (const swapId of this.swapContexts.keys()) this.evictSwapContext(swapId);
     this.swapContexts.clear();
+    this.pushProcessing.clear();
+    this.terminalOutcomes.clear();
     this.emittedPayoutKeys.clear();
     this.emittedRefundKeys.clear();
   }
+  isActiveSwapContext(context) {
+    return this.swapContexts.get(context.swapId) === context;
+  }
+  rememberTerminalOutcome(swapId, state, refund, storageError) {
+    const previous = this.terminalOutcomes.get(swapId);
+    this.terminalOutcomes.set(swapId, {
+      state,
+      ...refund !== void 0 && refund !== null ? { refund } : previous?.refund !== void 0 ? { refund: previous.refund } : {},
+      ...storageError !== void 0 ? { storageError } : previous?.storageError !== void 0 ? { storageError: previous.storageError } : {}
+    });
+    if (this.terminalOutcomes.size > MAX_EVENT_DEDUP_ENTRIES_PER_KIND) {
+      const oldest = this.terminalOutcomes.keys().next().value;
+      if (oldest !== void 0) this.terminalOutcomes.delete(oldest);
+    }
+  }
   async runSwap(params) {
     assertCurrentUserPayoutSpecRuntimeLimits(params.payoutSpec);
     this.beginOperation();
@@ -433,14 +475,38 @@ var UserCoordinatorSession = class {
       this.setSessionStatus("running");
       const context = this.ensureSwapContext(params.swapId);
       context.swapState = params.delegateShare ? "awaiting_deposit" : "awaiting_dkg";
+      context.bufferDepositConfirmedUntilDelegateAck = true;
       this.setCurrentContext(context);
       let jointPublicKey;
+      let depositAddress;
       let depositExpiresAtMs;
       let coordinatorTimestampMs;
       let delegateShare = params.delegateShare ? new Uint8Array(params.delegateShare) : void 0;
+      const persistence = this.clientPersistenceState();
+      const persistedResumeRecord = await readPersistedTransferForResume(
+        persistence,
+        context.swapId
+      );
+      if (params.delegateShare !== void 0 && persistedResumeRecord !== null) {
+        if (persistedResumeRecord.depositAddress === void 0 || persistedResumeRecord.depositExpiresAtMs === void 0 || persistedResumeRecord.coordinatorTimestampMs === void 0) {
+          throw new StorageError(
+            "STORAGE_KEY_MISSING",
+            "persisted DKG metadata is missing for saved delegate share",
+            { phase: "ready", swapId: context.swapId, remoteAccepted: false }
+          );
+        }
+        depositAddress = persistedResumeRecord.depositAddress;
+        depositExpiresAtMs = persistedResumeRecord.depositExpiresAtMs;
+        coordinatorTimestampMs = persistedResumeRecord.coordinatorTimestampMs;
+      }
       if (!delegateShare) {
-        const dkg = await this.runDkg(context, params.onDelegateShareReady);
+        const dkg = await this.runDkg(
+          context,
+          params.onDelegateShareReady,
+          persistedResumeRecord !== null
+        );
         jointPublicKey = dkg.jointPublicKey;
+        depositAddress = solanaAddressFromPublicKeyBytes(jointPublicKey);
         depositExpiresAtMs = dkg.depositExpiresAtMs;
         coordinatorTimestampMs = dkg.coordinatorTimestampMs;
         delegateShare = dkg.keyHandle.secretShareBytes();
@@ -476,8 +542,35 @@ var UserCoordinatorSession = class {
           "DelegateAck spending_policy does not match persisted policy_snapshot"
         );
       }
-      context.bufferDepositConfirmedUntilDelegateAck = false;
-      this.updateContextState(context, "awaiting_deposit");
+      context.requestedAmountLamports = delegateAck.spending_policy.entry_amount_lamports;
+      if (context.bufferedDepositConfirmed) {
+        assertDepositConfirmedAmount(
+          this.requireProtocol(),
+          context.bufferedDepositConfirmed,
+          delegateAck.spending_policy.entry_amount_lamports
+        );
+      }
+      if (persistedResumeRecord !== null) {
+        if (depositAddress === void 0 || depositExpiresAtMs === void 0 || coordinatorTimestampMs === void 0) {
+          throw new StorageError(
+            "STORAGE_KEY_MISSING",
+            "persisted DKG metadata is missing for saved delegate share",
+            { phase: "ready", swapId: context.swapId, remoteAccepted: true }
+          );
+        }
+        await persistTransferReady(persistence, {
+          swapId: context.swapId,
+          depositAddress,
+          depositExpiresAtMs,
+          delegatedAtMs,
+          coordinatorTimestampMs
+        });
+      }
+      const hadBufferedDeposit = context.bufferedDepositConfirmed !== null;
+      await this.releaseDepositConfirmedGate(context);
+      if (!hadBufferedDeposit && this.isActiveSwapContext(context)) {
+        this.updateContextState(context, "awaiting_deposit");
+      }
       completed = true;
       terminalStatus = "done";
       return {
@@ -518,6 +611,7 @@ var UserCoordinatorSession = class {
     this.statusReconciliationStops.clear();
   }
   restoreSwapContext(params) {
+    if (this.terminalOutcomes.has(params.swapId)) return;
     if (params.syncSecret !== void 0) {
       if (params.syncSecret.length !== SYNC_SECRET_BYTE_LENGTH) {
         throw new CommandError(
@@ -558,7 +652,13 @@ var UserCoordinatorSession = class {
       }
     );
     const status = this.requireProtocol().asSyncUserResponsePayload(env);
-    this.applySwapStatus(context, status, env.timestamp_ms);
+    const persistence = this.clientPersistenceState();
+    await this.enqueueSwapProcessing(context.swapId, async () => {
+      if (!this.isActiveSwapContext(context)) return;
+      await persistTransferStatus(persistence, context.swapId, status, env.timestamp_ms);
+      if (!this.isActiveSwapContext(context)) return;
+      this.applySwapStatus(context, status, env.timestamp_ms);
+    });
     return status;
   }
   startSwapStatusReconciliation(intervalMs = DEFAULT_SWAP_STATUS_RECONCILE_INTERVAL_MS) {
@@ -675,10 +775,12 @@ var UserCoordinatorSession = class {
           throw new CommandError("REJECTED_STATE", "syncSecret requires swapId");
         }
         this.restoreSwapContext({ swapId, syncSecret: params.syncSecret });
+        this.ensureRefundContext(swapId);
         requestSwapId = swapId;
       } else if (params.swapId) {
         const swapId = params.swapId;
         this.restoreSwapContext({ swapId });
+        this.ensureRefundContext(swapId);
         requestSwapId = swapId;
       }
       openedForRefund = !this.hasUsableSession();
@@ -703,9 +805,21 @@ var UserCoordinatorSession = class {
       }
       if (env.type === CoordinatorMessageType.WithdrawExecuted) {
         const resolvedSwapId2 = env.swap_id ?? requestSwapId;
-        const resolvedContext2 = resolvedSwapId2 ? this.ensureSwapContext(resolvedSwapId2) : null;
-        if (resolvedContext2) this.setCurrentContext(resolvedContext2);
-        return { kind: "executed", refund: this.requireProtocol().asWithdrawExecutedPayload(env) };
+        if (resolvedSwapId2) requestSwapId = resolvedSwapId2;
+        if (resolvedSwapId2) await this.waitForPushProcessing(resolvedSwapId2);
+        const terminalOutcome2 = resolvedSwapId2 ? this.terminalOutcomes.get(resolvedSwapId2) : void 0;
+        if (terminalOutcome2?.storageError) throw terminalOutcome2.storageError;
+        if (!terminalOutcome2) this.ensureRefundContext(resolvedSwapId2);
+        const refund = this.requireProtocol().asWithdrawExecutedPayload(env);
+        if (resolvedSwapId2 && terminalOutcome2?.refund === void 0) {
+          await persistTransferTerminal(
+            this.clientPersistenceState(),
+            resolvedSwapId2,
+            "refunded",
+            env.timestamp_ms
+          );
+        }
+        return { kind: "executed", refund };
       }
       if (env.type !== CoordinatorMessageType.WithdrawAccepted) {
         throw new CommandError(
@@ -715,10 +829,28 @@ var UserCoordinatorSession = class {
       }
       const accepted = this.requireProtocol().asWithdrawAcceptedPayload(env);
       const resolvedSwapId = env.swap_id ?? requestSwapId;
-      const resolvedContext = resolvedSwapId ? this.ensureSwapContext(resolvedSwapId) : null;
+      if (resolvedSwapId) requestSwapId = resolvedSwapId;
+      if (resolvedSwapId) await this.waitForPushProcessing(resolvedSwapId);
+      let terminalOutcome = resolvedSwapId ? this.terminalOutcomes.get(resolvedSwapId) : void 0;
+      if (terminalOutcome?.storageError) throw terminalOutcome.storageError;
+      let resolvedContext = terminalOutcome ? null : this.ensureRefundContext(resolvedSwapId);
+      if (resolvedSwapId && !terminalOutcome) {
+        await persistTransferRecoveryCode(
+          this.clientPersistenceState(),
+          resolvedSwapId,
+          recoveryCode
+        );
+        await this.waitForPushProcessing(resolvedSwapId);
+        terminalOutcome = this.terminalOutcomes.get(resolvedSwapId);
+        if (terminalOutcome?.storageError) throw terminalOutcome.storageError;
+        if (terminalOutcome) resolvedContext = null;
+      }
       if (!options.waitForFinality) {
         return { kind: "accepted", accepted };
       }
+      if (terminalOutcome?.refund !== void 0) {
+        return { kind: "executed", refund: terminalOutcome.refund };
+      }
       if (!resolvedContext) {
         throw new CommandError("REJECTED_STALE_JOB", REFUND_PENDING_FINALIZATION_MESSAGE);
       }
@@ -734,10 +866,21 @@ var UserCoordinatorSession = class {
       recoveryCode.fill(0);
       this.endOperation();
       if (openedForRefund && this.closeSessionAfterOperationFailure && this.activeOperations === 0) {
+        await this.waitForPushProcessing(requestSwapId);
         this.close();
       }
     }
   }
+  ensureRefundContext(swapId) {
+    if (swapId === null) return null;
+    if (this.terminalOutcomes.has(swapId)) return null;
+    const context = this.ensureSwapContext(swapId);
+    if (context.swapState === "new") {
+      context.swapState = "awaiting_deposit";
+      this.setCurrentContext(context);
+    }
+    return context;
+  }
   async awaitRefundOutcomeFromSwapStatus(context) {
     const deadline = Date.now() + DEFAULT_REFUND_OUTCOME_POLL_BUDGET_MS;
     for (; ; ) {
@@ -765,13 +908,11 @@ var UserCoordinatorSession = class {
     const protocol = this.requireProtocol();
     const prepared = await this.prepareContract(params);
     const depositEnv = await prepared.depositConfirmedPromise;
-    const depositPayload = protocol.asDepositConfirmedPayload(depositEnv);
-    if (depositPayload.amount_lamports !== params.amountLamports) {
-      throw new InvalidDepositAmountError(
-        BigInt(depositPayload.amount_lamports),
-        BigInt(params.amountLamports)
-      );
-    }
+    const depositPayload = assertDepositConfirmedAmount(
+      protocol,
+      depositEnv,
+      params.amountLamports
+    );
     this.log(
       `deposit confirmed tx=${depositPayload.tx_signature} amount=${depositPayload.amount_lamports}`,
       "in"
@@ -849,6 +990,7 @@ var UserCoordinatorSession = class {
     const swapId = swapPayload.swap_id;
     const context = {
       swapId,
+      requestedAmountLamports: params.amountLamports,
       swapState: "awaiting_dkg",
       syncSecret: new Uint8Array(syncSecret),
       resumeSecret: new Uint8Array(resumeSecret),
@@ -857,6 +999,14 @@ var UserCoordinatorSession = class {
     };
     this.swapContexts.set(swapId, context);
     this.setCurrentContext(context);
+    await persistTransferAllocation(this.clientPersistenceState(), {
+      swapId,
+      amountLamports: params.amountLamports,
+      payoutSpec: params.payoutSpec,
+      policySnapshot: swapPayload.policy_snapshot,
+      syncSecret,
+      coordinatorTimestampMs: swapResp.timestamp_ms
+    });
     await params.onSwapAllocated?.({
       swapId,
       syncSecretHex,
@@ -881,6 +1031,11 @@ var UserCoordinatorSession = class {
         recoveryCommitment = generated.commitment;
         try {
           recoveryCodeHex = recoveryCodeToHex(generated.code);
+          await persistTransferRecoveryCode(
+            this.clientPersistenceState(),
+            context.swapId,
+            generated.code
+          );
           await params.onRecoveryCodeReady?.({ codeHex: recoveryCodeHex });
         } finally {
           generated.code.fill(0);
@@ -917,8 +1072,22 @@ var UserCoordinatorSession = class {
           "DelegateAck spending_policy does not match ContractRequest policy_snapshot"
         );
       }
+      if (context.bufferedDepositConfirmed) {
+        assertDepositConfirmedAmount(
+          this.requireProtocol(),
+          context.bufferedDepositConfirmed,
+          params.amountLamports
+        );
+      }
+      await persistTransferReady(this.clientPersistenceState(), {
+        swapId,
+        depositAddress: solanaAddressFromPublicKeyBytes(jointPublicKey),
+        depositExpiresAtMs,
+        delegatedAtMs: delegateAck.delegated_at_ms,
+        coordinatorTimestampMs
+      });
       this.log(`delegated at ${delegateAck.delegated_at_ms}`, "in");
-      this.releaseDepositConfirmedGate(context);
+      await this.releaseDepositConfirmedGate(context);
       await params.onDepositAddressReady?.({
         swapId,
         jointPublicKey,
@@ -950,7 +1119,7 @@ var UserCoordinatorSession = class {
       }
     }
   }
-  async runDkg(context, onDelegateShareReady) {
+  async runDkg(context, onDelegateShareReady, persistDkgMetadata = true) {
     await ensureFrostWasm();
     const protocol = this.requireProtocol();
     const { dkgRound1 } = await loadFrost();
@@ -1007,6 +1176,14 @@ var UserCoordinatorSession = class {
         "DKG joint public key mismatch between Alice and coordinator"
       );
     }
+    if (persistDkgMetadata) {
+      await persistTransferDkgMetadata(this.clientPersistenceState(), {
+        swapId: context.swapId,
+        depositAddress: solanaAddressFromPublicKeyBytes(alicePubkey),
+        depositExpiresAtMs: complete.depositExpiresAtMs,
+        coordinatorTimestampMs: complete.coordinatorTimestampMs
+      });
+    }
     const pubkeyHexPrefix = Array.from(alicePubkey.slice(0, 8)).map((b) => b.toString(16).padStart(2, "0")).join("");
     this.log(`DKG complete - joint pubkey ${pubkeyHexPrefix}`, "info");
     return {
@@ -1081,6 +1258,18 @@ var UserCoordinatorSession = class {
   handleEnvelope(env) {
     const protocol = this.requireProtocol();
     this.log(`<- ${env.type} kind=${env.kind}`, "in");
+    if (env.kind === EnvelopeKind.PUSH) {
+      if (env.swap_id === null) {
+        this.log(`ignored ${env.type} without an explicit swap_id`, "info");
+        return;
+      }
+      if (!this.swapContexts.has(env.swap_id)) {
+        this.log(`ignored ${env.type} for unknown swap ${env.swap_id}`, "info");
+        return;
+      }
+      this.enqueuePush(env);
+      return;
+    }
     const context = env.swap_id ? this.swapContexts.get(env.swap_id) ?? null : null;
     if (env.swap_id === null && env.kind !== EnvelopeKind.ERROR) {
       this.log(`ignored ${env.type} without an explicit swap_id`, "info");
@@ -1090,27 +1279,8 @@ var UserCoordinatorSession = class {
       this.log(`ignored ${env.type} for unknown swap ${env.swap_id}`, "info");
       return;
     }
-    const payoutExecuted = env.kind === EnvelopeKind.PUSH && env.type === CoordinatorMessageType.PayoutExecuted ? protocol.asPayoutExecutedPayload(env) : null;
-    const payoutMatchesCurrentSwap = payoutExecuted !== null && context !== null;
-    const refundExecuted = env.kind === EnvelopeKind.PUSH && env.type === CoordinatorMessageType.WithdrawExecuted ? protocol.asWithdrawExecutedPayload(env) : null;
-    if (this.shouldBufferDepositConfirmed(env)) {
-      this.bufferDepositConfirmed(env);
-      return;
-    }
     const stateForEnvelope = context?.swapState ?? this.swapState;
-    const next = payoutExecuted !== null && !payoutMatchesCurrentSwap ? null : protocol.nextState(
-      stateForEnvelope,
-      env.kind,
-      env.type,
-      payoutExecuted ? { payoutFinal: payoutExecuted.final } : void 0
-    );
-    if (env.kind === EnvelopeKind.PUSH && next === null) {
-      this.log(
-        `ignored ${env.type} for swap ${env.swap_id ?? "null"} while client context is ${context?.swapId ?? "none"} in state ${stateForEnvelope}`,
-        "info"
-      );
-      return;
-    }
+    const next = protocol.nextState(stateForEnvelope, env.kind, env.type);
     if (next !== null) {
       if (context) {
         this.updateContextState(context, next);
@@ -1128,18 +1298,165 @@ var UserCoordinatorSession = class {
       }
       return;
     }
-    if (env.kind === EnvelopeKind.PUSH) {
-      if (payoutExecuted && payoutMatchesCurrentSwap && context) {
-        this.emitPayoutExecuted(payoutExecuted, context.swapId);
+  }
+  enqueuePush(env) {
+    const swapId = env.swap_id;
+    if (swapId === null) return;
+    const context = this.swapContexts.get(swapId);
+    if (context === void 0) return;
+    const persistence = this.clientPersistenceState();
+    void this.enqueueSwapProcessing(
+      swapId,
+      () => this.processPushEnvelope(env, context, persistence)
+    ).catch(() => void 0);
+  }
+  enqueueSwapProcessing(swapId, process) {
+    const previous = this.pushProcessing.get(swapId) ?? Promise.resolve();
+    const processing = previous.catch(() => void 0).then(process);
+    this.pushProcessing.set(swapId, processing);
+    void processing.finally(() => {
+      if (this.pushProcessing.get(swapId) === processing) {
+        this.pushProcessing.delete(swapId);
+      }
+    }).catch(() => void 0);
+    return processing;
+  }
+  async waitForPushProcessing(swapId) {
+    if (swapId === null) return;
+    await (this.pushProcessing.get(swapId)?.catch(() => void 0) ?? Promise.resolve());
+  }
+  async processPushEnvelope(env, context, persistence) {
+    const protocol = this.requireProtocol();
+    const payoutExecuted = env.type === CoordinatorMessageType.PayoutExecuted ? protocol.asPayoutExecutedPayload(env) : null;
+    const refundExecuted = env.type === CoordinatorMessageType.WithdrawExecuted ? protocol.asWithdrawExecutedPayload(env) : null;
+    if (this.shouldBufferDepositConfirmed(env)) {
+      this.bufferDepositConfirmed(env);
+      return;
+    }
+    if (env.type === CoordinatorMessageType.DkgComplete) {
+      this.settlePushListener(env);
+      return;
+    }
+    if (env.type === CoordinatorMessageType.DepositConfirmed) {
+      if (context.requestedAmountLamports === null) {
+        this.log(
+          `ignored DepositConfirmed for swap ${context.swapId} without requested amount`,
+          "info"
+        );
+        return;
+      }
+      try {
+        assertDepositConfirmedAmount(protocol, env, context.requestedAmountLamports);
+      } catch (error) {
+        this.settlePushListener(env, error instanceof Error ? error : new Error(String(error)));
+        return;
+      }
+    }
+    const next = protocol.nextState(
+      context.swapState,
+      env.kind,
+      env.type,
+      payoutExecuted ? { payoutFinal: payoutExecuted.final } : void 0
+    );
+    if (next === null) {
+      this.log(
+        `ignored ${env.type} for swap ${env.swap_id ?? "null"} while client context is ${context.swapId} in state ${context.swapState}`,
+        "info"
+      );
+      return;
+    }
+    if (env.type === CoordinatorMessageType.DelegateAck) {
+      if (!this.isActiveSwapContext(context)) {
+        context.swapState = next;
+        return;
+      }
+      this.updateContextState(context, next);
+      this.settlePushListener(env);
+      return;
+    }
+    if (isTerminalSwapState(next)) {
+      await this.handleTerminalPush(
+        env,
+        context,
+        next,
+        payoutExecuted,
+        refundExecuted,
+        persistence
+      );
+      return;
+    }
+    await this.handleNonTerminalPush(env, context, next, payoutExecuted, persistence);
+  }
+  async handleNonTerminalPush(env, context, next, payoutExecuted, persistence) {
+    if (!this.isActiveSwapContext(context)) {
+      context.swapState = next;
+      return;
+    }
+    let storageError = null;
+    try {
+      await persistTransferStatus(persistence, context.swapId, { state: next }, env.timestamp_ms);
+    } catch (error) {
+      storageError = storageErrorFromPush(error, context.swapId, null);
+    }
+    if (!this.isActiveSwapContext(context)) {
+      context.swapState = next;
+      return;
+    }
+    try {
+      this.updateContextState(context, next);
+      if (payoutExecuted) this.emitPayoutExecuted(payoutExecuted, context.swapId);
+    } finally {
+      try {
+        if (storageError) this.emitStorageError(storageError);
+      } finally {
+        this.settlePushListener(env);
       }
-      if (refundExecuted && context) {
-        this.emitRefundExecuted(refundExecuted, context.swapId);
+    }
+  }
+  async handleTerminalPush(env, context, next, payoutExecuted, refundExecuted, persistence) {
+    this.rememberTerminalOutcome(context.swapId, next, refundExecuted);
+    let storageError = null;
+    if (persistence.enabled) {
+      try {
+        await persistTransferTerminal(
+          persistence,
+          context.swapId,
+          next,
+          env.timestamp_ms,
+          refundExecuted ? "refund" : "sync"
+        );
+      } catch (error) {
+        storageError = storageErrorFromPush(error, context.swapId, refundExecuted);
+      }
+    }
+    if (storageError) {
+      this.rememberTerminalOutcome(context.swapId, next, refundExecuted, storageError);
+    }
+    if (!this.isActiveSwapContext(context)) {
+      context.swapState = next;
+      return;
+    }
+    try {
+      this.updateContextState(context, next);
+      if (payoutExecuted) this.emitPayoutExecuted(payoutExecuted, context.swapId);
+      if (refundExecuted) this.emitRefundExecuted(refundExecuted, context.swapId);
+    } finally {
+      try {
+        if (storageError) this.emitStorageError(storageError);
+      } finally {
+        this.settlePushListener(env);
       }
-      this.resolvePushListener(env);
     }
   }
+  emitStorageError(error) {
+    for (const listener of this.storageErrorListeners) listener(error);
+    this.log(`client persistence failed: ${normalizeError(error)}`, "info");
+  }
   applySwapStatus(context, status, coordinatorTimestampMs) {
     const keepTerminalState = TERMINAL_SWAP_STATES.has(context.swapState) && status.state !== context.swapState;
+    if (!keepTerminalState && isTerminalSwapState(status.state)) {
+      this.rememberTerminalOutcome(context.swapId, status.state, status.withdraw_execution);
+    }
     if (!keepTerminalState && context.swapState !== status.state) {
       this.updateContextState(context, status.state);
     }
@@ -1237,7 +1554,7 @@ var UserCoordinatorSession = class {
     }
     this.log("ignored duplicate DepositConfirmed while waiting for DelegateAck", "info");
   }
-  releaseDepositConfirmedGate(context) {
+  async releaseDepositConfirmedGate(context) {
     const protocol = this.requireProtocol();
     context.bufferDepositConfirmedUntilDelegateAck = false;
     const buffered = context.bufferedDepositConfirmed;
@@ -1248,10 +1565,26 @@ var UserCoordinatorSession = class {
       this.log(`ignored buffered DepositConfirmed in state ${context.swapState}`, "info");
       return;
     }
+    let storageError = null;
+    try {
+      await persistTransferStatus(
+        this.clientPersistenceState(),
+        context.swapId,
+        { state: next },
+        buffered.timestamp_ms
+      );
+    } catch (error) {
+      storageError = storageErrorFromPush(error, context.swapId, null);
+    }
+    if (storageError) {
+      this.emitStorageError(storageError);
+      throw storageError;
+    }
+    if (!this.isActiveSwapContext(context)) return;
     this.updateContextState(context, next);
-    this.resolvePushListener(buffered);
+    this.settlePushListener(buffered);
   }
-  resolvePushListener(env) {
+  settlePushListener(env, error) {
     const listeners = this.pushListeners.get(env.type);
     if (!listeners) return;
     const index = listeners.findIndex(
@@ -1261,7 +1594,8 @@ var UserCoordinatorSession = class {
     const listener = listeners.splice(index, 1)[0];
     if (listeners.length === 0) this.pushListeners.delete(env.type);
     if (listener.timer) clearTimeout(listener.timer);
-    listener.resolve(env);
+    if (error) listener.reject(error);
+    else listener.resolve(env);
   }
   clearPushListenerTimer(type, swapId) {
     const listener = this.pushListeners.get(type)?.find((candidate) => candidate.swapId === void 0 || candidate.swapId === swapId);
@@ -1420,6 +1754,12 @@ async function requestUserSync(session, swapId, syncSecret, timeoutMs) {
   );
   const payload = (await loadProtocol()).asSyncUserResponsePayload(env);
   assertSyncResponseContractId(env, payload, swapId);
+  await persistTransferStatus(
+    getSessionState(session).clientPersistence,
+    swapId,
+    payload,
+    env.timestamp_ms
+  );
   return {
     ...payload,
     coordinatorTimestampMs: env.timestamp_ms
@@ -1503,6 +1843,18 @@ function isRetryableSwapStatusReconciliationError(err) {
   if (err instanceof AttestationError) return false;
   return err instanceof CommandError && err.code === "REJECTED_STALE_JOB";
 }
+function isTerminalSwapState(state) {
+  return state === "completed" || state === "refunded" || state === "failed";
+}
+function storageErrorFromPush(error, swapId, refundExecuted) {
+  if (error instanceof StorageError) return error;
+  return new StorageError("STORAGE_NOT_AVAILABLE", "client persistence update failed", {
+    cause: error,
+    swapId,
+    phase: refundExecuted ? "refund" : "sync",
+    remoteAccepted: true
+  });
+}
 function coordinatorErrorFromEnvelope(protocol, env) {
   try {
     const payload = protocol.asErrorPayload(env);