config

type APIConfig struct {
	TLS apiconfig.TLSPolicy `yaml:"tls"`
}

type APIPluginsConfig struct {
	Blockfrost hostplugin.Selection `yaml:"blockfrost"`
	Mesh       hostplugin.Selection `yaml:"mesh"`
	Utxorpc    hostplugin.Selection `yaml:"utxorpc"`
}

type CacheConfig struct {
	// HotUtxoEntries is the maximum number of UTxO CBOR entries in the hot
	// cache.
	HotUtxoEntries int `yaml:"hotUtxoEntries"  envconfig:"DINGO_CACHE_HOT_UTXO_ENTRIES"`
	// HotTxEntries is the maximum number of transaction CBOR entries in the hot
	// cache.
	HotTxEntries int `yaml:"hotTxEntries"    envconfig:"DINGO_CACHE_HOT_TX_ENTRIES"`
	// HotTxMaxBytes is the maximum memory in bytes for the hot transaction
	// cache.
	HotTxMaxBytes int64 `yaml:"hotTxMaxBytes"   envconfig:"DINGO_CACHE_HOT_TX_MAX_BYTES"`
	// BlockLRUEntries is the maximum number of blocks in the LRU cache.
	BlockLRUEntries int `yaml:"blockLruEntries" envconfig:"DINGO_CACHE_BLOCK_LRU_ENTRIES"`
	// WarmupBlocks is the number of recent blocks to scan during cache warmup.
	WarmupBlocks int `yaml:"warmupBlocks"    envconfig:"DINGO_CACHE_WARMUP_BLOCKS"`
	// WarmupSync blocks startup until cache warmup is complete when true.
	WarmupSync bool `yaml:"warmupSync"      envconfig:"DINGO_CACHE_WARMUP_SYNC"`
}

type ChainsyncConfig struct {
	// MaxClients is the maximum number of concurrent chainsync client
	// connections. Default: 3.
	MaxClients int `yaml:"maxClients"   envconfig:"DINGO_CHAINSYNC_MAX_CLIENTS"`
	// StallTimeout is the duration after which a client with no
	// activity is considered stalled. Default: "2m".
	StallTimeout string `yaml:"stallTimeout" envconfig:"DINGO_CHAINSYNC_STALL_TIMEOUT"`
	// Strategy selects how headers from multiple eligible peers drive
	// ledger ingress: "primary", "parallel", or "round-robin".
	// Default: "primary".
	Strategy string `yaml:"strategy"     envconfig:"DINGO_CHAINSYNC_STRATEGY"`
}

type Config struct {
	Plugins PluginsConfig `yaml:"plugins"`
	// API holds shared TLS policy defaults for every selected
	// plugins.api.* provider. See APIConfig's own doc comment.
	API                    APIConfig `yaml:"api"`
	TlsKeyFilePath         string    `yaml:"tlsKeyFilePath"                      envconfig:"TLS_KEY_FILE_PATH"`
	Topology               string    `yaml:"topology"`
	CardanoConfig          string    `yaml:"cardanoConfig"                       envconfig:"config"`
	DatabasePath           string    `yaml:"databasePath"                                                                                 split_words:"true"`
	SocketPath             string    `yaml:"socketPath"                                                                                   split_words:"true"`
	TlsCertFilePath        string    `yaml:"tlsCertFilePath"                     envconfig:"TLS_CERT_FILE_PATH"`
	BindAddr               string    `yaml:"bindAddr"                                                                                     split_words:"true"`
	PrivateBindAddr        string    `yaml:"privateBindAddr"                                                                              split_words:"true"`
	ShutdownTimeout        string    `yaml:"shutdownTimeout"                                                                              split_words:"true"`
	LedgerCatchupTimeout   string    `yaml:"ledgerCatchupTimeout"                envconfig:"DINGO_LEDGER_CATCHUP_TIMEOUT"`
	Network                string    `yaml:"network"`
	NetworkMagic           uint32    `yaml:"networkMagic"                                                                                 split_words:"true"`
	PrivatePort            uint      `yaml:"privatePort"                                                                                  split_words:"true"`
	RelayPort              uint      `yaml:"relayPort"                           envconfig:"port"`
	BarkBaseUrl            string    `yaml:"barkBaseUrl"                         envconfig:"DINGO_BARK_BASE_URL"`
	BarkBlockDownloadHosts []string  `yaml:"barkBlockDownloadHosts"              envconfig:"DINGO_BARK_BLOCK_DOWNLOAD_HOSTS"`
	BarkPort               uint      `yaml:"barkPort"                            envconfig:"DINGO_BARK_PORT"`
	// BarkHost is the interface Bark binds to. Left empty, node.go defaults
	// it to loopback-only (127.0.0.1) whenever the database lifecycle
	// service (Restore/Truncate and friends — gated on BarkClientCAFilePath,
	// see its own doc comment) is mounted, rather than bark's own
	// all-interfaces "0.0.0.0" default; set explicitly to widen that on
	// purpose.
	BarkHost string `yaml:"barkHost"                            envconfig:"DINGO_BARK_HOST"`
	// BarkClientCAFilePath is a PEM CA bundle Bark verifies client
	// certificates (mTLS) against. Required whenever the database lifecycle
	// service is mounted (databaseLifecycle.snapshotDir set alongside
	// barkPort): every DatabaseService RPC requires a certificate verified
	// against this CA. Destructive methods additionally require an explicit
	// BarkOperatorCertificateFingerprints match. Also requires
	// TlsCertFilePath/TlsKeyFilePath to be set.
	BarkClientCAFilePath string `yaml:"barkClientCaFilePath"                envconfig:"DINGO_BARK_CLIENT_CA_FILE_PATH"`
	// BarkOperatorCertificateFingerprints is the explicit operator allowlist
	// for destructive DatabaseService RPCs. Every DatabaseService caller must
	// authenticate with BarkClientCAFilePath; only these SHA-256 certificate
	// fingerprints may invoke destructive methods.
	BarkOperatorCertificateFingerprints []string `yaml:"barkOperatorCertificateFingerprints" envconfig:"DINGO_BARK_OPERATOR_CERTIFICATE_FINGERPRINTS"`
	CORSAllowedOrigins                  []string `yaml:"corsAllowedOrigins"                  envconfig:"DINGO_CORS_ALLOWED_ORIGINS"`
	MetricsPort                         uint     `yaml:"metricsPort"                                                                                  split_words:"true"`
	// DebugBindAddr is the interface used by the unauthenticated pprof
	// listener. It defaults to loopback independently of BindAddr and
	// PrivateBindAddr; operators must set this field explicitly to expose
	// pprof on a wildcard or management-network address.
	DebugBindAddr string `yaml:"debugBindAddr"                       envconfig:"DINGO_DEBUG_BIND_ADDR"`
	DebugPort     uint   `yaml:"debugPort"                           envconfig:"DINGO_DEBUG_PORT"`
	// HealthPort serves the liveness (/health, /healthz) and readiness
	// (/readyz) probes on a listener of their own, so an operator can
	// expose them to an orchestrator or load balancer without also
	// exposing Prometheus metrics, pprof, or any API. It binds BindAddr,
	// the same address the relay and metrics listeners use and distinct
	// from the API listeners' own bind address: a probe is operational
	// surface, not API surface. 0 disables the listener.
	HealthPort uint `yaml:"healthPort"                          envconfig:"DINGO_HEALTH_PORT"`
	// HealthReadyGapSlots is how far the chain tip may trail the
	// wall-clock slot while /readyz still reports ready. Liveness ignores
	// it entirely; see internal/health for why the two are separate.
	HealthReadyGapSlots uint `yaml:"healthReadyGapSlots"                 envconfig:"DINGO_HEALTH_READY_GAP_SLOTS"`
	IntersectTip        bool `yaml:"intersectTip"                                                                                 split_words:"true"`
	// ValidateHistorical validates the complete replay from the selected
	// intersection. The default from-origin sync path must not trust peers to
	// have validated historical blocks for us.
	ValidateHistorical bool `yaml:"validateHistorical"                                                                           split_words:"true"`
	// StrictUtxoValidation errors out (instead of silently skipping) when a
	// consumed UTxO cannot be found or recovered for a block past the
	// recorded Mithril sync boundary. A non-genesis intersect without a
	// Mithril snapshot should explicitly opt out when pre-intersect UTxOs are
	// intentionally unavailable.
	StrictUtxoValidation bool `yaml:"strictUtxoValidation"                                                                         split_words:"true"`
	// SkipRewardLiveStakeBackfillCheck skips the startup consistency check
	// between reward_live_stake and the live UTxO/account set. That check
	// scans the entire live UTxO table every startup regardless of whether
	// anything needs fixing, which is expensive on a mainnet-scale database.
	// Unsafe to leave enabled permanently -- it exists to catch a stale or
	// pre-migration reward_live_stake table -- so this is for advanced/
	// diagnostic use only (e.g. repeated restarts against a database already
	// known to be consistent).
	//
	// It does not affect the stake-snapshot provenance check that runs in the
	// same startup step: that one is cheap, indexed, and fails closed, so it
	// runs unconditionally.
	SkipRewardLiveStakeBackfillCheck bool `yaml:"skipRewardLiveStakeBackfillCheck"                                                             split_words:"true"`
	// Tracing enables OpenTelemetry tracing. Disabled by default: with no
	// collector listening, the OTLP exporter logs noisy connection errors.
	// Spans are sent via OTLP HTTP; configure the destination with the
	// standard OTEL_EXPORTER_OTLP_* env vars.
	Tracing bool `yaml:"tracing"                             envconfig:"DINGO_TRACING_ENABLED"`
	// TracingStdout redirects spans to stdout instead of OTLP. Requires
	// Tracing to also be enabled. Mostly useful for local debugging.
	TracingStdout   bool     `yaml:"tracingStdout"                       envconfig:"DINGO_TRACING_STDOUT"`
	RunMode         RunMode  `yaml:"runMode"                             envconfig:"DINGO_RUN_MODE"`
	StartEra        StartEra `yaml:"startEra"                            envconfig:"DINGO_START_ERA"`
	ImmutableDbPath string   `yaml:"immutableDbPath"                     envconfig:"DINGO_IMMUTABLE_DB_PATH"`
	// Database worker pool tuning (worker count and task queue size)
	DatabaseWorkers   int `yaml:"databaseWorkers"                     envconfig:"DINGO_DATABASE_WORKERS"`
	DatabaseQueueSize int `yaml:"databaseQueueSize"                   envconfig:"DINGO_DATABASE_QUEUE_SIZE"`
	BackfillBatchSize int `yaml:"backfillBatchSize"                   envconfig:"DINGO_BACKFILL_BATCH_SIZE"`
	// BlockPipelineEnabled turns on parallel block decode in the chainsync
	// replay loop that reads blocks back from the primary chain and applies
	// them to the ledger. Not consensus-affecting -- it only changes how
	// CBOR decode work is scheduled, not validation or apply behavior -- but
	// defaults off until throughput and stability are proven (issue #1894
	// phase 1). See ARCHITECTURE.md ("Block Processing Pipeline").
	BlockPipelineEnabled bool `yaml:"blockPipelineEnabled"                envconfig:"DINGO_BLOCK_PIPELINE_ENABLED"`
	// BlockPipelineValidateEnabled adds parallel VRF/KES and OpCert checks to
	// block-pipeline replay (issue #1894 phase 3). It requires
	// BlockPipelineEnabled. Admission-time header validation remains the
	// authoritative gate because ls.chain is visible to downstream readers
	// before replay reaches this stage. See ARCHITECTURE.md ("Block Processing
	// Pipeline").
	BlockPipelineValidateEnabled bool `yaml:"blockPipelineValidateEnabled"        envconfig:"DINGO_BLOCK_PIPELINE_VALIDATE_ENABLED"`

	// Peer targets (0 = use default, -1 = unlimited)
	TargetNumberOfKnownPeers       int `yaml:"targetNumberOfKnownPeers"       envconfig:"DINGO_TARGET_KNOWN_PEERS"`
	TargetNumberOfEstablishedPeers int `yaml:"targetNumberOfEstablishedPeers" envconfig:"DINGO_TARGET_ESTABLISHED_PEERS"`
	TargetNumberOfActivePeers      int `yaml:"targetNumberOfActivePeers"      envconfig:"DINGO_TARGET_ACTIVE_PEERS"`
	TargetNumberOfRootPeers        int `yaml:"targetNumberOfRootPeers"        envconfig:"DINGO_TARGET_ROOT_PEERS"`

	// Per-source quotas for active peers (0 = use default, negative = disable)
	ActivePeersTopologyQuota int `yaml:"activePeersTopologyQuota" envconfig:"DINGO_ACTIVE_PEERS_TOPOLOGY_QUOTA"`
	ActivePeersGossipQuota   int `yaml:"activePeersGossipQuota"   envconfig:"DINGO_ACTIVE_PEERS_GOSSIP_QUOTA"`
	ActivePeersLedgerQuota   int `yaml:"activePeersLedgerQuota"   envconfig:"DINGO_ACTIVE_PEERS_LEDGER_QUOTA"`

	// Peer governor tuning (0 = use default)
	MinHotPeers              int           `yaml:"minHotPeers"              envconfig:"DINGO_MIN_HOT_PEERS"`
	ReconcileInterval        time.Duration `yaml:"reconcileInterval"        envconfig:"DINGO_RECONCILE_INTERVAL"`
	InactivityTimeout        time.Duration `yaml:"inactivityTimeout"        envconfig:"DINGO_INACTIVITY_TIMEOUT"`
	InboundWarmTarget        int           `yaml:"inboundWarmTarget"        envconfig:"DINGO_INBOUND_WARM_TARGET"`
	InboundHotQuota          int           `yaml:"inboundHotQuota"          envconfig:"DINGO_INBOUND_HOT_QUOTA"`
	InboundMinTenure         time.Duration `yaml:"inboundMinTenure"         envconfig:"DINGO_INBOUND_MIN_TENURE"`
	InboundHotScoreThreshold float64       `yaml:"inboundHotScoreThreshold" envconfig:"DINGO_INBOUND_HOT_SCORE_THRESHOLD"`
	InboundPruneAfter        time.Duration `yaml:"inboundPruneAfter"        envconfig:"DINGO_INBOUND_PRUNE_AFTER"`
	InboundDuplexOnlyForHot  bool          `yaml:"inboundDuplexOnlyForHot"  envconfig:"DINGO_INBOUND_DUPLEX_ONLY_FOR_HOT"`
	InboundCooldown          time.Duration `yaml:"inboundCooldown"          envconfig:"DINGO_INBOUND_COOLDOWN"`
	MaxConnectionsPerIP      int           `yaml:"maxConnectionsPerIP"      envconfig:"DINGO_MAX_CONNECTIONS_PER_IP"`
	MaxInboundConns          int           `yaml:"maxInboundConns"          envconfig:"DINGO_MAX_INBOUND_CONNS"`

	// Cache configuration for the tiered CBOR cache system
	Cache CacheConfig `yaml:"cache"`

	// Chainsync configuration for multi-client support
	Chainsync ChainsyncConfig `yaml:"chainsync"`

	// Genesis bootstrap configuration for from-origin chain selection.
	GenesisBootstrap GenesisBootstrapConfig `yaml:"genesisBootstrap"`

	// History expiry configuration for local immutable block CBOR expiry.
	HistoryExpiry HistoryExpiryConfig `yaml:"historyExpiry"`

	// KoiosParity configures the optional in-process Koios reward-parity
	// observer (dingo #3098). Disabled by default.
	KoiosParity KoiosParityConfig `yaml:"koiosParity"`

	// Off-chain metadata fetcher configuration.
	OffchainMetadata OffchainMetadataConfig `yaml:"offchainMetadata"`

	// CIP-26 off-chain token registry sync (API mode).
	TokenRegistry TokenRegistryConfig `yaml:"tokenRegistry"`

	// Logging configuration (output format and level)
	Logging LoggingConfig `yaml:"logging"`

	// Midnight indexer and gRPC API configuration.
	Midnight MidnightConfig `yaml:"midnight"`

	// KES (Key Evolving Signature) configuration for block production
	// SlotsPerKESPeriod is the number of slots in a KES period.
	// After this many slots, the KES key must be evolved to the next period.
	// Default: 129600 (mainnet value = 1.5 days at 1 second per slot)
	SlotsPerKESPeriod uint64 `yaml:"slotsPerKESPeriod" envconfig:"DINGO_SLOTS_PER_KES_PERIOD"`
	// MaxKESEvolutions is the maximum number of times a KES key can evolve.
	// For Cardano's KES depth of 6, this is 2^6 - 2 = 62 evolutions.
	// After this many evolutions, a new operational certificate must be issued.
	// Default: 62
	MaxKESEvolutions uint64 `yaml:"maxKESEvolutions"  envconfig:"DINGO_MAX_KES_EVOLUTIONS"`

	// Block production configuration (SPO mode)
	// Environment variables match cardano-node naming convention for compatibility
	// Note: envconfig.Process("cardano", ...) adds "CARDANO_" prefix automatically
	BlockProducer                 bool   `yaml:"blockProducer"                      envconfig:"BLOCK_PRODUCER"`
	ShelleyVRFKey                 string `yaml:"shelleyVrfKey"                      envconfig:"SHELLEY_VRF_KEY"`
	ShelleyKESKey                 string `yaml:"shelleyKesKey"                      envconfig:"SHELLEY_KES_KEY"`
	ShelleyOperationalCertificate string `yaml:"shelleyOperationalCertificate"      envconfig:"SHELLEY_OPERATIONAL_CERTIFICATE"`
	ForgeSyncToleranceSlots       uint64 `yaml:"forgeSyncToleranceSlots"            envconfig:"DINGO_FORGE_SYNC_TOLERANCE_SLOTS"`
	ForgeStaleGapThresholdSlots   uint64 `yaml:"forgeStaleGapThresholdSlots"        envconfig:"DINGO_FORGE_STALE_GAP_THRESHOLD_SLOTS"`
	// ForgePrimaryChainTipToleranceSlots bounds how far the ledger-applied tip
	// may trail this node's own primary chain tip before forging is skipped.
	// Raise it only if the ledger pipeline is legitimately slow on this
	// deployment; raising it lets the node forge blocks whose contents were
	// chosen against an older chain position than their parent.
	ForgePrimaryChainTipToleranceSlots uint64 `yaml:"forgePrimaryChainTipToleranceSlots" envconfig:"DINGO_FORGE_PRIMARY_CHAIN_TIP_TOLERANCE_SLOTS"`
	// ForgeUpstreamStalenessSlots bounds how far the newest block this node
	// holds may trail the corroborated upstream sync target before forging is
	// skipped. 0 (the default) disables it.
	//
	// Opt-in because the comparison is not like-for-like: the newest block
	// this node holds is a BLOCK, while the upstream target is published when
	// a HEADER is admitted, so the two differ by the inter-block gap during
	// ordinary operation. Set it well above the expected gap for the network.
	ForgeUpstreamStalenessSlots uint64 `yaml:"forgeUpstreamStalenessSlots"        envconfig:"DINGO_FORGE_UPSTREAM_STALENESS_SLOTS"`
	// ForgeAppliedTipStalenessSlots bounds how many slots older than the
	// current slot the newest block this node holds may be before forging is
	// skipped. 0 (the default) disables this wall-clock backstop; it is
	// off by default because on a low-throughput chain a fixed bound refuses
	// constantly. Set it only where the block interval is known and bounded.
	ForgeAppliedTipStalenessSlots uint64 `yaml:"forgeAppliedTipStalenessSlots"      envconfig:"DINGO_FORGE_APPLIED_TIP_STALENESS_SLOTS"`
	// ForgeEndorserBlockStalenessSlots bounds how far a corroborated Leios
	// endorser block may lead the ledger-applied tip before forging is
	// skipped. 0 (the default) disables it.
	//
	// Opt-in and separate from ForgePrimaryChainTipToleranceSlots, which
	// bounds a purely local block-against-block comparison. This one compares
	// a network-stage announcement watermark against a local applied tip, and
	// that watermark is monotonic and never lowered, so an always-on bound
	// sharing the local tolerance would tie two unrelated risk budgets to one
	// number and could withhold leader slots indefinitely.
	ForgeEndorserBlockStalenessSlots uint64 `yaml:"forgeEndorserBlockStalenessSlots"   envconfig:"DINGO_FORGE_ENDORSER_BLOCK_STALENESS_SLOTS"`
	// ValidateForgedBlock self-validates locally-forged blocks before
	// adoption and diffusion. Defaults to true (fail closed); set to false
	// only to explicitly opt out.
	ValidateForgedBlock bool `yaml:"validateForgedBlock"                envconfig:"DINGO_VALIDATE_FORGED_BLOCK"`

	// MinPoolMargin is the CIP-23 minimum pool margin (minimum variable fee) in
	// basis points, [0, 10000] (150 = 1.5%); 0 disables it. Consensus-affecting
	// and off by default; effective only in Dijkstra and later. Enable a nonzero
	// value only where every node also enables the same value. See
	// ARCHITECTURE.md ("Reward Calculation And Precomputation").
	MinPoolMargin uint `yaml:"minPoolMargin"                          envconfig:"DINGO_MIN_POOL_MARGIN"`
	// CIP-50 pledge-leverage staking rewards. Consensus-affecting; defaults
	// off. PledgeLeverageEnabled turns on the L*pledge reward cap and
	// PledgeLeverage is L in [1, 10000]. Enable only on a network where every
	// node also enables it. See ARCHITECTURE.md ("Reward Calculation And
	// Precomputation").
	PledgeLeverageEnabled bool `yaml:"pledgeLeverageEnabled"                  envconfig:"DINGO_PLEDGE_LEVERAGE_ENABLED"`
	PledgeLeverage        uint `yaml:"pledgeLeverage"                         envconfig:"DINGO_PLEDGE_LEVERAGE"`
	// CIP-0163 full-pot reward distribution. Consensus-affecting; defaults
	// off. When enabled the entire epoch reward pot is distributed to eligible
	// pools and delegators instead of returning the residual to reserves.
	// Enable only on a network where every node also enables it. See
	// ARCHITECTURE.md ("Reward Calculation And Precomputation").
	FullPotRewardsEnabled bool `yaml:"fullPotRewardsEnabled"                  envconfig:"DINGO_FULL_POT_REWARDS_ENABLED"`
	// UnsafeFullPotRewardsOnStandardNetworks is an explicit unsafe override
	// for running CIP-0163 full-pot rewards on predefined public networks.
	// Leave false except for controlled off-consensus experiments.
	UnsafeFullPotRewardsOnStandardNetworks bool `yaml:"unsafeFullPotRewardsOnStandardNetworks" envconfig:"DINGO_UNSAFE_FULL_POT_REWARDS_ON_STANDARD_NETWORKS"`
	// CIP-0163 reward-account inactivity expiry. Consensus-affecting; defaults
	// off. See ARCHITECTURE.md ("Stake Snapshots", CIP-0163 reward-account
	// inactivity).
	DelegatorInactivityEnabled bool   `yaml:"delegatorInactivityEnabled"             envconfig:"DINGO_DELEGATOR_INACTIVITY_ENABLED"`
	DelegatorInactivity        uint64 `yaml:"delegatorInactivity"                    envconfig:"DINGO_DELEGATOR_INACTIVITY"`

	// Leios voting configuration (experimental, leios runMode only).
	// LeiosVoteSigningKeyFile is the path to a Cardano text-envelope
	// BLS12-381 vote signing key (or a legacy raw hex scalar). When set on
	// a block producer whose pool is a committee member, the node emits
	// Leios votes for endorser blocks.
	LeiosVoteSigningKeyFile string `yaml:"leiosVoteSigningKeyFile" envconfig:"DINGO_LEIOS_VOTE_SIGNING_KEY_FILE"`

	// PeerSharing enables the peer sharing protocol, allowing this node
	// to advertise known peers to other nodes on request. Pointer
	// distinguishes "operator did not set this" (nil) from "explicitly
	// false". On a block producer the resolved default is false unless
	// this field is explicitly set to true.
	PeerSharing *bool `yaml:"peerSharing" envconfig:"DINGO_PEER_SHARING"`

	// Storage mode: "core" (default) or "api".
	// "core" stores only consensus data
	// (UTxOs, certs, pools, pparams).
	// "api" additionally stores witnesses, scripts,
	// datums, redeemers, and tx metadata.
	// APIs (blockfrost, utxorpc, mesh) require
	// "api" mode.
	StorageMode string `yaml:"storageMode" envconfig:"DINGO_STORAGE_MODE"`

	// Mithril snapshot bootstrap configuration
	Mithril MithrilConfig `yaml:"mithril"`

	// Database lifecycle (snapshot/restore/truncate) configuration
	DatabaseLifecycle DatabaseLifecycleConfig `yaml:"databaseLifecycle"`
	// contains filtered or unexported fields
}

type DatabaseLifecycleConfig struct {
	// SnapshotEnabled controls whether automatic epoch-boundary database
	// snapshots are captured. It is unsupported when the primary blob provider
	// is s3 or gcs because their backup walk would hold the commit barrier for
	// an unbounded remote-object read. Manual snapshots via the CLI are always
	// available regardless of this setting.
	SnapshotEnabled bool `yaml:"snapshotEnabled"                envconfig:"DINGO_DB_LIFECYCLE_SNAPSHOT_ENABLED"`
	// SnapshotDir is the local filesystem directory automatic snapshots
	// are written under (one subdirectory per snapshot). Required if
	// SnapshotEnabled is true.
	SnapshotDir string `yaml:"snapshotDir"                    envconfig:"DINGO_DB_LIFECYCLE_SNAPSHOT_DIR"`
	// SnapshotCloudDestination optionally mirrors every snapshot (manual
	// or automatic) to an object-storage location in addition to
	// SnapshotDir, as a URI: s3://<bucket>/<prefix> or
	// gcs://<bucket>/<prefix> (matching the scheme
	// database/plugin/blob/gcs already uses, not gs://). Requires dingo to
	// be built with the dingo_extra_plugins tag. Empty disables cloud
	// upload. Credentials are resolved from the ambient AWS/GCS SDK
	// credential chain (env vars, IAM role, ADC, etc.) — there is no
	// separate credential config here, matching how the existing s3/gcs
	// blob store plugins work.
	//
	// Each snapshot is uploaded under its own sub-path — <this URI>/
	// <snapshotID> — not flat directly under this URI, so more than one
	// snapshot can exist at the same configured destination without
	// overwriting each other. Restore accepts that same per-snapshot URI
	// directly in place of a local snapshot directory: it downloads the
	// snapshot into a local temp directory first, then proceeds exactly
	// as a local restore. This is also how a snapshot created on one node
	// can be restored onto another.
	SnapshotCloudDestination string `yaml:"snapshotCloudDestination"       envconfig:"DINGO_DB_LIFECYCLE_SNAPSHOT_CLOUD_DESTINATION"`
	// SnapshotCloudDestinationPrefix is an additional path segment appended
	// after SnapshotCloudDestination and before each snapshot's own ID
	// (e.g. epoch-<N> for automatic snapshots), so multiple nodes can point
	// at the very same SnapshotCloudDestination (a shared disaster-recovery
	// bucket, say) without their automatic epoch-boundary snapshots
	// colliding at the same remote key: every node captures its epoch-<N>
	// snapshot under the identical deterministic name, so without a
	// distinct prefix per node, two nodes sharing one destination would
	// race to upload to the same path, and an interleaving could even
	// leave one node's manifest.json paired with another node's backup
	// files at the same remote location. Leave unset for a single node (or
	// multiple nodes each already using distinct SnapshotCloudDestination
	// values); operators sharing one destination across nodes must set
	// this to a distinct value per node.
	SnapshotCloudDestinationPrefix string `yaml:"snapshotCloudDestinationPrefix" envconfig:"DINGO_DB_LIFECYCLE_SNAPSHOT_CLOUD_DESTINATION_PREFIX"`
	// SnapshotRetention is the number of most-recent automatic snapshots
	// to keep before pruning older ones. Zero keeps all of them.
	SnapshotRetention int `yaml:"snapshotRetention"              envconfig:"DINGO_DB_LIFECYCLE_SNAPSHOT_RETENTION"`
	// SnapshotEveryNEpochs captures an automatic snapshot every N epoch
	// boundaries instead of every single one.
	SnapshotEveryNEpochs int `yaml:"snapshotEveryNEpochs"           envconfig:"DINGO_DB_LIFECYCLE_SNAPSHOT_EVERY_N_EPOCHS"`
}

type GenesisBootstrapConfig struct {
	// Enabled controls whether Genesis bootstrap mode is used when the node
	// starts from origin.
	Enabled bool `yaml:"enabled"                     envconfig:"DINGO_GENESIS_BOOTSTRAP_ENABLED"`
	// WindowSlots overrides the Genesis density comparison window in slots.
	// A zero value derives the window from Shelley genesis parameters (3k/f).
	WindowSlots uint64 `yaml:"windowSlots"                 envconfig:"DINGO_GENESIS_BOOTSTRAP_WINDOW_SLOTS"`
	// PromotionMinDiversityGroups sets the minimum number of diversity groups
	// to prefer while promoting peers during bootstrap.
	PromotionMinDiversityGroups int `yaml:"promotionMinDiversityGroups" envconfig:"DINGO_GENESIS_BOOTSTRAP_PROMOTION_MIN_DIVERSITY_GROUPS"`
	// CorroborationPeers sets the number of independent peers that must report
	// the same recent blocks before a fast (shallow) block source may drive
	// Genesis-mode chain selection. This is the Ouroboros Genesis trust control
	// for biased fast-sync sources: an uncorroborated or divergent fast source
	// is denied selection and stalls rather than steering the local chain. A
	// zero value disables corroboration (density-only Genesis selection).
	CorroborationPeers int `yaml:"corroborationPeers"          envconfig:"DINGO_GENESIS_BOOTSTRAP_CORROBORATION_PEERS"`
}

type HistoryExpiryConfig struct {
	// Enabled starts the background expiry worker when true.
	Enabled bool `yaml:"enabled"   envconfig:"DINGO_HISTORY_EXPIRY_ENABLED"`
	// Frequency controls how often the worker scans for expired block CBOR.
	Frequency time.Duration `yaml:"frequency" envconfig:"DINGO_HISTORY_EXPIRY_FREQUENCY"`
}

type KoiosParityConfig struct {
	// Enabled subscribes the observer to epoch.transition when true.
	Enabled bool `yaml:"enabled"              envconfig:"DINGO_KOIOS_PARITY_ENABLED"`
	// Network is the Koios network to validate against: "preview" or
	// "preprod". Empty defaults to the node's own configured Network.
	Network string `yaml:"network"              envconfig:"DINGO_KOIOS_PARITY_NETWORK"`
	// CachePath is the Koios reference cache.db path. Empty defaults to
	// {DatabasePath}/.koios/cache.db, matching cmd/koios-parity's own
	// default cache location.
	CachePath string `yaml:"cachePath"            envconfig:"DINGO_KOIOS_PARITY_CACHE_PATH"`
	// APIKey is the Koios Bearer token for higher-rate-limit access. Empty
	// uses Koios's unauthenticated rate limit.
	APIKey string `yaml:"apiKey"               envconfig:"DINGO_KOIOS_PARITY_API_KEY"`
	// BaseURL overrides the public koios.rest host for the network, for a
	// self-hosted or mirrored Koios instance. Full v1 API root, e.g.
	// "https://preview-koios.example.com/api/v1". Empty selects the public
	// host. A custom host is not subject to the public tier's burst cap; see
	// koiosparity.NewKoiosClient.
	BaseURL string `yaml:"baseUrl"              envconfig:"DINGO_KOIOS_PARITY_BASE_URL"`
	// AllowInsecureHTTP permits a plain-HTTP BaseURL. The client attaches the
	// APIKey as a Bearer token to every request, so cleartext transport would
	// expose it, and the reference data this tool compares against would be
	// tamperable in flight -- a MITM could induce a false PASS. Local dev and
	// test only, mirroring Mithril.AllowInsecureHTTP.
	AllowInsecureHTTP bool `yaml:"allowInsecureHttp"    envconfig:"DINGO_KOIOS_PARITY_ALLOW_INSECURE_HTTP"`
	// Strict stops/cancels the node on the first Koios/tool error or exact
	// parity mismatch, rather than logging it and continuing normal node
	// operation.
	Strict bool `yaml:"strict"               envconfig:"DINGO_KOIOS_PARITY_STRICT"`
	// GraceHours is the window after an epoch closes during which a
	// Dingo-side row still missing is treated as reference/sync lag rather
	// than a failure. 0 selects the default (24).
	GraceHours int `yaml:"graceHours"           envconfig:"DINGO_KOIOS_PARITY_GRACE_HOURS"`
	// Accounts additionally runs #3097's per-account exact-parity fetch+check
	// phase for every epoch the observer processes, alongside the existing
	// epoch-aggregate/pool phases. Defaults to true (see
	// DefaultKoiosParityConfig): the in-process observer is the
	// operationally-real, continuously-driven path #3098 exists to make
	// possible, unlike the standalone koios-parity CLI's `--accounts` flag,
	// which stays opt-in-only for cost/compatibility reasons (see
	// cmd/koios-parity's addAccountsFlag). Set false explicitly to keep the
	// observer pool-level-only, e.g. to bound Koios request volume on a
	// resource-constrained deployment.
	Accounts bool `yaml:"accounts"             envconfig:"DINGO_KOIOS_PARITY_ACCOUNTS"`
	// AccountChunkSize/AccountChunkMaxBytes (dingo #3099) bound each
	// /account_reward_history request issued by the Accounts phase above, by
	// both address count and encoded body size. 0 for either selects the
	// package default (koiosparity.koiosAccountChunkSize/
	// koiosAccountChunkMaxBytesDefault). Unused when Accounts is false.
	AccountChunkSize     int `yaml:"accountChunkSize"     envconfig:"DINGO_KOIOS_PARITY_ACCOUNT_CHUNK_SIZE"`
	AccountChunkMaxBytes int `yaml:"accountChunkMaxBytes" envconfig:"DINGO_KOIOS_PARITY_ACCOUNT_CHUNK_MAX_BYTES"`
}

type LoggingConfig struct {
	// Format selects the log output handler: "text" (default) or "json".
	// JSON is intended for machine-parseable ingestion (ELK/Loki).
	Format string `yaml:"format" envconfig:"DINGO_LOGGING_FORMAT"`
	// Level is the minimum log level: "debug", "info" (default), "warn",
	// or "error". The --debug flag, when set, overrides this to "debug".
	Level string `yaml:"level"  envconfig:"DINGO_LOGGING_LEVEL"`
}

type MidnightConfig struct {
	// Enabled opts into running the Midnight indexer. Default false: an
	// api-mode deployment that wants Midnight indexing must set this
	// explicitly.
	Enabled bool `yaml:"enabled"           envconfig:"DINGO_MIDNIGHT_ENABLED"`
	// ServerEnabled independently opts into the Midnight gRPC listener.
	// Indexing and serving persisted Midnight rows are separate operations.
	ServerEnabled bool `yaml:"serverEnabled"     envconfig:"DINGO_MIDNIGHT_SERVER_ENABLED"`
	// ReflectionEnabled exposes gRPC service discovery when the server is
	// enabled. It defaults off because reflection broadens the public surface.
	ReflectionEnabled bool   `yaml:"reflectionEnabled" envconfig:"DINGO_MIDNIGHT_REFLECTION_ENABLED"`
	Port              uint   `yaml:"port"              envconfig:"DINGO_MIDNIGHT_PORT"`
	Host              string `yaml:"host"              envconfig:"DINGO_MIDNIGHT_HOST"`

	CNightPolicyID              string `yaml:"cnightPolicyId"`
	CNightAssetName             string `yaml:"cnightAssetName"`
	MappingValidatorAddress     string `yaml:"mappingValidatorAddress"`
	AuthTokenPolicyID           string `yaml:"authTokenPolicyId"`
	AuthTokenAssetName          string `yaml:"authTokenAssetName"`
	CommitteeCandidateAddress   string `yaml:"committeeCandidateAddress"`
	TechnicalCommitteeAddress   string `yaml:"technicalCommitteeAddress"`
	TechnicalCommitteePolicyID  string `yaml:"technicalCommitteePolicyId"`
	CouncilAddress              string `yaml:"councilAddress"`
	CouncilPolicyID             string `yaml:"councilPolicyId"`
	PermissionedCandidatePolicy string `yaml:"permissionedCandidatePolicy"`
}

type MithrilConfig struct {
	// Enabled controls whether Mithril integration is available.
	Enabled bool `yaml:"enabled"                envconfig:"DINGO_MITHRIL_ENABLED"`
	// AggregatorURL overrides the default aggregator URL for the network.
	// If empty, the URL is auto-detected from the configured network.
	AggregatorURL string `yaml:"aggregatorUrl"          envconfig:"DINGO_MITHRIL_AGGREGATOR_URL"`
	// AllowInsecureHTTP permits AggregatorURL and the snapshot artifact
	// locations the aggregator returns to use plain HTTP instead of
	// HTTPS. Defaults to false; this is an explicit escape hatch for
	// local development and tests against a plaintext aggregator and
	// should not be enabled in production.
	AllowInsecureHTTP bool `yaml:"allowInsecureHttp"      envconfig:"DINGO_MITHRIL_ALLOW_INSECURE_HTTP"`
	// Backend selects the Mithril artifact backend: "v2" (default) uses
	// incremental Cardano database artifacts; "v1" uses the legacy full
	// snapshot archives, which upstream Mithril is phasing out.
	Backend string `yaml:"backend"                envconfig:"DINGO_MITHRIL_BACKEND"`
	// DownloadDir is the directory where snapshot archives are downloaded.
	// If empty, a randomized temporary directory is created automatically.
	DownloadDir string `yaml:"downloadDir"            envconfig:"DINGO_MITHRIL_DOWNLOAD_DIR"`
	// DownloadIdleTimeout is the maximum idle time to wait for snapshot
	// response headers or body bytes before retrying. Empty uses the
	// downloader default; a negative duration disables idle detection.
	DownloadIdleTimeout string `yaml:"downloadIdleTimeout"    envconfig:"DINGO_MITHRIL_DOWNLOAD_IDLE_TIMEOUT"`
	// DownloadMaxIdleRetries is the number of consecutive idle retries
	// allowed without additional bytes. Zero uses the downloader default.
	DownloadMaxIdleRetries int `yaml:"downloadMaxIdleRetries" envconfig:"DINGO_MITHRIL_DOWNLOAD_MAX_IDLE_RETRIES"`
	// CleanupAfterLoad controls whether temporary files are removed
	// after the ImmutableDB has been loaded.
	CleanupAfterLoad bool `yaml:"cleanupAfterLoad"       envconfig:"DINGO_MITHRIL_CLEANUP"`
	// VerifyCertificates enables STM certificate-chain verification during
	// bootstrap. When true, bootstrap requires the Cardano network config's
	// pinned Mithril genesis verification key and verifies the chain back to it.
	// False explicitly selects the unverified bootstrap flow.
	VerifyCertificates bool `yaml:"verifyCertificates"     envconfig:"DINGO_MITHRIL_VERIFY_CERTS"`
}

type OffchainMetadataConfig struct {
	// Interval controls how often the fetcher discovers and fetches due rows.
	Interval time.Duration `yaml:"interval"              envconfig:"DINGO_OFFCHAIN_METADATA_INTERVAL"`
	// RequestTimeout limits each HTTP(S) metadata request.
	RequestTimeout time.Duration `yaml:"requestTimeout"        envconfig:"DINGO_OFFCHAIN_METADATA_REQUEST_TIMEOUT"`
	// UserAgent is sent with outbound metadata requests.
	UserAgent string `yaml:"userAgent"             envconfig:"DINGO_OFFCHAIN_METADATA_USER_AGENT"`
	// IPFSGatewayURL is the gateway prefix used for ipfs:// URLs.
	IPFSGatewayURL string `yaml:"ipfsGatewayUrl"        envconfig:"DINGO_OFFCHAIN_METADATA_IPFS_GATEWAY_URL"`
	// BatchSize bounds the number of due rows claimed per fetcher pass.
	BatchSize int `yaml:"batchSize"             envconfig:"DINGO_OFFCHAIN_METADATA_BATCH_SIZE"`
	// MaxBytes bounds the response body bytes read from each document.
	MaxBytes int64 `yaml:"maxBytes"              envconfig:"DINGO_OFFCHAIN_METADATA_MAX_BYTES"`
	// AllowPrivateAddresses permits fetching private, loopback, and link-local
	// addresses. Leave false for the default SSRF guard.
	AllowPrivateAddresses bool `yaml:"allowPrivateAddresses" envconfig:"DINGO_OFFCHAIN_METADATA_ALLOW_PRIVATE_ADDRESSES"`
}

type PluginsConfig struct {
	Storage StoragePluginsConfig `yaml:"storage"`
	Mempool hostplugin.Selection `yaml:"mempool"`
	API     APIPluginsConfig     `yaml:"api"`
}

type Provenance map[string]Source

type RunMode string

type Source int

type StartEra string

type StoragePluginsConfig struct {
	Blob     hostplugin.Selection `yaml:"blob"`
	Metadata hostplugin.Selection `yaml:"metadata"`
}

type TokenRegistryConfig struct {
	// Enabled turns the sync on. Only effective in API storage mode.
	Enabled bool `yaml:"enabled"               envconfig:"DINGO_TOKEN_REGISTRY_ENABLED"`
	// SourceURL overrides the network-derived registry tarball URL, for
	// operators running a mirror. Empty selects by network: the Cardano
	// Foundation registry for mainnet, the IOG testnet registry otherwise.
	SourceURL string `yaml:"sourceUrl"             envconfig:"DINGO_TOKEN_REGISTRY_SOURCE_URL"`
	// Interval controls how often the registry is re-checked. Each check
	// is a conditional request, so an unchanged registry costs no download.
	// Values below one minute are raised to it.
	Interval time.Duration `yaml:"interval"              envconfig:"DINGO_TOKEN_REGISTRY_INTERVAL"`
	// RequestTimeout bounds the whole download, not one request round trip.
	RequestTimeout time.Duration `yaml:"requestTimeout"        envconfig:"DINGO_TOKEN_REGISTRY_REQUEST_TIMEOUT"`
	// UserAgent is sent with the registry request.
	UserAgent string `yaml:"userAgent"             envconfig:"DINGO_TOKEN_REGISTRY_USER_AGENT"`
	// MaxBytes bounds the compressed registry download.
	MaxBytes int64 `yaml:"maxBytes"              envconfig:"DINGO_TOKEN_REGISTRY_MAX_BYTES"`
	// MaxEntryBytes bounds a single registry mapping document.
	MaxEntryBytes int64 `yaml:"maxEntryBytes"         envconfig:"DINGO_TOKEN_REGISTRY_MAX_ENTRY_BYTES"`
	// StoreLogos persists base64 logo payloads, which are roughly 90% of
	// registry bytes. Off by default; text properties are what wallets need.
	StoreLogos bool `yaml:"storeLogos"            envconfig:"DINGO_TOKEN_REGISTRY_STORE_LOGOS"`
	// AllowPrivateAddresses permits syncing from private, loopback, and
	// link-local addresses. Leave false for the default SSRF guard.
	AllowPrivateAddresses bool `yaml:"allowPrivateAddresses" envconfig:"DINGO_TOKEN_REGISTRY_ALLOW_PRIVATE_ADDRESSES"`
}