EVM interpreter written in Cairo, a sort of ZK-EVM emulator, leveraging STARK proof system.

Kakarot is an Ethereum Virtual Machine written in Cairo. It means it can be deployed on StarkNet, a layer 2 scaling solution for Ethereum, and run an EVM bytecode program. Hence, Kakarot can be used to run Ethereum smart contracts on StarkNet. Kakarot is the super sayajin ZK-EVM ! Why ? Because: It's over 9000!!!!!. It is a work in progress, and it is not ready for production.

Getting started • Supported opcodes • Build • Test . Report a bug

Getting started

Supported opcodes

%%{init: {'theme': 'forest', 'themeVariables': { 'darkMode': 'false'}}}%%

pie title Kakarot EMV opcodes support (96 / 142)
    "Supported" : 96
    "Not supported" : 46

    "Partially supported" : 0

Loading

Here is the list of supported opcodes: opcodes

For the moment the list is maintained manually, but it will likely be generated automatically in the future. If you want to contribute, you can help us by adding the missing opcodes. And if you implement a new opcode, please update the list.

Documentation

Architecture

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(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:

Installation

Install the requirements:

• protostar

Then, install the dependencies:

protostar install

Build

protostar build

Test

# Run all tests
protostar test

# Run only unit tests
protostar test tests/units

# Run only integration tests
protostar test tests/integrations

Debug

Start the debug server:

python3 tests/debug/debug_server.py
# then use DEBUG env variable
# for example:
DEBUG=True protostar test

Deploy

# On testnet
./scripts/deploy_kakarot.sh -p testnet -a admin

With:

• testnet profile defined in protostar config file (testnet for alpha-goerli)
• admin alias to the admin account (optional if it is your __default__ account, see also starknet account documentation)

Contract addresses will be logged into the prompt.

Inputs

To manage inputs sent to constructor during the deployment, you can customize the config files.

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 ⚠️ 📖 💻 🚇	Lucas 💻 ⚠️	Florian Bellotti 💻 ⚠️ 📖	Mentor 💻	Henri 💻	Lenny 💻	Lakhdar Slaim 💻 ⚠️
pscott 💻 ⚠️	Clément Walter 📖	danilowhk 💻	etash 💻