feat: Update workflow to be compatible with Stargate UI (#53)

Co-authored-by: Zied Guesmi <[email protected]>
Co-authored-by: gfournieriExec <[email protected]>

Author: 3 people

Makefile

@@ -30,7 +30,7 @@ generate-coverage:
 	FOUNDRY_PROFILE=test forge coverage \
 		--ir-minimum \
 		--report lcov \
-		--no-match-coverage "script|src/mocks|test"
+		--no-match-coverage "script|src/mocks|src/interfaces|test"
 	@if [ "$$CI" != "true" ]; then \
 		genhtml lcov.info --branch-coverage --output-dir coverage; \
 	fi

script/bridges/layerZero/IexecLayerZeroBridge.s.sol

@@ -20,6 +20,7 @@ contract Deploy is Script {
 
         vm.startBroadcast();
         address iexecLayerZeroBridgeProxy = deploy(
+            params.approvalRequired,
             params.approvalRequired ? params.rlcLiquidityUnifierAddress : params.rlcCrosschainTokenAddress,
             params.lzEndpoint,
             params.initialAdmin,
@@ -35,6 +36,7 @@ contract Deploy is Script {
     }
 
     function deploy(
+        bool approvalRequired,
         address bridgeableToken,
         address lzEndpoint,
         address initialAdmin,
@@ -43,7 +45,7 @@ contract Deploy is Script {
         address createxFactory,
         bytes32 createxSalt
     ) public returns (address) {
-        bytes memory constructorData = abi.encode(bridgeableToken, lzEndpoint);
+        bytes memory constructorData = abi.encode(approvalRequired, bridgeableToken, lzEndpoint);
         bytes memory initializeData = abi.encodeWithSelector(
             IexecLayerZeroBridge.initialize.selector, initialAdmin, initialUpgrader, initialPauser
         );
@@ -82,7 +84,7 @@ contract Upgrade is Script {
         vm.startBroadcast();
         UpgradeUtils.UpgradeParams memory params = UpgradeUtils.UpgradeParams({
             proxyAddress: commonParams.iexecLayerZeroBridgeAddress,
-            constructorData: abi.encode(bridgeableToken, commonParams.lzEndpoint),
+            constructorData: abi.encode(commonParams.approvalRequired, bridgeableToken, commonParams.lzEndpoint),
             contractName: "IexecLayerZeroBridgeV2Mock.sol:IexecLayerZeroBridgeV2", // Would be production contract in real deployment
             newStateVariable: newStateVariable
         });

src/RLCLiquidityUnifier.sol

@@ -9,8 +9,9 @@ import {AccessControlDefaultAdminRulesUpgradeable} from
     "@openzeppelin/contracts-upgradeable/access/extensions/AccessControlDefaultAdminRulesUpgradeable.sol";
 import {UUPSUpgradeable} from "@openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol";
 import {IERC20Metadata} from "@openzeppelin/contracts/token/ERC20/extensions/IERC20Metadata.sol";
-import {IERC7802} from "@openzeppelin/contracts/interfaces/draft-IERC7802.sol";
 import {IERC165} from "@openzeppelin/contracts/interfaces/IERC165.sol";
+import {IERC7802} from "@openzeppelin/contracts/interfaces/draft-IERC7802.sol";
+import {IRLCLiquidityUnifier} from "./interfaces/IRLCLiquidityUnifier.sol";
 
 /**
  * @dev This contract facilitates cross-chain liquidity unification by allowing
@@ -21,12 +22,14 @@ import {IERC165} from "@openzeppelin/contracts/interfaces/IERC165.sol";
  * without being an ERC20 token itself. Functions are overridden to lock/unlock
  * tokens on an external ERC20 contract.
  */
-contract RLCLiquidityUnifier is UUPSUpgradeable, AccessControlDefaultAdminRulesUpgradeable, IERC7802 {
+contract RLCLiquidityUnifier is
+    UUPSUpgradeable,
+    AccessControlDefaultAdminRulesUpgradeable,
+    IRLCLiquidityUnifier,
+    IERC7802
+{
     using SafeERC20 for IERC20Metadata;
 
-    error ERC7802InvalidToAddress(address addr);
-    error ERC7802InvalidFromAddress(address addr);
-
     bytes32 public constant UPGRADER_ROLE = keccak256("UPGRADER_ROLE");
     bytes32 public constant TOKEN_BRIDGE_ROLE = keccak256("TOKEN_BRIDGE_ROLE");
 

src/bridges/layerZero/IexecLayerZeroBridge.sol

@@ -5,13 +5,15 @@ pragma solidity ^0.8.22;
 
 import {OFTCoreUpgradeable} from "@layerzerolabs/oft-evm-upgradeable/contracts/oft/OFTCoreUpgradeable.sol";
 import {IERC20Metadata} from "@openzeppelin/contracts/token/ERC20/extensions/IERC20Metadata.sol";
-import {IERC7802} from "@openzeppelin/contracts/interfaces/draft-IERC7802.sol";
 import {OwnableUpgradeable} from "@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol";
 import {UUPSUpgradeable} from "@openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol";
 import {AccessControlDefaultAdminRulesUpgradeable} from
     "@openzeppelin/contracts-upgradeable/access/extensions/AccessControlDefaultAdminRulesUpgradeable.sol";
+import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
 import {DualPausableUpgradeable} from "../utils/DualPausableUpgradeable.sol";
 import {IIexecLayerZeroBridge} from "../../interfaces/IIexecLayerZeroBridge.sol";
+import {IERC7802} from "@openzeppelin/contracts/interfaces/draft-IERC7802.sol";
+import {IRLCLiquidityUnifier} from "../../interfaces/IRLCLiquidityUnifier.sol";
 
 /**
  * @title IexecLayerZeroBridge
@@ -31,6 +33,22 @@ import {IIexecLayerZeroBridge} from "../../interfaces/IIexecLayerZeroBridge.sol"
  * Dual-Pause Emergency System:
  * 1. Complete Pause: Blocks all bridge operations (incoming and outgoing transfers)
  * 2. Send Pause: Blocks only outgoing transfers, allows users to receive/withdraw funds
+ *
+ * Architecture Overview:
+ * This bridge supports two distinct deployment scenarios:
+ *
+ * 1. Non-Mainnet Chains (L2s, sidechains, etc.):
+ *    - BRIDGEABLE_TOKEN: Points to RLCCrosschain contract (mintable/burnable tokens)
+ *    - APPROVAL_REQUIRED: false (bridge can mint/burn directly)
+ *    - Mechanism: Mint tokens on transfer-in, burn tokens on transfer-out
+ *
+ * 2. Ethereum Mainnet:
+ *    - BRIDGEABLE_TOKEN: Points to LiquidityUnifier contract (manages original RLC tokens)
+ *    - APPROVAL_REQUIRED: true (requires user approval for token transfers)
+ *    - Mechanism: Lock tokens on transfer-out, unlock tokens on transfer-in
+ *      The LiquidityUnifier contract acts as a relayer, implementing ERC-7802 interface
+ *      to provide consistent lock/unlock operations for the original RLC token contract
+ *      that may not natively support the crosschain standard.
  */
 contract IexecLayerZeroBridge is
     UUPSUpgradeable,
@@ -39,20 +57,32 @@ contract IexecLayerZeroBridge is
     DualPausableUpgradeable,
     IIexecLayerZeroBridge
 {
+    using SafeERC20 for IERC20Metadata;
+
     /// @dev Role identifier for accounts authorized to upgrade the contract
     bytes32 public constant UPGRADER_ROLE = keccak256("UPGRADER_ROLE");
 
     /// @dev Role identifier for accounts authorized to pause/unpause the contract
     bytes32 public constant PAUSER_ROLE = keccak256("PAUSER_ROLE");
 
     /**
-     * @dev The RLC token contract that this bridge operates on
-     * Must implement the [ERC-7802](https://eips.ethereum.org/EIPS/eip-7802) interface.
+     * @custom:oz-upgrades-unsafe-allow state-variable-immutable
+     */
+    // slither-disable-next-line naming-convention
+    address public immutable BRIDGEABLE_TOKEN;
+
+    /**
+     * @dev Indicates the token transfer mechanism required for this deployment.
+     *
+     * - true: Ethereum Mainnet deployment requiring user approval (lock/unlock mechanism)
+     * - false: Non Ethereum Mainnet deployment with direct mint/burn capabilities
+     *
+     * This flag indicates on which chain the bridge is deployed.
      *
      * @custom:oz-upgrades-unsafe-allow state-variable-immutable
      */
     // slither-disable-next-line naming-convention
-    IERC7802 public immutable BRIDGEABLE_TOKEN;
+    bool private immutable APPROVAL_REQUIRED;
 
     /**
      * @dev Constructor for the LayerZero bridge contract
@@ -61,11 +91,12 @@ contract IexecLayerZeroBridge is
      *
      * @custom:oz-upgrades-unsafe-allow constructor
      */
-    constructor(address bridgeableToken, address lzEndpoint)
+    constructor(bool approvalRequired_, address bridgeableToken, address lzEndpoint)
         OFTCoreUpgradeable(IERC20Metadata(bridgeableToken).decimals(), lzEndpoint)
     {
         _disableInitializers();
-        BRIDGEABLE_TOKEN = IERC7802(bridgeableToken);
+        BRIDGEABLE_TOKEN = bridgeableToken;
+        APPROVAL_REQUIRED = approvalRequired_;
     }
 
     // ============ INITIALIZATION ============
@@ -143,15 +174,15 @@ contract IexecLayerZeroBridge is
      * @return requiresApproval Returns true if deployed on Ethereum Mainnet, false otherwise
      */
     function approvalRequired() external view virtual returns (bool) {
-        return block.chainid == 1;
+        return APPROVAL_REQUIRED;
     }
 
     /**
      * @notice Returns the address of the underlying token being bridged
      * @return The address of the RLC token contract
      */
     function token() external view returns (address) {
-        return address(BRIDGEABLE_TOKEN);
+        return APPROVAL_REQUIRED ? address(IRLCLiquidityUnifier(BRIDGEABLE_TOKEN).RLC_TOKEN()) : BRIDGEABLE_TOKEN;
     }
 
     // ============ ACCESS CONTROL OVERRIDES ============
@@ -183,6 +214,9 @@ contract IexecLayerZeroBridge is
      * It overrides the `_debit` function
      * https://github.com/LayerZero-Labs/devtools/blob/a2e444f4c3a6cb7ae88166d785bd7cf2d9609c7f/packages/oft-evm/contracts/OFT.sol#L56-L69
      *
+     * This function behavior is chain specific and works differently
+     * depending on whether the bridge is deployed on Ethereum Mainnet or a non-mainnet chain.
+     *
      * IMPORTANT ASSUMPTIONS:
      * - This implementation assumes LOSSLESS transfers (1 token burned = 1 token minted)
      * - If BRIDGEABLE_TOKEN implements transfer fees, burn fees, or any other fee mechanism,
@@ -213,8 +247,14 @@ contract IexecLayerZeroBridge is
         // Calculate the amounts using the parent's logic (handles slippage protection)
         (amountSentLD, amountReceivedLD) = _debitView(amountLD, minAmountLD, dstEid);
 
-        // Burn the tokens from the sender's balance
-        BRIDGEABLE_TOKEN.crosschainBurn(from, amountSentLD);
+        if (APPROVAL_REQUIRED) {
+            // Transfer RLC tokens from the user's account to the LiquidityUnifier contract.
+            //  The normal workflow would be to call `LiquidityUnifier#crosschainBurn()` but this workflow is not compatible with Stargate UI.
+            // Stargate UI does not support approving a contract other than the bridge itself, so here the LiquidityUnifier will not be able to send the `transferFrom` transaction.
+            IRLCLiquidityUnifier(BRIDGEABLE_TOKEN).RLC_TOKEN().safeTransferFrom(from, BRIDGEABLE_TOKEN, amountSentLD);
+        } else {
+            IERC7802(BRIDGEABLE_TOKEN).crosschainBurn(from, amountSentLD);
+        }
     }
 
     /**
@@ -225,6 +265,7 @@ contract IexecLayerZeroBridge is
      * It overrides the `_credit` function
      * https://github.com/LayerZero-Labs/devtools/blob/a2e444f4c3a6cb7ae88166d785bd7cf2d9609c7f/packages/oft-evm/contracts/OFT.sol#L78-L88
      *
+     * This function behavior is chain agnostic and works the same for both chains that does or doesn't require approval.
      *
      * IMPORTANT ASSUMPTIONS:
      * - This implementation assumes LOSSLESS transfers (1 token received = 1 token minted)
@@ -257,7 +298,7 @@ contract IexecLayerZeroBridge is
 
         // Mint the tokens to the recipient
         // This assumes crosschainMint doesn't apply any fees
-        BRIDGEABLE_TOKEN.crosschainMint(to, amountLD);
+        IERC7802(BRIDGEABLE_TOKEN).crosschainMint(to, amountLD);
 
         // Return the amount minted (assuming no fees)
         return amountLD;

src/interfaces/IRLCLiquidityUnifier.sol

@@ -0,0 +1,39 @@
+// SPDX-FileCopyrightText: 2025 IEXEC BLOCKCHAIN TECH <[email protected]>
+// SPDX-License-Identifier: Apache-2.0
+
+pragma solidity ^0.8.22;
+
+import {IERC20Metadata} from "@openzeppelin/contracts/token/ERC20/extensions/IERC20Metadata.sol";
+
+/**
+ * @title IRLCLiquidityUnifier
+ * @dev Interface for the RLC Liquidity Unifier contract.
+ *
+ * This interface defines the contract that is used to centralize the RLC liquidity
+ * across different bridges.
+ */
+interface IRLCLiquidityUnifier {
+    /**
+     * @dev Error indicating that the provided 'to' address is invalid for ERC-7802 operations.
+     * @param addr The invalid address.
+     */
+    error ERC7802InvalidToAddress(address addr);
+
+    /**
+     * @dev Error indicating that the provided 'from' address is invalid for ERC-7802 operations.
+     * @param addr The invalid address.
+     */
+    error ERC7802InvalidFromAddress(address addr);
+
+    /**
+     * @dev Returns the address of the RLC token contract
+     * @return The contract address of the RLC token
+     */
+    function RLC_TOKEN() external view returns (IERC20Metadata);
+
+    /**
+     * @dev Returns the number of decimal places used by the token
+     * @return The number of decimal places (typically 9 for RLC)
+     */
+    function decimals() external pure returns (uint8);
+}

src/mocks/IexecLayerZeroBridgeV2Mock.sol

@@ -16,7 +16,9 @@ contract IexecLayerZeroBridgeV2 is IexecLayerZeroBridge {
     uint256 public newStateVariable;
 
     /// @custom:oz-upgrades-unsafe-allow constructor
-    constructor(address _token, address _lzEndpoint) IexecLayerZeroBridge(_token, _lzEndpoint) {}
+    constructor(bool approvalRequired, address token, address lzEndpoint)
+        IexecLayerZeroBridge(approvalRequired, token, lzEndpoint)
+    {}
 
     /**
      * @notice Initializes V2 features (called after upgrade)

test/e2e/IexecLayerZeroBridgeScript.t.sol

@@ -6,37 +6,78 @@ pragma solidity ^0.8.22;
 import {Test} from "forge-std/Test.sol";
 import {Initializable} from "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
 import {Deploy as IexecLayerZeroBridgeDeploy} from "../../script/bridges/layerZero/IexecLayerZeroBridge.s.sol";
-import {IexecLayerZeroBridge} from "../../src/bridges/layerZero/IexecLayerZeroBridge.sol";
+import {Deploy as RLCLiquidityUnifierDeployScript} from "../../script/RLCLiquidityUnifier.s.sol";
 import {Deploy as RLCCrosschainTokenDeployScript} from "../../script/RLCCrosschainToken.s.sol";
+import {IexecLayerZeroBridge} from "../../src/bridges/layerZero/IexecLayerZeroBridge.sol";
+import {RLCLiquidityUnifier} from "../../src/RLCLiquidityUnifier.sol";
+import {RLCCrosschainToken} from "../../src/RLCCrosschainToken.sol";
+import {ConfigLib} from "../../script/lib/ConfigLib.sol";
 
 contract IexecLayerZeroBridgeScriptTest is Test {
-    // TODO read value from config.json file.
-    address LAYERZERO_ENDPOINT = 0x6EDCE65403992e310A62460808c4b910D972f10f; // LayerZero Arbitrum Sepolia endpoint
-    address CREATEX = 0xba5Ed099633D3B313e4D5F7bdc1305d3c28ba5Ed;
+    // The chain does not matter here as the LAYERZERO_ENDPOINT address is the same for both networks (Sepolia & Arbitrum Sepolia)
+    ConfigLib.CommonConfigParams params = ConfigLib.readCommonConfig("sepolia");
 
     address admin = makeAddr("admin");
     address upgrader = makeAddr("upgrader");
     address pauser = makeAddr("pauser");
-    address rlcAddress; // This will be set to a mock token address for testing
     bytes32 salt = keccak256("salt");
 
     IexecLayerZeroBridgeDeploy public deployer;
+    address private liquidityUnifier;
+    address private rlcCrosschainToken;
+
+    // Forks ID
+    uint256 private sepoliaFork;
+    uint256 private arbitrumSepoliaFork;
 
     function setUp() public {
-        vm.createSelectFork(vm.envString("ARBITRUM_SEPOLIA_RPC_URL"));
         deployer = new IexecLayerZeroBridgeDeploy();
-        rlcAddress =
-            new RLCCrosschainTokenDeployScript().deploy("iEx.ec Network Token", "RLC", admin, admin, CREATEX, salt);
-        vm.setEnv("CREATE_X_FACTORY", vm.toString(CREATEX));
+
+        // Create a forks
+        sepoliaFork = vm.createFork(vm.envString("SEPOLIA_RPC_URL"));
+        arbitrumSepoliaFork = vm.createFork(vm.envString("ARBITRUM_SEPOLIA_RPC_URL"));
+
+        // Setup Ethereum Mainnet fork
+        vm.selectFork(sepoliaFork);
+        liquidityUnifier = new RLCLiquidityUnifierDeployScript().deploy(
+            params.rlcToken, admin, upgrader, params.createxFactory, keccak256("salt")
+        );
+
+        // Setup Arbitrum Sepolia fork
+        vm.selectFork(arbitrumSepoliaFork);
+        rlcCrosschainToken = new RLCCrosschainTokenDeployScript().deploy(
+            "iEx.ec Network Token", "RLC", admin, admin, params.createxFactory, salt
+        );
+    }
+
+    function testFork_Deployment_WithApproval() public {
+        vm.selectFork(sepoliaFork);
+        _test_Deployment(true, liquidityUnifier);
     }
 
-    function testFork_Deployment() public {
+    function testFork_Deployment_WithoutApproval() public {
+        vm.selectFork(arbitrumSepoliaFork);
+        _test_Deployment(false, rlcCrosschainToken);
+    }
+
+    function _test_Deployment(bool requireApproval, address bridgeableToken) internal {
         IexecLayerZeroBridge iexecLayerZeroBridge = IexecLayerZeroBridge(
-            deployer.deploy(rlcAddress, LAYERZERO_ENDPOINT, admin, upgrader, pauser, CREATEX, salt)
+            deployer.deploy(
+                requireApproval,
+                bridgeableToken,
+                params.lzEndpoint,
+                admin,
+                upgrader,
+                pauser,
+                params.createxFactory,
+                salt
+            )
         );
 
         assertEq(iexecLayerZeroBridge.owner(), admin);
-        assertEq(iexecLayerZeroBridge.token(), address(rlcAddress));
+        assertEq(iexecLayerZeroBridge.token(), requireApproval ? params.rlcToken : rlcCrosschainToken);
+        // Check ApprovalRequired value
+        assertEq(iexecLayerZeroBridge.approvalRequired(), requireApproval, "Incorrect ApprovalRequired value");
         // Check all roles.
         assertTrue(iexecLayerZeroBridge.hasRole(iexecLayerZeroBridge.DEFAULT_ADMIN_ROLE(), admin));
         assertTrue(iexecLayerZeroBridge.hasRole(iexecLayerZeroBridge.UPGRADER_ROLE(), upgrader));
@@ -51,15 +92,19 @@ contract IexecLayerZeroBridgeScriptTest is Test {
     }
 
     function testFork_RevertWhen_TwoDeploymentsWithTheSameSalt() public {
-        deployer.deploy(rlcAddress, LAYERZERO_ENDPOINT, admin, upgrader, pauser, CREATEX, salt);
-        vm.expectRevert(abi.encodeWithSignature("FailedContractCreation(address)", CREATEX));
-        deployer.deploy(rlcAddress, LAYERZERO_ENDPOINT, admin, upgrader, pauser, CREATEX, salt);
+        deployer.deploy(
+            false, address(rlcCrosschainToken), params.lzEndpoint, admin, upgrader, pauser, params.createxFactory, salt
+        );
+        vm.expectRevert(abi.encodeWithSignature("FailedContractCreation(address)", params.createxFactory));
+        deployer.deploy(
+            false, address(rlcCrosschainToken), params.lzEndpoint, admin, upgrader, pauser, params.createxFactory, salt
+        );
     }
 
-    // TODO add tests for the configuration script.
+    // TODO: add tests for the configuration script.
 
     function testFork_ConfigureContractCorrectly() public {
-        // TODO check that the peer has been set with the correct config.
+        // TODO: check that the peer has been set with the correct config.
     }
 
     function testFork_RevertWhenPeerIsAlreadySet() public {}