fix(core): record melt quotes before settlement

.changeset/melt-observation-before-settlement.md

@@ -0,0 +1,6 @@
+---
+'@cashu/coco-core': patch
+---
+
+Record pending melt quote observations before settling local melt operations, and use cached PAID
+observations during recovery only when serialized settlement change is available.

packages/core/infra/handlers/melt/BaseQuoteMeltHandler.ts

@@ -147,6 +147,32 @@ export abstract class BaseQuoteMeltHandler<M extends MeltMethod> implements Melt
     return { changeAmount, effectiveFee };
   }
 
+  private getPersistedSettlementResponse(quote?: MeltQuote<M>): QuoteMeltResponse<M> | null {
+    if (!quote || quote.state !== 'PAID') {
+      return null;
+    }
+
+    if (!Array.isArray(quote.change)) {
+      return null;
+    }
+
+    const change = quote.change;
+
+    if (quote.method === 'onchain') {
+      return {
+        state: quote.state,
+        change,
+        outpoint: quote.outpoint ?? null,
+      } as QuoteMeltResponse<M>;
+    }
+
+    return {
+      state: quote.state,
+      change,
+      payment_preimage: quote.payment_preimage ?? null,
+    } as QuoteMeltResponse<M>;
+  }
+
   /**
    * Returns the amount of proofs that were actually sent to the melt call.
    * For swap melts this excludes proofs kept locally after the pre-swap.
@@ -570,8 +596,14 @@ export abstract class BaseQuoteMeltHandler<M extends MeltMethod> implements Melt
 
     ctx.logger?.debug('Finalizing pending melt operation', { operationId, quoteId });
 
-    // Fetch current melt quote state from mint to get change signatures
-    const res = await this.checkMeltQuote(ctx);
+    const persistedSettlement = this.getPersistedSettlementResponse(ctx.canonicalQuote);
+    if (ctx.canonicalQuote && ctx.canonicalQuote.state !== 'PAID') {
+      throw new Error(
+        `Cannot finalize: melt quote ${quoteId} is ${ctx.canonicalQuote.state}, expected PAID`,
+      );
+    }
+
+    const res = persistedSettlement ?? (await this.checkMeltQuote(ctx));
 
     if (res.state !== 'PAID') {
       throw new Error(`Cannot finalize: melt quote ${quoteId} is ${res.state}, expected PAID`);
@@ -649,7 +681,7 @@ export abstract class BaseQuoteMeltHandler<M extends MeltMethod> implements Melt
 
     ctx.logger?.debug('Checking pending melt operation', { operationId, quoteId });
 
-    const state = await this.checkMeltQuoteState(ctx);
+    const state = ctx.canonicalQuote?.state ?? (await this.checkMeltQuoteState(ctx));
 
     ctx.logger?.debug('Pending melt quote state', { operationId, quoteId, state });
 

packages/core/operations/melt/MeltMethodHandler.ts

@@ -136,10 +136,12 @@ export interface ExecuteContext<M extends MeltMethod = MeltMethod> extends BaseH
 export interface PendingContext<M extends MeltMethod = MeltMethod> extends BaseHandlerDeps {
   operation: PendingMeltOperation & MeltMethodMeta<M>;
   wallet: Wallet;
+  canonicalQuote?: MeltQuote<M>;
 }
 
 export interface FinalizeContext<M extends MeltMethod = MeltMethod> extends BaseHandlerDeps {
   operation: PendingMeltOperation & MeltMethodMeta<M>;
+  canonicalQuote?: MeltQuote<M>;
 }
 
 export type FinalizeResult<M extends MeltMethod = MeltMethod> = {

packages/core/operations/melt/MeltOperationService.ts

@@ -106,6 +106,29 @@ export class MeltOperationService {
     return this.recoveryLock !== null;
   }
 
+  private async resolvePendingSettlementQuote(
+    op: PendingMeltOperation,
+    canonicalQuote?: MeltQuote,
+  ): Promise<MeltQuote> {
+    if (canonicalQuote) {
+      if (canonicalQuote.state === 'PAID' && !Array.isArray(canonicalQuote.change)) {
+        return this.quoteLifecycle.refreshMeltQuote(op.mintUrl, op.method, op.quoteId);
+      }
+      return canonicalQuote;
+    }
+
+    const persistedQuote = await this.quoteLifecycle.getMeltQuote(
+      op.mintUrl,
+      op.method,
+      op.quoteId,
+    );
+    if (persistedQuote?.state === 'PAID' && Array.isArray(persistedQuote.change)) {
+      return persistedQuote;
+    }
+
+    return this.quoteLifecycle.refreshMeltQuote(op.mintUrl, op.method, op.quoteId);
+  }
+
   async init(
     mintUrl: string,
     method: MeltMethod,
@@ -430,7 +453,10 @@ export class MeltOperationService {
     }
   }
 
-  async finalize(operationId: string): Promise<FinalizeResult> {
+  async finalize(
+    operationId: string,
+    options: { canonicalQuote?: MeltQuote } = {},
+  ): Promise<FinalizeResult> {
     const releaseLock = await this.acquireOperationLock(operationId);
     try {
       const operation = await this.meltOperationRepository.getById(operationId);
@@ -459,9 +485,14 @@ export class MeltOperationService {
 
       const pendingOp = operation as PendingMeltOperation;
       const handler = this.handlerProvider.get(pendingOp.method);
+      const canonicalQuote = await this.resolvePendingSettlementQuote(
+        pendingOp,
+        options.canonicalQuote,
+      );
       const finalizeResult = await handler.finalize?.({
         ...this.buildDeps(),
         operation: pendingOp,
+        canonicalQuote,
       });
 
       const finalized: FinalizedMeltOperation = {
@@ -496,7 +527,11 @@ export class MeltOperationService {
     }
   }
 
-  async rollback(operationId: string, reason = 'Rolled back'): Promise<void> {
+  async rollback(
+    operationId: string,
+    reason = 'Rolled back',
+    options: { canonicalQuote?: MeltQuote } = {},
+  ): Promise<void> {
     const releaseLock = await this.acquireOperationLock(operationId);
     try {
       const operation = await this.meltOperationRepository.getById(operationId);
@@ -528,10 +563,13 @@ export class MeltOperationService {
       // This prevents releasing proofs that are still inflight with the Lightning network.
       if (operation.state === 'pending') {
         const pendingOp = operation as PendingMeltOperation;
+        // Re-read the quote while holding the operation lock; a pre-lock snapshot may be stale.
+        const canonicalQuote = await this.resolvePendingSettlementQuote(pendingOp);
         const decision = await handler.checkPending?.({
           ...this.buildDeps(),
           operation: pendingOp,
           wallet,
+          canonicalQuote,
         });
         if (decision !== 'rollback') {
           throw new Error(
@@ -663,17 +701,32 @@ export class MeltOperationService {
         }'`,
       );
     }
+    const persistedQuote = await this.quoteLifecycle.getMeltQuote(
+      op.mintUrl,
+      op.method,
+      op.quoteId,
+    );
+    if (persistedQuote?.state === 'PAID') {
+      await this.finalize(op.id, { canonicalQuote: persistedQuote });
+      return 'finalize';
+    }
+
     const handler = this.handlerProvider.get(op.method);
     const { wallet } = await this.walletService.getWalletWithActiveKeysetId(op.mintUrl, op.unit);
+    const quote = await this.quoteLifecycle.refreshMeltQuoteById({
+      mintUrl: op.mintUrl,
+      quoteId: op.quoteId,
+    });
     const decision: PendingCheckResult =
       (await handler.checkPending?.({
         ...this.buildDeps(),
         operation: op,
         wallet,
+        canonicalQuote: quote,
       })) ?? 'stay_pending';
 
     if (decision === 'finalize') {
-      await this.finalize(op.id);
+      await this.finalize(op.id, { canonicalQuote: quote });
       return 'finalize';
     } else if (decision === 'rollback') {
       await this.rollback(op.id, 'Rollback requested by handler');

packages/core/quotes/QuoteLifecycle.ts

@@ -155,6 +155,15 @@ function getMeltQuoteChange(existing: MeltQuote | null, incoming: MeltQuote): bo
   );
 }
 
+function shouldEnrichPaidMeltQuoteSettlement(existing: MeltQuote, incoming: MeltQuote): boolean {
+  return (
+    existing.state === 'PAID' &&
+    incoming.state === 'PAID' &&
+    !Array.isArray(existing.change) &&
+    Array.isArray(incoming.change)
+  );
+}
+
 export interface QuoteLifecycleDeps {
   mintHandlerProvider: MintHandlerProvider;
   meltHandlerProvider: MeltHandlerProvider;
@@ -718,6 +727,22 @@ export class QuoteLifecycle {
     );
 
     if (existing?.state === 'PAID') {
+      if (shouldEnrichPaidMeltQuoteSettlement(existing, canonicalQuote)) {
+        const persisted = await this.persistCanonicalMeltQuote({
+          ...existing,
+          change: canonicalQuote.change,
+          lastObservedRemoteState:
+            canonicalQuote.lastObservedRemoteState ?? existing.lastObservedRemoteState,
+          lastObservedRemoteStateAt:
+            canonicalQuote.lastObservedRemoteStateAt ?? existing.lastObservedRemoteStateAt,
+          updatedAt: canonicalQuote.updatedAt,
+        } as MeltQuote);
+        return {
+          quote: persisted,
+          remoteQuoteChanged: true,
+        };
+      }
+
       return {
         quote: existing,
         remoteQuoteChanged: false,

packages/core/test/unit/MeltBolt11Handler.test.ts

@@ -11,6 +11,7 @@ import {
 } from '../../infra/handlers/melt/QuoteMeltHandler.utils';
 import type { Logger } from '../../logging/Logger';
 import { MintOperationError, ProofValidationError } from '../../models/Error';
+import { meltQuoteFromBolt11Response } from '../../models/MeltQuote';
 import type {
   BasePrepareContext,
   CreateMeltQuoteContext,
@@ -903,6 +904,41 @@ describe('MeltBolt11Handler', () => {
   // ============================================================================
 
   describe('finalize', () => {
+    it('should finalize a pending operation from persisted canonical settlement fields', async () => {
+      const operation = makePendingOp('op-canonical-finalize', {
+        needsSwap: false,
+        inputProofSecrets: ['input-1'],
+      });
+      const changeSignatures: SerializedBlindedSignature[] = [
+        { id: keysetId, amount: Amount.from(5), C_: 'C_change' },
+      ];
+      const quote = meltQuoteFromBolt11Response(mintUrl, {
+        quote: operation.quoteId,
+        request: invoice,
+        amount: operation.amount,
+        unit: operation.unit,
+        fee_reserve: operation.fee_reserve,
+        expiry: Math.floor(Date.now() / 1000) + 3600,
+        state: 'PAID',
+        payment_preimage: 'preimage-canonical',
+        change: changeSignatures,
+      });
+
+      const result = await handler.finalize({
+        ...buildFinalizeContext(operation),
+        canonicalQuote: quote,
+      });
+
+      expect(mintAdapter.checkMeltQuote).not.toHaveBeenCalled();
+      expect(proofService.setProofState).toHaveBeenCalledWith(mintUrl, ['input-1'], 'spent');
+      expect(proofService.unblindAndSaveChangeProofs).toHaveBeenCalled();
+      expect(result).toEqual({
+        changeAmount: Amount.from(5),
+        effectiveFee: Amount.from(5),
+        finalizedData: { preimage: 'preimage-canonical' },
+      });
+    });
+
     it('should finalize a pending operation by fetching change', async () => {
       const operation = makePendingOp('op-1', {
         needsSwap: false,
@@ -933,6 +969,71 @@ describe('MeltBolt11Handler', () => {
       });
     });
 
+    it('should fetch full settlement when a PAID canonical quote omits change', async () => {
+      const operation = makePendingOp('op-partial-canonical', {
+        needsSwap: false,
+        inputProofSecrets: ['input-1'],
+      });
+      const changeSignatures: SerializedBlindedSignature[] = [
+        { id: keysetId, amount: Amount.from(5), C_: 'C_change' },
+      ];
+      const quote = meltQuoteFromBolt11Response(mintUrl, {
+        quote: operation.quoteId,
+        request: invoice,
+        amount: operation.amount,
+        unit: operation.unit,
+        fee_reserve: operation.fee_reserve,
+        expiry: Math.floor(Date.now() / 1000) + 3600,
+        state: 'PAID',
+        payment_preimage: 'preimage-partial',
+      });
+      (mintAdapter.checkMeltQuote as Mock<any>).mockImplementation(() =>
+        Promise.resolve({
+          state: 'PAID',
+          change: changeSignatures,
+          payment_preimage: 'preimage-remote',
+        }),
+      );
+
+      const result = await handler.finalize({
+        ...buildFinalizeContext(operation),
+        canonicalQuote: quote,
+      });
+
+      expect(mintAdapter.checkMeltQuote).toHaveBeenCalledWith(mintUrl, operation.quoteId);
+      expect(proofService.unblindAndSaveChangeProofs).toHaveBeenCalled();
+      expect(result).toEqual({
+        changeAmount: Amount.from(5),
+        effectiveFee: Amount.from(5),
+        finalizedData: { preimage: 'preimage-remote' },
+      });
+    });
+
+    it('should not re-check the mint when a supplied canonical quote is not PAID', async () => {
+      const operation = makePendingOp('op-canonical-pending');
+      const quote = meltQuoteFromBolt11Response(mintUrl, {
+        quote: operation.quoteId,
+        request: invoice,
+        amount: operation.amount,
+        unit: operation.unit,
+        fee_reserve: operation.fee_reserve,
+        expiry: Math.floor(Date.now() / 1000) + 3600,
+        state: 'PENDING',
+        payment_preimage: null,
+      });
+      (mintAdapter.checkMeltQuote as Mock<any>).mockImplementation(() =>
+        Promise.resolve({ state: 'PAID', change: [], payment_preimage: 'preimage-remote' }),
+      );
+
+      await expect(
+        handler.finalize({
+          ...buildFinalizeContext(operation),
+          canonicalQuote: quote,
+        }),
+      ).rejects.toThrow('Cannot finalize: melt quote quote-123 is PENDING, expected PAID');
+      expect(mintAdapter.checkMeltQuote).not.toHaveBeenCalled();
+    });
+
     it('should throw if quote is not PAID', async () => {
       const operation = makePendingOp('op-1');
       (mintAdapter.checkMeltQuote as Mock<any>).mockImplementation(() =>

packages/core/test/unit/MeltOnchainHandler.test.ts

@@ -1,6 +1,7 @@
 import { Amount } from '@cashu/cashu-ts';
 import { describe, expect, it, mock } from 'bun:test';
 import { MeltOnchainHandler } from '../../infra/handlers/melt/MeltOnchainHandler.ts';
+import { meltQuoteFromOnchainResponse } from '../../models/MeltQuote.ts';
 import type {
   BasePrepareContext,
   CreateMeltQuoteContext,
@@ -237,4 +238,26 @@ describe('MeltOnchainHandler', () => {
     expect(deps.mintAdapter.checkMeltQuoteOnchain).toHaveBeenCalledWith(mintUrl, quoteId);
     expect(result.finalizedData).toBeUndefined();
   });
+
+  it('finalizes pending onchain melt quotes from persisted canonical settlement fields', async () => {
+    const handler = new MeltOnchainHandler();
+    const deps = baseDeps();
+    const quote = meltQuoteFromOnchainResponse(mintUrl, {
+      ...remoteQuote,
+      state: 'PAID',
+      outpoint: 'txid:0',
+      change: [],
+    });
+
+    const result = await handler.finalize({
+      ...deps,
+      operation: buildPendingOperation(),
+      wallet: {},
+      canonicalQuote: quote,
+    } as unknown as FinalizeContext<'onchain'>);
+
+    expect(deps.mintAdapter.checkMeltQuoteOnchain).not.toHaveBeenCalled();
+    expect(deps.proofService.setProofState).toHaveBeenCalledWith(mintUrl, ['secret-1'], 'spent');
+    expect(result.finalizedData).toEqual({ outpoint: 'txid:0' });
+  });
 });