zkEVM-framework

Framework for test verification of state of cluster based on EVM

Content

• Message generator
• EVM assigner
• Proof generator

Libraries

• data_types - definitions of data structures used for verification

Dependencies

Build dependencies

• CMake
• GCC 13+ (required by SSZ++)
• Ninja (recommended)

SSZ++

• Hashtree Repository
• intx: GMP (intx dependency) Homepage, intx Repository
• SSZ++ Repository

EVM-assigner

• evmc Repository
• =nil; crypto3 Repository
• =nil; zkllvm-blueprint Repository
• =nil; evm-assigner Repository

Block generator

• Valijson Repository

Clone

Using SSH:

git clone [email protected]:NilFoundation/zkEVM-framework.git

Or if you are using GitHub PAT to authenticate using HTTPS:

git clone https://<GITGUB_TOKEN>@github.com/NilFoundation/zkEVM-framework.git

Nix environment

Instead of installing all dependencies manually, you can use Nix environment with all installed deps.

For using experimantal features flake, nix-command add follow line to your Nix configuration file (/etc/nix/nix.conf):

experimental-features = nix-command flakes

Because zkEVM-framework currently has EVM-assigner as a dependency which is private repository, it is required to configure Nix with GitHub Personal Access Token (PAT). In order to generate your PAT, go here. Your token must have access to content of private repositories.

Then add this to your Nix configuration file (/etc/nix/nix.conf):

access-tokens = github.com=<YOUR PAT>

If for some reason you don't want to use PAT, you can fallback to using SSH authentication using --override-input option. Add this to your Nix command:

--override-input nil_evm_assigner git+ssh://[email protected]/NilFoundation/evm-assigner.git

To activate development environment run:

nix develop

If you want Nix to use your local version of dependency instead of cloning it from GitHub, you can use --override-input. E.g. if you want to use your local evm-assigner, use this:

nix develop --override-input nil_evm_assigner path:/path/to/evm-assigner

Same option applies to nix build and etc.

Build

cmake --workflow --preset release-build

Or with Nix:

nix build

Assigner

Build && run

nix run .#assigner -- -b block -t assignments -e pallas

Test

Configure tests

Configure with tests enabled:

cmake -B ${BUILD_DIR:-build} -DENABLE_TESTS=TRUE ...

When configuring with enabled tests, you can specify, which tests to enable. By default all tests are enabled.

# Data types tests won't be enabled
cmake -B ${BUILD_DIR:-build} -DENABLE_TESTS=TRUE -DENABLE_DATA_TYPES_TESTS=FALSE ...

Build tests

cmake --build ${BUILD_DIR:-build}

When using Ninja generator, you can build only tests using target tests/all:

cmake --build ${BUILD_DIR:-build} -t tests/all

Run tests

ctest --test-dir ${BUILD_DIR:-build}/tests

When using Nix, you can configure, build and run tests with:

nix flake check

Build API documentation

zkEVM-framework is using Doxygen to generate API documentaion. To build it, firts enable building documentation at configuration:

cmake -B ${BUILD_DIR:-build} -DBUILD_DOCS=TRUE ...

Then build documentation:

cmake -B ${BUILD_DIR:-build} -t docs

To see HTML documentation, open ${BUILD_DIR}/html.

Usage

Block call

Account storage contains one account with deployed contract. Incoming block has one transaction which call deployed contract Config file with initial state of account storage could be passed with -s

nix run .#assigner [-L] [--override-input nil_evm_assigner /path_to/evm-assigner] -- -b bin/assigner/example_data/call_block.ssz -t assignments -e pallas [-s bin/assigner/example_data/state.json] [--log-level debug]

Block generation

Test block could be generated from config file in JSON format

nix run .#block_gen [-L] -- -i bin/assigner/example_data/call_block.json -o call_block.ssz

Nil CLI block generation

Wrapper script for nil_cli is available to deploy and call Solidity contracts. It requires nil and nil_cli binaries in PATH (already available inside Nix dev environment).

Usage:

# Generate CLI config with server endpoint, private key and wallet address
./bin/block_generator/block_generator.py --mode make-config --cli-config-name test_config.yaml
# Generate transactions described in config file
./bin/block_generator/block_generator.py --mode generate-blocks --cli-config-name test_config.yaml --block-config-name bin/block_generator/example_data/block_config.json

Config file format:

{
    "contracts" : [
        {
            "id": 1,
            "path": "path/to/solidity/contract"
        },
        ...
    ],

    "transactions" : [
        {
            "contractId" : 1, // index of the deployed contract
            "methodName" : "methodToCall", // name of a method in the contract
            "callArguments": [  // Optional arguments for the method
                "0x123456"
            ]
        },
        ...
    ]
}

To deploy and call contracts manually use nil_cli directly.

Human-readable assignments

While generating assignment table, you can partially dump it into text form. This is enabled by --output-text option, which specifies output filename or stdout.

assigner --output-text out.txt

Using this option enables other options for tables, columns and rows selection:

assigner --output-text - \
    --tables 0 \
    --rows 0- \
    --columns witness0-1,3 \
    --columns public_input-1

This extracts all raws of w_0, w_1, w_3 and firts public input columns from table with index 0 and prints it to stdout. The syntax for ranges specification is: Range(,Range)* where Range = N|N-|-N|N-N where N is a number.