Kakarot is an EVM implementation in Cairo. As such, it allows for provable executions of EVM transactions, and is de facto a so-called zkEVM. While other zkEVM implementations (see for example Scroll, Polygon zkEVM or Taiko) try to prove existing EVM implementations (mainly Geth), Kakarot is like another new Geth, but provable by design, simply because it runs on the CairoVM.
Indeed, 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 in the meantime. 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 • Supported opcodes • Build • Test • Report a bug
We support 100% of EVM opcodes and 8 out of 9 precompiles.
-
✅ Kakarot is a set of Cairo programs
-
✅ Kakarot can be packaged as a smart contract and deployed on any chain that runs the CairoVM (currently only Starknet mainnet).
-
✅ Kakarot is an EVM implementation.
-
❌ Kakarot is not a blockchain by itself. It still needs a chain that runs the CairoVM to be deployed
-
❌ Kakarot is not a compiler.
To contribute, please check out the contribution guide.
The easiest way to get started is to use
devcontainers:
- either directly from GitHub to have an online VSCode with everything ready
- or from VSCode, open the project and use "Dev Containers: Rebuild container" (requires Docker on your host machine)
Otherwise, you can proceed with a regular installation on your host:
# install poetry if you don't have it already
# curl -sSL https://install.python-poetry.org | python3 -
make setupNote that you may need to symlink starknet-compile-deprecated (new name of the
starknet-compile binary) to starknet-compile in order to make the CairoLS
VSCode extension work:
ln -s <YOUR_PATH_TO_YOUR_PYTHON_VENV_BINARIES>/starknet-compile-deprecated <YOUR_PATH_TO_LOCAL_BINARIES>/starknet-compile
# example: ln -s /Users/eliastazartes/code/kakarot/.venv/bin/starknet-compile-deprecated /usr/local/bin/starknet-compileTo build the Cairo files:
make buildTo 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-solThe project uses trunk.io to run a comprehensive list of linters.
To install Trunk, run:
curl https://get.trunk.io -fsSL | bashYou 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 syncKakarot 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.
# Run all tests
make test
# Run only unit tests
make test-units
# Run only integration tests
make test-integration
# 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/integration contains high level integrations tests running in the starknet test runner;
- tests/integration/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 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 %lang starknet and contracts
unless it's really required.
For an example of the starknet test runner, see for example the Contract Account tests. 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:
kwargsofcairo_runare available in theprogram_inputvariable- values written in the
outputsegment available in hints as a constant value are returned, e.g.segments.write_arg(output, [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.
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/ commonWith 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_Shanghai --features v0 -- --nocaptureSee this doc to learn how to debug a cairo trace when the CairoVM reverts.
The following describes how to deploy the Kakarot as a Starknet smart contract.
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 .envThe 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 deployDeployed 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.
kakarot is released under the MIT.
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.
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!
