docs(svm): document facilitator fee payer guards; tests(svm): add fee payer validation tests and fix mocks to Instruction accounts array; chore: align high-level tests with signer-aware verification (#546)

Author: notorious-d-e-v

specs/schemes/exact/scheme_exact.md

@@ -12,3 +12,15 @@ amount of funds they need to be transferred.
 - An LLM paying to use a tool
 
 ## Appendix
+
+## Critical Validation Requirements
+
+While implementation details vary by network, facilitators MUST enforce security constraints that prevent sponsorship abuse. Examples include:
+
+### SVM
+
+- Fee payer safety: the fee payer MUST NOT appear as an account in sensitive instructions or be the transfer authority/source.
+- Destination correctness: the receiver MUST match the `payTo` derived destination for the specified `asset`.
+- Amount exactness: the transferred amount MUST equal `maxAmountRequired`.
+
+Network-specific rules and exact instruction layouts are defined in the per-network scheme documents. For Solana (SVM), see `scheme_exact_svm.md`.

specs/schemes/exact/scheme_exact_svm.md

@@ -10,24 +10,23 @@ This scheme facilitates payments of a specific amount of an SPL token on the Sol
 
 ## Protocol Flow
 
-The protocol flow for `exact` on Solana is client-driven. 
+The protocol flow for `exact` on Solana is client-driven.
 
 1.  **Client** makes an HTTP request to a **Resource Server**.
 2.  **Resource Server** responds with a `402 Payment Required` status. The response body contains the `paymentRequirements` for the `exact` scheme. Critically, the `extra` field in the requirements contains a **feePayer** which is the public address of the identity that will pay the fee for the transaction. This will typically be the facilitator.
-3. **Client** creates a transaction that contains a transfer of an asset to the resource server's wallet address for a specified amount.
+3.  **Client** creates a transaction that contains a transfer of an asset to the resource server's wallet address for a specified amount.
 4.  **Client** signs the transaction with their wallet. This results in a partially signed transaction (since the signature of the facilitator that will sponsor the transaction is still missing).
 5.  **Client** serializes the partially signed transaction and encodes it as a Base64 string.
 6.  **Client** sends a new HTTP request to the resource server with the `X-PAYMENT` header containing the Base64-encoded partially-signed transaction payload.
 7.  **Resource Server** receives the request and forwards the `X-PAYMENT` header and `paymentRequirements` to a **Facilitator Server's** `/verify` endpoint.
 8.  **Facilitator** decodes and deserializes the proposed transaction.
 9.  **Facilitator** inspects the transaction to ensure it is valid and only contains the expected payment instruction.
-10.  **Facilitator** returns a response to the **Resource Server** verifying the **client**  transaction.
+10. **Facilitator** returns a response to the **Resource Server** verifying the **client** transaction.
 11. **Resource Server**, upon successful verification, forwards the payload to the facilitator's `/settle` endpoint.
 12. **Facilitator Server** provides its final signature as the `feePayer` and submits the now fully-signed transaction to the Solana network.
 13. Upon successful on-chain settlement, the **Facilitator Server** responds to the **Resource Server**.
 14. **Resource Server** grants the **Client** access to the resource in its response.
 
-
 ## `PaymentRequirements` for `exact`
 
 In addition to the standard x402 `PaymentRequirements` fields, the `exact` scheme on Solana requires the following inside the `extra` field:
@@ -50,13 +49,12 @@ In addition to the standard x402 `PaymentRequirements` fields, the `exact` schem
 }
 ```
 
--   `asset`: The public key of the token mint.
--   `extra.feePayer`: The public key of the account that will pay for the transaction fees. This is typically the facilitator's public key.
-
+- `asset`: The public key of the token mint.
+- `extra.feePayer`: The public key of the account that will pay for the transaction fees. This is typically the facilitator's public key.
 
 ## `X-PAYMENT` Header Payload
 
-The `X-PAYMENT` header is base64 encoded and sent in the request from the client to the resource server when paying for a resource. 
+The `X-PAYMENT` header is base64 encoded and sent in the request from the client to the resource server when paying for a resource.
 
 Once decoded, the `X-PAYMENT` header is a JSON string with the following properties:
 
@@ -73,7 +71,6 @@ Once decoded, the `X-PAYMENT` header is a JSON string with the following propert
 
 The `payload` field contains the base64-encoded, serialized, **partially-signed** versioned Solana transaction.
 
-
 ## `X-PAYMENT-RESPONSE` Header Payload
 
 The `X-PAYMENT-RESPONSE` header is base64 encoded and returned to the client from the resource server.
@@ -87,4 +84,43 @@ Once decoded, the `X-PAYMENT-RESPONSE` is a JSON string with the following prope
   "network": "solana" | "solana-devnet",
   "payer": "base58 encoded public address of the transaction fee payer"
 }
-```
+```
+
+## Facilitator Verification Rules (MUST)
+
+A facilitator verifying an `exact`-scheme SVM payment MUST enforce all of the following checks before sponsoring and signing the transaction:
+
+1. Instruction layout
+
+- The decompiled transaction MUST contain either 3 or 4 instructions in this exact order:
+  1. Compute Budget: Set Compute Unit Limit
+  2. Compute Budget: Set Compute Unit Price
+  3. Optional: Associated Token Account Create (when the destination ATA does not yet exist)
+  4. SPL Token or Token-2022 TransferChecked
+
+2. Fee payer (facilitator) safety
+
+- The configured fee payer address MUST NOT appear in the `accounts` of any instruction in the transaction.
+- The fee payer MUST NOT be the `authority` for the TransferChecked instruction.
+- The fee payer MUST NOT be the `source` of the transferred funds.
+
+3. Compute budget validity
+
+- The program for instructions (1) and (2) MUST be `ComputeBudget` with the correct discriminators (2 = SetLimit, 3 = SetPrice).
+- The compute unit price MUST be bounded to prevent gas abuse. The reference implementation enforces ≤ 5 lamports per compute unit.
+
+4. Transfer intent and destination
+
+- The TransferChecked program MUST be either `spl-token` or `token-2022`.
+- Destination MUST equal the Associated Token Account PDA for `(owner = payTo, mint = asset)` under the selected token program.
+
+5. Account existence
+
+- The `source` ATA MUST exist.
+- The destination ATA MUST exist if and only if the Create ATA instruction is NOT present in the transaction. If Create ATA is present, the destination ATA MAY be absent prior to execution.
+
+6. Amount
+
+- The `amount` in TransferChecked MUST equal `maxAmountRequired` exactly.
+
+These checks are security-critical to ensure the fee payer cannot be tricked into transferring their own funds or sponsoring unintended actions. Implementations MAY introduce stricter limits (e.g., lower compute price caps) but MUST NOT relax the above constraints.

specs/x402-specification.md

@@ -218,7 +218,7 @@ Each scheme defines:
 - Settlement and validation procedures
 - Scheme-specific requirements in the `extra` field of `PaymentRequirements`
 
-**6.1 Exact Scheme**
+**6.1 Exact Scheme (EVM overview)**
 
 The "exact" scheme uses EIP-3009 (Transfer with Authorization) to enable secure, gasless transfers of specific amounts of ERC-20 tokens.
 
@@ -254,6 +254,18 @@ The facilitator performs the following verification steps:
 
 Settlement is performed by calling the `transferWithAuthorization` function on the ERC-20 contract with the signature and authorization parameters provided in the payment payload.
 
+**6.2 Exact Scheme (SVM overview)**
+
+For Solana (SVM), the `exact` scheme is implemented using `TransferChecked` for SPL tokens. Critical verification requirements include:
+
+- Enforcing a strict instruction layout (Compute Unit Limit, Compute Unit Price, optional ATA Create, TransferChecked)
+- Ensuring the facilitator fee payer does not appear in any instruction accounts and is not the transfer `authority` or `source`
+- Bounding compute unit price to mitigate gas abuse
+- Verifying the destination ATA matches the `payTo`/`asset` PDA and account existence rules
+- Requiring the transfer `amount` to exactly equal `maxAmountRequired`
+
+Full SVM details are specified in `specs/schemes/exact/scheme_exact_svm.md`.
+
 **7. Facilitator Interface**
 
 The facilitator provides HTTP REST APIs for payment verification and settlement. This allows resource servers to delegate blockchain operations to trusted third parties or host the endpoints themselves. Note that while the core x402 protocol is transport-agnostic, facilitator APIs are currently standardized as HTTP endpoints.