feat(foundry): publish L2 state in @celo/devchain-anvil

.github/workflows/protocol-devchain-anvil.yml

@@ -22,7 +22,6 @@ env:
   FOUNDRY_CACHE_KEY: 1
   # Supported Foundry version defined at celo-org (GitHub organisation) level, for consistency across workflows.
   SUPPORTED_FOUNDRY_VERSION: ${{ vars.SUPPORTED_FOUNDRY_VERSION }}
-  ANVIL_PORT: 8546
 
 jobs:
   build:
@@ -124,17 +123,31 @@ jobs:
       - name: 'Install packages'
         shell: bash
         run: yarn
-
-      - name: Generate migrations and run devchain
-        if: success() || failure()
-        run: ./scripts/foundry/create_and_migrate_anvil_devchain.sh
-
-      - name: Run integration tests against local anvil devchain
+      
+      # Starting L1 from scratch instead of JSON state to circumvent this Anvil bug https://github.com/foundry-rs/foundry/issues/7502
+      # Install `lsof` dependency, because it's not readily available on CI, but is required by 
+      # `create_and_migrate_anvil_l2_devchain.sh`, because it uses `stop_anvil.sh` to kill 
+      # existing anvil servers.
+      - name: Generate L1 migrations and run integration tests against L1 devchain
         if: success() || failure()
         run: |
+          sudo apt-get update
+          sudo apt-get install -y lsof
+
+          source ./scripts/foundry/constants.sh
+
+          echo "Starting L1 from scratch to circumvent Anvil bug"
+          source ./scripts/foundry/create_and_migrate_anvil_devchain.sh
+
           forge test -vvv \
           --match-path "test-sol/integration/*" \
-          --fork-url http://127.0.0.1:${{ env.ANVIL_PORT }}
+          --fork-url $ANVIL_RPC_URL
+
+          ./scripts/foundry/stop_anvil.sh
+
+      - name: Generate L2 migration
+        if: success() || failure()
+        run: ./scripts/foundry/create_and_migrate_anvil_l2_devchain.sh
 
       - name: Sanitize ref name
         id: sanitize-ref-name
@@ -158,7 +171,7 @@ jobs:
         env:
           RELEASE_TYPE: ${{ env.RELEASE_TYPE }}
           RELEASE_VERSION: ${{ env.RELEASE_VERSION }}
-      
+
       - name: Upload devchain as artifact
         uses: actions/upload-artifact@v4
         with:

.github/workflows/protocol_tests.yml

@@ -14,7 +14,6 @@ env:
   FOUNDRY_CACHE_KEY: 2
   # Supported Foundry version defined at celo-org (GitHub organisation) level, for consistency across workflows.
   SUPPORTED_FOUNDRY_VERSION: ${{ vars.SUPPORTED_FOUNDRY_VERSION }}
-  ANVIL_PORT: 8546
 
 jobs:
   check:
@@ -129,13 +128,17 @@ jobs:
       - name: Run integration tests against local anvil devchain
         if: success() || failure()
         run: |
+          source ./scripts/foundry/constants.sh
+
           forge test -vvv \
           --match-path "test-sol/integration/*" \
-          --fork-url http://127.0.0.1:${{ env.ANVIL_PORT }}
+          --fork-url $ANVIL_RPC_URL
 
       - name: Run e2e tests against local anvil devchain
         if: success() || failure()
         run: |
+          source ./scripts/foundry/constants.sh
+
           forge test -vvv \
           --match-path "test-sol/e2e/*" \
-          --fork-url http://127.0.0.1:${{ env.ANVIL_PORT }}
+          --fork-url $ANVIL_RPC_URL

packages/protocol/migrations_sol/CONTRIBUTING.md

@@ -5,34 +5,51 @@ This devchain is useful for testing and development of the Celo protocol.
 
 ## Usage
 
-### Start devchain
+### Start L1 devchain
 
 ```sh
-$ yarn anvil-devchain:start
+$ yarn anvil-devchain:start-L1
 ``` 
 
 Starts a new anvil devchain serving at localhost (default port 8546).
 
-For example:
+You can now run commands against the local devchain. For example:
 
 ```sh
-$ yarn anvil-devchain:start
-
-yarn run v1.22.22
-$ ./scripts/foundry/create_and_migrate_anvil_devchain.sh
-# ...
-Total elapsed time: 193 seconds
-✨  Done in 193.09s.
+cast block-number \
+--rpc-url http://127.0.0.1:8546
+266
 ```
 
-You can now run commands against the local devchain.
+### Start L2 devchain
+
+```sh
+$ yarn anvil-devchain:start-L2
+``` 
 
-For example:
+Starts a new anvil devchain serving at localhost (default port 8546).
+
+You can now run commands against the local devchain. For example:
 
 ```sh
-cast block-number \
---rpc-url http://127.0.0.1:8546
-266
+# Call `isL2()` on `CeloDistributionSchedule.sol`
+cast call \
+0xA16cF67AFa80BB9Ce7a325597F80057c6B290fD4 \
+"isL2()(bool)" \
+--rpc-url=http://127.0.0.1:8546
+true
+```
+
+### Check if devchain is running
+
+```sh
+$ yarn anvil-devchain:status
+
+# If devchain is running
+Devchain is serving at http://localhost:8546
+
+# If devchain is not running
+Devchain is not running.
 ```
 
 ### Stop devchain
@@ -41,17 +58,10 @@ cast block-number \
 $ yarn anvil-devchain:stop
 ```
 
-Terminates any anvil nodes serving at localhost.
-
-For example:
+Terminates any anvil nodes serving at localhost. For example:
 
 ```sh
-# in packages/protocol/ directory
 $ yarn anvil-devchain:stop
 
-yarn run v1.22.22
-$ ./scripts/foundry/stop_anvil.sh
-Connection to localhost port 8546 [tcp/*] succeeded!
 Killed Anvil
-✨  Done in 0.11s.
 ```

packages/protocol/migrations_sol/Migration.s.sol

@@ -4,16 +4,29 @@ pragma solidity >=0.8.7 <0.8.20;
 
 import { Script } from "forge-std-8/Script.sol";
 
+// Foundry imports
 import "forge-std/console.sol";
 import "forge-std/StdJson.sol";
 
-import "@celo-contracts/common/interfaces/IProxyFactory.sol";
+// Helper contract imports
+import "@migrations-sol/HelperInterFaces.sol";
+import { Constants } from "@migrations-sol/constants.sol";
+import "@openzeppelin/contracts8/utils/math/Math.sol";
 
-// Initializer of the core contracts
+// Core contract imports on Solidity 0.5
+import "@celo-contracts/common/interfaces/IProxy.sol";
+import "@celo-contracts/common/interfaces/IProxyFactory.sol";
+import "@celo-contracts/common/interfaces/IRegistry.sol";
 import "@celo-contracts/common/interfaces/IRegistryInitializer.sol";
+import "@celo-contracts/common/interfaces/IFreezer.sol";
 import "@celo-contracts/common/interfaces/IFreezerInitializer.sol";
-import "@celo-contracts-8/common/interfaces/IFeeCurrencyDirectoryInitializer.sol";
 import "@celo-contracts/common/interfaces/ICeloTokenInitializer.sol";
+import "@celo-contracts/common/interfaces/IAccountsInitializer.sol";
+import "@celo-contracts/common/interfaces/IFeeHandlerSellerInitializer.sol";
+import "@celo-contracts/common/interfaces/IFeeHandler.sol";
+import "@celo-contracts/common/interfaces/IFeeHandlerInitializer.sol";
+import "@celo-contracts/common/interfaces/IFeeCurrencyWhitelist.sol";
+import "@celo-contracts/common/interfaces/IAccounts.sol";
 import "@celo-contracts/governance/interfaces/ILockedGoldInitializer.sol";
 import "@celo-contracts/governance/interfaces/IValidatorsInitializer.sol";
 import "@celo-contracts/governance/interfaces/IElectionInitializer.sol";
@@ -24,34 +37,22 @@ import "@celo-contracts/governance/interfaces/IDoubleSigningSlasherInitializer.s
 import "@celo-contracts/governance/interfaces/IDowntimeSlasherInitializer.sol";
 import "@celo-contracts/governance/interfaces/IGovernanceApproverMultiSigInitializer.sol";
 import "@celo-contracts/governance/interfaces/IGovernanceInitializer.sol";
-import "@celo-contracts/common/interfaces/IAccountsInitializer.sol";
-import "@celo-contracts/common/interfaces/IFeeHandlerSellerInitializer.sol";
-import "@celo-contracts/common/interfaces/IFeeHandlerInitializer.sol";
+import "@celo-contracts/governance/interfaces/ILockedGold.sol";
+import "@celo-contracts/governance/interfaces/IGovernance.sol";
 import "@celo-contracts/identity/interfaces/IRandomInitializer.sol";
 import "@celo-contracts/identity/interfaces/IEscrowInitializer.sol";
 import "@celo-contracts/identity/interfaces/IOdisPaymentsInitializer.sol";
 import "@celo-contracts/identity/interfaces/IFederatedAttestationsInitializer.sol";
 import "@celo-contracts/stability/interfaces/ISortedOraclesInitializer.sol";
+import "@celo-contracts/stability/interfaces/ISortedOracles.sol";
+
+// Core contract imports on Solidity 0.8
+import "@celo-contracts-8/common/interfaces/IFeeCurrencyDirectoryInitializer.sol";
 import "@celo-contracts-8/common/interfaces/IGasPriceMinimumInitializer.sol";
 import "@celo-contracts-8/common/interfaces/ICeloDistributionScheduleInitializer.sol";
-
-import "@celo-contracts/common/interfaces/IProxy.sol";
-import "@celo-contracts/common/interfaces/IRegistry.sol";
-import "@celo-contracts/common/interfaces/IFreezer.sol";
-import "@celo-contracts/common/interfaces/IFeeCurrencyWhitelist.sol";
 import "@celo-contracts-8/common/interfaces/IFeeCurrencyDirectory.sol";
-import "@celo-contracts/common/interfaces/IAccounts.sol";
-import "@celo-contracts/governance/interfaces/ILockedGold.sol";
-import "@celo-contracts/governance/interfaces/IGovernance.sol";
-import "@celo-contracts/common/interfaces/IFeeHandler.sol";
-import "@celo-contracts/stability/interfaces/ISortedOracles.sol";
-
-import "@migrations-sol/HelperInterFaces.sol";
-import "@openzeppelin/contracts8/utils/math/Math.sol";
 import "@celo-contracts-8/common/UsingRegistry.sol";
 
-import { Constants } from "@migrations-sol/constants.sol";
-
 contract ForceTx {
   // event to trigger so a tx can be processed
   event VanillaEvent(string);
@@ -66,9 +67,7 @@ contract ForceTx {
 contract Migration is Script, UsingRegistry, Constants {
   using stdJson for string;
 
-  /**
-   * This is Anvil's default account
-   */
+  // This is Anvil's default account
   address constant deployerAccount = 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266;
 
   IProxyFactory proxyFactory;
@@ -980,10 +979,10 @@ contract Migration is Script, UsingRegistry, Constants {
     );
 
     _setConstitution(governanceProxyAddress, json);
-    _transferOwnerShipCoreContact(governanceProxyAddress, json);
+    _transferOwnerShipCoreContract(governanceProxyAddress, json);
   }
 
-  function _transferOwnerShipCoreContact(address governanceAddress, string memory json) public {
+  function _transferOwnerShipCoreContract(address governanceAddress, string memory json) public {
     bool skipTransferOwnership = abi.decode(
       json.parseRaw(".governance.skipTransferOwnership"),
       (bool)

packages/protocol/migrations_sol/README.md

@@ -1,17 +1,96 @@
 # @celo/devchain-anvil
 
-Anvil state with Celo core contracts for local testing and development.
+This package contains anvil state that allows you to start an [anvil](https://book.getfoundry.sh/reference/anvil/) instance in seconds.
 
-# Usage
+This anvil instance serves at `localhost:8545` on your machine, and comes pre-configured with core contracts like the [`Registry`](https://github.com/celo-org/celo-monorepo/blob/master/packages/protocol/contracts/common/Registry.sol) contract (at `0x000000000000000000000000000000000000ce10`). You can make RPC calls against this anvil instance as if you were interacting with Celo on `Alfajores` or `Mainnet`.
+
+## Usage
 
 ```bash
 npm install --save-dev @celo/devchain-anvil
 anvil --state <path_to_devchain.json>
 ```
 
+Files in this package:
+
+1. Use `devchain.json` for a Celo L1-like devchain.
+1. Use `l2-devchain.json` for a Celo L2-like devchain.
+
+### Example
+
+1.  Make a test directory
+
+    ```sh
+    # Create a demo directory
+    $ mkdir ~/Documents/local-anvil-demo
+
+    # Move into the demo directory
+    $ cd ~/Documents/local-anvil-demo
+    ```
+
+2.  Install the package
+
+    ```sh
+    $ npm install --save-dev @celo/devchain-anvil
+    ```
+
+3.  Start an anvil instance with the state file from the package
+
+    ```sh
+    $ anvil --state node_modules/@celo/devchain-anvil/devchain.json
+
+                                 _   _
+                                (_) | |
+          __ _   _ __   __   __  _  | |
+         / _` | | '_ \  \ \ / / | | | |
+        | (_| | | | | |  \ V /  | | | |
+         \__,_| |_| |_|   \_/   |_| |_|
+
+        0.2.0 (f625d0f 2024-04-02T00:16:42.824772000Z)
+        https://github.com/foundry-rs/foundry
+
+    Available Accounts
+    ==================
+
+    (0) 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 (10000.000000000000000000 ETH)
+
+    # ...
+    Listening on 127.0.0.1:8545
+    ```
+
+4.  Make RPC calls against the anvil instance serving at `http://127.0.0.1:8545`
+
+## Background
+
+[Foundry](https://book.getfoundry.sh/reference/anvil/) allows you to start anvil instances with state you read from `json` files.
+The idea is to save the state of an anvil instance at a certain point in time, and then load it back up later.
+
+```
+$ anvil --state <PATH>
+    This is an alias for both --load-state and --dump-state.
+
+    It initializes the chain with the state and block environment stored at the file, if it
+    exists, and dumps the chain's state on exit.
+```
+
+Source: [Anvil docs](https://book.getfoundry.sh/reference/cli/anvil?highlight=--state#anvil)
+
+We use this feature to pre-configure an anvil instance with core contracts and other state, and then start it up in seconds for testing.
+We call this a "devchain". The scripts we use to configure the devchain are here: [`celo-org/celo-monorepo/` > `packages/protocol/migrations_sol`](https://github.com/celo-org/celo-monorepo/tree/master/packages/protocol/migrations_sol)
+
+## Limitations
+
+The anvil instance is not a full Celo node. It is a lightweight, in-memory instance that you can use for testing.
+
+1. It does not sync with the Celo network ❌
+1. It does not persist data between sessions ❌
+1. It does not support all RPC methods ❌
+1. It does not support fee currency transactions (like [CIP64](https://github.com/celo-org/celo-proposals/blob/master/CIPs/cip-0064.md) or [CIP66](https://github.com/celo-org/celo-proposals/blob/master/CIPs/cip-0066.md)) ❌
+1. It does not support all Celo pre-compiles ❌
+
 ## How we work
 
-We are a GitHub-first team, which means we have a strong preference for communicating via GitHub. 
+We are a GitHub-first team, which means we have a strong preference for communicating via GitHub.
 Please use GitHub to:
 
 🐞 [File a bug report](https://github.com/celo-org/celo-monorepo/issues/new/choose)
@@ -25,6 +104,6 @@ Please use GitHub to:
 🚔 [Report a security vulnerability](https://github.com/celo-org/celo-monorepo/issues/new/choose)
 
 > [!TIP]
-> 
-> Please avoid messaging us via Slack, Telegram, or email. We are more likely to respond to you on 
+>
+> Please avoid messaging us via Slack, Telegram, or email. We are more likely to respond to you on
 > GitHub than if you message us anywhere else. We actively monitor GitHub, and will get back to you shortly 🌟

packages/protocol/package.json

@@ -51,8 +51,12 @@
     "truffle:migrate": "truffle migrate",
     "devchain": "yarn ts-node scripts/devchain.ts",
     "devchain:reset": "yarn devchain generate-tar .tmp/devchain.tar.gz --upto 29",
-    "anvil-devchain:start": "./scripts/foundry/create_and_migrate_anvil_devchain.sh",
+    "anvil-devchain:start-L1": "./scripts/foundry/create_and_migrate_anvil_devchain.sh",
+    "anvil-devchain:start-L2": "./scripts/foundry/create_and_migrate_anvil_l2_devchain.sh",
+    "anvil-devchain:status": "if nc -z localhost 8546; then echo 'Devchain is serving at http://localhost:8546'; else echo 'Devchain is not running.'; fi",
     "anvil-devchain:stop": "./scripts/foundry/stop_anvil.sh",
+    "anvil-devchain:e2e-tests": "./scripts/foundry/run_e2e_tests_in_anvil.sh",
+    "anvil-devchain:integration-tests": "./scripts/foundry/run_integration_tests_in_anvil.sh",
     "view-tags": "git for-each-ref 'refs/tags/core-contracts.*' --sort=-committerdate --format='%(color:magenta)%(committerdate:short) %(color:blue)%(tree) %(color:green)github.com/celo-org/celo-monorepo/releases/tag/%(color:yellow)%(refname:short)'",
     "generate-stabletoken-files": "yarn ts-node ./scripts/generate-stabletoken-files.ts",
     "truffle-verify": "yarn truffle run verify"