Fundamentals
Configuration

Configuration

Configuring your Starknet client properly ensures that it answer your specific needs. Configuration can be done through three main avenues:

  • Command-line arguments
  • Environment variables
  • Configuration files

Priority of Configuration

ℹ️

Configuration priority is as follows: command-line arguments > environment variables > configuration files. When the same setting is configured in multiple places, the source with the highest priority takes effect.

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 recommend options for a quick and simple configuration of your Madara client:

  • --name <NAME>: The human-readable name for this node. It's used as network node name

  • -d, --base-path <PATH>: Set the directory for Starknet data (default is /tmp/madara).

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

ℹ️

For more information regarding synchronization configuration please refer to the next section

Advanced Command-Line Options by Namespace

Toggle details for each namespace to view additional settings:

 Network


  • -n, --network <NETWORK>: The network type to connect to.
    • [default: main]

Possible values:

  • main: The main network (mainnet). Alias: mainnet
  • test: 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. This affects the sync service after catching up with the blockchain tip.
    • [default: 4]

  • --pending-block-poll-interval <SECONDS>: Pending block polling interval in seconds. This affects the sync service after catching up with the blockchain tip.
    • [default: 2]


- --no-sync-polling: Disable sync polling. Sync service will not import new blocks after catching up with the blockchain tip.


  • --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. The sync service is responsible for listening for new blocks on Starknet and Ethereum.


- --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. Use --rpc-methods unsafe to expose all RPC methods.


  • --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. For example, --rpc-rate-limit 10 will allow a maximum of 10 calls per minute per connection.

  • --rpc-rate-limit-whitelisted-ips <IP ADDRESSES>: Disable RPC rate limiting for specific IP addresses or ranges (e.g., 1.2.3.4/24).


- --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. A comma-separated list of origins, or the special all value.

  • --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. Use with --restore-from-latest-backup or --backup-every-n-blocks <NUMBER OF BLOCKS>.

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


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

 Block Production


- --block-production-disabled: Disable the block production service. This service is only enabled with the authority (sequencer) mode.


- --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 (like SN_MAINNET, SN_SEPOLIA). This is unsafe because your devnet transactions can be replayed on the actual network.


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

 Metrics


- --telemetry-disabled: Disable connection to the Madara telemetry server. Telemetry is enabled by default.


  • --telemetry-url <URL VERBOSITY>: The URL of the telemetry server with verbosity level. Expected format is 'URL VERBOSITY', e.g., --telemetry-url 'wss://foo/bar 0'.
    • [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.

 P2p

Coming soon

Environment Variables

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

  • STARKNET_BASE_PATH=/path/to/data
  • STARKNET_LOG=info

These variables allow you to adjust the node's configuration without using command-line arguments.

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
}
💡

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.

ℹ️

For a custom Chain configuration you can head up to the configuration section of Chain operators deployments

OverviewSynchronization