Skip to content

Dingo v0.94.1 Configuration Reference

This page covers the configuration shipped with Dingo v0.94.1. The complete field reference, including descriptions, defaults, environment variables, command-line flags, provider settings, and deployment patterns, is in the release-matched dingo.yaml.example file. The same file is available in the Dingo v0.94.1 source.

The example has no active settings. Leave values commented to use Dingo’s built-in defaults; uncomment a setting only when you want to override its default. Do not copy a configuration file from a different Dingo release without checking the release’s example, because available fields and behavior can change.

Dingo resolves a setting from the command line first, then environment variables, the YAML file, and finally the built-in default. CLI flag and environment variable names are documented alongside the fields in the example. See Node Configuration and Storage Modes for the main runtime choices.

AreaMain settingsPurpose
Network and pathsnetwork, networkMagic, cardanoConfig, topology, databasePath, socketPath, socketModeSelect a Cardano network and locate node, topology, data files, and the node-to-client socket mode.
Listeners and diagnosticsbindAddr, privateBindAddr, relayPort, privatePort, metricsBindAddr, metricsAuthToken, metricsPort, healthPort, debugPort, debugBindAddr, debugMutexProfileFraction, debugBlockProfileRate, tracing, tracingEndpoint, tracingServiceName, tracingSampleRatio, tracingAlwaysSamplePools, localStateQueryViewMaxLifetimeConfigure node and private listeners, metrics, health probes, profiling, tracing, and LocalStateQuery snapshot lifetime.
Logging and TLSlogging, tlsCertFilePath, tlsKeyFilePath, api.tlsSelect log output and secure supported API or Bark listeners.
Storage and APIsstorageMode, plugins.storage, plugins.mempool, plugins.api, corsAllowedOriginsChoose stored history, storage providers, transaction ordering, and application APIs.
Consensus and plugin selectionplugins.consensusSelect the consensus provider used by the node.
Bootstrap and synchronizationmithril, mithril.downloadMaxBytes, mithril.server, mithril.server.aggregator, genesisBootstrap, genesisBootstrap.corroborationPeers, genesisBootstrap.chainSyncJumping, genesisBootstrap.controlGroups, intersectTip, immutableDbPath, chainsync, validateHistorical, strictUtxoValidationConfigure snapshot or genesis bootstrap, synchronization, and historical validation.
Peer managementtargetNumberOfKnownPeers, targetNumberOfEstablishedPeers, targetNumberOfActivePeers, targetNumberOfRootPeers, activePeersTopologyQuota, activePeersGossipQuota, activePeersLedgerQuota, inboundWarmTarget, inboundHotQuota, inboundMinTenure, inboundHotScoreThreshold, inboundPruneAfter, inboundDuplexOnlyForHot, inboundCooldownSet peer targets, source quotas, and inbound peer policy.
Block production and ledger rulesblockProducer, blockProducerPools, shelley*, forge*, validateForgedBlock, minPoolMargin, pledgeLeverage*, fullPotRewards*, delegatorInactivity*, ledgerApplyRowBatchingEnabled, ledgerPrefetchAheadEnabled, ledgerValidateAheadEnabledConfigure forging keys, multiple pool identities, safety thresholds, and optional ledger behaviors.
Archives and database lifecyclebark*, historyExpiry, databaseLifecycleServe or consume archive data, expire local history, and manage snapshots.
Optional indexes and diagnosticsmidnight, midnight.authTokenPolicyId, midnight.authTokenAssetName, tokenRegistry, tokenRegistry.manifestUrl, tokenRegistry.trustedManifestKey, tokenRegistry.allowRollback, koiosParity, cache, skipRewardLiveStakeBackfillCheckConfigure optional indexing, authenticated registry refresh, parity diagnostics, caching, and startup validation.

Set these keys in the Cardano node configuration file. Dingo does not expose these keys through a native CLI flag or environment variable.

SettingCardano node configuration keyDefault and behavior
Transaction submission logicTxSubmissionLogicVersionWhen omitted, Dingo uses TxSubmissionLogicV1, the implemented legacy per-peer inbound transaction-submission strategy. TxSubmissionLogicV1 is the only accepted value. Dingo rejects TxSubmissionLogicV2 and any unknown value during configuration loading.
Minimum endorser-block offer leadLeiosMinOfferLeadSets the minimum slot lead above the immutable tip for an endorser block that Dingo offers to a peer. When omitted, Dingo uses 3600 slots.

Cardano node Version 2 envelope configuration

Section titled “Cardano node Version 2 envelope configuration”

Dingo accepts both the existing flat Cardano node configuration and the Version 2 envelope format. A document with a top-level Version or Configuration key uses the envelope format and must include both keys. The supported sections map their fields to the corresponding Cardano node settings:

  • Configuration.Protocol supplies protocol settings, including genesis file paths and hashes.
  • Configuration.Testing supplies testing genesis settings and hard fork overrides.
  • Configuration.Consensus supplies consensus settings such as ConsensusMode.
  • Configuration.Network supplies network settings. Same-name fields remain in this section, including PeerSharing.
Version: 2
Configuration:
Protocol:
ByronGenesisFile: byron-genesis.json
Testing:
DijkstraGenesisFile: dijkstra-genesis.json
Consensus:
ConsensusMode: GenesisMode
Network:
PeerSharing: false
DeadlineTargetNumberOfRootPeers: 7

The four Configuration.Network.DeadlineTargetNumberOf*Peers fields map to the existing TargetNumberOf*Peers settings:

  • DeadlineTargetNumberOfRootPeers maps to TargetNumberOfRootPeers.
  • DeadlineTargetNumberOfKnownPeers maps to TargetNumberOfKnownPeers.
  • DeadlineTargetNumberOfEstablishedPeers maps to TargetNumberOfEstablishedPeers.
  • DeadlineTargetNumberOfActivePeers maps to TargetNumberOfActivePeers.

The flat format remains valid and continues to use its existing top-level fields. Version must be an integer with the value 2, and the envelope must contain an object in Configuration. Each supported section must also contain an object. Dingo rejects an envelope that omits either required key or gives a required value a different shape. Dingo also rejects duplicate keys in the envelope root, Configuration, or supported sections, including duplicates that resolve to the same flat field, such as TargetNumberOfRootPeers and DeadlineTargetNumberOfRootPeers. The envelope applies the same TxSubmissionLogicVersion validation as the flat format, so Dingo rejects invalid transaction submission logic in both formats. This format does not add support for unrelated or unknown cardano-node settings.

SettingYAML keyCLI flagEnvironment variableDefault and behavior
Consensus providerplugins.consensus.provider--consensusDINGO_PLUGINS_CONSENSUS_PROVIDERpraos by default. Selects the consensus provider used for header validation, chain comparison, and leader scheduling. Operators can select tachys for Babbage or Conway-shaped configurations. Tachys rejects Genesis or Mithril bootstrap, Leios mode, a Dijkstra start or transition, missing Shelley genesis configuration, nonzero Shelley-through-Babbage hard-fork epochs, and activeSlotsCoeff values other than 1/1.

Dingo records the selected provider’s database identity in the data directory and rejects startup when the stored identity differs from the selected provider. Praos is the default provider. For compatibility with legacy Praos databases, an unmarked nonempty database is accepted when the selected identity is praos/v1, and Dingo records that identity on success. Other selected identities reject an unmarked nonempty database; selecting Tachys for a Praos-identified database also fails. An empty database can adopt the selected provider identity before chain data import.

SettingYAML keyCLI flagEnvironment variableDefault and behavior
Mempool capacityplugins.mempool.config.capacity——1 MiB (1048576 bytes) for standard modes and Praos. 25 MiB (26214400 bytes) applies when the run mode is Leios or the network is Musashi, identified by name or network magic. An explicit YAML or provider capacity overrides both defaults.
SettingYAML keyCLI flagEnvironment variableDefault and behavior
Ledger row batchingledgerApplyRowBatchingEnabled--ledger-apply-row-batching-enabledDINGO_LEDGER_APPLY_ROW_BATCHING_ENABLEDfalse (off). In core storage mode, Dingo applies multi-row batching to eligible unvalidated block deltas. Dingo forwards this setting to serve and dingo load; API mode already uses batching. This setting does not affect consensus.
Ledger prefetch aheadledgerPrefetchAheadEnabled--ledger-prefetch-ahead-enabledDINGO_LEDGER_PREFETCH_AHEAD_ENABLEDtrue (enabled). For validated blocks, Dingo prefetches the next block’s input UTxOs from a read-only transaction while the current block applies. Disabling this setting also disables validation ahead. This setting does not affect consensus.
Ledger validation aheadledgerValidateAheadEnabled--ledger-validate-ahead-enabledDINGO_LEDGER_VALIDATE_AHEAD_ENABLEDtrue (enabled). Dingo verifies witness signatures for validated blocks before block application uses them. This setting requires ledgerPrefetchAheadEnabled; disabling prefetch also disables validation ahead. This setting does not affect consensus.
Blockfetch low watermarkblockfetchLowWatermarkEnabled--blockfetch-low-watermark-enabledDINGO_BLOCKFETCH_LOW_WATERMARK_ENABLEDfalse (off). When enabled while the header is far from the peer tip, Dingo starts blockfetch after one queued blockfetch header range instead of waiting for four. The setting leaves header queue capacity unchanged and does not affect consensus.
SettingYAML keyCLI flagEnvironment variableDefault and behavior
Metrics bind addressmetricsBindAddr--metrics-bind-addrDINGO_METRICS_BIND_ADDR127.0.0.1. This address is independent of bindAddr and defaults to loopback. Set it explicitly to a wildcard or remotely reachable address when a scraper runs outside the container or host.
Metrics authentication tokenmetricsAuthToken—DINGO_METRICS_AUTH_TOKENDingo accepts the legacy value for compatibility but ignores it; it has no effect. Metrics endpoints accept anonymous requests. Dingo provides no CLI flag because process arguments can be visible to other users.
Metrics portmetricsPort--metrics-port—12798 by default. Set it to 0 to disable the Prometheus listener.
SettingYAML keyCLI flagEnvironment variableDefault and behavior
Tracing collector endpointtracingEndpoint--tracing-endpointDINGO_TRACING_ENDPOINTEmpty by default. Set an OTLP HTTP collector URL to enable tracing. When empty, the tracing setting controls tracing and the standard OTEL_EXPORTER_OTLP_* environment variables select the destination.
Tracing service nametracingServiceName--tracing-service-nameDINGO_TRACING_SERVICE_NAMEEmpty by default. Sets the service name for exported telemetry. Dingo uses the configured value first, then OTEL_SERVICE_NAME, then dingo.
Tracing sample ratiotracingSampleRatio--tracing-sample-ratioDINGO_TRACING_SAMPLE_RATIO1 by default. Set a value from 0 through 1, inclusive. Dingo rejects values outside this range during configuration validation.
Always sampled stake poolstracingAlwaysSamplePools--tracing-always-sample-poolsDINGO_TRACING_ALWAYS_SAMPLE_POOLSDingo uses an empty list by default. Set stake pool IDs as Bech32 values, including uppercase Bech32, or as 56-character hexadecimal key hashes. Dingo samples blocks from listed pools regardless of tracingSampleRatio.
OpenTelemetry service name——OTEL_SERVICE_NAMEDingo uses this value when tracingServiceName is empty.
OpenTelemetry resource attributes——OTEL_RESOURCE_ATTRIBUTESDingo applies these attributes to exported telemetry. Malformed entries produce a warning without failing startup.
OpenTelemetry log exporter——OTEL_LOGS_EXPORTERAn unset or empty variable, or none, disables OTLP log export. A valid exporter value enables optional OTLP log export. Invalid exporter configuration produces a warning without stopping startup, and stdout logging remains available.
OpenTelemetry metric exporter——OTEL_METRICS_EXPORTERAn unset or empty variable, or none, disables OTLP metric export. A valid exporter value enables optional OTLP export of the Prometheus registry. Invalid exporter configuration produces a warning without stopping startup; the Prometheus /metrics endpoint remains available.
SettingYAML keyCLI flagEnvironment variableDefault and behavior
Mutex profile sampling fractiondebugMutexProfileFraction--debug-mutex-profile-fractionDINGO_DEBUG_MUTEX_PROFILE_FRACTION0 (off). A nonzero value samples mutex contention events for the pprof mutex profile. Dingo applies the setting only when debugPort is nonzero; the setting does not enable pprof by itself.
Block profile sampling ratedebugBlockProfileRate--debug-block-profile-rateDINGO_DEBUG_BLOCK_PROFILE_RATE0 (off). A nonzero value samples blocking events for the pprof block profile. Dingo applies the setting only when debugPort is nonzero; the setting does not enable pprof by itself.
SettingYAML keyCLI flagEnvironment variableDefault and validation
Node-to-client socket modesocketMode--socket-modeCARDANO_SOCKET_MODE0600 (owner only), regardless of the process umask. Enter an octal permission mode. On Unix, Dingo rejects modes that permit writes by other users. The parent directory for a managed pathname socket must belong to the current user or root. Dingo accepts group or other writable access only when the sticky bit is set; it rejects a writable parent without the sticky bit. Set the sticky bit with chmod +t or remove group or other write access. Linux abstract sockets retain their platform behavior; Windows skips the Unix write restriction.
SettingYAML keyCLI flagEnvironment variableDefaultValidation and behavior
Enableddmq.enabled--dmq-enabledDINGO_DMQ_ENABLEDfalseBoolean value; false disables the setting.
Topicdmq.topic--dmq-topicDINGO_DMQ_TOPICmithrilWhen enabled, Dingo requires the value mithril; no other value is valid.
Network magicdmq.networkMagic--dmq-network-magicDINGO_DMQ_NETWORK_MAGICDerived from the topic and Cardano network when unset.When omitted, Dingo derives the value from the topic and Cardano network. An explicit value overrides the derived value. Set it when the Cardano network has no default for the topic.
Socket pathdmq.socketPath--dmq-socket-pathDINGO_DMQ_SOCKET_PATHdingo-dmq.socketWhen enabled, Dingo requires a nonempty value different from the Cardano socketPath.
Socket modedmq.socketMode--dmq-socket-modeDINGO_DMQ_SOCKET_MODE0600 (owner only), regardless of the process umask. Enter an octal permission mode. On Unix, Dingo rejects modes that permit writes by other users.
Message TTLdmq.messageTtl--dmq-message-ttlDINGO_DMQ_MESSAGE_TTL1800 secondsWhen enabled, Dingo requires a positive value no greater than 9223372036 seconds.
Maximum mempool sizedmq.maxMempoolSize--dmq-max-mempool-sizeDINGO_DMQ_MAX_MEMPOOL_SIZE128 MBWhen enabled, Dingo requires a positive value no greater than 8796093022207 MB.
N2N peer portdmq.n2nPort--dmq-n2n-portDINGO_DMQ_N2N_PORT00 disables the N2N peer port. A nonzero value activates DMQ node-to-node listening and peer management when dmq.maxPeers is also nonzero.
IPv4 peer listener addressdmq.listenAddress--dmq-listen-addressDINGO_DMQ_LISTEN_ADDRESS0.0.0.0When dmq.n2nPort is nonzero, Dingo requires an IPv4 literal when this field is set.
IPv6 peer listener addressdmq.listenIpv6Address--dmq-listen-ipv6-addressDINGO_DMQ_LISTEN_IPV6_ADDRESS::When dmq.n2nPort is nonzero, Dingo requires an IPv6 literal when this field is set.
DMQ peer topology filedmq.topologyFile--dmq-topology-fileDINGO_DMQ_TOPOLOGY_FILEUnsetWhen configuration sets this field, the path must contain no .. traversal and identify an existing regular file. Dingo loads and validates the file before opening the DMQ socket.
Minimum DMQ peersdmq.minPeers--dmq-min-peersDINGO_DMQ_MIN_PEERS3Dingo requires dmq.minPeers <= dmq.maxPeers; 0 allows no required outbound peers. Only outbound or dialed peers count toward this minimum; inbound sessions cannot satisfy it.
Maximum DMQ peersdmq.maxPeers--dmq-max-peersDINGO_DMQ_MAX_PEERS10Dingo requires dmq.minPeers <= dmq.maxPeers; 0 allows no peers when minPeers is also 0. This is the total connection capacity for inbound and outbound peers. Dingo reserves capacity for outbound peers using the larger of minPeers and local-root valency, capped at maxPeers.

Dingo validates these six peer settings when DMQ starts. With dmq.n2nPort: 0, Dingo skips listener address validation. When dmq.n2nPort is nonzero, each configured listener address must use its matching IP version. When both dmq.n2nPort and dmq.maxPeers are nonzero, Dingo listens on the configured IPv4 and IPv6 addresses and maintains peers within dmq.minPeers and dmq.maxPeers. A configured topology supplies peers to the manager, which attempts local roots before public roots; the enabled topic can also discover ledger relay peers through its DNS SRV prefix. When either dmq.n2nPort or dmq.maxPeers is 0, Dingo accepts or dials no peers.

DMQ derives the inbound admission limit from the capacity remaining after it reserves the larger of dmq.minPeers and the local roots’ total valency, capped at dmq.maxPeers. The limit applies only to inbound sessions; Dingo still counts only outbound or dialed peers toward dmq.minPeers. Dingo does not expose this derived limit as a dmq.maxInbound YAML key, CLI flag, or environment variable. If the outbound reserve consumes all dmq.maxPeers, Dingo refuses inbound peers.

When configuration sets dmq.topologyFile, Dingo applies these topology rules before it opens the DMQ socket:

  • The file must be a JSON object no larger than 10 MiB. Dingo rejects malformed JSON, JSON null, and object keys that differ only by case.
  • Each localRoots or publicRoots access point must have a nonempty host and a port from 1 through 65535. Dingo trims host whitespace and IPv6 brackets.
  • A root uses valency, or hotValency as an alias when valency is absent. valency takes precedence when both appear. warmValency defaults to valency and must be greater than or equal to it. A valency may exceed the number of access points.
  • Dingo counts each distinct host and port once. Hostname comparison ignores case and a trailing dot; Dingo canonicalizes IP literals without resolving hostnames.
  • When bootstrapPeers or peerSnapshotFile contains a value, Dingo warns and ignores both fields. Dingo also ignores useLedgerAfterSlot.

Dingo logs the distinct peer count after loading the file and warns when the topology names no peers. An invalid topology causes startup to fail before the DMQ socket opens.

The immutableDbPath setting and the positional input to dingo load accept a local directory or a remote URL. Remote sources require an https:// URL; http:// works only for loopback hosts, and Dingo rejects non-loopback HTTP. For HTTPS sources, Dingo rejects private or special-use destinations for the initial URL, every redirect, and each dial-time DNS resolution. Dingo ignores ambient HTTP proxy settings for remote imports. Remote roots provide tip.json and numbered .chunk, .primary, and .secondary files as chunk triads. Dingo rejects mismatched or incomplete published chunk data. Dingo derives aggregate limits for transfer bytes, cache and staging, free-space reserves, and concurrency from the requested chunk range. Dingo reports an error and fails the import when a limit is exceeded or available free space is insufficient. It then removes staging files after the failure. For a remote import, if trusted replay or processing fails after copied immutable blocks advance beyond the ledger-applied tip, Dingo rewinds the unapplied blocks to that tip before returning the original error. Staging cleanup therefore does not leave unapplied immutable blocks ahead of the ledger tip. If the storage backend refuses the rewind, Dingo returns both the original and rewind errors, and the database requires recovery before another load. See the bootstrap and data maintenance guide for the remote source, chunk, and integrity requirements.

Dingo supports ledger-state imports only for Conway and later current eras. Shelley through Babbage snapshots fail during parsing with ErrPreConwaySnapshotUnsupported, before Dingo writes ledger state. See the bootstrap and data maintenance guide for the supported import workflow.

Historical validation and ledger-state imports

Section titled “Historical validation and ledger-state imports”
SettingYAML keyCLI flagEnvironment variableDefault and validation
Historical validationvalidateHistorical--validate-historicalCARDANO_VALIDATE_HISTORICALfalse. When false, Dingo skips full historical validation. However, Dingo still checks non-trusted peer-sourced historical blocks against inbound envelope rules and operational-certificate counter rules. Trusted replay and Mithril-certified history skip those specific checks.
SettingYAML keyCLI flagEnvironment variableDefault and behavior
Corroborating peersgenesisBootstrap.corroborationPeers--genesis-bootstrap-corroboration-peersDINGO_GENESIS_BOOTSTRAP_CORROBORATION_PEERS0 by default, which disables the corroboration gate. Set a positive value to explicitly enable the required corroboration behavior.
ChainSync JumpinggenesisBootstrap.chainSyncJumping--genesis-csjDINGO_GENESIS_CSJtrue by default. Dingo uses ChainSync Jumping while Genesis selection is active.
Genesis control groupsgenesisBootstrap.controlGroups——Dingo no longer supplies network-specific control groups implicitly. Configure this field explicitly to use a fixed control-group set.

For Musashi, a Cardano node configuration with ConsensusMode: PraosMode disables Genesis chain selection, even when genesisBootstrap is enabled and the node starts from origin without an intersection point. Dingo follows the Cardano configuration in this case instead of applying Genesis density, corroboration, or patience selection.

Configure the host explicitly when a deployment must accept UTxO RPC connections from another host or interface.

SettingYAML keyCLI flagEnvironment variableDefault and behavior
Hostplugins.api.utxorpc.config.host——127.0.0.1 by default. Remote access or access from outside loopback requires an explicit host.

The built-in Blockfrost provider listens on loopback by default. Read-only API requests are not subject to the Blockfrost mutation admission limits.

SettingYAML keyCLI flagEnvironment variableDefault and validation
Hostplugins.api.blockfrost.config.host——127.0.0.1 by default. An explicitly empty value uses the root bindAddr; set a host to expose the provider on another interface.
Authentication tokenplugins.api.blockfrost.config.authToken——Dingo accepts the legacy value for compatibility but ignores it; it has no effect. The setting is not required, and transaction submission and evaluation accept anonymous requests.
Total concurrent mutationsplugins.api.blockfrost.config.maxConcurrentMutations——0 or unset by default, which disables the global bound. Set a positive value to limit transaction submission and evaluation across the provider.
Concurrent mutations per clientplugins.api.blockfrost.config.maxConcurrentMutationsPerClient——0 or unset by default, which disables the per client bound. Set a positive value to limit work from one remote address. When maxConcurrentMutations is positive, this value cannot exceed it; a positive per client cap can also be used with an unlimited global cap.

Before reading the request body, the provider applies each configured positive mutation limit. When concurrent work reaches an active global or per-client limit, the provider returns HTTP 429 with Retry-After: 1 without reading the body.

The shared outbound HTTP user agent has no YAML key or CLI flag.

SettingYAML keyCLI flagEnvironment variableDefault and behavior
Shared HTTP user agent——DINGO_HTTP_USER_AGENTdingo/<version> (<GOOS>/<GOARCH>) by default. Dingo uses a valid value from this environment variable when set and ignores an invalid value. Component-specific userAgent settings for off-chain metadata and token registry take precedence.
SettingYAML keyCLI flagEnvironment variableDefaultValidation and behavior
Maximum lifetime of an acquired ledger snapshotlocalStateQueryViewMaxLifetime--local-state-query-view-max-lifetimeDINGO_LOCAL_STATE_QUERY_VIEW_MAX_LIFETIME5mUse a positive duration string, such as 5m. Dingo rejects an invalid, zero, or negative value during startup or configuration validation. After the maximum lifetime, Dingo closes the held snapshot. The next query reopens it at the acquired point and answers from that snapshot; tip acquires use their snapshotted tips. If a rollback removes the acquired point or retention pruning removes it, Dingo cannot reopen the snapshot and closes the connection.
SettingYAML keyCLI flagEnvironment variableDefault and behavior
Managed Mithril synchronizationmithril.enabled--mithril-enabledDINGO_MITHRIL_ENABLEDfalse (off). In serve with core storage, Dingo can synchronize from a certified Mithril v2 tip and falls back to Ouroboros synchronization when managed Mithril synchronization fails. Manual Mithril synchronization commands work regardless of this setting.
Mithril artifact backendmithril.backend--mithril-backendDINGO_MITHRIL_BACKENDv2 (empty also selects v2). Dingo rejects v1 and v1 CLI paths. The v2 backend uses incremental Cardano database artifacts, requires verified ancillary ledger state and immutable digests during bootstrap, and treats the v2 artifact layout as authoritative.
Mithril pinned digestmithril.pinnedDigest--mithril-pinned-digestDINGO_MITHRIL_PINNED_DIGESTEmpty by default. When configuration sets this value for a fresh bootstrap, the value must identify a v2 Cardano database artifact. Dingo rejects v1 snapshot pins and digests.
Cleanup after Mithril loadmithril.cleanupAfterLoad--mithril-cleanup-after-loadDINGO_MITHRIL_CLEANUPtrue by default. When enabled, Dingo retires extracted immutable chunks incrementally after committing their blocks. If a load stops before completion, Dingo reads the internal mithril_immutable_retired_below resume marker and starts the next run after the chunks it already retired.
SettingYAML keyCLI flagEnvironment variableDefault and behavior
Compressed size limit for each downloaded Mithril objectmithril.downloadMaxBytes--mithril-download-max-bytesDINGO_MITHRIL_DOWNLOAD_MAX_BYTES0 uses the built-in per-object compressed limits. A positive value replaces the limit for every downloaded object. Dingo rejects a negative value during startup or configuration validation.

When mithril.downloadMaxBytes is 0, Dingo uses these built-in compressed limits:

Mithril objectBuilt-in limit
v2 immutable archive1 GiB
v2 digest list256 MiB
v2 ancillary data64 GiB

The mithril.server settings control dingo mithril snapshot create and dingo mithril serve. Snapshot artifact reads are public. Aggregator signer registration and registration closure accept anonymous requests. Set mithril.server.publicBaseUrl to the public origin that appears in snapshot download locations.

SettingYAML keyCLI flagEnvironment variableDefault and behavior
Artifact server portmithril.server.port--mithril-server-portDINGO_MITHRIL_SERVER_PORT8081. dingo mithril serve listens on this port and the root bindAddr.
Public snapshot originmithril.server.publicBaseUrl--mithril-server-public-base-urlDINGO_MITHRIL_SERVER_PUBLIC_BASE_URLDingo requires this setting for dingo mithril serve. Set an absolute HTTP or HTTPS origin without credentials, a path, a query, or a fragment.
Artifact storemithril.server.artifactStore--mithril-server-artifact-storeDINGO_MITHRIL_SERVER_ARTIFACT_STOREEmpty. Set a filesystem directory, s3://bucket/prefix, or gcs://bucket/prefix. The latter two require a build with dingo_extra_plugins.
Redirect base URLmithril.server.redirectBaseUrl--mithril-server-redirect-base-urlDINGO_MITHRIL_SERVER_REDIRECT_BASE_URLEmpty. When set, archive requests redirect to this base URL plus the object key instead of streaming the object. Use it only when the remote objects are publicly readable.
Snapshot retentionmithril.server.keepSnapshots--mithril-server-keep-snapshotsDINGO_MITHRIL_SERVER_KEEP_SNAPSHOTS0 keeps every produced snapshot. A positive value retains that many newest snapshots.
Ancillary signing keymithril.server.ancillarySigningKeyFile--mithril-server-ancillary-signing-key-fileDINGO_MITHRIL_SERVER_ANCILLARY_SIGNING_KEY_FILEEmpty. Set the Ed25519 Mithril JSON hex key that signs each ancillary manifest.
Artifact server TLSmithril.server.tlsEnabled--mithril-server-tls-enabledDINGO_MITHRIL_SERVER_TLS_ENABLEDfalse. When enabled, the server uses the shared tlsCertFilePath and tlsKeyFilePath.
Aggregator endpointsmithril.server.aggregator.enabled--mithril-aggregator-enabledDINGO_MITHRIL_AGGREGATOR_ENABLEDfalse. Enable signer registration, signature collection, and snapshot certification.
Signer registration epochmithril.server.aggregator.epoch--mithril-aggregator-epochDINGO_MITHRIL_AGGREGATOR_EPOCH0 selects no usable epoch; set at least 1 when the aggregator is enabled. The genesis certificate uses the preceding epoch.
STM quorummithril.server.aggregator.k--mithril-aggregator-kDINGO_MITHRIL_AGGREGATOR_K0 until configured. Set a positive quorum that does not exceed m.
STM lottery sizemithril.server.aggregator.m--mithril-aggregator-mDINGO_MITHRIL_AGGREGATOR_M0 until configured. Set a positive value when the aggregator is enabled.
STM win probabilitymithril.server.aggregator.phiF--mithril-aggregator-phi-fDINGO_MITHRIL_AGGREGATOR_PHI_F0 until configured. Set a value greater than 0 and no greater than 1.
Aggregator genesis signing keymithril.server.aggregator.genesisSigningKeyFile--mithril-aggregator-genesis-signing-key-fileDINGO_MITHRIL_AGGREGATOR_GENESIS_SIGNING_KEY_FILERequired when the aggregator is enabled. Set an Ed25519 Mithril JSON hex key.
Aggregator operator tokenmithril.server.aggregator.operatorTokenFile--mithril-aggregator-operator-token-fileDINGO_MITHRIL_AGGREGATOR_OPERATOR_TOKEN_FILEDingo accepts this legacy value for compatibility but ignores it; it has no effect. The aggregator does not require this setting.

When plugins.storage.metadata.provider is sqlite, or when the configuration omits the provider and Dingo defaults it to sqlite, set a root databasePath that is not empty. Dingo rejects startup when databasePath is empty in either case.

Provider-generated PostgreSQL connections use sslMode: verify-full by default, which verifies the server certificate and hostname. Provider-generated MySQL connections use tls=true when sslMode is unset and the host is not a loopback host; localhost, 127.0.0.1, and ::1 remain exempt from this automatic remote-TLS default. An explicitly supplied dsn remains authoritative and bypasses these provider-generated defaults.

MySQL snapshot and restore reject tls=skip-verify instead of weakening the connection to opportunistic TLS. Use an explicit supported mode such as tls=false, tls=true, or tls=preferred when the lifecycle operation needs a different setting.

Configure the Midnight auth-token fields under midnight when registration authorization must use a specific policy and asset.

SettingYAML keyDefaultValidation and behavior
Auth-token policy IDmidnight.authTokenPolicyIdEmptyThe configured policy ID must contain exactly 56 hexadecimal characters and decode to 28 bytes.
Auth-token asset namemidnight.authTokenAssetNameEmptyDingo uses this value with the configured policy ID when it validates an auth token.

Operators must set both fields or leave both fields empty. A partial pair fails configuration and startup validation. When configured, Dingo accepts an auth token only when its policy ID and asset name exactly match the configured values.

Configure these provider YAML keys under plugins.storage.blob.config for the Badger provider. These settings do not add top-level CLI flags or environment variables.

Dingo uses 1 MiB as the default for plugins.storage.blob.config.valueThreshold, except during Core-mode sync and Mithril sync, when Dingo uses 1 KiB. An explicit YAML value overrides either mode default, including an explicit 0.

SettingProvider YAML keyDefaultValidation and behavior
Block cache sizeplugins.storage.blob.config.blockCacheSize0 in Core mode; 256 MiB in API modeFor a non-empty on-disk Badger data directory, Dingo rejects the configuration and returns an error when compression is enabled and blockCacheSize is 0; set a positive blockCacheSize for compression.
Index cache sizeplugins.storage.blob.config.indexCacheSize0 in Core mode and API modeSet a byte count for the index cache.
Compressionplugins.storage.blob.config.compressionfalse in Core mode; enabled in API modeDingo accepts a zero blockCacheSize when compression is disabled.
Memtable sizeplugins.storage.blob.config.memTableSize512 MiB only when storage mode is core and run mode is sync; all other storage and run mode combinations use 128 MiB when configuration omits this setting or sets it to 0Set a byte count. An explicit value overrides the built-in default. No top-level CLI flag or environment variable exists.
Value-log GC intervalplugins.storage.blob.config.gcInterval5mA zero interval selects the 5m default. Dingo rejects negative intervals.
Value-log GC discard ratioplugins.storage.blob.config.gcDiscardRatio0.5The value must be strictly greater than 0 and less than 1.

Dingo keeps value-log GC disabled in both load and sync bulk-import modes, even when the Badger provider configuration sets plugins.storage.blob.config.gc to true.

SettingYAML keyCLI flagEnvironment variableDefaultValidation and scope
Snapshot commit pause bounddatabaseLifecycle.snapshotMaxCommitPause--db-snapshot-max-commit-pauseDINGO_DB_LIFECYCLE_SNAPSHOT_MAX_COMMIT_PAUSE30s. Set 0s for no bound.Set a nonnegative duration. Dingo rejects negative values during configuration validation. A positive duration limits manual and offline, live, and automatic epoch-boundary snapshots after they acquire the commit barrier. If the bound is exceeded, Dingo cancels the snapshot, removes partial output, and reports an error that wraps ErrCommitPauseExceeded.
SettingYAML keyCLI flagEnvironment variableDefault and validation
Local snapshot directorydatabaseLifecycle.snapshotDir--db-snapshot-dir—Empty by default. Set the local directory for automatic and Bark-triggered snapshots. Dingo requires it when snapshotEnabled is true and when Bark mounts its DatabaseService. On Unix, Dingo requires the directory to belong to the process user or root and to be writable. On Windows, Dingo requires the current user or the Administrators group to own the directory and requires it to be writable.

Dingo keeps configured snapshot roots and generated local snapshot and staging paths private. Unix directories use 0700 permissions and files use 0600. Windows uses protected owner-only ACLs. Dingo rejects a snapshot directory that does not satisfy the ownership or writability requirements.

SettingYAML keyCLI flagEnvironment variableDefault and validation
Snapshot trust-key filedatabaseLifecycle.snapshotTrustKeyFile--db-snapshot-trust-key-fileDINGO_DB_LIFECYCLE_SNAPSHOT_TRUST_KEY_FILEEmpty by default. A configured file must contain at least 16 bytes and no more than 1024 bytes, and must be a regular, non-symlink file.

Unix requires the file to belong to the current user and to grant no group or other access. Windows accepts the current user or BUILTIN\Administrators as owner when the process belongs to that group. Its DACL may contain only the owner, Administrators, SYSTEM, Creator Owner, and Owner Rights, plus the restricted local Administrator ACE when Administrators owns the file. Dingo rejects an invalid file during snapshot authentication and during any lifecycle operation that needs the trust key. Operators must provide an acceptable trust key to enable cloud snapshot mirroring. Dingo rejects unsigned legacy snapshots instead of automatically signing them for mirroring.

On Unix, unkeyed local restores require a private snapshot location that the restoring process trusts. On Windows, they require an authenticated manifest. See the bootstrap and data maintenance guide for the required operational checks.

The remote Bark lifecycle service is disabled by default. When enabled, it provides Stop, Restart, and GetStatus operations through Bark. Bark uses 127.0.0.1 by default when a lifecycle service is mounted; set barkHost to expose it on another interface.

SettingYAML keyCLI flagEnvironment variableDefault and requirements
Enable lifecycle servicebarkLifecycleEnabled--bark-lifecycle-enabledDINGO_BARK_LIFECYCLE_ENABLEDfalse. Enabling it requires a nonzero barkPort. TLS certificate and key files are optional.
Lifecycle operator certificatesbarkLifecycleOperatorCertificateFingerprints--bark-lifecycle-operator-certificate-fingerprintsDINGO_BARK_LIFECYCLE_OPERATOR_CERTIFICATE_FINGERPRINTSDingo accepts legacy values for compatibility but ignores them; they have no effect. Lifecycle requests do not require these values.
Private or special-use addresses for block downloadsbarkBlockDownloadAllowPrivateAddresses--bark-block-download-allow-private-addressesDINGO_BARK_BLOCK_DOWNLOAD_ALLOW_PRIVATE_ADDRESSESfalse. When true, Dingo permits private or special-use resolved addresses for Bark block-download destinations. Dingo still checks the origin allowlist, requires HTTPS, validates redirects, and disables proxy use. This setting affects block downloads only, not Bark RPC traffic.

Bark accepts GetStatus, Stop, and Restart without client certificates or operator allowlists over plaintext HTTP. Bark ignores configured barkClientCaFilePath values. DatabaseService operator credentials remain separate and do not grant lifecycle access. Restart is available on Unix platforms; other platforms return an unsupported operation error.

SettingYAML keyCLI flagEnvironment variableDefault and validation
Global archive lookups per secondbarkArchiveLookupsPerSecond--bark-archive-lookups-per-secondDINGO_BARK_ARCHIVE_LOOKUPS_PER_SECOND0 or unset by default, which is unlimited. Set a positive value to limit all anonymous ArchiveService callers. Dingo rejects negative values.
Per-caller archive lookups per secondbarkArchiveCallerLookupsPerSecond--bark-archive-caller-lookups-per-secondDINGO_BARK_ARCHIVE_CALLER_LOOKUPS_PER_SECOND0 or unset by default, which is unlimited. Set a positive value to limit one caller address or IPv6 /64. Dingo rejects negative values.

Dingo charges one base lookup to both budgets for each FetchBlock reference. For a batch containing height references, Dingo also reserves 66 lookup units once to resolve the highest indexed block and reserves additional lookup units for each height reference based on binary-search probes up to that bound. Dingo reserves the budget for each stale-tail retry during bound resolution and each stale interior index skip during a height search before performing that work. The base and additional charges apply to both the global and per-caller budgets. If either budget cannot cover the required charge, Dingo refuses the request with RESOURCE_EXHAUSTED before the corresponding archive or cloud lookup. Large batches containing height references may need to be split.

File-backed inputs provide alternatives to literal values. Dingo applies the same CLI, environment, YAML, and built-in default precedence described above. Dingo rejects a source that sets both the literal form and the file form.

SettingYAML keyCLI flagEnvironment variableDefault and behavior
Dingo Koios parity API keykoiosParity.apiKeyRemoved; invalid: --koios-parity-api-keyDINGO_KOIOS_PARITY_API_KEYEmpty by default. YAML and this environment variable continue to accept literal API keys.
Dingo Koios parity API key filekoiosParity.apiKeyFile--koios-parity-api-key-fileDINGO_KOIOS_PARITY_API_KEY_FILEEmpty by default. CLI input uses this file-backed option. Dingo reads the file as the API key string.
Generic plugin configuration field file——DINGO_PLUGINS_<CAPABILITY>_CONFIG_<FIELD>_FILEUse instead of DINGO_PLUGINS_<CAPABILITY>_CONFIG_<FIELD>. Dingo reads the file as a plain string and does not parse its contents as YAML.
koios-parity API key file—--api-key-fileKOIOS_API_KEY_FILEUse instead of --api-key or KOIOS_API_KEY. CLI flags take precedence over environment variables.
koios-parity metadata DSN file—--metadata-dsn-file—Use instead of --metadata-dsn. The file supplies the connection string as plain text.
node-parity from-genesis Koios API key file—--koios-api-key-file—Use instead of --koios-api-key. The file supplies the API key used for the Koios request.
node-parity from-genesis boundary capture directory—--boundary-capture-dir—Optional directory where the from-genesis UTxO comparison flow stores boundary captures when UTxO comparison is enabled.
node-parity from-genesis transaction info batch size—--koios-tx-info-batch-size—40 by default. Controls the number of transaction hashes in each /tx_info request. The valid range is 1 through 999. The public host rejects request bodies over 5120 bytes, so use a larger value only with a host that accepts larger requests.
node-parity from-genesis transaction info concurrency—--koios-tx-info-concurrency—8 by default. Controls the number of /tx_info requests kept in flight. The valid range is 1 through 64.

Every file-backed value must meet these requirements:

  • The path must identify a regular file. Dingo rejects directories, devices, and other non-regular paths.
  • On Unix, Dingo requires the file and every ancestor path entry to belong to the Dingo process user or root. Dingo rejects a non-sticky directory in the path when group or other users can write to it.
  • Dingo accepts at most 64 KiB of file content. Dingo strips trailing CR and LF characters, then rejects empty or whitespace-only content.
  • File permissions or ACLs must satisfy the platform security policy. Unix files can allow owner and group access but cannot allow access to other users. Windows ACLs can allow only the owner, Administrators, and SYSTEM.
  • Dingo identifies the value or path in errors but never includes file contents.

Token registry source and manifest authentication

Section titled “Token registry source and manifest authentication”

When token registry sync is enabled, Dingo uses the public registry archive for the configured network when manifestUrl is empty. A signed operator mirror requires manifestUrl and trustedManifestKey together; setting only one makes the configuration invalid.

SettingYAML keyCLI flagEnvironment variableDefault and behavior
Signed manifest URLtokenRegistry.manifestUrl--token-registry-manifest-urlDINGO_TOKEN_REGISTRY_MANIFEST_URLEmpty by default. Leave empty for public archive sync. Set an absolute HTTPS URL only with trustedManifestKey for a signed mirror.
Trusted manifest keytokenRegistry.trustedManifestKey--token-registry-trusted-manifest-keyDINGO_TOKEN_REGISTRY_TRUSTED_MANIFEST_KEYEmpty by default. Leave empty for public archive sync. Set a hex-encoded 32-byte Ed25519 public key only with manifestUrl for a signed mirror.
Allow manifest rollbacktokenRegistry.allowRollback--token-registry-allow-rollbackDINGO_TOKEN_REGISTRY_ALLOW_ROLLBACKfalse by default. For signed manifest mirrors, set true only for an intentional publisher rollback.

If tokenRegistry.sourceUrl has an explicit value, Dingo requires an absolute HTTPS URL and uses it as the archive source instead of the network default.

When both signed mirror fields are set, Dingo verifies the signed manifest against the configured archive URL, exact compressed size, and BLAKE2b-256 digest. The manifest also supplies the sequence used for rollback checks. Dingo rejects unauthenticated, mismatched, or incomplete signed-manifest snapshots. Dingo also rejects a lower sequence unless allowRollback is true, and rejects a same-sequence digest change. A rejected signed-manifest snapshot does not replace the last accepted snapshot.

Use tokenRegistry.headerSecrets for credentials required by an authenticated token registry mirror. The YAML form is a map of header names to secret values:

tokenRegistry:
headerSecrets:
Authorization: "Bearer <token>"

The environment form is DINGO_TOKEN_REGISTRY_HEADER_SECRETS, using name:value pairs separated by commas. Dingo splits each pair at the first colon, so a value can contain additional colons but cannot contain a comma. No CLI flag exists because a command line would expose these credentials in the process list.

Dingo redacts header values from rendered configuration and errors. A request with header credentials must use an HTTPS source URL or a loopback source. Dingo rejects malformed header names and values as well as reserved header names used by the transport or request. When a redirect changes the scheme or host, Dingo removes the configured credentials before following it.

Dingo v0.94.0 does not support ForgePrimaryChainTipToleranceSlots or forgePrimaryChainTipToleranceSlots in YAML, the CLI, or environment variables. Remove these settings rather than replacing them with another field.

Set the optional forgeAppliedTipStalenessSlots setting in YAML, with the --forge-applied-tip-staleness-slots CLI flag, or with the DINGO_FORGE_APPLIED_TIP_STALENESS_SLOTS environment variable. Its default is 0, which disables the bound. Dingo evaluates the bound only when a corroborated upstream target exists and ignores it when the target is unknown.

SettingYAML keyCLI flagEnvironment variableDefault and behavior
Multiple block producer poolsblockProducerPools——Absent or empty by default. Dingo then uses the existing top level single pool shelley* key and KES settings. A populated list replaces those top level settings and configures each pool from its list entry. The list and its nested values are YAML only; no separate CLI flags or environment variables apply to list entries.

Each blockProducerPools entry requires shelleyVrfKey, shelleyOperationalCertificate, and exactly one KES source: shelleyKesKey, shelleyKesAgentSocket, or a remote shelleyKesAgentAddress or shelleyKesAgentAddresses. The top level shelleyKesAgentSignTimeout and shelleyKeyWatchInterval settings apply to all pools. Dingo rejects a populated list that also sets legacy top level single pool shelley* key or KES settings, and rejects duplicate operational certificate paths.

Pools may share a remote KES listener address only when each pool names a different shelleyKesAgentProfile. A missing or duplicated profile makes the configuration invalid. The single address and ordered address list remain available as shelleyKesAgentAddress and shelleyKesAgentAddresses.

The --shelley-kes-agent-socket flag supports filesystem socket paths and Linux abstract socket addresses. Dingo resolves a relative filesystem path once at client construction and reuses the resolved path across reconnects. It preserves @-prefixed abstract addresses, rejects literal NUL-prefixed addresses at client construction, and enforces platform socket-length limits.

The CLI flags and environment variables below configure the top-level remote KES settings. Each blockProducerPools entry accepts the YAML keys, but the CLI and environment bindings apply only to the top-level pool.

SettingYAML keyCLI flagEnvironment variableDefault and validation
Single remote KES agent addressshelleyKesAgentAddress or blockProducerPools[].shelleyKesAgentAddress--shelley-kes-agent-addressSHELLEY_KES_AGENT_ADDRESSEmpty. Use a host:port address for a remote signing listener; the setting selects sign mode. Use either this field or shelleyKesAgentAddresses, not both.
Ordered remote KES agent addressesshelleyKesAgentAddresses or blockProducerPools[].shelleyKesAgentAddresses--shelley-kes-agent-addressesSHELLEY_KES_AGENT_ADDRESSESEmpty. Enter an ordered list of host:port addresses. Dingo uses the list order for remote signing and validates every address.
Remote KES agent profileshelleyKesAgentProfile or blockProducerPools[].shelleyKesAgentProfile--shelley-kes-agent-profileSHELLEY_KES_AGENT_PROFILEEmpty. A profile requires a remote agent address. Shared remote listener addresses require a distinct profile for each pool; missing or duplicate profiles are invalid.

The optional Kupo provider belongs under plugins.api.kupo. Set provider: "builtin" to use the built-in provider. Kupo requires storageMode: api; the --kupo-provider flag selects the provider from the CLI. Set plugins.api.kupo.config.port to 0 to disable the Kupo listener.

The example also contains commented deployment patterns for relay, API/data, block producer, archive, history-expiry, and development nodes. Review the warnings in each pattern before enabling settings that alter consensus, forging, or network exposure.


Doc Holiday logo

Docs authored by Doc Holiday