Skip to content

ZK-EVM type 3 written in Cairo, leveraging STARK proof system.

License

Notifications You must be signed in to change notification settings

ptisserand/kakarot

Β 
Β 

Repository files navigation

zkEVM written in Cairo. proof system.

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

Kakarot is a zkEVM written in Cairo. It aims to allow users to leverage the scaling benefits of validity rollups while maintaining compatibility with the Ethereum ecosystem. Therefore, Kakarot can be used to run Ethereum smart contracts on Starknet.

We strongly believe the CairoVM will provide the best zero-knowledge toolbox in the coming years and that the Ethereum network effect will remain dominant 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.

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

Latest presentation of Kakarot at Starkware Session TLV 2023

Getting started β€’ Supported opcodes β€’ Build β€’ Test β€’ Report a bug β€’ Questions

Supported opcodes

We support 100% of EVM opcodes.

Documentation

Architecture

  • βœ… Kakarot is a smart contract, deployed on Starknet (goerli). It is written in Cairo.

  • βœ… Kakarot can: (a) execute arbitrary EVM bytecode, (b) deploy an EVM smart contract as is, (c) call a Kakarot-deployed EVM smart contract's functions (views and write methods).

  • βœ… Kakarot is an EVM bytecode interpreter.

  • ❌ Kakarot is not a blockchain.

  • ❌ Kakarot is not a compiler. Check out Warp for a Solidity -> Cairo transpiler

Main execution flow

sequenceDiagram
    title Simple bytecode execution flow example: [PUSH1 0x01 PUSH1 0x02 ADD]
    actor User
    participant Kakarot
    participant ExecutionContext
    participant EVMInstructions
    participant ArithmeticOperations
    participant PushOperations
    participant Stack
    User->>+Kakarot: execute(value, code, calldata)
    Kakarot->>+EVMInstructions: generate_instructions()
    EVMInstructions->>-Kakarot: instructions
    Kakarot->>+ExecutionContext: compute_intrinsic_gas_cost()
    ExecutionContext->>-Kakarot: ctx
    Kakarot->>Kakarot: run(instructions, ctx)
    loop opcode
        Kakarot->>+EVMInstructions: decode_and_execute(instructions, ctx)
        EVMInstructions->>EVMInstructions: retrieve the current program counter
        Note over EVMInstructions: revert if pc < 0, stop if pc > length of code
        EVMInstructions->>EVMInstructions: read opcode associated function from instruction set
        Note over PushOperations, Stack: x2 PUSH a=1, PUSH b=2
        EVMInstructions->>+PushOperations: exec_push1(ctx)
        PushOperations->>Stack: push(stack, element)
        PushOperations->>-EVMInstructions: ctx
        EVMInstructions->>+ArithmeticOperations: exec_add(ctx)
        Note over PushOperations, Stack: x2 POP a, POP b
        ArithmeticOperations->>Stack: pop(stack)
        Stack->>ArithmeticOperations: element
        ArithmeticOperations->>Stack: push(stack, result)
        ArithmeticOperations->>-EVMInstructions: ctx
        EVMInstructions->>-Kakarot: ctx
    end
    Kakarot->>-User: ctx
Loading

Execution sample

Execution of a simple EVM bytecode program on Kakarot.

The bytecode is the following:

6001600503600301610166016002026105b40460020500

Which corresponds to the following EVM program:

0x60 - PUSH1
0x60 - PUSH1
0x03 - SUB
0x60 - PUSH1
0x01 - ADD
0x61 - PUSH2
0x01 - ADD
0x60 - PUSH1
0x02 - MUL
0x61 - PUSH2
0x04 - DIV
0x60 - PUSH1
0x05 - SDIV
0x00 - STOP

Here is the execution trace of the program on Kakarot:

Tutorial

Getting started

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 Codespaces
  • 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 setup

Build

To build the Cairo 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

Test

# 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>  # with pytest
python3 -m unittest <PATH_TO_FILE>  # with unittest

# Run a specific test mark (markers in pyproject.toml)
make run-test-mark mark=<MARK>
make run-test-mark-log mark=<MARK> # with log

Test architecture is the following:

  • tests/unit/src contains cairo tests for each cairo function in the kakarot codebase
  • tests/integration/bytecode contains python tests for kakarot execute() function with forged bytecode
  • tests/integration/solidity_contracts contains python tests for solidity contracts that are compiled, deployed on kakarot local node and interacted with kakarot eth_call() and invoke()
  • the project also contains some forge tests (e.g. PlainOpcodes.t.sol) whose 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.

Deploy

The following describes how to deploy the entire Kakarot EVM on StarkNet.

It is not a description on how to deploy a contract on the official Kakarot zkEVM.

The Kakarot EVM can be deployed on StarkNet using a python script utilizing the starknet.py library.

First we need to declare some environment variables that are required for the deployment.

Start by copying the .env_example file located in the root directory (.files are usually hidden by default in most explorers. You should be able to see the file in your IDE).

Rename the copied file to .env.

The file holds the following content:

GITHUB_TOKEN=your_github_token

You will need to provide a Github access token to be able to build and deploy Kakarot.

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

PRIVATE_KEY=your_private_key
ACCOUNT_ADDRESS=your_account_address

Now replace the placeholder values with your account and network details.

PRIVATE_KEY is the private key of the account contract that will pay for the deployment. This should be a hexadecimal number

ACCOUNT_ADDRESS is the address of the account contract that will pay for the deployment (not the public key). This should be a hexadecimal number

Here is a concrete example:

ACCOUNT_ADDRESS=0x7e00d496e324876bbc8531f2d9a82bf154d1a04a50218ee74cdd372f75a551a
PRIVATE_KEY=0xe3e70682c2094cac629f6fbed82c07cd

By default, everything will run on a local starknet-devnet (started with make run). 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=testnet2 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.

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.

Callgraphs

The callgraph artifacts contains all the contract's call graph. Those are generated using thoth and can provide some more insight on the inside of this zkEVM. The legend can be found here. You can use this tool to visualize the .gv files online.

Questions / FAQ

Questions are welcome! If you have any questions regarding Kakarot, feel free to ask them using Newton.

FAQ

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

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

πŸ“–
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

πŸ’»

About

ZK-EVM type 3 written in Cairo, leveraging STARK proof system.

Resources

License

Code of conduct

Security policy

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Cairo 69.8%
  • Python 23.9%
  • Solidity 4.5%
  • Shell 1.4%
  • Other 0.4%