[](https://github.com/madara-alliance/madara/actions/workflows/push.yml) [](LICENSE) [](https://github.com/madara-alliance/madara/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22)

🥷 Madara: Starknet Client

Madara is a powerful Starknet client written in Rust.

Table of Contents

• ⬇️ Installation
  • Run from Source
  • Run with Docker
• ⚙️ Configuration
  • Basic Command-Line Options
  • Advanced Command-Line Options
• 🌐 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:

   Dependency	Version	Installation
   Rust	rustc 1.81	curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \| sh
   Clang	Latest	sudo apt-get install clang
   Scarb	v2.8.2	curl --proto '=https' --tlsv1.2 -sSf https://docs.swmansion.com/scarb/install.sh \| sh

   Clone the Madara repository:

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

2. Build Program

   Choose between different build modes:

   • Debug (fastest build mode, but lower performance, for testing purposes only):

     cargo build

   • Release (recommended build mode):

     cargo build --release

   • Production (recommended for production performance):

     cargo build --profile=production

3. Run Madara

   Start the Madara client with a basic set of arguments depending on your chosen mode:

   Full Node

   cargo run --release -- \
    --name Madara \
    --full \
    --base-path /var/lib/madara \
    --network mainnet \
    --l1-endpoint ${ETHEREUM_API_URL}

   Sequencer

   cargo run --release -- \
    --name Madara \
    --sequencer \
    --base-path /var/lib/madara \
    --preset test \
    --l1-endpoint ${ETHEREUM_API_URL}

   Devnet

   cargo run --release -- \
    --name Madara \
    --devnet \
    --base-path /var/lib/madara \
    --preset test

   ℹ️ Info: We recommend you to head to the Configuration section to customize your node parameters. ℹ️ Info: If you don't have an L1 endpoint URL, we recommend you refer to the relevant section to obtain one.

Run with Docker

1. Install Docker

   Ensure you have Docker installed on your machine. Once you have Docker installed, you can run Madara using the available Docker images.

   docker run -d \
    --name Madara \
    --full
    -p 9944:9944 \
    -v /var/lib/madara:/var/lib/madara \
    madara:latest \
    --base-path /var/lib/madara \
    --network mainnet \
    --l1-endpoint ${ETHEREUM_API_URL}

   ℹ️ Info: This is a default configuration for a Full Node on Starknet mainnet. For more information on possible configurations, please visit the Configuration section. ⚠️ Warning: Make sure to change the volume -v of your container if you change the --base-path. ℹ️ Info: If you don't have an L1 endpoint URL, we recommend you refer to the relevant section to obtain one.

2. Check Logs

   docker logs -f Madara

   ℹ️ Info: Now you can head to the Metrics section to deploy a Grafana and Prometheus dashboard.

⚙️ Configuration

Command-Line Options

For a comprehensive list of command-line options:

cargo run -- --help

Below are some essential command-line options and a categorized list of advanced configurations:

Basic Command-Line Options

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

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

• --full: The mode of your Madara client (either --sequencer, --full, or devnet).

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

ℹ️ Info: For more information regarding synchronization configuration, please refer to the Configuration section.

Advanced Command-Line Options

Toggle details for each namespace to view additional settings:

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

Environment Variables

Set up your node's environment variables using the MADARA_ prefix. For example:

• MADARA_BASE_PATH=/path/to/data
• MADARA_RPC_PORT=1111

These variables allow you to adjust the node's configuration without using command-line arguments. If the command-line argument is specified then it takes precedent over the environment variable.

[!CAUTION] Environment variables can be visible beyond the current process and are not encrypted. You should take special care when setting secrets through environment variables, such as MADARA_L1_ENDPOINT or MADARA_GATEWAY_KEY

Configuration File

You can use a JSON, TOML, or YAML file to structure your configuration settings. Specify your configuration file on startup with the -c option. Here's a basic example in JSON format:

{
  "name": "Deoxys",
  "base_path": "../deoxys-db",
  "network": "mainnet",
  "l1_endpoint": "l1_key_url",
  "rpc_port": 9944,
  "rpc_cors": "*",
  "rpc_external": true,
  "prometheus_external": true
}

💡 Tip: Review settings carefully for optimal performance and refer to Starknet's official documentation for detailed configuration guidelines.

Always test your configuration in a non-production environment before rolling it out to a live node to prevent downtime and other potential issues.

ℹ️ Info: For a custom chain configuration, you can refer to the configuration section of chain operator deployments.

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

ℹ️ Info: Madara currently supports the latest JSON-RPC 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.

📊 Analytics

Madara comes packed with OTEL integration, supporting export of traces, metrics and logs.

• OTEL version v0.25.0
• Trace and Logs are implemented using tokio tracing.
• Metric uses OTEL provided metrics.

Basic Command-Line Option

• --analytics-collection-endpoint <URL>: Endpoint for OTLP collector, if not provided then OTLP is not enabled.
• --analytics-log-level <Log Level>: Picked up from RUST_LOG automatically, can be provided using this flag as well.
• --analytics-service-name <Name>: Allows to customize the collection service name.

Setting up Signoz

• Signoz Dashboard JSONs are provided at infra/Signoz/dashboards.
• Signoz Docker Standalone can be setup following this guide.
• Ensure to configure the correct service_name after importing the json to the dashboard.

✔ 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

For guidelines on how to contribute to Madara, please see the Contribution Guidelines.

🤝 Partnerships

To establish a partnership with the Madara team, or if you have any suggestions or special requests, feel free to reach us on Telegram.

⚠️ License

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