Home

Awesome

<!-- markdownlint-disable --> <div align="center"> <img src="https://github.com/keep-starknet-strange/madara-branding/blob/main/logo/PNGs/Madara%20logomark%20-%20Red%20-%20Duotone.png?raw=true" width="500"> </div> <div align="center"> <br /> <!-- markdownlint-restore -->

Workflow - Push Project license Pull Requests welcome <a href="https://twitter.com/madara-alliance"> <img src="https://img.shields.io/twitter/follow/madara-alliance?style=social"/> </a> <a href="https://github.com/madara-alliance/madara"> <img src="https://img.shields.io/github/stars/madara-alliance/madara?style=social"/> </a>

</div>

šŸ„· Madara: Starknet Client

Madara is a powerful Starknet client written in Rust.

Table of Contents

ā¬‡ļø Installation

Run from Source

  1. Install dependencies

    Ensure you have the necessary dependencies:

    DependencyVersionInstallation
    Rustrustc 1.81curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
    ClangLatestsudo apt-get install clang
    Scarbv2.8.2curl --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:

ā„¹ļø 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:

<details> <summary><strong>Network</strong></summary> </details> <details> <summary><strong>RPC</strong></summary> </details> <details> <summary><strong>Database</strong></summary> </details> <details> <summary><strong>Block Production</strong></summary> </details> <details> <summary><strong>Metrics</strong></summary> </details>

ā„¹ļø 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:

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:

<details> <summary>Read Methods</summary>
StatusMethod
āœ…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
</details> <details> <summary>Trace Methods</summary>
StatusMethod
āœ…starknet_traceTransaction
āœ…starknet_simulateTransactions
āœ…starknet_traceBlockTransactions
</details> <details> <summary>Write Methods</summary>
StatusMethod
āœ…starknet_addInvokeTransaction
āœ…starknet_addDeclareTransaction
āœ…starknet_addDeployAccountTransaction
</details>

ā„¹ļø 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.

Basic Command-Line Option

Setting up Signoz

āœ” Supported Features

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

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.