Linea Arithmetization (zkEVM)

A Linea tracing implementation for Hyperledger Besu based on an existing implementation in Go.

Development Setup

Install Java 17

brew install openjdk@17

Install the Go toolchain

Install Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Use local git executable to fetch from repos (needed for private repos)
echo "net.git-fetch-with-cli=true" >> .cargo/config.toml

Install Corset

cargo install --git ssh://git@github.com/ConsenSys/corset --locked --force

Update Constraints Submodule

git submodule update --init --recursive

Install pre-commit

pip install --user pre-commit

# For macOS users.
brew install pre-commit

Then run pre-commit install to set up git hook scripts. Used hooks can be found here.

---

NOTE

pre-commit aids in running checks (end of file fixing, markdown linting, linting, runs tests, json validation, etc.) before you perform your git commits.

---

Run tests

# Run all tests
./gradlew clean test

# Run only unit tests
./gradlew clean unitTests

# Run only acceptance tests
./gradlew clean acceptanceTests

# Run EVM test suite BlockchainTests
./gradlew clean referenceBlockchainTests

# Run EVM test suite GeneralStateTests
./gradlew clean referenceGeneralStateTests

# Run all EVM test suite reference tests
./gradlew clean referenceTests

# Run single reference test via gradle, e.g for net.consensys.linea.generated.blockchain.BlockchainReferenceTest_583
./gradlew :reference-tests:referenceTests --tests "net.consensys.linea.generated.blockchain.BlockchainReferenceTest_583"

---

NOTE

Please be aware if the reference test code generation tasks blockchainReferenceTests and generalStateReferenceTests do not generate any java code, than probably you are missing the Ethereum tests submodule which you can clone via git submodule update --init --recursive.

---

Capturing a replay

For debugging and inspection purposes, it is possible to capture a replay, i.e. all the minimal information required to replay a series of blocks as they played on the blockchain, which is done with scripts/capture.pl.

A typical invocation would be:

scripts/capture.pl --start 1300923

which would capture a replay of block #1300923 and store it in arithmetization/src/test/resources/replays. More options are available, refer to scripts/capture.pl -h.

IntelliJ IDEA Setup

Enable Annotation Processing

• Go to Settings | Build, Execution, Deployment | Compiler | Annotation Processors and tick the following checkbox:

  

---

NOTE

This setting is required to avoid IDE compilation errors because of the Lombok library used for code generation of boilerplate Java code such as:

• Getters/Setters (via @Getter/@Setter)
• Class log instances (via @Slf4j)
• Builder classes (via @Builder)
• Constructors ( via @NoArgsConstructor/@RequiredArgsConstructor/@AllArgsConstructor)
• etc.

Learn more about how Java annotation processing works here.

---

Set Up IDE Code Re-formatting

• Install Checkstyle plugin and set IDE code reformatting to comply with the project's Checkstyle configuration:

  • Go to Settings | Editor | Code Style | Java | <hamburger menu> | Import Scheme | Checkstyle configuration:

    

    and select <project_root>/config/checkstyle.xml.

Install Optional Plugins

• Install Spotless Gradle plugin to re-format through the IDE according to spotless configuration.

Debugging Traces

• JSON files can be debugged with the following command:

corset check -T <JSON_FILE> -v zkevm-constraints/zkevm.bin

Plugins

Plugins are documented here.

Release Process

Here are the steps for releasing a new version of the plugins:

1. Create a tag with the release version number in the format vX.Y.Z (e.g., v0.2.0 creates a release version 0.2.0).
2. Push the tag to the repository.
3. GitHub Actions will automatically create a draft release for the release tag.
4. Once the release workflow completes, update the release notes, uncheck "Draft", and publish the release.

Note: Release tags (of the form v*) are protected and can only be pushed by organization and/or repository owners.