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

Network

• -n, --network <NETWORK>: The network type to connect to.

  • [default: mainnet]

  Possible values:

  • mainnet: The main network (mainnet). Alias: main
  • testnet: The test network (testnet). Alias: sepolia
  • integration: The integration network
  • devnet: A devnet for local testing

• --l1-endpoint <ETHEREUM RPC URL>: Specify the Layer 1 RPC endpoint for state verification.

• --gateway-key <API KEY>: Gateway API key to avoid rate limiting (optional).

• --sync-polling-interval <SECONDS>: Polling interval in seconds.

  • [default: 4]

• --pending-block-poll-interval <SECONDS>: Pending block polling interval in seconds.

  • [default: 2]

• --no-sync-polling: Disable sync polling.

• --n-blocks-to-sync <NUMBER OF BLOCKS>: Number of blocks to sync, useful for benchmarking.

• --unsafe-starting-block <BLOCK NUMBER>: Start syncing from a specific block. May cause database inconsistency.

• --sync-disabled: Disable the sync service.

• --sync-l1-disabled: Disable L1 sync service.

• --gas-price-sync-disabled: Disable the gas price sync service.

• --gas-price-poll-ms <MILLISECONDS>: Interval in milliseconds for the gas price sync service to fetch the gas price.

  • [default: 10000]

RPC

• --rpc-disabled: Disable the RPC server.

• --rpc-external: Listen to all network interfaces.

• --rpc-methods <METHOD>: RPC methods to expose.

  • [default: auto]

  Possible values:

  • auto: Expose all methods if RPC is on localhost, otherwise serve only safe methods.
  • safe: Allow only a safe subset of RPC methods.
  • unsafe: Expose all RPC methods (even potentially unsafe ones).

• --rpc-rate-limit <CALLS/MIN>: RPC rate limiting per connection.

• --rpc-rate-limit-whitelisted-ips <IP ADDRESSES>: Disable RPC rate limiting for specific IP addresses or ranges.

• --rpc-rate-limit-trust-proxy-headers: Trust proxy headers for disabling rate limiting in reverse proxy setups.

• --rpc-max-request-size <MEGABYTES>: Maximum RPC request payload size for both HTTP and WebSockets.

  • [default: 15]

• --rpc-max-response-size <MEGABYTES>: Maximum RPC response payload size for both HTTP and WebSockets.

  • [default: 15]

• --rpc-max-subscriptions-per-connection <COUNT>: Maximum concurrent subscriptions per connection.

  • [default: 1024]

• --rpc-port <PORT>: The RPC port to listen on.

  • [default: 9944]

• --rpc-max-connections <COUNT>: Maximum number of RPC server connections at a given time.

  • [default: 100]

• --rpc-disable-batch-requests: Disable RPC batch requests.

• --rpc-max-batch-request-len <LEN>: Limit the max length for an RPC batch request.

• --rpc-cors <ORIGINS>: Specify browser origins allowed to access the HTTP & WebSocket RPC servers.

• --rpc-message-buffer-capacity-per-connection <CAPACITY>: Maximum number of messages in memory per connection.

  • [default: 64]

Database

• --base-path <PATH>: The path where Madara will store the database.

  • [default: /tmp/madara]

• --backup-dir <PATH>: Directory for backups.

• --backup-every-n-blocks <NUMBER OF BLOCKS>: Periodically create a backup.

• --restore-from-latest-backup: Restore the database from the latest backup version.

Block Production

• --block-production-disabled: Disable the block production service.

• --devnet: Launch in block production mode, with devnet contracts.

• --devnet-contracts <DEVNET_CONTRACTS>: Create this number of contracts in the genesis block for the devnet configuration.

  • [default: 10]

• --override-devnet-chain-id: Launch a devnet with a production chain ID.

• --authority: Enable authority mode; the node will run as a sequencer and try to produce its own blocks.

Metrics

• --telemetry: Enable connection to the Madara telemetry server.

• --telemetry-url <URL VERBOSITY>: The URL of the telemetry server with verbosity level.

  • [default: "wss://starknodes.com/submit 0"]

• --prometheus-port <PORT>: The port used by the Prometheus RPC service.

  • [default: 9615]

• --prometheus-external: Listen on all network interfaces for Prometheus.

• --prometheus-disabled: Disable the Prometheus service.

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

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