Kakaro2

<div align="center"> <h1>Kakarot RPC</h1> <p align="center"> <img src="docs/images/kakarot_github_banner.png" width="700"> </p> <br /> <a href="https://github.com/sayajin-labs/kakarot-rpc/issues/new?assignees=&labels=bug&template=01_BUG_REPORT.md&title=bug%3A+"> Report a Bug </a> - <a href="https://github.com/sayajin-labs/kakarot-rpc/issues/new?assignees=&labels=enhancement&template=02_FEATURE_REQUEST.md&title=feat%3A+"> Request a Feature </a> - <a href="https://github.com/sayajin-labs/kakarot-rpc/discussions">Ask a Question</a> </div> <div align="center"> <br />

</div> <details open="open"> <summary>Table of Contents</summary>

• Report a Bug
• Request a Feature
• About
• Architecture
  • High level
  • Low level
• Getting Started
  • Prerequisites
• Installation
  • Setup the project
  • Build from source
  • Environment variables
  • Dev mode with Katana
  • Building a Docker Image
  • Sending transactions to RPC using forge script
  • Configuration
• Running a Node in Various Environments
  • Local Environment
  • Staging Environment
  • Production Environment
  • Potential Pitfalls, Caveats, and Requirements
    • Requirements
    • Potential Pitfalls
    • Caveats
  • API
• Testing
  • Rust tests
  • Apibara indexer tests
  • Hive
• Project assistance
• Contributing
• Glossary
• Authors & contributors
• Security
• License
• Acknowledgements
• Benchmarks
• Contributors ✨

</details>

---

Update

The development of kakarot-rpc is halted for now. This repository - an Ethereum RPC gateway to Starknet EVM - is frozen, mainly to halt creation of new issues and pull requests. It is MIT licensed, not audited.

About

Kakarot RPC fits in the three-part architecture of the Kakarot zkEVM rollup (Kakarot EVM Cairo Programs, Kakarot RPC, Kakarot Indexer). It is the implementation of the Ethereum JSON-RPC specification made to interact with Kakarot zkEVM in a fully Ethereum-compatible way.

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

Note that this is necessary because Kakarot zkEVM is implemented as a set of Cairo Programs that run on an underlying CairoVM (so-called StarknetOS) chain.

This adapter layer is based on:

• The Ethereum JSON-RPC spec
• The Starknet JSON-RPC spec
• And their differences

Architecture

High level

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

Low level

Below is a lower level detailed overview of the internal architecture.

Getting Started

TL;DR:

• Run make setup to build dependencies.
• Run cargo build to build Kakarot RPC.
• Test with make test.
• Run Kakarot RPC in dev mode:
  • Run dev RPC: make run-dev (you'll need a StarknetOS instance running in another process and Kakarot contracts deployed)
• Run with Docker Compose:
  • make local-rpc-up
  • To kill these processes, make docker-down
• Build the docker image for the RPC:
  • make docker-build

Prerequisites

• Rust: The codebase is written in Rust to ensure high performance, maintainability, and a developer-friendly experience.
• Docker: Required for containerizing and running the various services and components in a consistent environment.
• Python: Used primarily for interacting with and building our Kakarot programs.
• UV: An extremely fast Python package and project manager, written in Rust. Used for managing the dependencies of our Kakarot programs.
• Deno: A JavaScript runtime used for our indexing service, based on the Apibara third-party service.
• Make: Utilized to interact with the Makefile for running commands such as building the project or executing tests.

Installation

Setup the project

To set up the repository (pulling git submodule and building Cairo dependencies), run:

make setup

Caveats:

1. the setup make command uses linux (MacOs compatible) commands to allow running the ./scripts/extract_abi.sh. This script is used to use strongly typed Rust bindings for Cairo programs. If you encounter problems when building the project, try running ./scripts/extract_abi.sh.
2. the kakarot submodule uses Python to build and deploy Kakarot contracts. If you don't have the right version available, we recommend to use pyenv to install it.
3. We use a pre-commit hook to ensure code quality and consistency. The hook are managed and automatically installed by trunk.

Build from source

To build the project from source (in release mode):

cargo build --release

Note that there are sometimes issues with some dependencies (notably scarb or cairo related packages, there are sometimes needs to cargo clean and cargo build)

Environment variables

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

cp .env.example .env

Meanwhile you can just use unit tests to dev.

make test

The binaries will be located in target/release/.

Dev mode with Katana

To run a local Starknet sequencer, you can use Katana. Katana, developed by the Dojo team, is a sequencer designed to aid in local development. It allows you to perform all Starknet-related activities in a local environment, making it an efficient platform for development and testing. To run Katana and deploy the Kakarot zkEVM (a set of Cairo smart contracts implementing the EVM):

make run-katana

This command will install Katana and generate a genesis file at .katana/genesis.json. Katana's genesis configuration feature is a way to define the initial state and settings of the Kakarot blockchain network locally, providing a customizable starting point for the chain. Among other things, it allows you to:

• Specify the token used for network fees.
• Allocate initial token balances to accounts.
• Pre-declare classes at the start of the chain.
• Pre-deploy smart contracts at the start of the chain.

To deploy Kakarot Core EVM (set of Cairo Programs):

 make deploy-kakarot

To run the Kakarot RPC pointing to this local devnet:

STARKNET_NETWORK=katana make run-dev

Some notes on this local devnet:

• this will run a devnet by running katana, with contracts automatically deployed, so you don't have to do them manually (see in ./lib/kakarot/kakarot_scripts/deploy_kakarot.py for the list of contracts).

• 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 deploy-kakarot command.

Building a Docker Image

In order to build a Docker Image for the RPC, you can run the below command which will setup the local environment and compile the binary:

make docker-build

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. Check out .env.example file to see the environment variables.

Running a Node in Various Environments

This section outlines how to run a complete node in different environments: local, staging, and production. Running a node involv