feat(svm): add post-settlement transfer verification (TOCTOU defense)

After confirmTransaction on Path 2 (smart wallet) settlements, verify
the TransferChecked actually executed on-chain before returning success.

Primary: fetch confirmed transaction inner instructions via getTransaction.
Fallback: balance-delta check on destination ATA (no indexing lag).

Closes the TOCTOU gap where a malicious program could pass simulation
but skip the transfer during on-chain execution.

New optional signer methods:
- getConfirmedTransactionInnerInstructions
- getTokenAccountBalance

5 new test cases covering both verification paths and failure modes.

Made-with: Cursor

Author: BranchManager69

typescript/packages/http/paywall/src/evm/gen/template.ts

@@ -33,7 +33,7 @@ import { SettlementCache } from "../../settlement-cache";
 import type { FacilitatorSvmSigner } from "../../signer";
 import type { ExactSvmPayloadV2 } from "../../types";
 import { decodeTransactionFromPayload, getTokenPayerFromTransaction } from "../../utils";
-import { verifySmartWalletTransaction } from "./smartWalletVerification";
+import { verifySmartWalletTransaction, verifyPostSettlement } from "./smartWalletVerification";
 
 /**
  * Configuration options for ExactSvmScheme.
@@ -267,6 +267,40 @@ export class ExactSvmScheme implements SchemeNetworkFacilitator {
       };
     }
 
+    // Determine if this settlement went through the smart wallet (Path 2) verify path.
+    // If so, we need post-settlement verification to defend against TOCTOU.
+    const isSmartWalletSettlement = this.options?.enableSmartWalletVerification && (() => {
+      try {
+        const tx = decodeTransactionFromPayload(exactSvmPayload);
+        const payer = getTokenPayerFromTransaction(tx);
+        // If getTokenPayerFromTransaction returns null, the static path would have
+        // failed, meaning this went through the smart wallet path.
+        return !payer;
+      } catch {
+        return false;
+      }
+    })();
+
+    // For smart wallet settlements: record destination ATA balance before sending.
+    // Used as fallback verification if getTransaction has indexing lag.
+    let balanceBefore: bigint | null = null;
+    if (isSmartWalletSettlement && typeof this.signer.getTokenAccountBalance === "function") {
+      try {
+        const [destinationAta] = await findAssociatedTokenPda({
+          mint: requirements.asset as Address,
+          owner: requirements.payTo as Address,
+          tokenProgram: TOKEN_PROGRAM_ADDRESS as unknown as Address,
+        });
+        balanceBefore = await this.signer.getTokenAccountBalance(
+          destinationAta.toString(),
+          requirements.network,
+        );
+      } catch {
+        // If balance fetch fails, we proceed without fallback capability.
+        // The primary getTransaction path still works.
+      }
+    }
+
     try {
       // Extract feePayer from requirements (already validated in verify)
       const feePayer = requirements.extra.feePayer as Address;
@@ -287,6 +321,30 @@ export class ExactSvmScheme implements SchemeNetworkFacilitator {
       // Wait for confirmation
       await this.signer.confirmTransaction(signature, requirements.network);
 
+      // Post-settlement verification for smart wallet transactions.
+      // Confirms the TransferChecked actually executed on-chain (TOCTOU defense).
+      if (isSmartWalletSettlement) {
+        const signerAddresses = this.signer.getAddresses().map(a => a.toString());
+        const postVerify = await verifyPostSettlement(
+          this.signer,
+          signature,
+          requirements.network,
+          requirements,
+          signerAddresses,
+          balanceBefore,
+        );
+
+        if (!postVerify.verified && postVerify.method !== "unverified") {
+          return {
+            success: false,
+            errorReason: "post_settlement_transfer_not_confirmed",
+            transaction: signature,
+            network: payload.accepted.network,
+            payer: valid.payer || "",
+          };
+        }
+      }
+
       return {
         success: true,
         transaction: signature,

typescript/packages/http/paywall/src/svm/gen/template.ts

@@ -396,3 +396,108 @@ export async function verifySmartWalletTransaction(
 
   return { isValid: true, payer: matchingTransfers[0].authority };
 }
+
+/**
+ * Post-settlement verification for smart wallet transactions.
+ *
+ * After a transaction confirms on-chain, verifies the TransferChecked actually
+ * executed by inspecting the confirmed transaction's inner instructions.
+ * Falls back to balance-delta checking if the RPC's transaction index has lag.
+ *
+ * This closes the TOCTOU gap where a malicious program could pass simulation
+ * but skip the transfer during on-chain execution.
+ *
+ * @param signer - Facilitator signer with optional getConfirmedTransactionInnerInstructions
+ * @param signature - Confirmed transaction signature
+ * @param network - CAIP-2 network identifier
+ * @param requirements - Payment requirements (asset, payTo, amount)
+ * @param signerAddresses - Facilitator signer addresses
+ * @param balanceBefore - Destination ATA balance before settlement (for fallback)
+ * @returns Whether the transfer was verified on-chain
+ */
+export async function verifyPostSettlement(
+  signer: FacilitatorSvmSigner,
+  signature: string,
+  network: string,
+  requirements: PaymentRequirements,
+  signerAddresses: string[],
+  balanceBefore: bigint | null,
+): Promise<{ verified: boolean; method: "innerInstructions" | "balanceDelta" | "unverified" }> {
+  const requiredAmount = BigInt(requirements.amount);
+
+  // Primary path: fetch confirmed transaction and inspect inner instructions.
+  if (typeof signer.getConfirmedTransactionInnerInstructions === "function") {
+    try {
+      const confirmed = await signer.getConfirmedTransactionInnerInstructions(signature, network);
+
+      if (confirmed?.innerInstructions) {
+        // Reuse the same extraction logic used for simulation results.
+        // We pass an empty accountKeys array because the confirmed transaction's
+        // inner instructions from jsonParsed encoding are already in parsed format
+        // (programId as string, not index), so index-based resolution isn't needed.
+        const transfers = extractTransfersFromInnerInstructions(confirmed.innerInstructions, []);
+
+        // Derive expected destination ATAs (same logic as in verifySmartWalletTransaction).
+        const expectedATAs = new Set<string>();
+        for (const tokenProgram of [TOKEN_PROGRAM_ADDRESS, TOKEN_2022_PROGRAM_ADDRESS]) {
+          try {
+            const [ata] = await findAssociatedTokenPda({
+              mint: requirements.asset as Address,
+              owner: requirements.payTo as Address,
+              tokenProgram: tokenProgram as unknown as Address,
+            });
+            expectedATAs.add(ata.toString());
+          } catch {
+            // Skip invalid address combinations
+          }
+        }
+
+        const matching = transfers.filter(
+          t =>
+            t.mint === requirements.asset &&
+            expectedATAs.has(t.destination) &&
+            t.amount === requiredAmount &&
+            !signerAddresses.includes(t.authority),
+        );
+
+        if (matching.length >= 1) {
+          return { verified: true, method: "innerInstructions" };
+        }
+
+        // Inner instructions fetched but no matching transfer found.
+        // The malicious program skipped the CPI. TOCTOU caught.
+        return { verified: false, method: "innerInstructions" };
+      }
+    } catch {
+      // getTransaction failed or returned null (indexing lag). Fall through to balance delta.
+    }
+  }
+
+  // Fallback: balance-delta check.
+  // If we recorded balanceBefore and the signer supports getTokenAccountBalance,
+  // check whether the destination ATA balance increased by at least the required amount.
+  if (balanceBefore !== null && typeof signer.getTokenAccountBalance === "function") {
+    try {
+      const [destinationAta] = await findAssociatedTokenPda({
+        mint: requirements.asset as Address,
+        owner: requirements.payTo as Address,
+        tokenProgram: TOKEN_PROGRAM_ADDRESS as unknown as Address,
+      });
+
+      const balanceAfter = await signer.getTokenAccountBalance(destinationAta.toString(), network);
+
+      if (balanceAfter !== null && balanceAfter - balanceBefore >= requiredAmount) {
+        return { verified: true, method: "balanceDelta" };
+      }
+
+      // Balance didn't increase enough. Transfer likely didn't execute.
+      return { verified: false, method: "balanceDelta" };
+    } catch {
+      // Balance check failed. Cannot verify.
+    }
+  }
+
+  // Neither verification method available or both failed.
+  // Return unverified — caller decides policy.
+  return { verified: false, method: "unverified" };
+}

typescript/packages/mechanisms/svm/src/exact/facilitator/scheme.ts

@@ -14,6 +14,7 @@ export {
   validateComputeBudgetLimits,
   extractTransfersFromInnerInstructions,
   verifySmartWalletTransaction,
+  verifyPostSettlement,
 } from "./exact/facilitator/smartWalletVerification";
 export type {
   SmartWalletOptions,

typescript/packages/mechanisms/svm/src/exact/facilitator/smartWalletVerification.ts

@@ -183,6 +183,38 @@ export type FacilitatorSvmSigner = {
     feePayer: Address,
     network: string,
   ): Promise<SmartWalletSimulationResult>;
+
+  /**
+   * Fetch inner instructions from a confirmed transaction.
+   * Used for post-settlement verification to confirm that the TransferChecked
+   * actually executed on-chain (defends against TOCTOU in simulation path).
+   *
+   * Optional — if not implemented, post-settlement verification falls back
+   * to balance-delta checking only.
+   *
+   * @param signature - Transaction signature to fetch
+   * @param network - CAIP-2 network identifier
+   * @returns Inner instructions from the confirmed transaction, or null if not yet indexed
+   */
+  getConfirmedTransactionInnerInstructions?(
+    signature: string,
+    network: string,
+  ): Promise<SmartWalletSimulationResult | null>;
+
+  /**
+   * Get the token balance of a specific token account.
+   * Used for balance-delta fallback in post-settlement verification.
+   *
+   * Optional — if not implemented, balance-delta fallback is unavailable.
+   *
+   * @param tokenAccountAddress - Base58 encoded token account (ATA) address
+   * @param network - CAIP-2 network identifier
+   * @returns Token balance in atomic units, or null if account not found
+   */
+  getTokenAccountBalance?(
+    tokenAccountAddress: string,
+    network: string,
+  ): Promise<bigint | null>;
 };
 
 /**
@@ -486,5 +518,42 @@ export function toFacilitatorSvmSigner(
 
       return { innerInstructions: value.innerInstructions ?? null };
     },
+
+    getConfirmedTransactionInnerInstructions: async (
+      signature: string,
+      network: string,
+    ): Promise<SmartWalletSimulationResult | null> => {
+      const rpc = getRpcForNetwork(network);
+      const result = await rpc
+        .getTransaction(signature as never, {
+          commitment: "confirmed",
+          maxSupportedTransactionVersion: 0,
+          encoding: "jsonParsed",
+        } as never)
+        .send();
+
+      if (!result) {
+        return null;
+      }
+
+      const meta = (result as unknown as { meta?: { innerInstructions?: SmartWalletSimulationResult["innerInstructions"] } }).meta;
+      return { innerInstructions: meta?.innerInstructions ?? null };
+    },
+
+    getTokenAccountBalance: async (
+      tokenAccountAddress: string,
+      network: string,
+    ): Promise<bigint | null> => {
+      const rpc = getRpcForNetwork(network);
+      try {
+        const result = await rpc
+          .getTokenAccountBalance(tokenAccountAddress as never, { commitment: "confirmed" } as never)
+          .send();
+        const amount = (result as unknown as { value?: { amount?: string } }).value?.amount;
+        return amount ? BigInt(amount) : null;
+      } catch {
+        return null;
+      }
+    },
   };
 }