Kakarot RPC

Report a Bug - Request a Feature - Ask a Question

Table of Contents

Report a Bug
Request a Feature
About
Architecture
Getting Started
Installation
- API
Roadmap
Support
Project assistance
Contributing
Authors & contributors
Security
License
Acknowledgements

About

Kakarot RPC is the JSON-RPC server adapter to interact with Kakarot ZK-EVM in a fully EVM-compatible way.

This adapter layer is based on:

The Kakarot RPC layer's goal is to receive and output EVM-compatible JSON-RPC payloads & calls while interacting with the Starknet Blockchain. This enables Kakarot zkEVM to interact with the usual Ethereum tooling: Metamask, Hardhat, Foundry, etc.

Architecture

Here is a high level overview of the architecture of Kakarot RPC.

Getting Started

TL;DR:

Run make build to build Kakarot RPC.
Test with make test.
Run Kakarot RPC in dev mode:
- Run devnet: make devnet ( or feel free to run your own )
- Run dev RPC: make run
- Run production RPC make run-release

Prerequisites

Rust
Docker
Make

Installation

Build from source

To build the project from source do make build (this requires nightly rustup):

make build

Environment variables

Copy the .env.example file to a .env file and populate each variable

cp examples/.env.example .env

Meanwhile you can just use unit tests to dev.

make test

The binaries will be located in target/release/.

Specify the environment variables and run the binary.

make run-release

Dev mode with katana

run devnet

make devnet

run

make run

Some notes on make devnet:

you can run a devnet, by running make devnet at the project root.
this will run a devnet by running katana, with contracts automatically deployed, so you don't have to do them manually (see below for list of contracts and addresses).
it will use the values from .env.example file for deployment by default, but you can override any variable that you want by passing it to docker { changing .env.example won't work as it was copied during build phase of the image }, you can see the devnet target in the Makefile of the project, and see how we are overriding STARKNET_NETWORK environment variable, in similar fashion, you can override any other environment variable.
the deployments and declarations for the devnet will be written to the deployments/katana folder inside your project root after a successful run of the make devnet command.
feel free to run your own devnet if you are playing around with some custom changes to Kakarot.

Running with Docker Compose

To orchestrate running a Katana/Madara devnet instance, deploy Kakarot contracts and initialize the RPC, you may use the following commands:

Note: Ensure that you have the .env file

For Katana

make katana-rpc-up

For Madara

make madara-rpc-up

Sending transactions to RPC using forge script

An example script to run which uses a pre-funded EOA account with private key EVM_PRIVATE_KEY

forge script scripts/PlainOpcodes.s.sol --broadcast --legacy --slow

Configuration

Kakarot RPC is configurable through environment variables.

Here is the list of all the available environment variables:

Name	Default value	Description
TARGET_RPC_URL	http://0.0.0.0:5050/rpc	Target Starknet RPC URL
RUST_LOG	Debug	Log level
KAKAROT_HTTP_RPC_ADDRESS	0.0.0.0:3030	Kakarot RPC URL
KAKAROT_ADDRESS	see below	Kakarot address
PROXY_ACCOUNT_CLASS_HASH	see below	Proxy account class hash
DEPLOYER_ACCOUNT_ADDRESS	N/A	Deployer Account Address
DEPLOYER_ACCOUNT_PRIVATE_KEY	see below	Deployer Account Private Key

Devnet deployed/declared contracts

Deployed:

Contract	Address
Kakarot	0x7a88f6f9d63ccaa5855babb32cbb0230b8588aaaa6bc4ce2d173fa528ce7567
EOA	0x54b288676b749DEF5Fc10Eb17244fe2C87375de1
Counter	0x2e11Ed82f5eC165AB8Ce3cC094f025Fe7527F4D1

Declared:

Contract	Class hash
Proxy account class hash	0x3010a53967fa04842bcbcb6de8817101f047ef0d074b3eacbe714a3fc42a2eb

The Counter contract implementation can be found here

Deployer Account

The Kakarot RPC requires a funded deployer account to deploy ethereum EOAs whose on-chain smart contract don't exist, the role of the deployer is to deploy these accounts for a smoother UX { the deployer recovers the amount spent of this deployments }

The kakarot deploy scripts deploy and fund an account with the private key "0x0288a51c164874bb6a1ca7bd1cb71823c234a86d0f7b150d70fa8f06de645396" for Katana and Madara, the address of this account can be found in the file deployments/{network}/deployments.json with the key deployer_account after running this script on Kakarot.

You can configure Kakarot RPC to run with a particular Deployer Account via the following environment variables:

DEPLOYER_ACCOUNT_ADDRESS
DEPLOYER_ACCOUNT_PRIVATE_KEY

When running in production on testnet and mainnet it is advised to have a separate pre-funded account for this.

API

You can take a look at rpc-call-examples directory. Please note the following:

sendRawTransaction.hurl: the raw transaction provided allows to call the inc() function for the Counter contract. However, given that this transaction is signed for the EOA's nonce at the current devnet state (0x2), the call will only work once. If you want to keep incrementing (or decrementing) the counter, you need to regenerate the payload for the call with an updated nonce using the provided python script.

Roadmap

See the open issues for a list of proposed features (and known issues).

Top Feature Requests (Add your votes using the 👍 reaction)
Top Bugs (Add your votes using the 👍 reaction)
Newest Bugs

Support

Reach out to the maintainer at one of the following places:

GitHub Discussions
Contact options listed on this GitHub profile

Project assistance

If you want to say thank you or/and support active development of Kakarot RPC:

Add a GitHub Star to the project.
Tweet about the Kakarot RPC.
Write interesting articles about the project on Dev.to, Medium or your personal blog.

Together, we can make Kakarot RPC better!

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!

Authors & contributors

For a full list of all authors and contributors, see the contributors page.

Security

Kakarot RPC follows good practices of security, but 100% security cannot be assured. Kakarot RPC 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.