Skip to content

config.md

Latest commit

 

History

History
815 lines (592 loc) · 23.1 KB

config.md

File metadata and controls

815 lines (592 loc) · 23.1 KB

Config

This document provides a comprehensive reference for all configuration options available in Evolve. Understanding these configurations will help you tailor Evolve's behavior to your specific needs, whether you're running an aggregator, a full node, or a light client.

Table of Contents

DA-Only Sync Mode

Evolve supports running nodes that sync exclusively from the Data Availability (DA) layer without participating in P2P networking. This mode is useful for:

  • Pure DA followers: Nodes that only need the canonical chain data from DA
  • Resource optimization: Reducing network overhead by avoiding P2P gossip
  • Simplified deployment: No need to configure or maintain P2P peer connections
  • Isolated environments: Nodes that should not participate in P2P communication

To enable DA-only sync mode:

  1. Leave P2P peers empty (default behavior):

    p2p:
  peers: ""  # Empty or omit this field entirely

  2. Configure DA connection (required):

    da:
  address: "your-da-service:port"
  namespace: "your-namespace"
  # ... other DA configuration

  3. Optional: You can still configure P2P listen address for potential future connections, but without peers, no P2P networking will occur.

When running in DA-only mode, the node will:

  • ✅ Sync blocks and headers from the DA layer
  • ✅ Validate transactions and maintain state
  • ✅ Serve RPC requests
  • ❌ Not participate in P2P gossip or peer discovery
  • ❌ Not share blocks with other nodes via P2P
  • ❌ Not receive transactions via P2P (only from direct RPC submission)

Configs

Evolve configurations can be managed through a YAML file (typically evolve.yaml located in ~/.evolve/config/ or <your_home_dir>/config/) and command-line flags. The system prioritizes configurations in the following order (highest priority first):

  1. Command-line flags: Override all other settings.
  2. YAML configuration file: Values specified in the config.yaml file.
  3. Default values: Predefined defaults within Evolve.

Environment variables can also be used, typically prefixed with your executable's name (e.g., YOURAPP_CHAIN_ID="my-chain").

Base Configuration

These are fundamental settings for your Evolve node.

Root Directory

Description: The root directory where Evolve stores its data, including the database and configuration files. This is a foundational setting that dictates where all other file paths are resolved from.

YAML: This option is not set within the YAML configuration file itself, as it specifies the location of the configuration file and other application data.

Command-line Flag: --home <path> Example: --home /mnt/data/evolve_node Default: ~/.evolve (or a directory derived from the application name if defaultHome is customized). Constant: FlagRootDir

Database Path

Description: The path, relative to the Root Directory, where the Evolve database will be stored. This database contains blockchain state, blocks, and other critical node data.

YAML: Set this in your configuration file at the top level:

db_path: "data"

Command-line Flag: --rollkit.db_path <path> Example: --rollkit.db_path "node_db" Default: "data" Constant: FlagDBPath

Chain ID

Description: The unique identifier for your chain. This ID is used to differentiate your network from others and is crucial for network communication and transaction validation.

YAML: Set this in your configuration file at the top level:

chain_id: "my-evolve-chain"

Command-line Flag: --chain_id <string> Example: --chain_id "super_rollup_testnet_v1" Default: "evolve" Constant: FlagChainID

Node Configuration (node)

Settings related to the core behavior of the Evolve node, including its mode of operation and block production parameters.

YAML Section:

node:
  # ... node configurations ...

Aggregator Mode

Description: If true, the node runs in aggregator mode. Aggregators are responsible for producing blocks by collecting transactions, ordering them, and proposing them to the network.

YAML:

node:
  aggregator: true

Command-line Flag: --rollkit.node.aggregator (boolean, presence enables it) Example: --rollkit.node.aggregator Default: false Constant: FlagAggregator

Light Client Mode

Description: If true, the node runs in light client mode. Light clients rely on full nodes for block headers and state information, offering a lightweight way to interact with the chain without storing all data.

YAML:

node:
  light: true

Command-line Flag: --rollkit.node.light (boolean, presence enables it) Example: --rollkit.node.light Default: false Constant: FlagLight

Block Time

Description: The target time interval between consecutive blocks produced by an aggregator. This duration (e.g., "500ms", "1s", "5s") dictates the pace of block production.

YAML:

node:
  block_time: "1s"

Command-line Flag: --rollkit.node.block_time <duration> Example: --rollkit.node.block_time 2s Default: "1s" Constant: FlagBlockTime

Maximum Pending Blocks

Description: The maximum number of blocks that can be pending Data Availability (DA) submission. When this limit is reached, the aggregator pauses block production until some blocks are confirmed on the DA layer. Use 0 for no limit. This helps manage resource usage and DA layer capacity.

YAML:

node:
  max_pending_blocks: 100

Command-line Flag: --rollkit.node.max_pending_blocks <uint64> Example: --rollkit.node.max_pending_blocks 50 Default: 0 (no limit) Constant: FlagMaxPendingBlocks

Lazy Mode (Lazy Aggregator)

Description: Enables lazy aggregation mode. In this mode, blocks are produced only when new transactions are available in the mempool or after the lazy_block_interval has passed. This optimizes resource usage by avoiding the creation of empty blocks during periods of inactivity.

YAML:

node:
  lazy_mode: true

Command-line Flag: --rollkit.node.lazy_mode (boolean, presence enables it) Example: --rollkit.node.lazy_mode Default: false Constant: FlagLazyAggregator

Lazy Block Interval

Description: The maximum time interval between blocks when running in lazy aggregation mode (lazy_mode). This ensures that blocks are produced periodically even if there are no new transactions, keeping the chain active. This value is generally larger than block_time.

YAML:

node:
  lazy_block_interval: "30s"

Command-line Flag: --rollkit.node.lazy_block_interval <duration> Example: --rollkit.node.lazy_block_interval 1m Default: "30s" Constant: FlagLazyBlockTime

Trusted Hash

Description: The initial trusted hash used to bootstrap the header exchange service. This allows nodes to start synchronizing from a specific, trusted point in the chain history instead of from the genesis block. When provided, the node will fetch the corresponding header/block from peers using this hash. If not provided, the node attempts to sync from genesis.

YAML:

node:
  trusted_hash: "YOUR_TRUSTED_HASH_HEX_STRING"

Command-line Flag: --rollkit.node.trusted_hash <string> Example: --rollkit.node.trusted_hash ABCDEF012345... Default: "" (empty, sync from genesis) Constant: FlagTrustedHash

Data Availability Configuration (da)

Parameters for connecting and interacting with the Data Availability (DA) layer, which Evolve uses to publish block data.

YAML Section:

da:
  # ... DA configurations ...

DA Service Address

Description: The network address (host:port) of the Data Availability layer service. Evolve connects to this endpoint to submit and retrieve block data.

YAML:

da:
  address: "localhost:26659"

Command-line Flag: --rollkit.da.address <string> Example: --rollkit.da.address 192.168.1.100:26659 Default: "" (empty, must be configured if DA is used) Constant: FlagDAAddress

DA Authentication Token

Description: The authentication token required to interact with the DA layer service, if the service mandates authentication.

YAML:

da:
  auth_token: "YOUR_DA_AUTH_TOKEN"

Command-line Flag: --rollkit.da.auth_token <string> Example: --rollkit.da.auth_token mysecrettoken Default: "" (empty) Constant: FlagDAAuthToken

DA Gas Price

Description: The gas price to use for transactions submitted to the DA layer. A value of -1 indicates automatic gas price determination (if supported by the DA layer). Higher values may lead to faster inclusion of data.

YAML:

da:
  gas_price: 0.025

Command-line Flag: --rollkit.da.gas_price <float64> Example: --rollkit.da.gas_price 0.05 Default: -1 (automatic) Constant: FlagDAGasPrice

DA Gas Multiplier

Description: A multiplier applied to the gas price when retrying failed DA submissions. Values greater than 1 increase the gas price on retries, potentially improving the chances of successful inclusion.

YAML:

da:
  gas_multiplier: 1.1

Command-line Flag: --rollkit.da.gas_multiplier <float64> Example: --rollkit.da.gas_multiplier 1.5 Default: 1.0 (no multiplication) Constant: FlagDAGasMultiplier

DA Submit Options

Description: Additional options passed to the DA layer when submitting data. The format and meaning of these options depend on the specific DA implementation being used.

YAML:

da:
  submit_options: "{"key":"value"}" # Example, format depends on DA layer

Command-line Flag: --rollkit.da.submit_options <string> Example: --rollkit.da.submit_options '{"custom_param":true}' Default: "" (empty) Constant: FlagDASubmitOptions

DA Namespace

Description: The namespace ID used when submitting blobs (block data) to the DA layer. This helps segregate data from different chains or applications on a shared DA layer.

YAML:

da:
  namespace: "MY_UNIQUE_NAMESPACE_ID"

Command-line Flag: --rollkit.da.namespace <string> Example: --rollkit.da.namespace 0x1234567890abcdef Default: "" (empty, must be configured) Constant: FlagDANamespace

DA Block Time

Description: The average block time of the Data Availability chain (specified as a duration string, e.g., "15s", "1m"). This value influences:

  • The frequency of DA layer syncing.
  • The maximum backoff time for retrying DA submissions.
  • Calculation of transaction expiration when multiplied by mempool_ttl.

YAML:

da:
  block_time: "6s"

Command-line Flag: --rollkit.da.block_time <duration> Example: --rollkit.da.block_time 12s Default: "6s" Constant: FlagDABlockTime

DA Start Height

Description: The block height on the DA layer from which Evolve should begin syncing. This is useful when deploying a new chain on an existing DA chain, allowing it to ignore historical data before its inception.

YAML:

da:
  start_height: 100000

Command-line Flag: --rollkit.da.start_height <uint64> Example: --rollkit.da.start_height 500000 Default: 0 (sync from the beginning) Constant: FlagDAStartHeight

DA Mempool TTL

Description: The number of DA blocks after which a transaction submitted to the DA layer is considered expired and potentially dropped from the DA layer's mempool. This also controls the retry backoff timing for DA submissions.

YAML:

da:
  mempool_ttl: 20

Command-line Flag: --rollkit.da.mempool_ttl <uint64> Example: --rollkit.da.mempool_ttl 30 Default: 20 Constant: FlagDAMempoolTTL

P2P Configuration (p2p)

Settings for peer-to-peer networking, enabling nodes to discover each other, exchange blocks, and share transactions.

YAML Section:

p2p:
  # ... P2P configurations ...

P2P Listen Address

Description: The network address (host:port) on which the Evolve node will listen for incoming P2P connections from other nodes.

YAML:

p2p:
  listen_address: "0.0.0.0:7676"

Command-line Flag: --rollkit.p2p.listen_address <string> Example: --rollkit.p2p.listen_address /ip4/127.0.0.1/tcp/26656 Default: "/ip4/0.0.0.0/tcp/7676" Constant: FlagP2PListenAddress

P2P Peers

Description: A comma-separated list of peer addresses (e.g., multiaddresses) that the node will attempt to connect to for bootstrapping its P2P connections. These are often referred to as seed nodes.

For DA-only sync mode: Leave this field empty (default) to disable P2P networking entirely. When no peers are configured, the node will sync exclusively from the Data Availability layer without participating in P2P gossip, peer discovery, or block sharing. This is useful for nodes that only need to follow the canonical chain data from DA.

YAML:

p2p:
  peers: "/ip4/some_peer_ip/tcp/7676/p2p/PEER_ID1,/ip4/another_peer_ip/tcp/7676/p2p/PEER_ID2"
  # For DA-only sync, leave peers empty:
  # peers: ""

Command-line Flag: --rollkit.p2p.peers <string> Example: --rollkit.p2p.peers /dns4/seed.example.com/tcp/26656/p2p/12D3KooW... Default: "" (empty - enables DA-only sync mode) Constant: FlagP2PPeers

P2P Blocked Peers

Description: A comma-separated list of peer IDs that the node should block from connecting. This can be used to prevent connections from known malicious or problematic peers.

YAML:

p2p:
  blocked_peers: "PEER_ID_TO_BLOCK1,PEER_ID_TO_BLOCK2"

Command-line Flag: --rollkit.p2p.blocked_peers <string> Example: --rollkit.p2p.blocked_peers 12D3KooW...,12D3KooX... Default: "" (empty) Constant: FlagP2PBlockedPeers

P2P Allowed Peers

Description: A comma-separated list of peer IDs that the node should exclusively allow connections from. If this list is non-empty, only peers in this list will be able to connect.

YAML:

p2p:
  allowed_peers: "PEER_ID_TO_ALLOW1,PEER_ID_TO_ALLOW2"

Command-line Flag: --rollkit.p2p.allowed_peers <string> Example: --rollkit.p2p.allowed_peers 12D3KooY...,12D3KooZ... Default: "" (empty, allow all unless blocked) Constant: FlagP2PAllowedPeers

RPC Configuration (rpc)

Settings for the Remote Procedure Call (RPC) server, which allows clients and applications to interact with the Evolve node.

YAML Section:

rpc:
  # ... RPC configurations ...

RPC Server Address

Description: The network address (host:port) to which the RPC server will bind and listen for incoming requests.

YAML:

rpc:
  address: "127.0.0.1:7331"

Command-line Flag: --rollkit.rpc.address <string> Example: --rollkit.rpc.address 0.0.0.0:26657 Default: "127.0.0.1:7331" Constant: FlagRPCAddress

Instrumentation Configuration (instrumentation)

Settings for enabling and configuring metrics and profiling endpoints, useful for monitoring node performance and debugging.

YAML Section:

instrumentation:
  # ... instrumentation configurations ...

Enable Prometheus Metrics

Description: If true, enables the Prometheus metrics endpoint, allowing Prometheus to scrape operational data from the Evolve node.

YAML:

instrumentation:
  prometheus: true

Command-line Flag: --rollkit.instrumentation.prometheus (boolean, presence enables it) Example: --rollkit.instrumentation.prometheus Default: false Constant: FlagPrometheus

Prometheus Listen Address

Description: The network address (host:port) where the Prometheus metrics server will listen for scraping requests.

See Metrics for more details on what metrics are exposed.

YAML:

instrumentation:
  prometheus_listen_addr: ":2112"

Command-line Flag: --rollkit.instrumentation.prometheus_listen_addr <string> Example: --rollkit.instrumentation.prometheus_listen_addr 0.0.0.0:9090 Default: ":2112" Constant: FlagPrometheusListenAddr

Maximum Open Connections

Description: The maximum number of simultaneous connections allowed for the metrics server (e.g., Prometheus endpoint).

YAML:

instrumentation:
  max_open_connections: 100

Command-line Flag: --rollkit.instrumentation.max_open_connections <int> Example: --rollkit.instrumentation.max_open_connections 50 Default: (Refer to DefaultInstrumentationConfig() in code, typically a reasonable number like 100) Constant: FlagMaxOpenConnections

Enable Pprof Profiling

Description: If true, enables the pprof HTTP endpoint, which provides runtime profiling data for debugging performance issues. Accessing these endpoints can help diagnose CPU and memory usage.

YAML:

instrumentation:
  pprof: true

Command-line Flag: --rollkit.instrumentation.pprof (boolean, presence enables it) Example: --rollkit.instrumentation.pprof Default: false Constant: FlagPprof

Pprof Listen Address

Description: The network address (host:port) where the pprof HTTP server will listen for profiling requests.

YAML:

instrumentation:
  pprof_listen_addr: "localhost:6060"

Command-line Flag: --rollkit.instrumentation.pprof_listen_addr <string> Example: --rollkit.instrumentation.pprof_listen_addr 0.0.0.0:6061 Default: "localhost:6060" Constant: FlagPprofListenAddr

Logging Configuration (log)

Settings that control the verbosity and format of log output from the Evolve node. These are typically set via global flags.

YAML Section:

log:
  # ... logging configurations ...

Log Level

Description: Sets the minimum severity level for log messages to be displayed. Common levels include debug, info, warn, error.

YAML:

log:
  level: "info"

Command-line Flag: --log.level <string> (Note: some applications might use a different flag name like --log_level) Example: --log.level debug Default: "info" Constant: FlagLogLevel (value: "evolve.log.level", but often overridden by global app flags)

Log Format

Description: Sets the format for log output. Common formats include text (human-readable) and json (structured, machine-readable).

YAML:

log:
  format: "text"

Command-line Flag: --log.format <string> (Note: some applications might use a different flag name like --log_format) Example: --log.format json Default: "text" Constant: FlagLogFormat (value: "evolve.log.format", but often overridden by global app flags)

Log Trace (Stack Traces)

Description: If true, enables the inclusion of stack traces in error logs. This can be very helpful for debugging issues by showing the call stack at the point of an error.

YAML:

log:
  trace: false

Command-line Flag: --log.trace (boolean, presence enables it; Note: some applications might use a different flag name like --log_trace) Example: --log.trace Default: false Constant: FlagLogTrace (value: "evolve.log.trace", but often overridden by global app flags)

Signer Configuration (signer)

Settings related to the signing mechanism used by the node, particularly for aggregators that need to sign blocks.

YAML Section:

signer:
  # ... signer configurations ...

Signer Type

Description: Specifies the type of remote signer to use. Common options might include file (for key files) or grpc (for connecting to a remote signing service).

YAML:

signer:
  signer_type: "file"

Command-line Flag: --rollkit.signer.type <string> Example: --rollkit.signer.type grpc Default: (Depends on application, often "file" or none if not an aggregator) Constant: FlagSignerType

Signer Path

Description: The path to the signer file (if signer_type is file) or the address of the remote signer service (if signer_type is grpc or similar).

YAML:

signer:
  signer_path: "/path/to/priv_validator_key.json" # For file signer
  # signer_path: "localhost:9000" # For gRPC signer

Command-line Flag: --rollkit.signer.path <string> Example: --rollkit.signer.path ./keys/mykey.pem Default: (Depends on application) Constant: FlagSignerPath

Signer Passphrase

Description: The passphrase required to decrypt or access the signer key, particularly if using a file signer and the key is encrypted, or if the aggregator mode is enabled and requires it. This flag is not directly a field in the SignerConfig struct but is used in conjunction with it.

YAML: This is typically not stored in the YAML file for security reasons but provided via flag or environment variable.

Command-line Flag: --rollkit.signer.passphrase <string> Example: --rollkit.signer.passphrase "mysecretpassphrase" Default: "" (empty) Constant: FlagSignerPassphrase Note: Be cautious with providing passphrases directly on the command line in shared environments due to history logging. Environment variables or secure input methods are often preferred.

This reference should help you configure your Evolve node effectively. Always refer to the specific version of Evolve you are using, as options and defaults may change over time.