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 = "[::]:3100"

[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)

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

`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	”[::]:3100”
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_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.

Schema

upstream section

Peer mode

Emulator mode

storage section

storage.wal section

storage.state section

storage.archive section

storage.index section

storage.mempool section

genesis section

chain section

chain.custom_utxos section

sync section

submit section

serve.grpc section

serve.minibf section

serve.minikupo section

serve.trp section

serve.ouroboros section

relay section

retries section

mithril section

snapshot section

logging section

telemetry section