feat(svm): add simulation-based smart wallet verification

Adds wallet-agnostic smart wallet verification to the SVM facilitator.
Verifies payment outcomes by inspecting CPI inner instructions from
transaction simulation, rather than parsing each wallet type's
proprietary instruction format.

Works for any smart wallet program (Squads, Swig, SPL Governance, etc.)
that executes TransferChecked via CPI. No per-wallet code required.

Security model:
- Fee payer isolation (fee payer never in instruction accounts)
- Operator-configurable compute budget caps
- Exactly one matching TransferChecked in CPI trace
- Simulation proves transaction viability

Made-with: Cursor

Author: BranchManager69

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

@@ -33,9 +33,53 @@ import { SettlementCache } from "../../settlement-cache";
 import type { FacilitatorSvmSigner } from "../../signer";
 import type { ExactSvmPayloadV2 } from "../../types";
 import { decodeTransactionFromPayload, getTokenPayerFromTransaction } from "../../utils";
+import { verifySmartWalletTransaction } from "./smartWalletVerification";
+
+/**
+ * Configuration options for ExactSvmScheme.
+ */
+export type ExactSvmSchemeOptions = {
+  /**
+   * Enable simulation-based smart wallet verification.
+   * When enabled, transactions rejected by the static validation path
+   * (unknown programs, wrong instruction count) are re-verified using
+   * simulation inner instruction analysis. Works for any smart wallet
+   * program (Squads, Swig, SPL Governance, etc.) without per-wallet parsers.
+   *
+   * Default: false (only standard wallet transactions are accepted)
+   */
+  enableSmartWalletVerification?: boolean;
+
+  /**
+   * Maximum compute units allowed for smart wallet transactions.
+   * Smart wallet programs need more CU for CPI overhead.
+   * Only applies when enableSmartWalletVerification is true.
+   *
+   * Default: 400,000
+   */
+  smartWalletMaxComputeUnits?: number;
+
+  /**
+   * Maximum priority fee in microlamports for smart wallet transactions.
+   * Only applies when enableSmartWalletVerification is true.
+   *
+   * Default: 50,000
+   */
+  smartWalletMaxPriorityFeeMicroLamports?: number;
+};
 
 /**
  * SVM facilitator implementation for the Exact payment scheme.
+ *
+ * Dual-path verification:
+ *
+ * Path 1 (Static): Strict positional instruction validation for standard wallets.
+ *   Fast, preserves existing behavior.
+ *
+ * Path 2 (Simulation): Outcome-based verification for smart wallets.
+ *   When Path 1 rejects a transaction and smart wallet verification is enabled,
+ *   falls back to simulation-based validation that inspects CPI inner instructions.
+ *   Works for any wallet program that executes TransferChecked via CPI.
  */
 export class ExactSvmScheme implements SchemeNetworkFacilitator {
   readonly scheme = "exact";
@@ -44,15 +88,16 @@ export class ExactSvmScheme implements SchemeNetworkFacilitator {
   private readonly settlementCache: SettlementCache;
 
   /**
-   * Creates a new ExactSvmFacilitator instance.
+   * Creates a new ExactSvmScheme instance.
    *
-   * @param signer - The SVM RPC client for facilitator operations
+   * @param signer - The SVM signer for facilitator operations
    * @param settlementCache - Optional shared settlement cache (one is created if omitted)
-   * @returns ExactSvmFacilitator instance
+   * @param options - Optional configuration for smart wallet verification
    */
   constructor(
     private readonly signer: FacilitatorSvmSigner,
     settlementCache?: SettlementCache,
+    private readonly options?: ExactSvmSchemeOptions,
   ) {
     this.settlementCache = settlementCache ?? new SettlementCache();
   }
@@ -70,9 +115,11 @@ export class ExactSvmScheme implements SchemeNetworkFacilitator {
     const addresses = this.signer.getAddresses();
     const randomIndex = Math.floor(Math.random() * addresses.length);
 
-    return {
-      feePayer: addresses[randomIndex],
-    };
+    const extra: Record<string, unknown> = { feePayer: addresses[randomIndex] };
+    if (this.options?.enableSmartWalletVerification) {
+      extra.features = { smartWalletSupported: true };
+    }
+    return extra;
   }
 
   /**
@@ -134,7 +181,7 @@ export class ExactSvmScheme implements SchemeNetworkFacilitator {
       };
     }
 
-    // Step 2: Parse and Validate Transaction Structure
+    // Step 2: Parse Transaction
     let transaction;
     try {
       transaction = decodeTransactionFromPayload(exactSvmPayload);
@@ -146,6 +193,135 @@ export class ExactSvmScheme implements SchemeNetworkFacilitator {
       };
     }
 
+    // ─── Path 1: Static validation (standard wallets) ───────────────────
+    const staticResult = await this.verifyStaticPath(
+      transaction,
+      exactSvmPayload,
+      requirements,
+      signerAddresses,
+    );
+
+    if (staticResult.isValid) {
+      return staticResult;
+    }
+
+    // ─── Path 2: Simulation-based verification (smart wallets) ──────────
+    // If static validation failed and smart wallet verification is enabled,
+    // try simulation-based outcome verification. This handles any wallet
+    // program (Squads, Swig, SPL Governance, etc.) that executes
+    // TransferChecked via CPI.
+    if (this.options?.enableSmartWalletVerification) {
+      const feePayer = requirements.extra.feePayer;
+      return verifySmartWalletTransaction(
+        exactSvmPayload.transaction,
+        requirements,
+        this.signer,
+        feePayer,
+        signerAddresses,
+        {
+          enabled: true,
+          maxComputeUnits: this.options.smartWalletMaxComputeUnits,
+          maxPriorityFeeMicroLamports: this.options.smartWalletMaxPriorityFeeMicroLamports,
+        },
+      );
+    }
+
+    return staticResult;
+  }
+
+  /**
+   * Settles a payment by submitting the transaction.
+   * Ensures the correct signer is used based on the feePayer specified in requirements.
+   *
+   * @param payload - The payment payload to settle
+   * @param requirements - The payment requirements
+   * @returns Promise resolving to settlement response
+   */
+  async settle(
+    payload: PaymentPayload,
+    requirements: PaymentRequirements,
+  ): Promise<SettleResponse> {
+    const exactSvmPayload = payload.payload as ExactSvmPayloadV2;
+
+    const valid = await this.verify(payload, requirements);
+    if (!valid.isValid) {
+      return {
+        success: false,
+        network: payload.accepted.network,
+        transaction: "",
+        errorReason: valid.invalidReason ?? "verification_failed",
+        payer: valid.payer || "",
+      };
+    }
+
+    // Duplicate settlement check: reject if this transaction is already being settled.
+    // Must occur before any async work so concurrent calls for the same tx are caught.
+    const txKey = exactSvmPayload.transaction;
+    if (this.settlementCache.isDuplicate(txKey)) {
+      return {
+        success: false,
+        network: payload.accepted.network,
+        transaction: "",
+        errorReason: "duplicate_settlement",
+        payer: valid.payer || "",
+      };
+    }
+
+    try {
+      // Extract feePayer from requirements (already validated in verify)
+      const feePayer = requirements.extra.feePayer as Address;
+
+      // Sign transaction with the feePayer's signer
+      const fullySignedTransaction = await this.signer.signTransaction(
+        exactSvmPayload.transaction,
+        feePayer,
+        requirements.network,
+      );
+
+      // Send transaction to network
+      const signature = await this.signer.sendTransaction(
+        fullySignedTransaction,
+        requirements.network,
+      );
+
+      // Wait for confirmation
+      await this.signer.confirmTransaction(signature, requirements.network);
+
+      return {
+        success: true,
+        transaction: signature,
+        network: payload.accepted.network,
+        payer: valid.payer,
+      };
+    } catch (error) {
+      console.error("Failed to settle transaction:", error);
+      return {
+        success: false,
+        errorReason: "transaction_failed",
+        transaction: "",
+        network: payload.accepted.network,
+        payer: valid.payer || "",
+      };
+    }
+  }
+
+  /**
+   * Path 1: Static instruction-layout verification for standard wallets.
+   * Validates positional instruction structure, program allowlist, and
+   * transfer details. Unchanged from the original implementation.
+   *
+   * @param transaction - Decoded transaction to verify
+   * @param exactSvmPayload - The raw SVM payload containing the base64 transaction
+   * @param requirements - Payment requirements to verify against
+   * @param signerAddresses - Facilitator signer addresses (for self-spend protection)
+   * @returns Verification result
+   */
+  private async verifyStaticPath(
+    transaction: ReturnType<typeof decodeTransactionFromPayload>,
+    exactSvmPayload: ExactSvmPayloadV2,
+    requirements: PaymentRequirements,
+    signerAddresses: string[],
+  ): Promise<VerifyResponse> {
     const compiled = getCompiledTransactionMessageDecoder().decode(transaction.messageBytes);
     const decompiled = decompileTransactionMessage(compiled);
     const instructions = decompiled.instructions ?? [];
@@ -164,7 +340,7 @@ export class ExactSvmScheme implements SchemeNetworkFacilitator {
       };
     }
 
-    // Step 3: Verify Compute Budget Instructions
+    // Verify Compute Budget Instructions
     try {
       this.verifyComputeLimitInstruction(instructions[0] as never);
       this.verifyComputePriceInstruction(instructions[1] as never);
@@ -186,7 +362,7 @@ export class ExactSvmScheme implements SchemeNetworkFacilitator {
       };
     }
 
-    // Step 4: Verify Transfer Instruction
+    // Verify Transfer Instruction
     const transferIx = instructions[2];
     const programAddress = transferIx.programAddress.toString();
 
@@ -201,7 +377,6 @@ export class ExactSvmScheme implements SchemeNetworkFacilitator {
       };
     }
 
-    // Parse the transfer instruction using the appropriate library helper
     let parsedTransfer;
     try {
       if (programAddress === TOKEN_PROGRAM_ADDRESS.toString()) {
@@ -228,7 +403,6 @@ export class ExactSvmScheme implements SchemeNetworkFacilitator {
       };
     }
 
-    // Verify mint address matches requirements
     const mintAddress = parsedTransfer.accounts.mint.address.toString();
     if (mintAddress !== requirements.asset) {
       return {
@@ -238,7 +412,6 @@ export class ExactSvmScheme implements SchemeNetworkFacilitator {
       };
     }
 
-    // Verify destination ATA matches expected ATA for payTo address
     const destATA = parsedTransfer.accounts.destination.address.toString();
     try {
       const [expectedDestATA] = await findAssociatedTokenPda({
@@ -265,7 +438,6 @@ export class ExactSvmScheme implements SchemeNetworkFacilitator {
       };
     }
 
-    // Verify transfer amount meets requirements
     const amount = parsedTransfer.data.amount;
     if (amount !== BigInt(requirements.amount)) {
       return {
@@ -275,7 +447,7 @@ export class ExactSvmScheme implements SchemeNetworkFacilitator {
       };
     }
 
-    // Step 5: Verify optional instructions (if present)
+    // Verify optional instructions (if present)
     // Allowed optional programs: Lighthouse (wallet protection) and Memo (uniqueness)
     const optionalInstructions = instructions.slice(3);
     const invalidReasonByIndex = [
@@ -301,19 +473,17 @@ export class ExactSvmScheme implements SchemeNetworkFacilitator {
       };
     }
 
-    // Step 6: Sign and Simulate Transaction
+    // Sign and Simulate Transaction
     // CRITICAL: Simulation proves transaction will succeed (catches insufficient balance, invalid accounts, etc)
     try {
-      const feePayer = requirements.extra.feePayer as Address;
+      const feePayer = requirements.extra!.feePayer as Address;
 
-      // Sign transaction with the feePayer's signer
       const fullySignedTransaction = await this.signer.signTransaction(
         exactSvmPayload.transaction,
         feePayer,
         requirements.network,
       );
 
-      // Simulate to verify transaction would succeed
       await this.signer.simulateTransaction(fullySignedTransaction, requirements.network);
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
@@ -332,82 +502,6 @@ export class ExactSvmScheme implements SchemeNetworkFacilitator {
     };
   }
 
-  /**
-   * Settles a payment by submitting the transaction.
-   * Ensures the correct signer is used based on the feePayer specified in requirements.
-   *
-   * @param payload - The payment payload to settle
-   * @param requirements - The payment requirements
-   * @returns Promise resolving to settlement response
-   */
-  async settle(
-    payload: PaymentPayload,
-    requirements: PaymentRequirements,
-  ): Promise<SettleResponse> {
-    const exactSvmPayload = payload.payload as ExactSvmPayloadV2;
-
-    const valid = await this.verify(payload, requirements);
-    if (!valid.isValid) {
-      return {
-        success: false,
-        network: payload.accepted.network,
-        transaction: "",
-        errorReason: valid.invalidReason ?? "verification_failed",
-        payer: valid.payer || "",
-      };
-    }
-
-    // Duplicate settlement check: reject if this transaction is already being settled.
-    // Must occur before any async work so concurrent calls for the same tx are caught.
-    const txKey = exactSvmPayload.transaction;
-    if (this.settlementCache.isDuplicate(txKey)) {
-      return {
-        success: false,
-        network: payload.accepted.network,
-        transaction: "",
-        errorReason: "duplicate_settlement",
-        payer: valid.payer || "",
-      };
-    }
-
-    try {
-      // Extract feePayer from requirements (already validated in verify)
-      const feePayer = requirements.extra.feePayer as Address;
-
-      // Sign transaction with the feePayer's signer
-      const fullySignedTransaction = await this.signer.signTransaction(
-        exactSvmPayload.transaction,
-        feePayer,
-        requirements.network,
-      );
-
-      // Send transaction to network
-      const signature = await this.signer.sendTransaction(
-        fullySignedTransaction,
-        requirements.network,
-      );
-
-      // Wait for confirmation
-      await this.signer.confirmTransaction(signature, requirements.network);
-
-      return {
-        success: true,
-        transaction: signature,
-        network: payload.accepted.network,
-        payer: valid.payer,
-      };
-    } catch (error) {
-      console.error("Failed to settle transaction:", error);
-      return {
-        success: false,
-        errorReason: "transaction_failed",
-        transaction: "",
-        network: payload.accepted.network,
-        payer: valid.payer || "",
-      };
-    }
-  }
-
   /**
    * Verify that the compute limit instruction is valid.
    *