dingo.yaml.example

# Example config file for dingo
# The values shown below correspond to the in-code defaults unless a
# setting is left commented out to preserve a storage-mode-specific
# runtime default.

# Public bind address for the Dingo server
# CLI: --bind-addr
bindAddr: "0.0.0.0"

# Path to the Cardano node configuration file
#
# Can be overridden with the config environment variable
# CLI: --cardano-config
cardanoConfig: "./config/cardano/preview/config.json"

# Global data directory for both blob and metadata storage plugins.
# Can be overridden with CARDANO_DATABASE_PATH or --data-dir.
# Plugin-specific data-dir settings below override this value.
databasePath: ".dingo"

# Database configuration
database:
  # Blob storage plugin configuration
  blob:
    # Plugin to use for blob storage (badger, gcs, s3)
    # badger is always built; gcs and s3 require a build with
    # -tags dingo_extra_plugins or an official release binary.
    plugin: "badger"
    # Configuration options for each plugin
    badger:
      # Data directory for BadgerDB storage
      data-dir: ".dingo/badger"
      # Block cache size in bytes.
      # Leave unset to use the storage-mode default:
      # - 0 when storageMode: "core"
      # - 268435456 (256MB) when storageMode: "api"
      # block-cache-size: 0
      # Index cache size in bytes.
      # Leave unset to use the runtime default (0 in both core and api modes).
      # index-cache-size: 0
      # Enable garbage collection (default: true)
      gc: true
      # Enable ZSTD compression.
      # Leave unset to use the storage-mode default:
      # - false when storageMode: "core"
      # - true when storageMode: "api"
      # compression: false
      # ZSTD compression level used when compression is enabled.
      # Higher levels give a better compression ratio at the cost of
      # throughput. Badger recommends level 1 (default).
      # compression-level: 1
    gcs:
      # Google Cloud Storage bucket name
      bucket: ""
      # Google Cloud project ID
      project-id: ""
      # Path prefix within the bucket
      prefix: ""
    s3:
      # AWS Endpoint
      endpoint: ""
      # AWS S3 bucket name
      bucket: ""
      # AWS region
      region: ""
      # Path prefix within the bucket
      prefix: ""
      # AWS access key ID (optional - uses default credential chain if not set)
      access-key-id: ""
      # AWS secret access key (optional - uses default credential chain if not set)
      secret-access-key: ""

  # Metadata storage plugin configuration
  metadata:
    # Plugin to use for metadata storage (sqlite, postgres, mysql)
    # sqlite is the default. postgres and mysql are still included in plain
    # source builds on current main; issue #2586 tracks moving them behind
    # -tags dingo_extra_plugins.
    plugin: "sqlite"
    # Configuration options for each plugin
    sqlite:
      # Path to SQLite database file
      data-dir: ".dingo/metadata.db"
    postgres:
      # NOTE: These are example values for local development only.
      # Do not use these credentials in production environments.
      # Postgres host
      host: "localhost"
      # Postgres port
      port: 5432
      # Postgres user
      user: "postgres"
      # Postgres password (required - no default)
      password: ""
      # Postgres database name
      database: "postgres"
      # Postgres sslmode
      ssl-mode: "disable"
      # Postgres TimeZone
      timezone: "UTC"
      # Full Postgres DSN (overrides other options when set)
      dsn: ""
    mysql:
      # NOTE: These are example values for local development only.
      # Do not use these credentials in production environments.
      # MySQL host
      host: "localhost"
      # MySQL port
      port: 3306
      # MySQL user
      user: "root"
      # MySQL password (required - no default)
      password: ""
      # MySQL database name
      database: "mysql"
      # MySQL TLS mode (mapped to tls= in DSN)
      ssl-mode: ""
      # MySQL time zone location
      timezone: "UTC"
      # Full MySQL DSN (overrides other options when set)
      dsn: ""

# Path to the UNIX domain socket file used by the server
# CLI: --socket-path
socketPath: "dingo.socket"

# Name of the Cardano network
# CLI: --network
network: "preview"

# Logging output configuration
# format: "text" (default, human-readable) or "json" (machine-parseable,
#         for ELK/Loki ingestion)
# level:  "debug", "info" (default), "warn", or "error".
#         The --debug flag overrides this to "debug".
# Env: DINGO_LOGGING_FORMAT, DINGO_LOGGING_LEVEL
logging:
  format: text
  level: info

# TLS certificate file path (for HTTPS)
#
# Can be overridden with the TLS_CERT_FILE_PATH environment variable
tlsCertFilePath: ""

# TLS key file path (for HTTPS)
#
# Can be overridden with the TLS_KEY_FILE_PATH environment variable
tlsKeyFilePath: ""

# Path to the topology configuration file for Cardano node
topology: ""

# TCP port to bind for Prometheus metrics endpoint
# CLI: --metrics-port
metricsPort: 12798

# TCP port to bind for pprof debug endpoints (heap, profile, goroutine, etc).
# 0 disables. Operators opt in; never enable in production by default — debug
# endpoints expose internal state and run on a separate listener from metrics.
# CLI: --debug-port  Env: DINGO_DEBUG_PORT
debugPort: 0

# Enable OpenTelemetry tracing. Disabled by default: with no collector
# listening, the OTLP exporter logs noisy connection errors. When enabled,
# spans are sent via OTLP HTTP; configure the destination with the standard
# OTEL_EXPORTER_OTLP_* env vars documented for
# go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp.
# CLI: --tracing  Env: DINGO_TRACING_ENABLED
tracing: false

# Export traces to stdout instead of OTLP. Requires tracing to also be
# enabled. Mostly useful for local debugging.
# CLI: --tracing-stdout  Env: DINGO_TRACING_STDOUT
tracingStdout: false

# Internal/private address to bind for listening for Ouroboros NtC
privateBindAddr: "127.0.0.1"

# TCP port to bind for listening for Ouroboros NtC
# CLI: --private-port
privatePort: 3002

# TCP port to bind for listening for Ouroboros NtN
#
# Can be overridden with the port environment variable
# CLI: --port
relayPort: 3001

# Storage mode controls how much data is persisted.
# - "core": Only consensus data (UTxOs, certs, pools, pparams). Suitable for
#   block producers and relay nodes. API ports are ignored in core mode.
# - "api": Core data plus full transaction metadata (witnesses, scripts, datums,
#   redeemers). All APIs start automatically on their default ports.
#
# Can be overridden with DINGO_STORAGE_MODE
# CLI: --storage-mode
storageMode: "core"

# API ports — only used when storageMode is "api".
# In API mode, all APIs start on their default ports. Set a port to 0 to
# disable an individual API.
#
# UTxO RPC gRPC API port (default: 9090)
# Can be overridden with DINGO_UTXORPC_PORT
# CLI: --utxorpc-port
utxorpcPort: 9090
# Blockfrost-compatible REST API port (default: 3000)
# Can be overridden with DINGO_BLOCKFROST_PORT
# CLI: --blockfrost-port
blockfrostPort: 3000
# Mesh (Coinbase Rosetta) REST API port (default: 8080)
# Can be overridden with DINGO_MESH_PORT
# CLI: --mesh-port
meshPort: 8080

# Base URL of a remote Bark archive server. When set, this node keeps using
# its configured local blob plugin but wraps it with Bark archive fallback for
# expired or missing historical blocks.
# Can be overridden with DINGO_BARK_BASE_URL
# CLI: --bark-url
barkBaseUrl: ""

# TCP port bind for listening for Bark RPC calls. Enable this on archive nodes.
# Can be overridden with DINGO_BARK_PORT
# CLI: --bark-port
barkPort: 0

# Local immutable block history expiry. When enabled, Dingo replaces block CBOR
# older than the ledger-derived stability window with an expired-history marker
# while retaining local indexes and metadata. Bark fallback is optional.
historyExpiry:
  # Can be overridden with DINGO_HISTORY_EXPIRY_ENABLED
  # CLI: --history-expiry-enabled
  enabled: false
  # Can be overridden with DINGO_HISTORY_EXPIRY_FREQUENCY
  # CLI: --history-expiry-frequency
  frequency: 1h

# ---
# Deployment pattern examples (uncomment one block):
#
# Relay node (core storage, API ports ignored):
#   storageMode: "core"
#   blockProducer: false
#
# Data node (all APIs start on defaults automatically):
#   storageMode: "api"
#   # Override individual ports or set to 0 to disable:
#   # blockfrostPort: 3100
#   # meshPort: 0            # disable Mesh API
#   # With storageMode: "api", leave mode-sensitive Badger settings unset to keep:
#   #   block-cache-size: 268435456
#   #   index-cache-size: 0
#   #   compression: true
#
# Validator / block producer (core storage, API ports ignored):
#   storageMode: "core"
#   blockProducer: true
#   shelleyVrfKey: "/keys/vrf.skey"
#   shelleyKesKey: "/keys/kes.skey"
#   shelleyOperationalCertificate: "/keys/opcert.cert"
#   # With storageMode: "core", Badger blob defaults switch to mmap-only:
#   #   block-cache-size: 0
#   #   index-cache-size: 0
#   #   compression: false
#   # You can still override any of those explicitly under database.blob.badger.
#   # Optional forging tolerances (0 = defaults)
#   forgeSyncToleranceSlots: 0
#   forgeStaleGapThresholdSlots: 0
#
# Archive node (full immutable block history in object storage, Bark enabled):
#   storageMode: "core"
#   database:
#     blob:
#       plugin: "s3" # or "gcs"
#       s3:
#         bucket: "dingo-archive"
#         region: "us-east-1"
#         prefix: "preview"
#   barkPort: 9091
#
# History-expiry node (local blobs plus remote archive fallback):
#   storageMode: "core"
#   database:
#     blob:
#       plugin: "badger"
#   historyExpiry:
#     enabled: true
#     frequency: 1h
#   barkBaseUrl: "http://archive.example.internal:9091"
#
# Dev mode (isolated, forge blocks, no outbound):
#   runMode: "dev"
# ---

# Ignore prior chain history and start from current tip (default: false)
# This is experimental and may break — use with caution
intersectTip: false

# Maximum total size (in bytes) of all transactions allowed in the mempool.
# Transactions exceeding this limit will be rejected.
# Default: 1048576 (1 MiB) for Praos modes; 26214400 (25 MiB) for Leios.
# Leave commented to use the mode default; uncomment to override.
# CLI: --mempool-capacity
# mempoolCapacity: 1048576

# Forging tolerances (0 = defaults)
# forgeSyncToleranceSlots controls how far the local chain can lag the upstream
# tip before forging is skipped. forgeStaleGapThresholdSlots controls when to
# log an error if the chain tip is far ahead of the slot clock.
forgeSyncToleranceSlots: 0
forgeStaleGapThresholdSlots: 0

# Operational mode: "serve" (default), "load", "dev", or "leios"
# - serve: Full node with network connectivity (default)
# - load: Batch import from ImmutableDB (requires immutableDbPath)
# - dev: Development mode (forge blocks, disable outbound, skip topology)
# - leios: Full node with experimental Leios/Dijkstra protocol support
# Note: CLI commands (serve, load) take priority over this setting
#
# Can be overridden with the DINGO_RUN_MODE environment variable
# CLI: --run-mode
runMode: "serve"

# Experimental startup era. Empty follows the genesis protocol version.
# Set to "dijkstra" only for Dijkstra/Leios test networks.
#
# Can be overridden with the DINGO_START_ERA environment variable
# CLI: --start-era
startEra: ""

# Leios voting (experimental, leios runMode only)
#
# leiosVoteSigningKeyFile is the path to a hex-encoded BLS12-381 vote
# signing key (32-byte scalar; the file must not be group/other readable).
# When set on a block producer whose pool is a member of the epoch's
# stake-truncated voting committee, the node signs and emits one Leios
# vote per observed endorser block.
#
# leiosVoterPublicKeys maps hex pool key hashes to hex-encoded 96-byte
# compressed BLS12-381 public keys. It stands in for CIP-0164 key
# registration (not yet specified) so vote signatures can be verified on
# test networks. Votes from voters without a registered key still count
# toward observed stake but cannot contribute to certificates.
#
# Can be overridden with the DINGO_LEIOS_VOTE_SIGNING_KEY_FILE and
# DINGO_LEIOS_VOTER_PUBLIC_KEYS environment variables
# leiosVoteSigningKeyFile: "/keys/leios-vote.skey"
# leiosVoterPublicKeys:
#   "<pool key hash hex>": "<compressed G2 public key hex>"

# Path to ImmutableDB for batch import (used when runMode is "load")
# Can also be provided as argument to 'dingo load' command
#
# Can be overridden with the DINGO_IMMUTABLE_DB_PATH environment variable
# CLI: --immutable-db-path
immutableDbPath: ""

# Validate historical blocks during ledger processing (default: false)
validateHistorical: false

# Error out (instead of silently skipping) when a consumed UTxO cannot be
# found or recovered for a block past the recorded Mithril sync boundary.
# Leave disabled when bootstrapping from a non-genesis chainsync intersect
# point without a Mithril snapshot import, where pre-intersect UTxOs are
# legitimately absent. (default: false)
#
# Can be overridden with the CARDANO_STRICT_UTXO_VALIDATION environment variable
# CLI: --strict-utxo-validation
strictUtxoValidation: false

# Peer targets - target number of peers in each state
# These are goals the system works toward, not hard limits.
# Use 0 for default values, -1 for unlimited
# Default: known=150, established=50, active=20
#
# Target number of known (cold) peers
# CLI: --target-known-peers
targetNumberOfKnownPeers: 0
# Target number of established (warm) peers
# CLI: --target-established-peers
targetNumberOfEstablishedPeers: 0
# Target number of active (hot) peers
# CLI: --target-active-peers
targetNumberOfActivePeers: 0

# Per-source quotas for active peers
# These specify how active peer slots are distributed by source.
# Use 0 for default values.
# Default: topology=3, gossip=12, ledger=5
#
# Active peer slots for topology sources (local + public roots)
activePeersTopologyQuota: 0
# Active peer slots for gossip sources
activePeersGossipQuota: 0
# Active peer slots for ledger sources
activePeersLedgerQuota: 0

# Inbound peer governance budget (phase 1)
# These define explicit operator intent for inbound peers as a governed source.
# Current behavior remains conservative; these values are surfaced in metrics and
# quota/status output to make inbound policy visible.
#
# Target number of inbound peers to keep in warm state.
# CLI: --inbound-warm-target
inboundWarmTarget: 0
# Quota for inbound peers in hot state.
# CLI: --inbound-hot-quota
inboundHotQuota: 0
# Minimum tenure before inbound peers are eligible for hot promotion.
# CLI: --inbound-min-tenure
inboundMinTenure: 0s
# Minimum score threshold for inbound hot promotion.
# CLI: --inbound-hot-score-threshold
inboundHotScoreThreshold: 0
# Future prune grace window for inbound peers.
# CLI: --inbound-prune-after
inboundPruneAfter: 0s
# Future duplex policy knob for inbound peers.
# CLI: --inbound-duplex-only-for-hot
inboundDuplexOnlyForHot: false
# Future cooldown knob for inbound peer governance actions.
# CLI: --inbound-cooldown
inboundCooldown: 0s

# Genesis bootstrap configuration
# Used only for from-origin sync. Default behavior keeps this enabled and
# exits Genesis mode automatically near the best known peer tip.
genesisBootstrap:
  # Enable/disable Genesis bootstrap mode (default: true).
  enabled: true
  # Override the Genesis comparison window in slots.
  # 0 auto-derives the window from genesis params (3k/f).
  windowSlots: 0
  # Minimum diversity groups to prefer while promoting peers during bootstrap.
  # 0 uses the peer-governor default.
  promotionMinDiversityGroups: 0

# Midnight indexer configuration
# Indexing is active only in API storage mode. Setting port to 0 disables
# the Midnight gRPC server while leaving indexing eligible to run.
# CLI: --midnight-port, --midnight-host
# Env: DINGO_MIDNIGHT_PORT, DINGO_MIDNIGHT_HOST
# Address and policy fields are YAML only.
midnight:
  # gRPC listen port
  port: 50051
  # gRPC listen address
  host: "0.0.0.0"
  # Midnight network constants. Known network defaults are applied when
  # available; set these explicitly for custom networks or overrides.
  cnightPolicyId: ""
  cnightAssetName: ""
  mappingValidatorAddress: ""
  # Auth token policy ID (28-byte / 56 hex char). When set, only tokens minted
  # under this exact policy are accepted as registration auth tokens.
  authTokenPolicyId: ""
  authTokenAssetName: ""
  committeeCandidateAddress: ""
  technicalCommitteeAddress: ""
  technicalCommitteePolicyId: ""
  councilAddress: ""
  councilPolicyId: ""
  permissionedCandidatePolicy: ""

# Cache configuration for tiered CBOR cache system
# This controls the in-memory caching of UTxO and transaction CBOR data
cache:
  # Number of entries in the hot UTxO cache (LFU eviction)
  # Default: 50000
  # CLI: --cache-hot-utxo-entries
  hotUtxoEntries: 50000
  # Number of entries in the hot transaction cache (LFU eviction)
  # Default: 10000
  hotTxEntries: 10000
  # Maximum memory in bytes for hot transaction cache
  # Default: 268435456 (256 MB)
  hotTxMaxBytes: 268435456
  # Number of blocks to keep in the block LRU cache
  # Default: 500
  # CLI: --cache-block-lru-entries
  blockLruEntries: 500
  # Number of recent blocks to warm up on startup
  # Default: 1000
  warmupBlocks: 1000
  # Wait for cache warmup to complete before serving requests
  # Default: true
  # CLI: --cache-warmup-sync
  warmupSync: true

# Multi-client ChainSync (header synchronization) configuration
chainsync:
  # Maximum number of concurrent ChainSync client connections
  # Default: 3
  # CLI: --chainsync-max-clients  Env: DINGO_CHAINSYNC_MAX_CLIENTS
  maxClients: 3
  # Duration with no activity after which a ChainSync client is
  # considered stalled and eligible for failover/recycling
  # Default: "2m"
  # CLI: --chainsync-stall-timeout  Env: DINGO_CHAINSYNC_STALL_TIMEOUT
  stallTimeout: "2m"
  # Header-sync strategy: how headers from multiple eligible peers drive
  # ledger ingress.
  # - "primary":     a single active peer drives ingress, failing over to
  #                  another eligible peer when it stalls or disconnects
  #                  (default; preserves prior behavior).
  # - "parallel":    every eligible peer may supply headers concurrently;
  #                  duplicates are deduplicated before ledger ingress so a
  #                  header never enters ledger processing twice.
  # - "round-robin": a single ingress-driving peer that rotates across the
  #                  eligible peers over time.
  # Default: "primary"
  # CLI: --chainsync-strategy  Env: DINGO_CHAINSYNC_STRATEGY
  strategy: "primary"

# Mithril snapshot bootstrap configuration
# Use 'dingo mithril sync' or 'dingo sync --mithril' to bootstrap from a snapshot
# CLI: --mithril-enabled, --mithril-verify-certs
mithril:
  # Enable Mithril integration (default: true)
  enabled: true
  # Override aggregator URL (auto-detected from network if empty)
  # Supported networks: mainnet, preprod, preview
  aggregatorUrl: ""
  # Mithril artifact backend: "v2" (default) restores from incremental
  # per-immutable-file archives verified against the certified merkle
  # root; "v1" uses the legacy full snapshot tarballs (being phased
  # out upstream)
  # CLI: --mithril-backend
  backend: "v2"
  # Directory for downloading snapshot archives
  # If empty, a randomized temporary directory is created automatically
  # downloadDir: ""
  # Maximum idle time waiting for snapshot headers or body bytes before retrying
  # Empty uses the built-in default. A negative duration disables idle detection.
  # CLI: --mithril-download-idle-timeout
  # downloadIdleTimeout: ""
  # Consecutive idle retries allowed without additional downloaded bytes
  # 0 uses the built-in default
  # CLI: --mithril-download-max-idle-retries
  # downloadMaxIdleRetries: 0
  # Remove temporary files after loading completes
  # Default: true
  cleanupAfterLoad: true
  # Verify the Mithril certificate chain from snapshot back to genesis
  # Default: true
  verifyCertificates: true