Never map a Solana confirmation timeout to regenerate/pay-again (#105)

## Summary

Fixes a live double-charge on the Solana MPP rail, shared by all three
hosted stores.

`@solana/mpp`'s `verifyTransaction` broadcasts the transfer (funds move,
a signature is minted) and then awaits confirmation in the same
synchronous `verify()` call, with a hardcoded 30s window not exposed
through `charge()`. Under load that window can expire before the network
surfaces confirmation, even on a healthy production RPC (verified:
Helius `getHealth` ok in ~70ms during the failure), so `verify()` throws
`Transaction confirmation timeout` on a transfer that may already have
landed. `Checkout.handleMppx` mapped every unclassified mppx failure to
`payment_proof_invalid` + `regenerate_payment_credential`, so the
merchant told the agent to pay again for money that already left the
wallet. Observed live 2026-08-12 on scaledown and fullenrich: an
on-chain balance delta with no service delivered and a regenerate 402 in
hand.

`classifyMppxFailure` now recognizes the confirmation-timeout reason and
returns `payment_pending_confirmation` (HTTP 504, `action:
check_settlement_before_retry`) with a message telling the buyer to
verify settlement before retrying. 504 rather than 402 is deliberate:
x402/MPP clients version-route on status and a 402 auto-triggers a
re-pay retry, which is the double-charge this guards. A confirmation
timeout cannot be reliably distinguished from never-landed (the recovery
`getSignatureStatuses` with `searchTransactionHistory` lags too), so the
response surfaces the ambiguity rather than asserting success or
failure.

## Type of change

- [x] Bug fix (no breaking change)
- [ ] New feature (no breaking change)
- [ ] Breaking change (existing callers must update)
- [ ] Docs, tests, or internal maintenance only

## Public API

No signature changes. Behavior change on one error path only: a Solana
MPP settle whose confirmation times out now returns HTTP 504
`payment_pending_confirmation` instead of a 402 `payment_proof_invalid`
/ `regenerate_payment_credential`. Callers that branched on that 402 to
auto-repay should treat 504 as "submitted, unconfirmed, do not blindly
resubmit."

## Test plan

lint (0 warnings), typecheck including examples, full suite 1808
passing, build clean. New coverage: the classifier returns 504
`payment_pending_confirmation` (never 402, never
`regenerate_payment_credential`) with a do-not-double-pay message on
both the plain and status-recovery-failed variants; a Checkout-level
test proves a captured `Transaction confirmation timeout` yields 504
rather than the regenerate 402.

## Checklist

- [x] Tests cover the new behavior, and the suite passes locally
- [x] Lint, format, and type checks pass
- [x] Docs and README examples updated if the public surface changed
- [x] No secrets, credentials, or personal data in the diff or the tests

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: vvillait88

src/payment/mppx_failures.ts

@@ -39,6 +39,43 @@ const TEMPO_KEY_NOT_REGISTERED: ClassifiedMppxFailure = {
   extra: { upstream_error: 'KeyNotFound', chain: 'tempo' },
 };
 
+/**
+ * The DANGEROUS one, and why this classifier is not just a nicety.
+ *
+ * `@solana/mpp` verifies a `transaction`-payload credential by BROADCASTING it
+ * (`sendTransaction`, so funds move and a signature is minted) and THEN
+ * awaiting confirmation in the same synchronous verify() call. When
+ * confirmation times out (routine under load, since Solana status propagation
+ * can lag the library's fixed 30s window even on a production RPC), verify()
+ * throws `Transaction confirmation timeout` on a transaction that MAY HAVE
+ * ALREADY LANDED. Left unclassified, that maps to the generic
+ * `payment_proof_invalid` + `regenerate_payment_credential`: the merchant
+ * tells the agent its payment was rejected and to pay AGAIN, for money that
+ * already left the wallet. Observed live 2026-08-12 (an on-chain balance delta
+ * with no service delivered and a "regenerate" 402 in hand).
+ *
+ * A confirmation timeout cannot be reliably told apart from "never landed"
+ * (the recovery `getSignatureStatuses` with searchTransactionHistory lags
+ * too), so the honest response is neither "success" nor "invalid, repay". It
+ * is 504 with an explicit do-not-blindly-resubmit instruction: the payment was
+ * submitted, its on-chain state is unconfirmed, and the buyer must check
+ * whether it settled before paying a second time. x402/MPP clients version-
+ * route on status; 504 (unlike 402) does not trigger an automatic
+ * re-pay-with-new-credential retry, which is the whole point.
+ */
+const SOLANA_CONFIRMATION_TIMEOUT: ClassifiedMppxFailure = {
+  code: 'payment_pending_confirmation',
+  status: 504,
+  message:
+    'Payment was submitted on-chain but its confirmation timed out. It may have settled. Do NOT resubmit without checking first, or you risk paying twice.',
+  nextSteps: {
+    action: 'check_settlement_before_retry',
+    user_message:
+      'Your payment was broadcast to the network but confirmation timed out, so it is unconfirmed rather than failed. Check your wallet balance and the recipient before retrying: if the balance decreased, the payment likely landed and you should NOT pay again — wait for the merchant to reconcile or contact support. Only resubmit if the funds are still in your wallet.',
+  },
+  extra: { chain: 'solana', broadcast: true },
+};
+
 /** Classify a failure reason against known patterns.
  *
  *  Returns `null` when the reason is unrecognized — callers fall back to
@@ -52,5 +89,10 @@ export function classifyMppxFailure(reason: string | null | undefined): Classifi
   if (lower.includes('keychain validation failed') || lower.includes('keynotfound')) {
     return TEMPO_KEY_NOT_REGISTERED;
   }
+  // A broadcast Solana transfer whose confirmation timed out: money may have
+  // moved, so this must never fall through to `regenerate_payment_credential`.
+  if (lower.includes('confirmation timeout') || lower.includes('confirmation timed out')) {
+    return SOLANA_CONFIRMATION_TIMEOUT;
+  }
   return null;
 }

tests/checkout.test.ts

@@ -256,6 +256,33 @@ describe('Checkout — composeMppx hook', () => {
     expect(result.settlePhase).toBe('verify_failed');
   });
 
+  it('a Solana confirmation timeout does NOT become a regenerate/pay-again 402', async () => {
+    // The dangerous case: @solana/mpp broadcast the transfer (money moved),
+    // then confirmation timed out and verify() threw. This must NOT reach the
+    // agent as `payment_proof_invalid` + regenerate, or a compliant client
+    // pays twice.
+    const composeMppx = vi.fn(
+      async (): Promise<MppxComposeOutcome> => {
+        console.error('mppx: internal verification error', {
+          message: 'Transaction confirmation timeout',
+        });
+        return { status: 402, headers: { 'www-authenticate': 'Payment id="ord_x"' } };
+      },
+    );
+    const checkout = new Checkout({
+      rails: { solanaMpp: { recipient: 'SoLanaRecipient1111111111111111111111111111' } as never },
+      url: 'https://api.example/purchase',
+      computePricing: () => ({ amountUsd: 1 }),
+      composeMppx,
+    });
+    const result = await checkout.handle(req({ headers: { authorization: `Payment ${FAKE_MPP_CRED}` } }));
+    expect(result.status).toBe(504);
+    const err = result.body.error as Record<string, unknown>;
+    expect(err.code).toBe('payment_pending_confirmation');
+    expect(err.code).not.toBe('payment_proof_invalid');
+    expect((result.body.next_steps as Record<string, unknown>).action).not.toBe('regenerate_payment_credential');
+  });
+
   it('discovery-leg compose_mppx layers fresh WWW-Auth into the 402', async () => {
     const composeMppx = vi.fn(
       async (): Promise<MppxComposeOutcome> => ({

tests/payment/mppx_failures.test.ts

@@ -14,6 +14,37 @@ describe('classifyMppxFailure', () => {
     expect(classifyMppxFailure('Transaction reverted: ERC20: transfer amount exceeds balance')).toBeNull();
   });
 
+  describe('Solana confirmation timeout (broadcast-then-unconfirmed)', () => {
+    it('classifies a confirmation timeout as pending, NOT as regenerate/pay-again', () => {
+      const out = classifyMppxFailure('Transaction confirmation timeout');
+      expect(out).not.toBeNull();
+      expect(out?.code).toBe('payment_pending_confirmation');
+      // 504, not 402: a 402 would trigger x402 clients to auto-repay, which is
+      // exactly the double-charge this guards against.
+      expect(out?.status).toBe(504);
+      expect(out?.status).not.toBe(402);
+      // The action must never tell the agent to regenerate the credential.
+      expect(out?.nextSteps.action).not.toBe('regenerate_payment_credential');
+      expect(out?.nextSteps.action).toBe('check_settlement_before_retry');
+      expect(out?.extra?.chain).toBe('solana');
+      expect(out?.extra?.broadcast).toBe(true);
+    });
+
+    it('matches the status-recovery-failed variant too', () => {
+      const out = classifyMppxFailure(
+        'Transaction confirmation timeout (status recovery failed: RPC error)',
+      );
+      expect(out?.code).toBe('payment_pending_confirmation');
+    });
+
+    it('warns the buyer not to pay twice and to check the balance first', () => {
+      const msg = classifyMppxFailure('Transaction confirmation timeout')!.nextSteps.user_message;
+      expect(msg.toLowerCase()).toContain('confirmation timed out');
+      expect(msg.toLowerCase()).toMatch(/check your (wallet )?balance/);
+      expect(msg.toLowerCase()).toMatch(/not pay again|only resubmit/);
+    });
+  });
+
   it('classifies Tempo keychain rejection by literal pattern', () => {
     const out = classifyMppxFailure(
       'RPC Request failed. (keychain validation failed: AccountKeychainError(KeyNotFound(KeyNotFound)))',