feat: advanced tests

foundry.toml

@@ -8,6 +8,9 @@ number_underscore = 'thousands'
 multiline_func_header = 'params_first'
 sort_imports = true
 
+[profile.default]
+solc_version = '0.8.25'
+
 [profile.optimized]
 via_ir = true
 out = 'out-via-ir'

package.json

@@ -17,7 +17,9 @@
  "lint:sol-tests": "solhint -c .solhint.tests.json 'test/**/*.sol'",
  "prepare": "husky install",
  "test": "forge test -vvv",
+ "test:fuzz": "echidna test/invariants/fuzz/OpUSDC.t.sol --config test/invariants/fuzz/config.yaml --contract OpUsdcTest",
  "test:integration": "forge test --match-contract Integration -vvv",
+ "test:symb": "halmos",
  "test:unit": "forge test --match-contract Unit -vvv",
  "test:unit:deep": "FOUNDRY_FUZZ_RUNS=5000 yarn test:unit"
  },
@@ -37,6 +39,7 @@
  "@defi-wonderland/natspec-smells": "1.0.3",
  "ds-test": "github:dapphub/ds-test#e282159",
  "forge-std": "github:foundry-rs/forge-std#1.8.2",
+ "halmos-cheatcodes": "github:a16z/halmos-cheatcodes#c0d8655",
  "husky": ">=8",
  "lint-staged": ">=10",
  "solhint": "github:solhint-community/solhint-community#v4.0.0-rc01",

remappings.txt

@@ -2,4 +2,5 @@ ds-test/=node_modules/ds-test/src
 forge-std/=node_modules/forge-std/src
 contracts/=src/contracts
 interfaces/=src/interfaces
+halmos-cheatcodes/=node_modules/halmos-cheatcodes/src
 libraries/=src/libraries

test/SUMMARY.md

@@ -0,0 +1,49 @@
+# Tests summary.
+
+There are 4 main contracts, one abstract and 2 peripherals ones (lib, utils), total sloc is 379. Main implementation is built symetrically - L1 and L2, with a factory/child pattern.
+
+## Unit Tests
+Current coverage is 100% of the branches for the 7 contracts, across 121 tests (all passing), except one branch flagged as non covered in the L1Adapter (a burn amount of 0, which should not revert) - manually reviewed as covered.
+| File | % Lines | % Statements | % Branches | % Funcs |
+|-------------------------------------------------|------------------|------------------|-----------------|-----------------|
+| src/contracts/L1OpUSDCBridgeAdapter.sol | 100.00% (45/45) | 100.00% (68/68) | 95.83% (23/24) | 100.00% (10/10) |
+| src/contracts/L1OpUSDCFactory.sol | 100.00% (12/12) | 100.00% (17/17) | 100.00% (2/2) | 100.00% (2/2) |
+| src/contracts/L2OpUSDCBridgeAdapter.sol | 100.00% (40/40) | 100.00% (52/52) | 100.00% (16/16) | 100.00% (10/10) |
+| src/contracts/L2OpUSDCFactory.sol | 100.00% (26/26) | 100.00% (40/40) | 100.00% (4/4) | 100.00% (3/3) |
+| src/contracts/universal/OpUSDCBridgeAdapter.sol | 100.00% (5/5) | 100.00% (6/6) | 100.00% (2/2) | 100.00% (2/2) |
+| src/contracts/utils/FallbackProxyAdmin.sol | 100.00% (4/4) | 100.00% (4/4) | 100.00% (0/0) | 100.00% (4/4) |
+| src/libraries/CrossChainDeployments.sol | 100.00% (25/25) | 100.00% (26/26) | 100.00% (16/16) | 100.00% (3/3) |
+
+
+## Integration Tests
+The integration tests are implemented by switching between 3 different forks: mainnet, Optimism and Base. Crosschain messaging is achieved via the ICrossDomainMessenger contracts already deployed on the 3 chains (see IntegrationBase.sol).
+
+The setup deploys the factory on mainnet, then proceed to deploy the L1 adapters and L2 factories and adapters on both Optimism and Base. Initial tests are conducted to both insure deployment addresses never collide if there are multiple deployments on a given chain, as well as to ensure correct deployment on the multiple chains.
+
+The rest of the integration tests are then conducted from/to mainnet to/from optimism only (given the reassurance of the functional equivalece based on the initial setup tests).
+
+The following tests are conducted: 
+- bridge usdc from mainnet to optimism (same or different address receiving the usdc.e, using the address of the sender or a message signed by it).
+- bridge usdc from optimism to mainnet (same or different address receiving the usdc.e, using the address of the sender or a message signed by it).
+- a sad-path where a signed message from mainnet to optimism fails to verify
+- the same sad-path from optimism to mainner
+- migrate to the native usdc
+- stop and resuming the messaging from mainnet to optimism
+- upgrade the usdc proxy on optimism (with or without triggering an additional call to the new implementation)
+- update different privilegied roles in the L2 deployment (pauser, master minter, black lister, rescuer)
+
+## Property Tests
+We identified 19 properties before, during and after the implementation period. One became deprecated following additional refactor, leaving with 18 to tests.
+
+### Fuzzing Campaign
+We used Echidna to test these 18 properties. The setup runs entirely on the same chains, introducing 2 small differences with the real-life deployments: we use a mock bridge contract relaying every call received to another address atomically; the "L2" adapter has not the same address as its L1 counterpart (as they'd collide otherwise).
+
+The 18 properties tested currently hold.
+
+Limitations and future improvements:
+- A more realistic implementation of the mock bridge should have a queue, executing transaction in fifo ordering
+- The call generators should add additional constraints and post-conditions check, to have a more reliable test setup
+
+
+### Formal Verification: Symbolic Execution
+We used Halmos to test 6 of these properties. Properties not tested are either not easily challenged with symbolic execution (statefullness needed) or limited by Halmos itself (hitting loops in the implementation for instance).

test/invariants/AdvancedTestsUtils.sol

@@ -0,0 +1,139 @@
+// SPDX-License-Identifier: UNLICENSED
+pragma solidity 0.8.25;
+
+import {Test} from 'forge-std/Test.sol';
+import {MockERC20} from 'forge-std/mocks/MockERC20.sol';
+import {SymTest} from 'halmos-cheatcodes/SymTest.sol';
+
+interface IHevm {
+ // Set block.timestamp to newTimestamp
+ function warp(uint256 newTimestamp) external;
+
+ // Set block.number to newNumber
+ function roll(uint256 newNumber) external;
+
+ // Add the condition b to the assumption base for the current branch
+ // This function is almost identical to require
+ function assume(bool b) external;
+
+ // Sets the eth balance of usr to amt
+ function deal(address usr, uint256 amt) external;
+
+ // Loads a storage slot from an address
+ function load(address where, bytes32 slot) external returns (bytes32);
+
+ // Stores a value to an address' storage slot
+ function store(address where, bytes32 slot, bytes32 value) external;
+
+ // Signs data (privateKey, digest) => (v, r, s)
+ function sign(uint256 privateKey, bytes32 digest) external returns (uint8 v, bytes32 r, bytes32 s);
+
+ // Gets address for a given private key
+ function addr(uint256 privateKey) external returns (address addr);
+
+ // Performs a foreign function call via terminal
+ function ffi(string[] calldata inputs) external returns (bytes memory result);
+
+ // Performs the next smart contract call with specified `msg.sender`
+ function prank(address newSender) external;
+
+ // Creates a new fork with the given endpoint and the latest block and returns the identifier of the fork
+ function createFork(string calldata urlOrAlias) external returns (uint256);
+
+ // Takes a fork identifier created by createFork and sets the corresponding forked state as active
+ function selectFork(uint256 forkId) external;
+
+ // Returns the identifier of the current fork
+ function activeFork() external returns (uint256);
+
+ // Labels the address in traces
+ function label(address addr, string calldata label) external;
+}
+
+contract FuzzERC20 is MockERC20 {
+ function mint(address _to, uint256 _amount) public {
+ _mint(_to, _amount);
+ }
+
+ function burn(address _from, uint256 _amount) public {
+ _burn(_from, _amount);
+ }
+}
+
+contract AgentsHandler {
+ uint256 internal _agentsIndex;
+ address[] internal _agents;
+
+ address internal _currentCaller;
+
+ modifier agentOrDeployer() {
+ uint256 _currentAgentIndex = _agentsIndex;
+ _currentCaller = _currentAgentIndex == 0 ? address(this) : _agents[_agentsIndex];
+ _;
+ }
+
+ constructor(uint256 _numAgents) {
+ for (uint256 i = 0; i < _numAgents; i++) {
+ _agents.push(address(bytes20(keccak256(abi.encodePacked(i)))));
+ }
+ }
+
+ function nextAgent() public {
+ _agentsIndex = (_agentsIndex + 1) % _agents.length;
+ }
+
+ function getCurrentAgent() public view returns (address) {
+ return _agents[_agentsIndex];
+ }
+
+ function _addToAgents(address _newAgent) internal {
+ _agents.push(_newAgent);
+ }
+}
+
+contract EchidnaTest is AgentsHandler {
+ event AssertionFailed();
+
+ IHevm hevm = IHevm(0x7109709ECfa91a80626fF3989D68f67F5b1DD12D);
+
+ constructor() AgentsHandler(5) {}
+
+ function clamp(uint256 _value, uint256 _min, uint256 _max) internal pure returns (uint256) {
+ return _min + (_value % (_max - _min));
+ }
+
+ function max(uint256 a, uint256 b) internal pure returns (uint256) {
+ return a > b ? a : b;
+ }
+
+ function min(uint256 a, uint256 b) internal pure returns (uint256) {
+ return a < b ? a : b;
+ }
+}
+
+contract HalmosTest is SymTest, Test {}
+
+library HalmosUtils {
+ function computeCreateAddress(address _origin, uint256 _nonce) internal pure returns (address _address) {
+ bytes memory _data;
+ if (_nonce == 0x00) {
+ _data = abi.encodePacked(bytes1(0xd6), bytes1(0x94), _origin, bytes1(0x80));
+ } else if (_nonce <= 0x7f) {
+ _data = abi.encodePacked(bytes1(0xd6), bytes1(0x94), _origin, uint8(_nonce));
+ } else if (_nonce <= 0xff) {
+ _data = abi.encodePacked(bytes1(0xd7), bytes1(0x94), _origin, bytes1(0x81), uint8(_nonce));
+ } else if (_nonce <= 0xffff) {
+ _data = abi.encodePacked(bytes1(0xd8), bytes1(0x94), _origin, bytes1(0x82), uint16(_nonce));
+ } else if (_nonce <= 0xffffff) {
+ _data = abi.encodePacked(bytes1(0xd9), bytes1(0x94), _origin, bytes1(0x83), uint24(_nonce));
+ } else {
+ _data = abi.encodePacked(bytes1(0xda), bytes1(0x94), _origin, bytes1(0x84), uint32(_nonce));
+ }
+
+ bytes32 _hash = keccak256(_data);
+ assembly {
+ mstore(0, _hash)
+ _address := mload(0)
+ }
+ }
+}

test/invariants/PROPERTIES.md

@@ -1,16 +1,26 @@
-| Properties | Type |
-| ----------------------------------------------------------------------------------------------------------- | ---------- |
-| Both messenger's state of if they can send messages should match | High level |
-| New messages should not be sent if the state is not active | High level |
-| All in flight transactions should successfully settle after a migration to native usdc | High level |
-| Bridged USDC Proxy should only be upgradeable through the L2 Adapter | High level |
-| Incoming successful messages should only come from the linked adapter's | High level |
-| Any chain should be able to have as many protocols deployed without the factory blocking deployments | High level |
-| All addresses precomputed in the factory match the deployed addresses | High level |
-| Deprecated state should be irreversible | High level |
-| User who bridges tokens should receive them on the destination chain | High level |
-| Protocols deployed on one L2 should never have a matching address with a protocol on a different L2 | High level |
-| Assuming the adapter is the only minter the amount locked in L1 should always equal the amount minted on L2 | High level |
-| USDC proxy admin and token ownership rights can only be transferred during the migration to native flow | High level |
-| Different L2 deployed contracts addresses can never match on different L2s | High level |
-| Precalculated addresses on the L1 Factory should always match the deployed addresses on L2s | High level |
+| Properties | Type | Id | Fuzz | Symb |
+| ----------------------------------------------------------------------------------------------------------- | ------------------- | --- | ---- | ---- |
+| New messages should not be sent if the state is not active | Unit test | 1 | [X] | [x] |
+| User who bridges tokens should receive them on the destination chain | High level | 2 | [X] | [x] |
+| Assuming the adapter is the only minter the amount locked in L1 should always equal the amount minted on L2 | High level | 3 | [X] | [x] |
+| Both messenger's state or if they can send messages should match | Valid state | 4 | depr | depr |
+| user nonce should be monotonically increasing | Variable transition | 5 | [X] | :( |
+| burn locked only if deprecated | Unit test | 6 | [X] | [X] |
+| paused only via stop messaging | State transition | 7 | [X] | |
+| resumed only via resume messaging | State transition | 8 | [X] | |
+| set burn only if migrating state | State transition | 9 | [X] | |
+| Deprecated state should be irreversible | State transition | 10 | [X] | |
+| Upgrading state only via migrate to native, should be callable multiple times (msg fails) | State transition | 11 | [X] | [X] |
+| All in flight transactions should successfully settle after a migration to native usdc | High level | 12 | [X] | [X] |
+| Bridged USDC Proxy should only be upgradeable through the L2 Adapter | High level | 13 | [X] | :( |
+| Incoming successful messages should only come from the linked adapter's | High level | 14 | [X] | [X] |
+| Any chain should be able to have as many protocols deployed without the factory blocking deployments | High level | 15 | [X] | :( |
+| Protocols deployed on one L2 should never have a matching address with a protocol on a different L2 | High level | 16 | [X] | :( |
+| USDC proxy admin and token ownership rights can only be transferred during the migration to native flow | High level | 17 | [X] | |
+| Status should either be active, paused, upgrading or deprecated | Valid state | 18 | [X] | |
+| All addresses precomputed in the factory match the deployed addresses / L1 nonce == L2 factory nonce | Variable transition | | depr | depr | 
+
+[] planed to implement and still to do
+[x] implemented and tested
+:( implemented but judged as incorrect (tool limitation, etc)
+empty not implemented and will not be (design, etc)

test/invariants/fuzz/Create2Deployer.sol

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: UNLICENSED
+pragma solidity 0.8.25;
+
+// Identical to the OZ implementation used
+contract Create2Deployer {
+ // solhint-disable custom-errors
+ function deploy(uint256 _value, bytes32 _salt, bytes memory _initCode) public returns (address) {
+ address addr;
+ require(address(this).balance >= _value, 'Create2: insufficient balance');
+ require(_initCode.length != 0, 'Create2: bytecode length is zero');
+
+ assembly {
+ addr := create2(_value, add(_initCode, 0x20), mload(_initCode), _salt)
+ }
+ require(addr != address(0), 'Create2: Failed on deploy');
+
+ return addr;
+ }
+}

test/invariants/fuzz/MockBridge.sol

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: UNLICENSED
+pragma solidity 0.8.25;
+
+import {ITestCrossDomainMessenger} from 'test/utils/interfaces/ITestCrossDomainMessenger.sol';
+
+// Relay any message
+contract MockBridge is ITestCrossDomainMessenger {
+ uint256 public messageNonce;
+ address internal _currentXDomSender;
+ bool internal _paused;
+
+ function OTHER_MESSENGER() external pure returns (address) {
+ return address(0);
+ }
+
+ function xDomainMessageSender() external view returns (address) {
+ return _currentXDomSender;
+ }
+
+ function sendMessage(address _target, bytes calldata _message, uint32) external {
+ if (_paused) return;
+ _currentXDomSender = msg.sender;
+ messageNonce++;
+
+ (bool success,) = _target.call(_message);
+ success;
+ }
+
+ function relayMessage(
+ uint256,
+ address,
+ address _target,
+ uint256 _value,
+ uint256,
+ bytes calldata _message
+ ) external payable {
+ _currentXDomSender = msg.sender;
+ messageNonce++;
+ (bool succ, bytes memory ret) = _target.call{value: _value}(_message);
+
+ if (!succ) revert(string(ret));
+ }
+
+ function pauseMessaging() external {
+ _paused = true;
+ }
+
+ function setDomainMessageSender(address _sender) external {
+ _currentXDomSender = _sender;
+ }
+}