Skip to content

kkrt-labs/kakarot

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

Kakarot, the zkEVM written in Cairo.

GitHub Workflow Status GitHub GitHub contributors GitHub top language Telegram Contributions welcome GitHub Repo stars Twitter Follow Discord

This repository contains the set of Cairo (Cairo compiler version Zero) programs that implement the core EVM logic of Kakarot zkEVM.

Kakarot is an EVM implementation in Cairo. Cairo being a high-level zero-knowledge domain specific language (zkDSL), Kakarot is provable by design. This allows for proving the execution of EVM transactions, and makes Kakarot a de facto so-called zkEVM.

While some zkEVM implementations (see for example Scroll or Taiko) tries to prove existing EVM implementations (mainly Geth), Kakarot is like another new Geth, but provable by design, simply because it runs on the CairoVM.

We strongly believe the CairoVM will provide the best zero-knowledge toolbox in the coming years and that the Ethereum network effect will remain prevalent. We present to developers an abstraction layer they're familiar with: the EVM. Build and deploy as if you were working on Ethereum, be forward compatible with the future of zero-knowledge.

Kakarot is a work in progress, and it is not ready for production.

Kakarot presentations and talks around the world

Getting started β€’ Build β€’ Test β€’ Report a bug

Supported opcodes

We support 100% of EVM opcodes and 6 out of 9 precompiles.

Documentation

Architecture

Here is a high-level architecture diagram of the entire Kakarot zkEVM system.

Kakarot high-level architecture

The set of Cairo programs in this repository are represented below:

Kakarot Core EVM diagram

  • βœ… Kakarot Core EVM is a set of Cairo programs

  • βœ… Kakarot can be packaged as a smart contract and deployed on any chain that runs the CairoVM (StarknetOS chains, Starknet Appchains, Starknet clients).

  • βœ… Kakarot is an EVM implementation.

  • ⚠️ Kakarot Core EVM (the Cairo programs in this repository) is not a blockchain by itself. Combined with an underlying CairoVM chain, an RPC layer, it forms an Ethereum-compatible L2 network.

  • ❌ Kakarot is not a compiler.

Getting started

To contribute and setup your development environment, please check out the contribution guide.

Build

The project uses uv to manage python dependencies and run commands. To install uv:

curl -LsSf https://astral.sh/uv/install.sh | sh

To setup the project and install all dependencies:

make setup

To build the CairoZero files:

make build

To build the test Solidity smart contracts:

# install foundry if you don't have it already
# curl -L https://foundry.paradigm.xyz | bash
# foundryup
make build-sol

Code style

The project uses trunk.io to run a comprehensive list of linters.

To install Trunk, run:

curl https://get.trunk.io -fsSL | bash

You can also add Trunk to VSCode with this extension.

Then, don't forget to select Trunk as your default formatter in VSCode (command palette > Format Document With > Trunk).

Once Trunk is installed, you can install a pre-push hook to run the linters before each push:

trunk git-hooks sync

Test

Kakarot tests

Kakarot tests uses pytest as test runner. Make sure to read the doc and get familiar with the tool to benefit from all of its features.

# Runs a local CairoVM client (or StarknetOS chain)
make run-nodes

# Run all tests. This requires a Katana instance and an Anvil instance running in the background: `make run-nodes`
make test

# Run only unit tests
make test-unit

# Run only e2e tests
make test-end-to-end

# Run a specific test file
pytest <PATH_TO_FILE>

# Run a specific test mark (markers in pyproject.toml)
pytest -m <MARK>

Test architecture is the following:

  • tests/src contains cairo tests for each cairo function in the kakarot codebase running either in plain cairo or with the starknet test runner;
  • tests/end_to_end contains end-to-end tests running on an underlying Starknet-like network (using the Starknet RPC), currently Katana. These end-to-end tests contain both raw bytecode execution tests and test on real solidity contracts.

The difference between the starknet test runner (when using contracts) and the plain cairo one is that the former emulate a whole starknet network and is as such much slower (~10x).

Consequently, when writing tests, don't use contracts unless it's really required. Actually, for tests requiring a Starknet devnet, prefer end-to-end relying only on a RPC endpoint and currently running on Katana.

For an example of the cairo test runner, see for example the RLP library tests. Especially, the cairo runner uses hints to communicate values and return outputs:

  • kwargs of cairo_run are available in the program_input variable
  • values written in the output_ptr segment are returned, e.g. segments.write_arg(output_ptr, [ids.x]) will return the list [x].

Both cairo and starknet tests can be used with the --profile-cairo flag to generate a profiling file (see the --profile_output flag of the cairo-run CLI). The file can then be used with pprof, for example:

go tool pprof --png <path_to_file.pb.gz>

The project also contains a regular forge project (./solidity_contracts) to generate real artifacts to be tested against. This project also contains some forge tests (e.g. PlainOpcodes.t.sol) which purpose is to test easily the solidity functions meant to be tested with kakarot, i.e. quickly making sure that they return the expected output so that we know that we focus on kakarot testing and not .sol testing. They are not part of the CI. Simply use forge test to run them.

EF tests

To run the Ethereum Foundation test suite, you need to pull locally the Kakarot ef-tests runner. To simplify the devX, you can create symlinks in the ef-tests repo pointing to your local changes. For example:

ln -s /Users/clementwalter/Documents/kkrt-labs/kakarot/blockchain-tests-skip.yml blockchain-tests-skip.yml
mkdir build && cd build
ln -s /Users/clementwalter/Documents/kkrt-labs/kakarot/build/ v0
ln -s /Users/clementwalter/Documents/kkrt-labs/kakarot/build/fixtures/ common

With this setting, you can run a given EF test against your local Kakarot build by running (in the ef test directory):

cargo test <test_name> --features v0 -- --nocapture
# e.g. cargo test test_sha3_d7g0v0_Cancun --features v0 -- --nocapture

See this doc to learn how to debug a cairo trace when the CairoVM reverts.

Deploy

The following describes how to deploy the Kakarot as a Starknet smart contract on an underlying StarknetOS network.

It is not a description on how to deploy a solidity contract on the Kakarot EVM.

The deploy script relies on some env variables defined in a .env file located at the root of the project and loaded in the constant file. To get started, just

cp .env.example .env

The default file is self sufficient for using Kakarot with KATANA. If targeting other networks, make sure to fill the corresponding variables.

Furthermore, if you want to run the check-resources locally to check the steps usage of your local changes in the EF tests against main and other branches, you need to fill the following

GITHUB_TOKEN=your_github_token

You can learn how to create this token from here, we would suggest using a fine-grained token with only read access.

By default, everything will run on a local katana (started with make run-katana). If you want to deploy to a given target, set the STARKNET_NETWORK env variable, for example:

make deploy # localhost
STARKNET_NETWORK=testnet make deploy
STARKNET_NETWORK=mainnet make deploy

Deployed contract addresses will be stored in ./deployments/{networks}/deployments.json.

A step by step description of the individual components and how they are deployed/configured can be found here.

Slither

To run slither against provided Kakarot solidity contracts, you need to install slither and run:

forge build --build-info --force
slither . --foundry-out-directory solidity_contracts/build --ignore-compile --include-paths "DualVmToken.sol|L1KakarotMessaging.sol|L2KakarotMessaging.sol" --checklist > report.md

License

kakarot is released under the MIT.

Security

Kakarot follows good practices of security, but 100% security cannot be assured. Kakarot is provided "as is" without any warranty. Use at your own risk.

For more information and to report security issues, please refer to our security documentation.

Contributing

First off, thanks for taking the time to contribute! Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make will benefit everybody else and are greatly appreciated.

Please read our contribution guidelines, and thank you for being involved!

Contributors

Abdel @ StarkWare
Abdel @ StarkWare

πŸ’» ⚠️ πŸ“– πŸš‡ πŸ“† πŸ§‘β€πŸ«
Lucas
Lucas

πŸ’» ⚠️ πŸ“– πŸ§‘β€πŸ«
Mentor Reka
Mentor Reka

πŸ’» ⚠️ πŸ“– πŸš‡
danilowhk
danilowhk

πŸ’» ⚠️
Lenny
Lenny

πŸ’» ⚠️
Florian Bellotti
Florian Bellotti

πŸ’» ⚠️
Henri
Henri

πŸ’» ⚠️
FreshPizza
FreshPizza

πŸ’» ⚠️
ClΓ©ment Walter
ClΓ©ment Walter

πŸ“– ⚠️ πŸ’»
Rich Warner
Rich Warner

πŸ’» ⚠️
pscott
pscott

πŸ’» ⚠️
Elias Tazartes
Elias Tazartes

πŸ’» ⚠️
Riad-Quadratic
Riad-Quadratic

πŸ’» ⚠️
Tyler Smith
Tyler Smith

⚠️
Shahar Papini
Shahar Papini

πŸ§‘β€πŸ« πŸ’» ⚠️
Riad | Quadratic
Riad | Quadratic

πŸ’»
thomas-quadratic
thomas-quadratic

πŸ’»
Pedro Bergamini
Pedro Bergamini

πŸ’»
ptisserand
ptisserand

πŸ’»
TurcFort07
TurcFort07

πŸ’»
Mnemba Chambuya
Mnemba Chambuya

πŸ’»
Matthieu Auger
Matthieu Auger

πŸ§‘β€πŸ« ⚠️ πŸ’»
ftupas
ftupas

πŸ’»
johann bestowrous
johann bestowrous

πŸ’»
Seshanth.S
Seshanth.S

πŸ’»
Flydexo
Flydexo

πŸ’» ⚠️ πŸ“–
Petar Calic
Petar Calic

πŸ’» ⚠️
gaetbout
gaetbout

πŸš‡
greged93
greged93

πŸ’» ⚠️
Francisco Strambini
Francisco Strambini

πŸ’» ⚠️
sparqet
sparqet

πŸ’» ⚠️
omahs
omahs

πŸ“–
ArnaudBD
ArnaudBD

πŸ“–
Dragan Pilipovic
Dragan Pilipovic

πŸ’» ⚠️
Harsh Bajpai
Harsh Bajpai

πŸ’» ⚠️ πŸ“–
Antoine
Antoine

πŸ’»
Bal7hazar @ Carbonable
Bal7hazar @ Carbonable

πŸ“–
Daniel Bejarano
Daniel Bejarano

⚠️
JuMi231
JuMi231

πŸ“–
Juan Rigada
Juan Rigada

πŸ’»
Mete Karasakal
Mete Karasakal

πŸ“–
Ng Wei Han
Ng Wei Han

πŸ’»
etash
etash

πŸ’»
kasteph
kasteph

πŸ“–
Lakhdar Slaim
Lakhdar Slaim

πŸ’»
mmsc2
mmsc2

πŸ’»
sarantapodarousa
sarantapodarousa

πŸ’»