zkEVM-framework

Framework for test verification of state of cluster based on EVM

Content

• Block generator
• EVM assigner
• Proof producer

Libraries

• NilCore - definitions of data structures used for fetching data from shards
• zkEVMAssignerRunner - provide interace for run EVM assigner and fill assignment tables
• zkEVMRpc - provide interface for send / process requests to RPC
• zkEVMJsonHelpers - provide interface for process json configuration files
• zkEVMOutputArtifacts - provide interface for manage difernt modes of printing assignment tables (binary, readable, paricular display)

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
• Valijson Repository

Clone

Using SSH:

git clone git@github.com: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://git@github.com/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

WARNING: for use block_generator script need to clone and build nil repository. Make sure if nild and nil in PATH.

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 is available to deploy and call Solidity contracts. It requires nild and nil binaries in PATH (already available inside Nix dev environment).

Usage:

For use not default wallet neet to create custom configuration file

# Generate custom coniguration file
./bin/block_generator/block_generator.py --mode make-config --cli-config-name <path to create new config file>

And use --cli-config-name <path to create new config file> in each follow commands

# Generate block, get ShardId, BlockHash. Write block data and state of the correspond contract to the files
./bin/block_generator/block_generator.py --mode generate-block --block-config-name bin/block_generator/example_data/block_config.json [-o block.jsdon] [-s state.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.