Madara is a powerfull Starknet hybrid client written in Rust.

• ⬇️ Installation
  • Run from Source
  • Run with Docker
  • Run with Docker Compose
• ⚙️ Configuration
  • Basic Command-Line Options
  • Advanced Command-Line Options
• 📸 Snapshots
• 🌐 Interactions
  • Supported JSON-RPC Methods
  • Example of Calling a JSON-RPC Method
• Supported Features
• 👍 Contribute

1. Install dependencies

   Ensure you have the necessary dependencies:

   sudo apt-get update && sudo apt-get install -y \
     clang \
     protobuf-compiler \
     build-essential

   Install Rust:

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s

   Clone the Madara repository:

   cd <your-destination-path>
   git clone https://github.com/KasarLabs/madara .

2. Run Madara

   Start the Madara client with synchronization to Starknet mainnet:

   cargo run --release \
     --name madara \
     --base-path ../madara-db \
     --network main \
     --l1-endpoint ${ETHEREUM_API_URL} \

1 Run docker image

To run Madara with Docker, use the following command:

docker run -d \
    --name madara \
    -p 9944:9944 \
    -v /var/lib/madara:/var/lib/madara \
    madara:latest \
    --base-path ../madara-db \
    --network main \
    --l1-endpoint <rpc key> \

Check the logs of the running Madara service:

docker logs -f madara

1. Ensure environment variable

   Set the necessary environment variable:

   export ETHEREUM_API_URL="your-ethereum-api-url"

   Or create a .env file in the same directory as your docker-compose.yml file:

   ETHEREUM_API_URL=your-ethereum-api-url

2. Build and Run the Container

   Navigate to the directory with your docker-compose.yml file and run:

   docker-compose up -d

   Check the logs of the running Madara service:

   docker-compose logs -f madara

Configuring your Madara node properly ensures it meets your specific needs

Here are the recommended options for a quick and simple configuration of your Madara full node:

• --name <NAME>: The human-readable name for this node. It's used as the network node name.
• --base-path <PATH>: Set the directory for Starknet data (default is /tmp/madara).
• --network <NETWORK>: The network type to connect to (main, test, or integration).
• --l1-endpoint <URL>: Specify the Layer 1 endpoint the node will verify its state from.
• --rpc-port <PORT>: Specify the JSON-RPC server TCP port.
• --rpc-cors <ORIGINS>: Specify browser origins allowed to access the HTTP & WS RPC servers.
• --rpc-external: Listen to all RPC interfaces. Default is local.
• --snap <BLOCK_NUMBER>: Start syncing from the closest snapshot available for the desired block (default is highest).

Here are more advanced command-line options, organized by namespace, for running and development purposes:

ℹ️ Info: Note that not all parameters may be referenced here. Please refer to the cargo run -- --help command for the full list of parameters.

Snapshots are under developpement and will be available trought the --snap <block_number> parameter.

Madara fully supports all the JSON-RPC methods as specified in the Starknet mainnet official JSON-RPC specs. These methods can be categorized into three main types: Read-Only Access Methods, Trace Generation Methods, and Write Methods.

Here is a list of all the supported methods with their current status:

ℹ️ Info: Madara currently supports latest JSON-RPC specs specs up to version v0.7.1

Here is an example of how to call a JSON-RPC method using Madara:

{
  "jsonrpc": "2.0",
  "method": "starknet_getBlockWithTxHashes",
  "params": {
    "block_id": "latest"
  },
  "id": 1
}

You can use any JSON-RPC client to interact with the Madara node, such as curl, httpie, or a custom client in your preferred programming language. For more detailed information and examples on each method, please refer to the Starknet JSON-RPC specs.

⚠️ Warning: Write methods are forwarded to the Sequencer for execution. Ensure you handle errors appropriately as per the JSON-RPC schema.

Madara offers numerous features and is constantly improving to stay at the cutting edge of Starknet technology.

• Starknet Version: v0.13.1
• JSON-RPC Version: v0.7.1
• Feeder-Gateway State Synchronization
• State Commitment Computation
• L1 State Verification
• Handling L1 and L2 Reorgs

Each feature is designed to ensure optimal performance and seamless integration with the Starknet ecosystem.

To establish a partnership with the Kasar team, or if you have any suggestion or special request, feel free to reach us on telegram.

Copyright (c) 2022-present, with the following contributors.

Madara is open-source software licensed under the Apache-2.0 License.