Configuration Reference

Complete reference for all Prism configuration options.

Configuration File

Prism uses TOML configuration files. The configuration file location can be specified via the PRISM_CONFIG environment variable.

# Use custom config file
export PRISM_CONFIG=/path/to/config.toml
cargo make run-server

If PRISM_CONFIG is not set, Prism looks for config/config.toml in the current directory.

Configuration Loading Priority

TOML file values (from PRISM_CONFIG or default path)
Environment variables with PRISM__ prefix (override TOML values)
Built-in defaults (used if not specified)

Environment Variable Overrides

Use PRISM__ prefix with __ as separator for nested fields:

# Override server port
export PRISM__SERVER__BIND_PORT=8080

# Override cache settings
export PRISM__CACHE__ENABLED=true
export PRISM__CACHE__CACHE_TTL_SECONDS=600

# Override logging
export PRISM__LOGGING__LEVEL=debug

Server Configuration

HTTP server settings for binding address, port, and request handling.

Configuration Block

[server]
bind_address = "127.0.0.1"
bind_port = 3030
max_concurrent_requests = 100
request_timeout_seconds = 30

Options

Option

Type

Default

Description

bind_address

string

"127.0.0.1"

IP address to bind the server. Use "0.0.0.0" to listen on all interfaces

bind_port

integer

3030

Port number for the HTTP server. Must be > 0

max_concurrent_requests

integer

100

Maximum number of concurrent RPC requests. Limits memory and prevents overload

request_timeout_seconds

integer

30

Global request timeout in seconds. Requests exceeding this are cancelled

Examples

Public Server (listen on all interfaces):

[server]
bind_address = "0.0.0.0"  # WARNING: Ensure firewall is configured!
bind_port = 80
max_concurrent_requests = 1000

High-Throughput Configuration:

[server]
bind_address = "127.0.0.1"
bind_port = 3030
max_concurrent_requests = 2000  # Handle more concurrent requests
request_timeout_seconds = 60    # Longer timeout for complex queries

Development Configuration:

[server]
bind_address = "127.0.0.1"
bind_port = 3030
max_concurrent_requests = 50
request_timeout_seconds = 15

Upstream Providers

Configuration for upstream Ethereum RPC providers.

Configuration Block

[upstreams]
[[upstreams.providers]]
name = "provider-name"
chain_id = 1
https_url = "https://eth-mainnet.provider.com"
wss_url = "wss://eth-mainnet.provider.com"  # Optional
weight = 1
timeout_seconds = 30
circuit_breaker_threshold = 2
circuit_breaker_timeout_seconds = 1

Options

Option

Type

Required

Default

Description

name

string

Yes

Human-readable identifier for metrics and logs

chain_id

integer

Yes

Ethereum chain ID (1 for mainnet, 11155111 for Sepolia, etc.)

https_url

string

Yes

HTTP(S) endpoint URL for JSON-RPC requests

wss_url

string

WebSocket URL for subscriptions (e.g., newHeads)

weight

integer

1

Load balancing weight. Higher weight = more traffic

timeout_seconds

integer

30

Request timeout for this provider

circuit_breaker_threshold

integer

2

Consecutive failures before circuit opens

circuit_breaker_timeout_seconds

integer

1

Seconds to wait before retrying after circuit opens

Multiple Providers Example

[upstreams]
# Primary provider - higher weight
[[upstreams.providers]]
name = "alchemy-mainnet"
chain_id = 1
https_url = "https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY"
wss_url = "wss://eth-mainnet.g.alchemy.com/v2/YOUR_KEY"
weight = 3
timeout_seconds = 30
circuit_breaker_threshold = 5
circuit_breaker_timeout_seconds = 60

# Backup provider
[[upstreams.providers]]
name = "infura-mainnet"
chain_id = 1
https_url = "https://mainnet.infura.io/v3/YOUR_PROJECT_ID"
wss_url = "wss://mainnet.infura.io/ws/v3/YOUR_PROJECT_ID"
weight = 2
timeout_seconds = 30
circuit_breaker_threshold = 3
circuit_breaker_timeout_seconds = 30

# Fallback public endpoint
[[upstreams.providers]]
name = "publicnode"
chain_id = 1
https_url = "https://ethereum-rpc.publicnode.com"
wss_url = "wss://ethereum-rpc.publicnode.com"
weight = 1
timeout_seconds = 45  # Slower public endpoint
circuit_breaker_threshold = 2
circuit_breaker_timeout_seconds = 10

Provider Selection Behavior

Weight: Determines relative traffic distribution. Provider with weight 3 receives ~3x traffic of weight 1 provider
Circuit Breaker: Automatically isolates failing providers to prevent cascade failures
WebSocket: Required for real-time chain tip updates and reorg detection

Cache Configuration

Advanced caching system with multi-layer architecture.

Basic Cache Settings

[cache]
enabled = true
cache_ttl_seconds = 300

Option

Type

Default

Description

enabled

boolean

true

Master switch for caching. Set to false to disable all caching

cache_ttl_seconds

integer

300

Default TTL for cache entries (currently not actively used)

Cache Manager Configuration

[cache.manager_config]
retain_blocks = 1000
enable_auto_cleanup = true
cleanup_interval_seconds = 300

Option

Type

Default

Description

retain_blocks

integer

1000

Number of recent blocks to retain in cache

enable_auto_cleanup

boolean

true

Enable automatic background cleanup of old cache entries

cleanup_interval_seconds

integer

300

Interval for background cleanup tasks (5 minutes)

Log Cache Configuration

Event log caching with partial-range support.

[cache.manager_config.log_cache]
chunk_size = 1000
max_exact_results = 10000
max_bitmap_entries = 100000
safety_depth = 12

Option

Type

Default

Description

chunk_size

integer

1000

Number of blocks per chunk for log storage

max_exact_results

integer

10000

Maximum number of individual log records to cache

max_bitmap_entries

integer

100000

Maximum bitmap entries for efficient range tracking

safety_depth

integer

12

Blocks from tip to consider "safe" (reorg protection)

Memory Impact:

max_exact_results = 10000 ≈ 30-60MB (depending on log size)
max_bitmap_entries = 100000 ≈ 10-20MB

Block Cache Configuration

Block header and body caching with hot window optimization.

[cache.manager_config.block_cache]
hot_window_size = 200
max_headers = 10000
max_bodies = 10000
safety_depth = 12

Option

Type

Default

Description

hot_window_size

integer

200

Number of recent blocks kept in O(1) hot window

max_headers

integer

10000

Maximum block headers to cache

max_bodies

integer

10000

Maximum block bodies to cache

safety_depth

integer

12

Blocks from tip to consider "safe"

Memory Impact:

max_headers = 10000 ≈ 5-10MB
max_bodies = 10000 ≈ 10-30MB (varies with transaction count)
hot_window_size = 200 ≈ 1-2MB

Transaction Cache Configuration

Transaction and receipt caching.

[cache.manager_config.transaction_cache]
max_transactions = 50000
max_receipts = 50000
safety_depth = 12

Option

Type

Default

Description

max_transactions

integer

50000

Maximum transactions to cache

max_receipts

integer

50000

Maximum receipts to cache

safety_depth

integer

12

Blocks from tip to consider "safe"

Memory Impact:

max_transactions = 50000 ≈ 20-40MB
max_receipts = 50000 ≈ 30-50MB

Reorg Manager Configuration

Chain reorganization detection and cache invalidation.

[cache.manager_config.reorg_manager]
safety_depth = 12
max_reorg_depth = 100
coalesce_window_ms = 100

Option

Type

Default

Description

safety_depth

integer

12

Blocks from tip considered safe from reorgs (~2.5 minutes on mainnet)

max_reorg_depth

integer

100

Maximum depth to search for divergence point during reorg

coalesce_window_ms

integer

100

Milliseconds to batch reorg events (prevents cache thrashing)

Cache Tuning Examples

Low Memory Configuration (< 1GB):

[cache.manager_config]
retain_blocks = 500

[cache.manager_config.log_cache]
max_exact_results = 5000
max_bitmap_entries = 50000

[cache.manager_config.block_cache]
hot_window_size = 100
max_headers = 5000
max_bodies = 5000

[cache.manager_config.transaction_cache]
max_transactions = 10000
max_receipts = 10000

High Memory Configuration (8GB+):

[cache.manager_config]
retain_blocks = 5000

[cache.manager_config.log_cache]
max_exact_results = 100000
max_bitmap_entries = 500000

[cache.manager_config.block_cache]
hot_window_size = 500
max_headers = 50000
max_bodies = 50000

[cache.manager_config.transaction_cache]
max_transactions = 200000
max_receipts = 200000

DeFi Application (high eth_getLogs traffic):

[cache.manager_config]
retain_blocks = 2000

[cache.manager_config.log_cache]
chunk_size = 1000
max_exact_results = 50000   # More log storage
max_bitmap_entries = 200000 # Better range tracking

[cache.manager_config.block_cache]
hot_window_size = 300
max_headers = 20000
max_bodies = 5000  # Don't need many full blocks

[cache.manager_config.transaction_cache]
max_transactions = 100000
max_receipts = 100000

Authentication Configuration

API key authentication and quota management.

Configuration Block

[auth]
enabled = true
database_url = "sqlite://db/auth.db"

Option

Type

Default

Description

enabled

boolean

false

Enable API key authentication

database_url

string

"sqlite://./db/auth.db"

SQLite database URL for API keys

Creating API Keys

Use the CLI to manage API keys:

# Create a new key
cargo run --bin cli -- auth create \
  --name "production-api" \
  --description "Main production service" \
  --rate-limit 100 \
  --refill-rate 10 \
  --daily-limit 100000 \
  --expires-in-days 365 \
  --methods "eth_getLogs,eth_getBlockByNumber"

# List all keys
cargo run --bin cli -- auth list

# Revoke a key
cargo run --bin cli -- auth revoke --name "production-api"

Using API Keys

Include the API key in requests:

Header (recommended):

curl -X POST http://localhost:3030/ \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

Query parameter:

curl -X POST "http://localhost:3030/?api_key=your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

Metrics and Logging

Observability configuration for Prometheus metrics and structured logging.

Metrics Configuration

[metrics]
enabled = true
prometheus_port = 9090

Option

Type

Default

Description

enabled

boolean

true

Enable Prometheus metrics collection

prometheus_port

integer

9090

Port for /metrics endpoint (optional)

Access metrics at: http://localhost:3030/metrics

Logging Configuration

[logging]
level = "info"
format = "pretty"

Option

Type

Default

Description

level

string

"info"

Log level: trace, debug, info, warn, error

format

string

"pretty"

Output format: pretty (human-readable) or json (structured)

Logging Examples

Production (JSON logs for aggregation):

[logging]
level = "info"
format = "json"

Development (readable logs):

[logging]
level = "debug"
format = "pretty"

Troubleshooting (verbose):

[logging]
level = "trace"
format = "pretty"

Health Check Configuration

[health_check]
interval_seconds = 60

Option

Type

Default

Description

interval_seconds

integer

60

Interval between upstream health checks (using eth_blockNumber)

Advanced Features

Advanced routing and optimization features.

Consensus Validation

Multi-upstream validation for critical methods.

[consensus]
enabled = true
max_count = 3
min_count = 2
timeout_seconds = 10
dispute_behavior = "PreferBlockHeadLeader"
methods = ["eth_getBlockByNumber", "eth_getBlockByHash", "eth_getLogs"]

Option

Type

Default

Description

enabled

boolean

false

Enable consensus validation

max_count

integer

3

Maximum upstreams to query

min_count

integer

2

Minimum upstreams for consensus

timeout_seconds

integer

10

Timeout for consensus requests

dispute_behavior

string

"PreferBlockHeadLeader"

How to resolve disputes

methods

array

[eth_getBlockByNumber, ...]

Methods requiring consensus

See Routing Strategies for details.

Hedging (Tail Latency Reduction)

Parallel request execution to reduce P99 latency.

[hedging]
enabled = true
latency_quantile = 0.95
min_delay_ms = 50
max_delay_ms = 2000
max_parallel = 2

Option

Type

Default

Description

enabled

boolean

false

Enable request hedging

latency_quantile

float

0.95

Latency percentile for hedge trigger

min_delay_ms

integer

50

Minimum delay before hedging

max_delay_ms

integer

2000

Maximum delay before hedging

max_parallel

integer

2

Maximum parallel requests

See Routing Strategies for details.

Scoring Engine

Multi-factor upstream ranking and selection.

[scoring]
enabled = true
window_seconds = 1800
min_samples = 10
max_block_lag = 5
top_n = 3

[scoring.weights]
latency = 8.0
error_rate = 4.0
throttle_rate = 3.0
block_head_lag = 2.0
total_requests = 1.0

Option

Type

Default

Description

enabled

boolean

false

Enable scoring-based selection

window_seconds

integer

1800

Metric collection window (30 min)

min_samples

integer

10

Minimum samples before scoring

max_block_lag

integer

5

Max block lag before penalty

top_n

integer

3

Top upstreams for selection

weights.latency

float

8.0

Latency factor weight

weights.error_rate

float

4.0

Error rate factor weight

weights.throttle_rate

float

3.0

Throttle factor weight

weights.block_head_lag

float

2.0

Block lag factor weight

weights.total_requests

float

1.0

Request count factor weight

See Routing Strategies for details.

Example Configurations

Development

environment = "development"

[server]
bind_address = "127.0.0.1"
bind_port = 3030
max_concurrent_requests = 50

[[upstreams.providers]]
name = "local-geth"
chain_id = 1337
https_url = "http://localhost:8545"
weight = 1

[cache]
enabled = true

[auth]
enabled = false

[logging]
level = "debug"
format = "pretty"

Production

environment = "production"

[server]
bind_address = "0.0.0.0"
bind_port = 3030
max_concurrent_requests = 1000
request_timeout_seconds = 60

[[upstreams.providers]]
name = "alchemy-primary"
chain_id = 1
https_url = "https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY"
wss_url = "wss://eth-mainnet.g.alchemy.com/v2/YOUR_KEY"
weight = 3
circuit_breaker_threshold = 5

[[upstreams.providers]]
name = "infura-backup"
chain_id = 1
https_url = "https://mainnet.infura.io/v3/YOUR_ID"
wss_url = "wss://mainnet.infura.io/ws/v3/YOUR_ID"
weight = 2
circuit_breaker_threshold = 3

[cache]
enabled = true

[cache.manager_config]
retain_blocks = 2000

[cache.manager_config.log_cache]
max_exact_results = 50000
max_bitmap_entries = 200000

[cache.manager_config.block_cache]
hot_window_size = 300
max_headers = 20000
max_bodies = 20000

[auth]
enabled = true
database_url = "sqlite://db/auth.db"

[metrics]
enabled = true

[logging]
level = "info"
format = "json"

[health_check]
interval_seconds = 30

High-Performance DeFi

environment = "production"

[server]
bind_address = "0.0.0.0"
bind_port = 3030
max_concurrent_requests = 2000

[[upstreams.providers]]
name = "alchemy-1"
chain_id = 1
https_url = "https://eth-mainnet.g.alchemy.com/v2/KEY1"
wss_url = "wss://eth-mainnet.g.alchemy.com/v2/KEY1"
weight = 2

[[upstreams.providers]]
name = "alchemy-2"
chain_id = 1
https_url = "https://eth-mainnet.g.alchemy.com/v2/KEY2"
wss_url = "wss://eth-mainnet.g.alchemy.com/v2/KEY2"
weight = 2

[[upstreams.providers]]
name = "quicknode"
chain_id = 1
https_url = "https://your-endpoint.quiknode.pro/YOUR_KEY"
wss_url = "wss://your-endpoint.quiknode.pro/YOUR_KEY"
weight = 1

[cache]
enabled = true

[cache.manager_config]
retain_blocks = 5000

[cache.manager_config.log_cache]
chunk_size = 1000
max_exact_results = 100000
max_bitmap_entries = 500000

[cache.manager_config.block_cache]
hot_window_size = 500
max_headers = 50000
max_bodies = 10000  # DeFi apps don't need many full blocks

[cache.manager_config.transaction_cache]
max_transactions = 200000
max_receipts = 200000

[scoring]
enabled = true
window_size = 200

[hedging]
enabled = true
initial_timeout_ms = 50
max_hedge_requests = 2

[auth]
enabled = true

[logging]
level = "info"
format = "json"

Configuration Validation

Always validate configuration before deploying:

# Validate config file
cargo make cli-config-validate

# Show resolved configuration (with environment overrides)
cargo make cli-config-show

# Test upstream connectivity
cargo make cli-test-upstreams

Environment-Specific Configs

Organize configs by environment:

config/
├── config.toml          # Default config
├── development.toml     # Development settings
├── staging.toml         # Staging environment
└── production.toml      # Production settings

Load specific config:

export PRISM_CONFIG=config/production.toml
cargo make run-server-release

Next: Learn about the Caching System or explore the API Reference.

PreviousGetting Started with Prism NextCLI Reference

Last updated 7 hours ago

Good afternoon

Table of Contents

Configuration File

Configuration Loading Priority

Environment Variable Overrides

Server Configuration

Configuration Block

Options

Examples

Upstream Providers

Configuration Block

Options

Multiple Providers Example

Provider Selection Behavior

Cache Configuration

Basic Cache Settings

Cache Manager Configuration

Log Cache Configuration

Block Cache Configuration

Transaction Cache Configuration

Reorg Manager Configuration

Cache Tuning Examples

Authentication Configuration

Configuration Block

Creating API Keys

Using API Keys

Metrics and Logging

Metrics Configuration

Logging Configuration

Logging Examples

Health Check Configuration

Advanced Features

Consensus Validation

Hedging (Tail Latency Reduction)

Scoring Engine

Example Configurations

Development

Production

High-Performance DeFi

Configuration Validation

Environment-Specific Configs