chore: merge upstream

.github/workflows/e2e_tests.yml

@@ -53,6 +53,7 @@ jobs:
           {
             echo "SERVER_EVM_ADDRESS=${{ secrets.SERVER_EVM_ADDRESS }}"
             echo "SERVER_SVM_ADDRESS=${{ secrets.SERVER_SVM_ADDRESS }}"
+            echo "SERVER_SVM_RECEIVER_AUTHORIZER_PRIVATE_KEY=${{ secrets.SERVER_SVM_RECEIVER_AUTHORIZER_PRIVATE_KEY }}"
             echo "SERVER_AVM_ADDRESS=${{ secrets.SERVER_AVM_ADDRESS }}"
             echo "SERVER_APTOS_ADDRESS=${{ secrets.SERVER_APTOS_ADDRESS }}"
             echo "SERVER_CCD_ADDRESS=${{ secrets.SERVER_CCD_ADDRESS }}"
@@ -94,7 +95,7 @@ jobs:
             echo "FACILITATOR_CARDANO_MNEMONIC=${{ secrets.FACILITATOR_CARDANO_MNEMONIC }}"
             echo "BLOCKFROST_PROJECT_ID=${{ secrets.BLOCKFROST_PROJECT_ID }}"
             echo "SERVER_EVM_RECEIVER_AUTHORIZER_PRIVATE_KEY=${{ secrets.SERVER_EVM_RECEIVER_AUTHORIZER_PRIVATE_KEY }}"
-            echo "CLIENT_EVM_VOUCHER_SIGNER_PRIVATE_KEY=${{ secrets.CLIENT_EVM_VOUCHER_SIGNER_PRIVATE_KEY }}"
+            echo "CLIENT_EVM_BATCH_SETTLEMENT_VOUCHER_SIGNER_PRIVATE_KEY=${{ secrets.CLIENT_EVM_BATCH_SETTLEMENT_VOUCHER_SIGNER_PRIVATE_KEY }}"
             echo "TVM_PROVIDER=${{ secrets.TVM_PROVIDER }}"
             echo "TVM_TONAPI_API_KEY=${{ secrets.TVM_TONAPI_API_KEY }}"
             echo "TVM_TONCENTER_API_KEY=${{ secrets.TVM_TONCENTER_API_KEY }}"
@@ -158,10 +159,29 @@ jobs:
           pnpm install --frozen-lockfile
           pnpm build
 
+      - name: Print wallet status
+        if: steps.families.outputs.configured == 'true'
+        run: pnpm wallet:status
+
       - name: Setup E2E components
         if: steps.families.outputs.configured == 'true'
         run: ./setup.sh
 
+      # Create/fund the Swig smart wallet when SVM is in the run and persist
+      # SWIG_ACCOUNT_ADDRESS to e2e/.env for the test step (and later steps).
+      - name: Setup Swig smart wallet
+        if: steps.families.outputs.configured == 'true' && contains(steps.families.outputs.families, 'svm')
+        run: |
+          set -a
+          # shellcheck disable=SC1091
+          source .env
+          set +a
+          # Only forward a custom RPC; empty SVM_TESTNET_RPC_URL falls back to devnet in swig-setup.
+          if [[ -n "${SVM_TESTNET_RPC_URL:-}" ]]; then
+            export SVM_RPC_URL="$SVM_TESTNET_RPC_URL"
+          fi
+          pnpm swig:setup
+
       - name: Run minimized e2e tests (testnet)
         if: steps.families.outputs.configured == 'true'
         run: |

contracts/evm/README.md

@@ -23,7 +23,7 @@ Both contracts:
 | Contract | Address |
 |----------|---------|
 | x402ExactPermit2Proxy | `0x402085c248EeA27D92E8b30b2C58ed07f9E20001` |
-| x402UptoPermit2Proxy | `0x402015c795ecb48A360bDC6e35a2EaEb313a0002` |
+| x402UptoPermit2Proxy | `0x4020A4f3b7b90ccA423B9fabCc0CE57C6C240002` |
 
 **Batch settlement (CREATE2 vanity `0x4020…`)**
 
@@ -41,7 +41,7 @@ Both contracts:
 
 | Chain | Exact | Upto |
 |-------|-------|------|
-| Base Mainnet | [Deployed](https://basescan.org/address/0x402085c248EeA27D92E8b30b2C58ed07f9E20001) | — |
+| Base Mainnet | [Deployed](https://basescan.org/address/0x402085c248EeA27D92E8b30b2C58ed07f9E20001) | [Deployed](https://basescan.org/address/0x4020A4f3b7b90ccA423B9fabCc0CE57C6C240002) |
 | Base Sepolia | [Deployed](https://sepolia.basescan.org/address/0x402085c248EeA27D92E8b30b2C58ed07f9E20001) | [Legacy\*](https://sepolia.basescan.org/address/0x402039b3d6E6BEC5A02c2C9fd937ac17A6940002) |
 
 **Batch settlement deployments**
@@ -61,7 +61,7 @@ Both contracts:
 | Monad Mainnet | [Deployed](https://monadscan.com/address/0x4020074e9dF2ce1deE5A9C1b5c3f541D02a10003) | [Deployed](https://monadscan.com/address/0x4020806089470a89826cB9fB1f4059150b550004) | [Deployed](https://monadscan.com/address/0x4020425FAf3B746C082C2f942b4E5159887B0005) |
 
 > \*Older testnet deployments may use prior vanity salts; the canonical **Upto** address for
-> CREATE2 deployments from this tree is `0x402015c7…313a0002` (see `forge script script/ComputeAddress.s.sol`).
+> CREATE2 deployments from this tree is `0x4020A4f3…C240002` (see `forge script script/ComputeAddress.s.sol`).
 
 ## Prerequisites
 
@@ -106,7 +106,7 @@ and `keccak256(initCode)`—not on who sends the transaction.
    ```
    You should see:
    - Exact → `0x402085c248EeA27D92E8b30b2C58ed07f9E20001`
-   - Upto  → `0x402015c795ecb48A360bDC6e35a2EaEb313a0002`
+   - Upto  → `0x4020A4f3b7b90ccA423B9fabCc0CE57C6C240002`
 
 3. **Check prerequisites on the target chain**
    - [Permit2](https://github.com/Uniswap/permit2) must be deployed at `0x000000000022D473030F116dDEE9F6B43aC78BA3`
@@ -115,15 +115,29 @@ and `keccak256(initCode)`—not on who sends the transaction.
 
 4. **Deploy**
    ```bash
-   export PRIVATE_KEY="your_private_key"
+   cast wallet import x402-deployment-signer --interactive
 
    forge script script/Deploy.s.sol \
      --rpc-url <RPC_URL> \
+     --account x402-deployment-signer \
+     --sender <DEPLOYMENT_SIGNER_ADDRESS> \
      --broadcast \
      --verify
    ```
 
-   The script automatically:
+   To deploy only the Upto proxy, select its deployment entry point:
+
+   ```bash
+   forge script script/Deploy.s.sol \
+     --sig "runUpto()" \
+     --rpc-url <RPC_URL> \
+     --account x402-deployment-signer \
+     --sender <DEPLOYMENT_SIGNER_ADDRESS> \
+     --broadcast \
+     --verify
+   ```
+
+   The default `run()` entry point automatically:
    - Loads the pre-built initCode for Exact and compiler-derived initCode for Upto
    - Skips any contract already deployed at the expected address
    - Verifies `PERMIT2()` returns the correct address after deployment

contracts/evm/script/ComputeAddress.s.sol

@@ -43,8 +43,8 @@ contract ComputeAddress is Script {
     bytes32 constant DEFAULT_EXACT_SALT = 0x0000000000000000000000000000000000000000000000003000000007263b0e;
 
     /// @notice Default salt for x402UptoPermit2Proxy
-    /// @dev Vanity mined for address 0x402015c795ecb48a360bdc6e35a2eaeb313a0002
-    bytes32 constant DEFAULT_UPTO_SALT = 0x0000000000000000000000000000000000000000000000000800000007e2e4de;
+    /// @dev Vanity mined for address 0x4020a4f3b7b90cca423b9fabcc0ce57c6c240002
+    bytes32 constant DEFAULT_UPTO_SALT = 0x000000000000000000000000000000000000000000000000b000000001db633d;
 
     /// @notice Expected initCodeHash for x402ExactPermit2Proxy (pre-built, includes CBOR metadata)
     bytes32 constant EXACT_INIT_CODE_HASH = 0xe774d1d5a07218946ab54efe010b300481478b86861bb17d69c98a57f68a604c;

contracts/evm/script/Deploy.s.sol

@@ -45,8 +45,8 @@ contract DeployX402Proxies is Script {
     bytes32 constant EXACT_SALT = 0x0000000000000000000000000000000000000000000000003000000007263b0e;
 
     /// @notice Salt for x402UptoPermit2Proxy deterministic deployment
-    /// @dev Vanity mined for address 0x402015c795ecb48a360bdc6e35a2eaeb313a0002
-    bytes32 constant UPTO_SALT = 0x0000000000000000000000000000000000000000000000000800000007e2e4de;
+    /// @dev Vanity mined for address 0x4020a4f3b7b90cca423b9fabcc0ce57c6c240002
+    bytes32 constant UPTO_SALT = 0x000000000000000000000000000000000000000000000000b000000001db633d;
 
     /// @notice Expected initCodeHash for x402ExactPermit2Proxy (pre-built, includes CBOR metadata)
     bytes32 constant EXACT_INIT_CODE_HASH = 0xe774d1d5a07218946ab54efe010b300481478b86861bb17d69c98a57f68a604c;
@@ -81,6 +81,21 @@ contract DeployX402Proxies is Script {
         console2.log("");
     }
 
+    /// @notice Deploys only x402UptoPermit2Proxy.
+    function runUpto() public {
+        address permit2 = vm.envOr("PERMIT2_ADDRESS", CANONICAL_PERMIT2);
+
+        if (block.chainid != 31_337 && block.chainid != 1337) {
+            require(permit2.code.length > 0, "Permit2 not found on this network");
+            console2.log("Permit2 verified");
+
+            require(CREATE2_DEPLOYER.code.length > 0, "CREATE2 deployer not found on this network");
+            console2.log("CREATE2 deployer verified");
+        }
+
+        _deployUpto(permit2);
+    }
+
     function _deployExact(
         address permit2
     ) internal {

contracts/evm/src/x402BasePermit2Proxy.sol

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.20;
 
-import {ReentrancyGuardTransient} from "@openzeppelin/contracts/utils/ReentrancyGuardTransient.sol";
+import {ReentrancyGuard} from "@openzeppelin/contracts/utils/ReentrancyGuard.sol";
 import {IERC20Permit} from "@openzeppelin/contracts/token/ERC20/extensions/IERC20Permit.sol";
 
 import {ISignatureTransfer} from "./interfaces/ISignatureTransfer.sol";
@@ -22,11 +22,9 @@ import {ISignatureTransfer} from "./interfaces/ISignatureTransfer.sol";
  *      every chain keeps the initCode identical, preserving a uniform CREATE2
  *      address for these proxies across all chains.
  *
- *      Uses {ReentrancyGuardTransient} (EIP-1153); deploy only on chains with transient storage support.
- *
  * @author x402 Protocol
  */
-abstract contract x402BasePermit2Proxy is ReentrancyGuardTransient {
+abstract contract x402BasePermit2Proxy is ReentrancyGuard {
     /// @notice The Permit2 contract address (set once at construction, immutable)
     ISignatureTransfer public immutable PERMIT2;
 

contracts/evm/test/Deploy.t.sol

@@ -0,0 +1,89 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import {Test} from "forge-std/Test.sol";
+import {DeployX402Proxies} from "../script/Deploy.s.sol";
+import {x402ExactPermit2Proxy} from "../src/x402ExactPermit2Proxy.sol";
+import {x402UptoPermit2Proxy} from "../src/x402UptoPermit2Proxy.sol";
+
+/// @title DeployX402ProxiesTest
+/// @notice Regression tests for the CREATE2 deployment path (non-local chain IDs), where
+///         Deploy.s.sol must reproduce the documented canonical addresses exactly. A prior
+///         change silently regressed UPTO_SALT to a stale value that no longer matched the
+///         live, SDK-referenced x402UptoPermit2Proxy deployment; these tests pin both
+///         canonical addresses so a future salt/initCode regression fails loudly here
+///         instead of silently deploying an orphaned contract on a new chain.
+contract DeployX402ProxiesTest is Test {
+    address constant CANONICAL_PERMIT2 = 0x000000000022D473030F116dDEE9F6B43aC78BA3;
+    address constant CREATE2_DEPLOYER = 0x4e59b44847b379578588920cA78FbF26c0B4956C;
+
+    address constant EXPECTED_EXACT_ADDRESS = 0x402085c248EeA27D92E8b30b2C58ed07f9E20001;
+    address constant EXPECTED_UPTO_ADDRESS = 0x4020A4f3b7b90ccA423B9fabCc0CE57C6C240002;
+
+    /// @dev Bytecode of Arachnid's deterministic CREATE2 deployer, same on every EVM chain.
+    bytes constant CREATE2_DEPLOYER_CODE =
+        hex"7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffe03601600081602082378035828234f58015156039578182fd5b8082525050506014600cf3";
+
+    function _simulateRealChain() internal {
+        vm.chainId(8453); // any non-anvil chain ID forces the CREATE2 (non-local) deployment path
+        vm.etch(CREATE2_DEPLOYER, CREATE2_DEPLOYER_CODE);
+        vm.etch(CANONICAL_PERMIT2, hex"60006000fd"); // just needs non-empty code for the prereq check
+    }
+
+    function test_runDeploysToCanonicalAddresses() public {
+        _simulateRealChain();
+
+        DeployX402Proxies deployer = new DeployX402Proxies();
+        deployer.run();
+
+        assertGt(EXPECTED_EXACT_ADDRESS.code.length, 0, "no code at canonical Exact address");
+        assertGt(EXPECTED_UPTO_ADDRESS.code.length, 0, "no code at canonical Upto address");
+
+        assertEq(
+            address(x402ExactPermit2Proxy(EXPECTED_EXACT_ADDRESS).PERMIT2()),
+            CANONICAL_PERMIT2,
+            "Exact PERMIT2 mismatch"
+        );
+        assertEq(
+            address(x402UptoPermit2Proxy(EXPECTED_UPTO_ADDRESS).PERMIT2()), CANONICAL_PERMIT2, "Upto PERMIT2 mismatch"
+        );
+    }
+
+    function test_runIsIdempotent() public {
+        _simulateRealChain();
+
+        DeployX402Proxies deployer = new DeployX402Proxies();
+        deployer.run();
+        deployer.run(); // must detect existing deployments and skip, not attempt to redeploy
+
+        assertGt(EXPECTED_EXACT_ADDRESS.code.length, 0);
+        assertGt(EXPECTED_UPTO_ADDRESS.code.length, 0);
+    }
+
+    function test_runUptoDeploysOnlyUpto() public {
+        DeployX402Proxies deployer = new DeployX402Proxies();
+        uint64 nonceBefore = vm.getNonce(DEFAULT_SENDER);
+        address expectedAddress = vm.computeCreateAddress(DEFAULT_SENDER, nonceBefore);
+
+        deployer.runUpto();
+
+        assertEq(vm.getNonce(DEFAULT_SENDER), nonceBefore + 1);
+        assertGt(expectedAddress.code.length, 0);
+        x402UptoPermit2Proxy referenceProxy = new x402UptoPermit2Proxy(CANONICAL_PERMIT2);
+        assertEq(expectedAddress.codehash, address(referenceProxy).codehash);
+        assertEq(address(x402UptoPermit2Proxy(expectedAddress).PERMIT2()), CANONICAL_PERMIT2);
+    }
+
+    function test_runUptoDeploysToCanonicalAddress() public {
+        _simulateRealChain();
+
+        DeployX402Proxies deployer = new DeployX402Proxies();
+        deployer.runUpto();
+
+        assertGt(EXPECTED_UPTO_ADDRESS.code.length, 0, "no code at canonical Upto address");
+        assertEq(EXPECTED_EXACT_ADDRESS.code.length, 0, "Exact should not be deployed");
+        assertEq(
+            address(x402UptoPermit2Proxy(EXPECTED_UPTO_ADDRESS).PERMIT2()), CANONICAL_PERMIT2, "Upto PERMIT2 mismatch"
+        );
+    }
+}

contracts/evm/vanity-miner/src/main.rs

@@ -39,7 +39,7 @@ const EXACT_INIT_CODE_HASH: [u8; 32] =
     hex_literal::hex!("e774d1d5a07218946ab54efe010b300481478b86861bb17d69c98a57f68a604c");
 // x402UptoPermit2Proxy (deterministic build, no CBOR metadata)
 const UPTO_INIT_CODE_HASH: [u8; 32] =
-    hex_literal::hex!("01575bfc9cacbf6463db62ee8867594b1657139c8493a712ef6bcefa848a20b7");
+    hex_literal::hex!("74f7a29cbc3c55f87cdef7f7c551643189e8bb62eed9de67753aebc402b83797");
 // x402BatchSettlement — keccak256(type(x402BatchSettlement).creationCode) after `forge build`
 const BATCH_INIT_CODE_HASH: [u8; 32] =
     hex_literal::hex!("ed07c0a1aeb6bd4b8e28932959d66e9f2c1a2f6ebb1fd3dc5f3fbcf8135850f6");

docs/core-concepts/facilitator.md

@@ -63,11 +63,17 @@ Multiple facilitators are live in production, supporting various networks includ
 11. `Facilitator server` returns a `Payment Execution Response` to the resource server.
 12. `Resource server` returns a response to the `Client` with a `PAYMENT-RESPONSE` header containing the `Settlement Response` as Base64-encoded JSON. On success, this is a `200 OK` with the requested resource. On failure, this is a `402 Payment Required` with error details.
 
-### Settlement Pending (EVM)
+### Settlement pending and auto-recovery
 
-When an EVM settlement transaction is broadcast but its confirmation cannot be established — for example, due to an RPC error or a timeout while waiting for the receipt — the facilitator returns `settlement_pending` instead of a terminal failure. This is a **non-terminal** error: the transaction may still confirm on chain. The `SettlementResponse` carries the broadcast transaction hash in `transaction` and the network in `network`, so callers can reconcile on chain before deciding whether to retry.
+When a settlement transaction is broadcast but its confirmation cannot be established — for example, due to an RPC error or a timeout while waiting for the receipt — the facilitator returns `settlement_pending` instead of a terminal failure. This is a **non-terminal** error: the transaction may still confirm on chain. The `SettlementResponse` carries the broadcast transaction hash in `transaction` and the network in `network`, so callers can reconcile on chain before deciding whether to retry.
 
-This applies to the `exact`, `upto`, and `batch-settlement` EVM schemes (v2 only).
+This applies to the `exact`, `upto`, and `batch-settlement` schemes on both EVM and SVM (v2 only).
+
+#### Automatic retry and reconciliation
+
+The resource server automatically retries settlement exactly once when it receives a `settlement_pending` response. On the retry, the facilitator mechanism checks a `PendingSettlementStore` for the broadcast transaction hash keyed to the payment payload. When a match is found, the mechanism reconciles against the already-broadcast transaction instead of verifying and broadcasting a second one. This prevents double-spend and avoids redundant on-chain submissions.
+
+The `PendingSettlementStore` is an interface, not a concrete type, so multi-instance facilitators (running several replicas with no session affinity) can supply a shared, network-backed implementation such as Redis instead of the default in-memory store. The in-memory default only works when the retry lands on the same process.
 
 **Facilitators deployed behind a platform request deadline** (serverless functions, gateway timeouts) should bound the receipt wait below that deadline. If the process is killed mid-wait, the caller receives a 5xx with no transaction hash instead of `settlement_pending` with a hash to reconcile against.
 

docs/dev-tools/facilitators.md

@@ -25,6 +25,7 @@ If you are evaluating a mainnet EVM route, decide on your production facilitator
 | [Corbits](https://corbits.dev) | Production-grade multi-network, multi-token facilitator supporting EVM and Solana |
 | [Dexter](https://dexter.cash/facilitator) | Free public x402 facilitator across Solana and EVM chains with no fees and no account required |
 | [Fireblocks Facilitator](https://developers.fireblocks.com/docs/x402-facilitator-overview) | Open-source and hosted facilitator with Fireblocks vault settlement; private keys never leave Fireblocks |
+| [FTP Canton Facilitator](https://www.ftptech.xyz/x402) | Production x402 facilitator for Canton Network mainnet, supporting Canton Coin and CIP-56 tokens |
 | [HPP Facilitator](https://docs.hpp.io/x402/facilitator) | Gasless, public x402 facilitator for HPP Mainnet and Sepolia |
 | [Meridian](https://mrdn.finance) | Multi-chain facilitator with developer-first features |
 | [Mogami Facilitator](https://facilitator.mogami.tech) | Free, developer-focused facilitator for Base with optional self-hosted Docker deployment |

docs/extensions/bazaar.mdx

@@ -463,7 +463,7 @@ The Bazaar extension supports parameterized routes (e.g., `/users/[userId]`, `/w
 
 This means `/users/123`, `/users/456`, and `/users/789` all map to the same catalog entry: `/users/:userId`.
 
-**Note:** Wildcard segments (`*`) are automatically converted to named parameters (`:var1`, `:var2`, etc.) for catalog normalization.
+**Note:** Wildcard segments (`*`) within a path (e.g. `/api/*/data`) are automatically converted to named parameters (`:var1`, `:var2`, etc.) for catalog normalization. However, bare wildcard patterns (e.g. `"*"` with no literal path segments) do **not** produce a `routeTemplate` — use a keyed path pattern in `withX402` (e.g. `{ "/api/weather": config }`) so the resource is indexed with the correct URL.
 
 #### Service Metadata