Schema

This is an example configuration file for dolos:

[upstream]
peer_address = "preprod-node.world.dev.cardano.org:30000"

# Emulator mode (omit peer_* fields when using this)
# block_production_interval = 5

[storage]
version = "v3"
path = "data"

[genesis]
byron_path = "byron.json"
shelley_path = "shelley.json"
alonzo_path = "alonzo.json"
conway_path = "conway.json"
force_protocol = 2

[chain]
type = "cardano"
magic = 1
is_testnet = true
stop_epoch = 400

[[chain.custom_utxos]]
ref = ["8d910e3a410a353787d50a708e24c6ba2cc2b6b86ec6d8cb5bf9bbec20bfc937", 0]
era = 7
cbor = [162, 0, 88, 29]

[sync]
max_history = 10000
max_rollback = 10000

[submit]
prune_height = 200

[serve.grpc]
listen_address = "[::]:50051"

[serve.minibf]
listen_address = "[::]:3000"

[serve.ouroboros]
listen_path = "dolos.socket"

[serve.minikupo]
listen_address = "[::]:1442"

[serve.trp]
listen_address = "[::]:8164"

[relay]
listen_address = "[::]:30031"

[retries]
max_retries = 6
backoff_unit_sec = 1
backoff_factor = 2
max_backoff_sec = 60
dismissible = false

[mithril]
aggregator = "https://aggregator.release-preprod.api.mithril.network/aggregator"
genesis_key = "5b3...45d" # redacted

[snapshot]
download_url = "https://example.com/snapshot.tar.zst"

Each section of the toml controls a different aspect of Dolos’ processes. The rest of this document describes in detail each of these sections.

upstream section

The upstream section defines how to connect to the Ouroboros network to synchronize the chain and submit transactions. It can point to a peer node or use the built-in emulator.

Peer mode

property	type	example
peer_address	string	”preprod-node.world.dev.cardano.org:30000”

• peer_address: network address of peer node using {host}:{port} syntax.

Emulator mode

property	type	example
block_production_interval	integer	5

• block_production_interval: seconds between blocks produced by the emulator.

storage section

The storage section controls how Dolos stores data in the local file system. Each store (wal, state, archive, index, mempool) can be configured independently with its own backend and options.

property	type	example
path	string	”data”
version	string	”v3”

• path: root directory where all data will be stored.
• version: storage schema version (v0 - v3).

storage.wal section

property	type	example
backend	string	”redb”
path	string	”wal”
cache	integer	50

• backend: redb or in_memory (defaults to redb).
• path: optional override for the WAL path (defaults to <storage.path>/wal).
• cache: size (MB) of the WAL cache (Redb only).

storage.state section

property	type	example
backend	string	”fjall”
path	string	”state”
cache	integer	500
max_history	integer	10000
max_journal_size	integer	1024
flush_on_commit	boolean	false
l0_threshold	integer	4
worker_threads	integer	4
memtable_size_mb	integer	64

• backend: redb, fjall, or in_memory (defaults to fjall).
• path: optional override for the state path (defaults to <storage.path>/state).
• cache: size (MB) of the state cache (Redb/Fjall only).
• max_history: maximum number of slots to keep before pruning (Redb/Fjall only).
• max_journal_size, flush_on_commit, l0_threshold, worker_threads, memtable_size_mb: Fjall tuning options.

storage.archive section

property	type	example
backend	string	”redb”
path	string	”archive”
blocks_path	string	”blocks”
cache	integer	500

• backend: redb, in_memory, or no_op (defaults to redb).
• path: optional override for the archive path (defaults to <storage.path>/archive).
• blocks_path: optional override for block segment files (Redb only).
• cache: size (MB) of the archive cache (Redb only).

storage.index section

property	type	example
backend	string	”fjall”
path	string	”index”
cache	integer	500
max_journal_size	integer	1024
flush_on_commit	boolean	false
l0_threshold	integer	8
worker_threads	integer	8
memtable_size_mb	integer	128

• backend: redb, fjall, in_memory, or no_op (defaults to fjall).
• path: optional override for the index path (defaults to <storage.path>/index).
• cache: size (MB) of the index cache (Redb/Fjall only).
• max_journal_size, flush_on_commit, l0_threshold, worker_threads, memtable_size_mb: Fjall tuning options.

storage.mempool section

property	type	example
backend	string	”in_memory”
path	string	”mempool”
cache	integer	50

• backend: redb or in_memory (defaults to in_memory).
• path: optional override for the mempool path (defaults to <storage.path>/mempool).
• cache: size (MB) of the mempool cache (Redb only).

genesis section

Dolos requires Cardano genesis data to operate. For simplicity sake, we’ve decided to follow the schema for the existing .json files used by the Haskell node. The genesis section indicates how to locate the different json files with genesis data for each required era. The content of the json files should match the ones used in the Haskell node.

property	type	example
byron_path	string	”./byron.json”
shelley_path	string	”./shelley.json”
alonzo_path	string	”./alonzo.json”
conway_path	string	”./conway.json”
force_protocol	integer	2

• byron_path: file path to the Byron json genesis file
• shelley_path: file path to the Shelley json genesis file
• alonzo_path: file path to the Alonzo json genesis file
• conway_path: file path to the Conway json genesis file
• force_protocol: (optional) the protocol version to force the node to start from. This is useful for networks such as preview which skips the Byron era.

chain section

The chain section specifies the type of blockchain to connect to.

property	type	example
type	string	”cardano”
magic	integer	1
is_testnet	boolean	true
stop_epoch	integer	400

• type: the type of chain network.
• magic: Cardano network magic used across upstream sync, relay, and Ouroboros services.
• is_testnet: whether the configured chain is testnet.
• stop_epoch: optional epoch number to stop syncing at.

chain.custom_utxos section

Custom UTxOs can be injected at startup (useful for testing). Each entry is an object inside an array.

property	type	example
ref	array	[”…”, 0]
era	integer	7
cbor	array	[162, 0, 88, 29]

• ref: transaction hash and output index tuple.
• era: optional era number for the CBOR payload.
• cbor: CBOR bytes for the UTxO output.

If custom_utxos is omitted, it defaults to an empty list.

sync section

The sync section controls how Dolos synchronizes the chain from upstream peers. This involves fetching a batch of blocks from the upstream node and updating the corresponding local storage.

property	type	example
pull_batch_size	integer	100 (default)
max_history	integer	10000
max_rollback	integer	10000
sync_limit	string	”NoLimit” (default)

• pull_batch_size: the number of blocks that are fetched per batch (defaults to 100).
• max_history: maximum number of slots to keep in archive history before housekeeping prunes old data.
• max_rollback: maximum number of slots to keep in WAL history before housekeeping prunes old entries.
• sync_limit: one of "NoLimit", "UntilTip", or { MaxBlocks = <number> } (defaults to "NoLimit").

submit section

The submit section controls how Dolos submits transactions to the network. This involves maintaining a mempool of txs and sharing them with the upstream node.

property	type	example
prune_height	integer	60

• prune_height: the number of stacked blocks since the tx to be considered safe for pruning.

serve.grpc section

The serve.grpc section controls the options for the gRPC endpoint that can be used by clients.

property	type	example
listen_address	string	”[::]:50051”
tls_client_ca_root	string	”./ca.pem”
permissive_cors	boolean	true (default)
http2_adaptive_window	boolean	true (default)
http2_initial_stream_window_size	integer	8388608
http2_initial_connection_window_size	integer	16777216
http2_max_frame_size	integer	16384
http2_max_concurrent_streams	integer	256

• listen_address: the local address (IP:PORT) to listen for incoming gRPC connections ([::] represents any IP address).
• tls_client_ca_root: optional path to a CA root file for client TLS authentication.
• permissive_cors: allow cross-origin requests from any origin (defaults to true).
• http2_adaptive_window: enable hyper’s adaptive (BDP-based) HTTP/2 flow-control windowing, auto-sizing the stream/connection windows to the link instead of pinning them at the 64 KiB default. Defaults to true. When enabled, http2_initial_stream_window_size and http2_initial_connection_window_size are ignored (the two modes are mutually exclusive in hyper).
• http2_initial_stream_window_size: explicit initial stream-level flow-control window in bytes. Only takes effect when http2_adaptive_window is set to false.
• http2_initial_connection_window_size: explicit initial connection-level flow-control window in bytes. Only takes effect when http2_adaptive_window is set to false.
• http2_max_frame_size: maximum HTTP/2 frame size in bytes.
• http2_max_concurrent_streams: maximum number of concurrent HTTP/2 streams per connection.

Note: HTTP/2 flow control is hop-by-hop and the receiver advertises the window that gates the sender. For server-streaming RPCs dolos is the sender, so these server-side windows govern downloads only when a client connects to dolos directly; behind a proxy the proxy’s advertised window applies instead.

serve.minibf section

The serve.minibf section controls the options for the HTTP endpoint that hosts a Blockfrost-like endpoint.

property	type	example
listen_address	string	”[::]:3000”
permissive_cors	boolean	true (default)
token_registry_url	string	”https://token-registry.io”
url	string	”https://minibf.local”
max_scan_items	integer	3000

• listen_address: the local address (IP:PORT) to listen for incoming connections ([::] represents any IP address).
• permissive_cors: allow cross-origin requests from any origin (defaults to true).
• token_registry_url: optional token registry base URL used for off-chain asset metadata.
• url: optional public URL used in the / root response.
• max_scan_items: caps page-based scans for heavy endpoints (defaults to 3000 if unset).

serve.minikupo section

The serve.minikupo section controls the options for the HTTP endpoint that hosts a Kupo-like endpoint.

property	type	example
listen_address	string	”[::]:1442”
permissive_cors	boolean	true (default)

• listen_address: the local address (IP:PORT) to listen for incoming connections ([::] represents any IP address).
• permissive_cors: allow cross-origin requests from any origin (defaults to true).

serve.trp section

The serve.trp section controls the options for the Transaction Resolver Protocol endpoint.

property	type	example
listen_address	string	”[::]:8164”
max_optimize_rounds	integer	10 (default)
permissive_cors	boolean	true (default)
extra_fees	integer	200000

• listen_address: the local address (IP:PORT) to listen for incoming TRP connections.
• max_optimize_rounds: maximum optimization rounds for transactions (defaults to 10).
• permissive_cors: allow cross-origin requests from any origin (defaults to true).
• extra_fees: optional extra fees (lovelace) to add during optimization.

serve.ouroboros section

The serve.ouroboros section controls the options for the Ouroboros mini-protocols endpoint that can be used by clients.

property	type	example
listen_path	string	”dolos.socket”

• listen_path: the file path for the unix socket that will listen for Ouroboros node-to-client mini-protocols.

relay section

The relay section controls the options for handling inbound connection from other peers through Ouroboros node-to-node miniprotocols.

property	type	example
listen_address	string	”[::]:50051”

• listen_address: the local address (IP:PORT) to listen for incoming Ouroboros connections ([::] represents any IP address).

retries section

The retries section controls backoff behavior for transient failures.

property	type	example
max_retries	integer	6
backoff_unit_sec	integer	1
backoff_factor	integer	2
max_backoff_sec	integer	60
dismissible	boolean	false

• max_retries: maximum retry attempts before giving up.
• backoff_unit_sec: base backoff unit in seconds.
• backoff_factor: multiplier applied to the backoff unit.
• max_backoff_sec: maximum backoff delay in seconds.
• dismissible: allow skipping further retries for specific errors.

mithril section

The mithril section controls the configuration for Mithril bootstrap.

property	type	example
aggregator	string	”https://aggregator.release-preprod.api.mithril.network/aggregator”
genesis_key	string	”5b3…45d”
ancillary_key	string	”…”

• aggregator: Mithril aggregator URL.
• genesis_key: Mithril genesis verification key.
• ancillary_key: optional ancillary verification key.

snapshot section

The snapshot section controls bootstrap from a snapshot archive.

property	type	example
download_url	string	”https://example.com/snapshot.tar.zst”

• download_url: URL of the snapshot archive to download.

logging section

The logging section controls the logging options to define the level of details to output.

property	type	default
max_level	string	”info”
include_tokio	boolean	false
include_pallas	boolean	false
include_grpc	boolean	false
include_trp	boolean	false
include_minibf	boolean	false
include_minikupo	boolean	false
include_otlp	boolean	false
include_fjall	boolean	false

• max_level: log level (debug, info, warn, error).
• include_tokio: include logs from Tokio.
• include_pallas: include logs from Pallas.
• include_grpc: include logs from the gRPC server.
• include_trp: include logs from the TRP server.
• include_minibf: include logs from the MiniBF server.
• include_minikupo: include logs from the MiniKupo server.
• include_otlp: include logs from OpenTelemetry exporters.
• include_fjall: include logs from Fjall storage.

All logging fields are optional in TOML; omitted values use these defaults.

telemetry section

The telemetry section controls OpenTelemetry trace export for mempool transaction lifecycle tracking. When enabled, Dolos sends per-transaction traces to an OTLP-compatible collector (e.g. Jaeger, Grafana Tempo). See the tracing guide for a full walkthrough.

property	type	default	description
enabled	boolean	false	Enable OpenTelemetry trace export
otlp_endpoint	string	"http://localhost:4317"	gRPC endpoint of the OTLP collector
service_name	string	"dolos"	Service name reported in exported traces

All telemetry fields are optional in TOML; omitted values use these defaults.