@across-protocol/contracts 5.0.16 → 5.0.19

package/contracts/interfaces/ICounterfactualBeacon.sol

@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity ^0.8.0;
+
+import { IBeacon } from "@openzeppelin/contracts/proxy/beacon/IBeacon.sol";
+
+/**
+ * @title ICounterfactualBeacon
+ * @notice Global, per-chain registry and **beacon** for every counterfactual `BeaconProxy`:
+ *         `implementation()` is the single implementation all proxies run; `upgradeRoot()` is the
+ *         `(proxy, latestRoot)` tree authorizing best-effort per-proxy root updates. It is also the single
+ *         source of every chain-specific value the leaves need (bridge endpoints, domains/EIDs, fee
+ *         `signer`, token addresses), exposed as `public immutable` getters so leaves stay byte-identical
+ *         across chains. Changing any value (or adding a token) is a UUPS upgrade; the proxy address never
+ *         changes.
+ * @dev `implementation()` is the **counterfactual** implementation (beacon target), not the registry's own.
+ * @custom:security-contact bugs@across.to
+ */
+interface ICounterfactualBeacon is IBeacon {
+    /// @notice Emitted when the admin sets the global implementation (the beacon target).
+    event ImplementationSet(address indexed implementation);
+
+    /// @notice Emitted when the admin sets the upgrade-tree root.
+    event UpgradeRootSet(bytes32 indexed upgradeRoot);
+
+    // `implementation()` is inherited from `IBeacon` — the canonical implementation every counterfactual
+    // proxy runs (resolved live by each `BeaconProxy`).
+
+    /// @notice Root of the `(proxy, latestRoot)` merkle tree authorizing per-proxy root updates.
+    function upgradeRoot() external view returns (bytes32);
+
+    // --- Chain-specific config (immutable; read by leaf implementations under delegatecall) ---
+
+    /// @notice Off-chain signer that authorizes runtime execution fees for every leaf implementation.
+    function signer() external view returns (address);
+
+    /// @notice Across SpokePool on this chain.
+    function spokePool() external view returns (address);
+
+    /// @notice Wrapped native token (e.g. WETH) used as the SpokePool input token for native deposits.
+    function wrappedNativeToken() external view returns (address);
+
+    /// @notice Input token for the "native" SpokePool route: the native sentinel
+    ///         (`0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE`) where the deposit is `msg.value` (wrapped to
+    ///         `wrappedNativeToken()`), or an ERC-20 on chains with no native gas token. The SpokePool leaf
+    ///         names this via `inputTokenGetter` and branches on the sentinel, so one leaf serves both.
+    function nativeToken() external view returns (address);
+
+    /// @notice SponsoredCCTPSrcPeriphery on this chain (sponsored CCTP route).
+    function cctpSrcPeriphery() external view returns (address);
+
+    /// @notice Circle CCTP v2 TokenMessenger on this chain (vanilla CCTP route).
+    function cctpTokenMessenger() external view returns (address);
+
+    /// @notice Circle CCTP source domain id for this chain (sponsored CCTP route).
+    function cctpSourceDomain() external view returns (uint32);
+
+    /// @notice SponsoredOFTSrcPeriphery (USDT0 today). OFT peripheries are single-token; the OFT leaf picks
+    ///         which to use by this getter's selector, so another OFT token = another getter (beacon upgrade).
+    function oftSrcPeriphery() external view returns (address);
+
+    /// @notice LayerZero OFT source endpoint id for this chain.
+    function oftSrcEid() external view returns (uint32);
+
+    /// @notice USDC token address on this chain.
+    function usdc() external view returns (address);
+
+    /// @notice USDT token address on this chain.
+    function usdt() external view returns (address);
+
+    // --- Per-(token, bridge) execution-fee caps (input-token units). A leaf names which to enforce via its
+    //     `maxExecutionFeeGetter` selector. Illustrative set; for SpokePool this is the fixed fee component. ---
+
+    /// @notice Max execution fee for the USDC CCTP route(s).
+    function usdcCctpMaxExecutionFee() external view returns (uint256);
+
+    /// @notice Cap on the submitter-chosen Circle fast-transfer fee (vanilla CCTP route), in bps of the
+    ///         burned amount; 0 ⇒ standard transfers only.
+    function usdcCctpMaxFeeBps() external view returns (uint256);
+
+    /// @notice Max execution fee for the USDT OFT route.
+    function usdtOftMaxExecutionFee() external view returns (uint256);
+
+    /// @notice Max (fixed) fee for the USDC SpokePool route.
+    function usdcSpokePoolMaxExecutionFee() external view returns (uint256);
+
+    /// @notice Max (fixed) fee for the USDT SpokePool route.
+    function usdtSpokePoolMaxExecutionFee() external view returns (uint256);
+
+    /// @notice Max (fixed) fee for the WETH/native SpokePool route.
+    function wethSpokePoolMaxExecutionFee() external view returns (uint256);
+}

package/contracts/interfaces/ICounterfactualDeposit.sol

@@ -23,4 +23,25 @@ interface ICounterfactualDeposit {
         bytes calldata submitterData,
         bytes32[] calldata proof
     ) external payable;
+
+    /**
+     * @notice Update `activeRoot` to `newRoot` (if not already there), then execute, atomically.
+     * @dev Lets an executor activate a newly-added route and use it in one transaction. The root
+     *      update is skipped when the proxy is already at `newRoot`, so this never reverts
+     *      `RootUnchanged` for an already-current proxy.
+     * @param newRoot The root to bring the proxy to before executing.
+     * @param updateProof Merkle proof for the (proxy, newRoot) leaf in the beacon's upgrade tree.
+     * @param implementation The implementation contract to delegatecall.
+     * @param params ABI-encoded route parameters (hashed into the merkle leaf).
+     * @param submitterData ABI-encoded data supplied by the caller at execution time.
+     * @param executeProof Merkle proof for the (implementation, keccak256(params)) leaf.
+     */
+    function updateRootAndExecute(
+        bytes32 newRoot,
+        bytes32[] calldata updateProof,
+        address implementation,
+        bytes calldata params,
+        bytes calldata submitterData,
+        bytes32[] calldata executeProof
+    ) external payable;
 }

package/contracts/libraries/TronClones.sol

@@ -50,6 +50,19 @@ library TronClones {
         return _computeTronAddress(salt, bytecodeHash, deployer);
     }
 
+    /**
+     * @notice Generic Tron CREATE2 address prediction (0x41 prefix) for an arbitrary init-code hash.
+     * @dev Mirrors OZ `Create2.computeAddress` but uses Tron's 0x41 prefix. Use for non-clone init code
+     *      (e.g. an `ERC1967Proxy`) where the caller already has `keccak256(initCode)`.
+     * @param salt The CREATE2 salt.
+     * @param bytecodeHash The keccak256 hash of the init code.
+     * @param deployer The deploying contract address.
+     * @return The predicted address on Tron.
+     */
+    function computeAddress(bytes32 salt, bytes32 bytecodeHash, address deployer) internal pure returns (address) {
+        return _computeTronAddress(salt, bytecodeHash, deployer);
+    }
+
     /**
      * @dev Tron CREATE2 address computation using 0x41 prefix.
      *      Memory layout mirrors OZ Create2.computeAddress but replaces 0xff with 0x41.

package/contracts/periphery/counterfactual/CounterfactualBeacon.sol

@@ -0,0 +1,115 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity ^0.8.0;
+
+import { ICounterfactualBeacon } from "../../interfaces/ICounterfactualBeacon.sol";
+import { CounterfactualBeaconBase } from "./CounterfactualBeaconBase.sol";
+
+/**
+ * @notice Chain-specific config baked into a `CounterfactualBeacon` implementation as `public immutable`s,
+ *         so leaves read endpoints/tokens/signer from the registry and stay byte-identical across chains.
+ *         Each chain deploys its own implementation with its own config.
+ */
+struct CounterfactualChainConfig {
+    address signer;
+    address spokePool;
+    address wrappedNativeToken;
+    /// @dev "Native" SpokePool route: the native sentinel where the deposit is `msg.value` (wrapped to
+    ///      `wrappedNativeToken`), or an ERC-20 on chains with no native gas token. See `nativeToken()`.
+    address nativeToken;
+    address cctpSrcPeriphery;
+    address cctpTokenMessenger;
+    uint32 cctpSourceDomain;
+    /// @dev Single-token OFT periphery (USDT0). The OFT leaf picks the periphery by its getter selector, so
+    ///      another OFT token is a beacon upgrade adding another getter.
+    address oftSrcPeriphery;
+    uint32 oftSrcEid;
+    address usdc;
+    address usdt;
+    /// @dev Per-(token, bridge) execution-fee caps, in input-token units. A leaf names which to enforce via
+    ///      a `bytes4` selector (its `maxExecutionFeeGetter`). Illustrative set — add more as routes need them.
+    ///      For SpokePool this is the fixed component of the fee cap (added to the leaf's `maxFeeBps` term).
+    uint256 usdcCctpMaxExecutionFee;
+    /// @dev Cap on the submitter-chosen Circle fast-transfer fee (vanilla CCTP route), in bps of the
+    ///      burned amount (0 ⇒ standard transfers only).
+    uint256 usdcCctpMaxFeeBps;
+    uint256 usdtOftMaxExecutionFee;
+    uint256 usdcSpokePoolMaxExecutionFee;
+    uint256 usdtSpokePoolMaxExecutionFee;
+    uint256 wethSpokePoolMaxExecutionFee;
+}
+
+/**
+ * @title CounterfactualBeacon
+ * @notice The **configuration** of the per-chain counterfactual registry/beacon: every chain-specific value
+ *         (bridge endpoints, domains/EIDs, fee signer, token addresses, fee caps) as a `public immutable`,
+ *         named getter. All logic — root/implementation management, UUPS, ownership — lives in
+ *         `CounterfactualBeaconBase`.
+ * @dev The config is `public immutable` (in code, readable through the proxy under delegatecall), so changing
+ *      a value or adding a token/cap means deploying a new implementation and `upgradeToAndCall`-ing to it.
+ *      For an identical proxy address across chains, deploy against a uniform bootstrap then upgrade to the
+ *      chain-specific implementation.
+ *
+ *      NOTE: these `immutable` values are **pure configuration**. A new implementation that changes only
+ *      them (this contract's constructor wiring, with no change to `CounterfactualBeaconBase`) is a
+ *      configuration change and is **not subject to audit** — only changes to the base's *logic* are audited.
+ * @custom:security-contact bugs@across.to
+ */
+contract CounterfactualBeacon is CounterfactualBeaconBase {
+    /// @inheritdoc ICounterfactualBeacon
+    address public immutable signer;
+    /// @inheritdoc ICounterfactualBeacon
+    address public immutable spokePool;
+    /// @inheritdoc ICounterfactualBeacon
+    address public immutable wrappedNativeToken;
+    /// @inheritdoc ICounterfactualBeacon
+    address public immutable nativeToken;
+    /// @inheritdoc ICounterfactualBeacon
+    address public immutable cctpSrcPeriphery;
+    /// @inheritdoc ICounterfactualBeacon
+    address public immutable cctpTokenMessenger;
+    /// @inheritdoc ICounterfactualBeacon
+    uint32 public immutable cctpSourceDomain;
+    /// @inheritdoc ICounterfactualBeacon
+    address public immutable oftSrcPeriphery;
+    /// @inheritdoc ICounterfactualBeacon
+    uint32 public immutable oftSrcEid;
+    /// @inheritdoc ICounterfactualBeacon
+    address public immutable usdc;
+    /// @inheritdoc ICounterfactualBeacon
+    address public immutable usdt;
+    /// @inheritdoc ICounterfactualBeacon
+    uint256 public immutable usdcCctpMaxExecutionFee;
+    /// @inheritdoc ICounterfactualBeacon
+    uint256 public immutable usdcCctpMaxFeeBps;
+    /// @inheritdoc ICounterfactualBeacon
+    uint256 public immutable usdtOftMaxExecutionFee;
+    /// @inheritdoc ICounterfactualBeacon
+    uint256 public immutable usdcSpokePoolMaxExecutionFee;
+    /// @inheritdoc ICounterfactualBeacon
+    uint256 public immutable usdtSpokePoolMaxExecutionFee;
+    /// @inheritdoc ICounterfactualBeacon
+    uint256 public immutable wethSpokePoolMaxExecutionFee;
+
+    /// @param config The chain-specific configuration baked into this implementation (see
+    ///        `CounterfactualChainConfig`). Each field becomes an immutable, named getter.
+    constructor(CounterfactualChainConfig memory config) {
+        signer = config.signer;
+        spokePool = config.spokePool;
+        wrappedNativeToken = config.wrappedNativeToken;
+        nativeToken = config.nativeToken;
+        cctpSrcPeriphery = config.cctpSrcPeriphery;
+        cctpTokenMessenger = config.cctpTokenMessenger;
+        cctpSourceDomain = config.cctpSourceDomain;
+        oftSrcPeriphery = config.oftSrcPeriphery;
+        oftSrcEid = config.oftSrcEid;
+        usdc = config.usdc;
+        usdt = config.usdt;
+        usdcCctpMaxExecutionFee = config.usdcCctpMaxExecutionFee;
+        usdcCctpMaxFeeBps = config.usdcCctpMaxFeeBps;
+        usdtOftMaxExecutionFee = config.usdtOftMaxExecutionFee;
+        usdcSpokePoolMaxExecutionFee = config.usdcSpokePoolMaxExecutionFee;
+        usdtSpokePoolMaxExecutionFee = config.usdtSpokePoolMaxExecutionFee;
+        wethSpokePoolMaxExecutionFee = config.wethSpokePoolMaxExecutionFee;
+        _disableInitializers();
+    }
+}

package/contracts/periphery/counterfactual/CounterfactualBeaconBase.sol

@@ -0,0 +1,121 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity ^0.8.0;
+
+import { Initializable } from "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
+import { UUPSUpgradeable } from "@openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol";
+import { Ownable2StepUpgradeable } from "@openzeppelin/contracts-upgradeable/access/Ownable2StepUpgradeable.sol";
+import { IBeacon } from "@openzeppelin/contracts/proxy/beacon/IBeacon.sol";
+import { ICounterfactualBeacon } from "../../interfaces/ICounterfactualBeacon.sol";
+
+/// @dev Minimal view used to verify a candidate beacon target is bound to this beacon — every
+///      counterfactual implementation embeds its beacon as the immutable `BEACON` (for `updateRoot`).
+interface IBeaconTarget {
+    function BEACON() external view returns (address);
+}
+
+/**
+ * @title CounterfactualBeaconBase
+ * @notice The **logic** of the counterfactual registry/beacon: the mutable `implementation` (beacon target)
+ *         every proxy runs, the `upgradeRoot` authorizing per-proxy root updates, UUPS upgradeability and the
+ *         `Ownable2Step` admin. The chain-specific configuration (endpoints, tokens, fee signer, fee caps)
+ *         lives in the derived `CounterfactualBeacon` as immutables. Splitting it out keeps the audit
+ *         boundary clean: this base is the reviewable logic; a config-only change is a new derived contract
+ *         that touches no logic here (see `CounterfactualBeacon`).
+ * @dev Abstract — the config getters declared in `ICounterfactualBeacon` are implemented by the derived
+ *      contract's immutables. A UUPS proxy, so the registry address is permanent (anchoring every
+ *      `BeaconProxy`) while logic/config evolve. `Ownable2Step` admin (no timelock) — it can retarget every
+ *      proxy instantly, so use a trusted multisig. `implementation()` is the beacon target, not the
+ *      registry's own UUPS implementation.
+ * @custom:security-contact bugs@across.to
+ */
+abstract contract CounterfactualBeaconBase is
+    ICounterfactualBeacon,
+    Initializable,
+    UUPSUpgradeable,
+    Ownable2StepUpgradeable
+{
+    /// @custom:storage-location erc7201:across.counterfactual.beacon.storage
+    struct RegistryStorage {
+        address implementation;
+        bytes32 upgradeRoot;
+    }
+
+    /// @dev Implementation target is not a contract.
+    error NotAContract();
+    /// @dev Implementation target's `BEACON()` does not point back at this beacon.
+    error WrongBeacon();
+
+    // keccak256(abi.encode(uint256(keccak256("across.counterfactual.beacon.storage")) - 1)) & ~bytes32(uint256(0xff))
+    bytes32 private constant STORAGE_LOCATION = 0xb8f0bb8c74633417634f6191ee000dac3f927914fa2e1d714b73a72668a01500;
+
+    /**
+     * @notice Initialize the registry's mutable storage (chain config comes from the derived constructor).
+     * @dev With the bootstrap→upgrade deploy the proxy is initialized by the bootstrap and this is never
+     *      reached (initializer already consumed); set `implementation`/`upgradeRoot` via the owner setters.
+     * @param owner_ The admin (use a multisig).
+     * @param implementation_ Initial beacon target (may be address(0), set later via `setImplementation`).
+     * @param upgradeRoot_ Initial upgrade-tree root (may be 0, set later).
+     */
+    function initialize(address owner_, address implementation_, bytes32 upgradeRoot_) external initializer {
+        __Ownable_init(owner_);
+        __Ownable2Step_init();
+        // Allow `address(0)` for lazy init (the standard deploy flow is beacon → impl → setImplementation);
+        // otherwise the target must be a contract bound to this beacon, matching `setImplementation`.
+        if (implementation_ != address(0)) _validateImplementation(implementation_);
+        _setImplementation(implementation_);
+        _setUpgradeRoot(upgradeRoot_);
+    }
+
+    /// @inheritdoc IBeacon
+    /// @dev The counterfactual implementation every `BeaconProxy` resolves and delegatecalls.
+    function implementation() external view returns (address) {
+        return _getStorage().implementation;
+    }
+
+    /// @inheritdoc ICounterfactualBeacon
+    function upgradeRoot() external view returns (bytes32) {
+        return _getStorage().upgradeRoot;
+    }
+
+    /// @notice Set the global implementation (the beacon target) every proxy runs. Must be a contract
+    ///         bound to this beacon; setting it instantly retargets all counterfactual proxies.
+    function setImplementation(address newImplementation) external onlyOwner {
+        _validateImplementation(newImplementation);
+        _setImplementation(newImplementation);
+    }
+
+    /// @notice Set the root of the `(proxy, latestRoot)` upgrade tree.
+    function setUpgradeRoot(bytes32 newUpgradeRoot) external onlyOwner {
+        _setUpgradeRoot(newUpgradeRoot);
+    }
+
+    /// @dev A valid target is a contract whose immutable `BEACON()` points back here — guarding against
+    ///      retargeting every proxy to logic bound to a different beacon (which would brick `updateRoot`).
+    ///      The `try` tolerates non-conforming targets: they leave `boundBeacon == 0` and revert below.
+    function _validateImplementation(address impl) private view {
+        if (impl.code.length == 0) revert NotAContract();
+        address boundBeacon;
+        try IBeaconTarget(impl).BEACON() returns (address b) {
+            boundBeacon = b;
+        } catch {}
+        if (boundBeacon != address(this)) revert WrongBeacon();
+    }
+
+    function _setImplementation(address newImplementation) internal {
+        _getStorage().implementation = newImplementation;
+        emit ImplementationSet(newImplementation);
+    }
+
+    function _setUpgradeRoot(bytes32 newUpgradeRoot) internal {
+        _getStorage().upgradeRoot = newUpgradeRoot;
+        emit UpgradeRootSet(newUpgradeRoot);
+    }
+
+    function _authorizeUpgrade(address) internal override onlyOwner {}
+
+    function _getStorage() private pure returns (RegistryStorage storage $) {
+        assembly {
+            $.slot := STORAGE_LOCATION
+        }
+    }
+}

package/contracts/periphery/counterfactual/CounterfactualBeaconBootstrap.sol

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: BUSL-1.1
+pragma solidity ^0.8.0;
+
+import { Initializable } from "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
+import { UUPSUpgradeable } from "@openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol";
+import { Ownable2StepUpgradeable } from "@openzeppelin/contracts-upgradeable/access/Ownable2StepUpgradeable.sol";
+
+/**
+ * @title CounterfactualBeaconBootstrap
+ * @notice Minimal, chain-identical UUPS implementation used only to deploy the `CounterfactualBeacon`
+ *         proxy at the **same address on every chain**.
+ * @dev The real `CounterfactualBeacon` implementation bakes chain-specific immutables in, so its address —
+ *      and therefore the proxy's (the implementation is in the proxy init code) — differs per chain. This
+ *      bootstrap has no immutables, so it has one deterministic address everywhere; the proxy is created
+ *      against it then `upgradeToAndCall`-ed to the chain-specific `CounterfactualBeacon`. After that, set
+ *      `implementation`/`upgradeRoot` via the owner setters (the initializer slot is already consumed, so
+ *      `CounterfactualBeacon.initialize` can't rerun). Shares the OZ `Ownable2Step`/`UUPS` storage layout,
+ *      so the admin set here is preserved.
+ *
+ *      **Bytecode pinning:** the chain-invariant proxy address depends on this contract's exact creation
+ *      code, so any bytecode change (solc/optimizer/imports/AST) moves the Bootstrap and every dependent
+ *      address. Once the canonical Bootstrap ships on the first chain, deploy later chains from the saved
+ *      canonical creation code, not a recompile — treat it as frozen and flag any PR touching it, its OZ
+ *      imports, or its compiler profile.
+ * @custom:security-contact bugs@across.to
+ */
+contract CounterfactualBeaconBootstrap is Initializable, UUPSUpgradeable, Ownable2StepUpgradeable {
+    constructor() {
+        _disableInitializers();
+    }
+
+    /// @notice Set the admin that will perform the upgrade to the chain-specific implementation.
+    function initialize(address owner_) external initializer {
+        __Ownable_init(owner_);
+        __Ownable2Step_init();
+    }
+
+    function _authorizeUpgrade(address) internal override onlyOwner {}
+}

package/contracts/periphery/counterfactual/CounterfactualDeposit.sol

@@ -1,53 +1,119 @@
 // SPDX-License-Identifier: BUSL-1.1
 pragma solidity ^0.8.0;
 
-import { Clones } from "@openzeppelin/contracts/proxy/Clones.sol";
+import { Initializable } from "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
 import { MerkleProof } from "@openzeppelin/contracts/utils/cryptography/MerkleProof.sol";
-import { ICounterfactualImplementation } from "../../interfaces/ICounterfactualImplementation.sol";
+import { ICounterfactualBeacon } from "../../interfaces/ICounterfactualBeacon.sol";
 import { ICounterfactualDeposit } from "../../interfaces/ICounterfactualDeposit.sol";
+import { ICounterfactualImplementation } from "../../interfaces/ICounterfactualImplementation.sol";
 
 /**
  * @title CounterfactualDeposit
- * @notice Merkle-dispatched entrypoint for counterfactual deposit clones. All clones are instances of this contract.
- * @dev The clone's immutable arg is a merkle root. Each leaf is `keccak256(bytes.concat(keccak256(abi.encode(implementation, keccak256(params)))))`.
- *      Callers prove leaf inclusion, then the dispatcher delegatecalls the implementation.
+ * @notice The counterfactual implementation — the merkle-dispatched entry point every counterfactual
+ *         `BeaconProxy` runs (the registry/beacon's `implementation()`). It also owns the proxy's
+ *         mutable state: `activeRoot` (the route tree), held in an ERC-7201 namespaced slot. Verifies a
+ *         leaf against `activeRoot`, then delegatecalls the per-bridge implementation the leaf authorizes
+ *         (which decodes the destination identity from `params` and bridges).
+ * @dev Resolved live from the beacon (`CounterfactualBeacon.implementation()`) on every call, so all proxies
+ *      always run the current implementation — there is no per-proxy upgrade and no bootstrap. Runs
+ *      under the proxy's delegatecall, so `address(this)` is the proxy (correct for EIP-712 domains and
+ *      token balances), `msg.sender` is the original caller, `msg.value` the original value.
  *
- *      Call chain: Caller → CALL → Clone (EIP-1167 proxy) → DELEGATECALL → Dispatcher → DELEGATECALL → Implementation
- *      - address(this) = clone address throughout (correct for EIP-712, token balances)
- *      - msg.sender = original caller throughout
- *      - msg.value = original value throughout
+ *      The implementation is upgraded **globally** by the admin setting the beacon's `implementation`;
+ *      only the per-proxy `activeRoot` is mutable here, via the permissionless `updateRoot` (proven
+ *      against the registry's `(proxy, latestRoot)` tree). Root updates are **best-effort** — a proxy
+ *      keeps its `activeRoot` until someone updates it; there is no on-chain version/min-version gate.
+ *      **Every future implementation version MUST preserve this ERC-7201 storage layout.**
  *
- *      Note: Some implementations — such as CounterfactualDepositSpokePool — use authorization signatures
- *      that cover execution-time parameters (amounts, deadlines, etc.) but do not commit to the leaf's
- *      route-specific `params` (destination chain, tokens, recipient, etc.). If two leaves share the same
- *      implementation address, a caller could prove leaf A's route params while submitting an authorization
- *      signature intended for leaf B's route, since the signature is valid for either leaf. The system is
- *      intended to be used such that a clone's merkle tree never contains multiple leaves with the same
- *      implementation address.
+ *      Note: every leaf implementation's fee signature binds the leaf's route via `routeParamsHash` (the
+ *      EIP-712 typehash for all four — SpokePool, CCTP, VanillaCCTP, OFT — commits it). So a fee signature
+ *      authored for one leaf cannot be replayed against another, and a clone's tree MAY safely contain
+ *      multiple leaves that share an implementation address (e.g. two OFT routes for different input tokens
+ *      to one destination identity). Cross-chain replay is independently prevented by the `chainId` in the
+ *      EIP-712 domain, and cross-clone replay by `verifyingContract = address(this)`.
+ * @custom:security-contact bugs@across.to
  */
-contract CounterfactualDeposit is ICounterfactualDeposit {
-    /// @dev Accept native ETH sent to the clone (e.g. user deposits or refunds).
+contract CounterfactualDeposit is Initializable, ICounterfactualDeposit {
+    /// @custom:storage-location erc7201:across.counterfactual.upgradeable.storage
+    struct CounterfactualStorage {
+        bytes32 activeRoot;
+    }
+
+    // keccak256(abi.encode(uint256(keccak256("across.counterfactual.upgradeable.storage")) - 1)) & ~bytes32(uint256(0xff))
+    bytes32 private constant STORAGE_LOCATION = 0x5b89d334b964a560e5498fb6b9c95b4213116f116bbd1e59c9c85ba952217700;
+
+    /// @notice The `CounterfactualBeacon` — the beacon every counterfactual `BeaconProxy` resolves its
+    ///         implementation from, and the source of the `upgradeRoot` used by `updateRoot`.
+    ICounterfactualBeacon public immutable BEACON;
+
+    /// @notice Emitted when `activeRoot` is updated via the upgrade tree.
+    event RootUpdated(bytes32 newRoot);
+
+    /// @dev Merkle proof against the registry's `(proxy, latestRoot)` tree failed.
+    error InvalidUpgradeProof();
+    /// @dev New root equals the current `activeRoot` (no-op).
+    error RootUnchanged();
+
+    constructor(ICounterfactualBeacon beacon) {
+        BEACON = beacon;
+        _disableInitializers();
+    }
+
+    /// @notice Initialize the proxy's `activeRoot` from `initialRoot`.
+    /// @dev Delegatecalled once by the `BeaconProxy` constructor (its `data` carries `initialRoot`, which
+    ///      thereby enters the CREATE2 preimage — binding the address to `initialRoot`).
+    function initialize(bytes32 initialRoot) external initializer {
+        _getStorage().activeRoot = initialRoot;
+    }
+
+    /// @dev Accept native value sent to the proxy (deposits before/after deployment, refunds).
     receive() external payable {}
 
-    /**
-     * @notice Execute an implementation by proving its inclusion in the clone's merkle tree.
-     * @param implementation The implementation contract to delegatecall.
-     * @param params ABI-encoded route parameters (hashed into the merkle leaf).
-     * @param submitterData ABI-encoded data supplied by the caller at execution time.
-     * @param proof Merkle proof for the (implementation, keccak256(params)) leaf.
-     */
+    /// @notice The merkle root authorizing this proxy's deposit routes.
+    function activeRoot() public view returns (bytes32) {
+        return _getStorage().activeRoot;
+    }
+
+    /// @inheritdoc ICounterfactualDeposit
     function execute(
         address implementation,
         bytes calldata params,
         bytes calldata submitterData,
         bytes32[] calldata proof
     ) external payable {
-        bytes32 merkleRoot = abi.decode(Clones.fetchCloneArgs(address(this)), (bytes32));
+        _execute(implementation, params, submitterData, proof);
+    }
 
+    /// @inheritdoc ICounterfactualDeposit
+    function updateRootAndExecute(
+        bytes32 newRoot,
+        bytes32[] calldata updateProof,
+        address implementation,
+        bytes calldata params,
+        bytes calldata submitterData,
+        bytes32[] calldata executeProof
+    ) external payable {
+        // Skip the update (and its `RootUnchanged` revert) when the proxy is already current. NOTE:
+        // `updateProof` is therefore NOT validated in that case — there is no root change to authorize.
+        if (newRoot != activeRoot()) _updateRoot(newRoot, updateProof);
+        _execute(implementation, params, submitterData, executeProof);
+    }
+
+    /// @notice Update `activeRoot`, proving `(address(this), newRoot)` is in the registry's upgrade tree.
+    /// @dev Permissionless. Root updates are best-effort — a proxy keeps its `activeRoot` until updated.
+    function updateRoot(bytes32 newRoot, bytes32[] calldata proof) external {
+        _updateRoot(newRoot, proof);
+    }
+
+    function _execute(
+        address implementation,
+        bytes calldata params,
+        bytes calldata submitterData,
+        bytes32[] calldata proof
+    ) private {
         // Double-hash to prevent leaf/internal-node ambiguity (OpenZeppelin standard).
         bytes32 leaf = keccak256(bytes.concat(keccak256(abi.encode(implementation, keccak256(params)))));
-
-        if (!MerkleProof.verify(proof, merkleRoot, leaf)) revert InvalidProof();
+        if (!MerkleProof.verify(proof, activeRoot(), leaf)) revert InvalidProof();
 
         (bool success, bytes memory result) = implementation.delegatecall(
             abi.encodeCall(ICounterfactualImplementation.execute, (params, submitterData))
@@ -58,4 +124,19 @@ contract CounterfactualDeposit is ICounterfactualDeposit {
             }
         }
     }
+
+    function _updateRoot(bytes32 newRoot, bytes32[] calldata proof) private {
+        CounterfactualStorage storage $ = _getStorage();
+        if (newRoot == $.activeRoot) revert RootUnchanged();
+        bytes32 leaf = keccak256(bytes.concat(keccak256(abi.encode(address(this), newRoot))));
+        if (!MerkleProof.verify(proof, BEACON.upgradeRoot(), leaf)) revert InvalidUpgradeProof();
+        $.activeRoot = newRoot;
+        emit RootUpdated(newRoot);
+    }
+
+    function _getStorage() private pure returns (CounterfactualStorage storage $) {
+        assembly {
+            $.slot := STORAGE_LOCATION
+        }
+    }
 }