🥷 Madara: Starknet client

Madara is a powerfull Starknet hybrid client written in Rust.

Table of Contents

• ⬇️ 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

⬇️ Installation

Run from Source

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/madara-alliance/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} \

Run with Docker

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

Run with Docker Compose

1. Ensure environment variable

   Set the necessary environment variable:

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

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

   L1_ENDPOINT=your-ethereum-api-url

2. Build and Run the Container

   Navigate to the directory with your docker-compose.yml file and run one of the following commands:

   • Mainnet:

     docker-compose --profile mainnet up -d

   • Testnet:

     docker-compose --profile testnet up -d

   Check the logs of the running Madara service:

   docker-compose logs -f madara

⚙️ Configuration

Configuring your Madara node properly ensures it meets your specific needs

Basic Command-Line Options

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).

Advanced Command-Line Options

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

Network

• -n, --network <NETWORK>: The network type to connect to (default: integration).
• --port <PORT>: Set the network listening port.
• --l1-endpoint <URL>: Specify the Layer 1 endpoint the node will verify its state from.
• --gateway-key <GATEWAY_KEY>: Gateway API key to avoid rate limiting (optional).
• --sync-polling-interval <SECONDS>: Polling interval in seconds (default: 2).
• --no-sync-polling: Stop sync polling.
• --n-blocks-to-sync <NUMBER>: Number of blocks to sync.
• --starting-block <BLOCK>: The block to start syncing from (make sure to set --disable-root).

RPC

• --rpc-external: Listen to all RPC interfaces. Note: not all RPC methods are safe to be exposed publicly. Use an RPC proxy server to filter out dangerous methods.
• --rpc-methods <METHOD_SET>: RPC methods to expose (auto, safe, unsafe).
• --rpc-max-request-size <SIZE>: Set the maximum RPC request payload size in megabytes (default: 15).
• --rpc-max-response-size <SIZE>: Set the maximum RPC response payload size in megabytes (default: 15).
• --rpc-max-subscriptions-per-connection <NUMBER>: Set the maximum concurrent subscriptions per connection (default: 1024).
• --rpc-port <PORT>: Specify JSON-RPC server TCP port.
• --rpc-max-connections <NUMBER>: Maximum number of RPC server connections (default: 100).
• --rpc-cors <ORIGINS>: Specify browser origins allowed to access the HTTP & WS RPC servers.

Database

• --base-path <PATH>: Specify custom base path (default: /tmp/madara).
• --snap <BLOCK_NUMBER>: Start syncing from the closest snapshot available for the desired block.
• --tmp: Run a temporary node. A temporary directory will be created and deleted at the end of the process.
• --cache: Enable caching of blocks and transactions to improve response times.
• --db-cache <MiB>: Limit the memory the database cache can use.
• --trie-cache-size <Bytes>: Specify the state cache size (default: 67108864).
• --backup-every-n-blocks <NUMBER>: Specify the number of blocks after which a backup should be created.
• --backup-dir <DIR>: Specify the directory where backups should be stored.
• --restore-from-latest-backup: Restore the database from the latest backup available.

ℹ️ 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

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

🌐 Interactions

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.

Supported JSON-RPC Methods

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

Read Methods

Status	Method
✅	starknet_specVersion
✅	starknet_getBlockWithTxHashes
✅	starknet_getBlockWithReceipts
✅	starknet_getBlockWithTxs
✅	starknet_getStateUpdate
✅	starknet_getStorageAt
✅	starknet_getTransactionStatus
✅	starknet_getTransactionByHash
✅	starknet_getTransactionByBlockIdAndIndex
✅	starknet_getTransactionReceipt
✅	starknet_getClass
✅	starknet_getClassHashAt
✅	starknet_getClassAt
✅	starknet_getBlockTransactionCount
✅	starknet_call
✅	starknet_estimateFee
✅	starknet_estimateMessageFee
✅	starknet_blockNumber
✅	starknet_blockHashAndNumber
✅	starknet_chainId
✅	starknet_syncing
✅	starknet_getEvents
✅	starknet_getNonce

Trace Methods

Status	Method
✅	starknet_traceTransaction
✅	starknet_simulateTransactions
✅	starknet_traceBlockTransactions

Write Methods

Status	Method
✅	starknet_addInvokeTransaction
✅	starknet_addDeclareTransaction
✅	starknet_addDeployAccountTransaction

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

Example of Calling a JSON-RPC Method

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.

✔ Supported Features

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

• Starknet Version: v0.13.2
• 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.

👍 Contribute

🤝 Partnerships

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

⚠️ License

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

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