Configuration
Zingod reads one TOML file: $XDG_CONFIG_HOME/zingod/zingod.toml, or the path given with -c.
zingod generate-config writes a file with every key at its default.
Settings are applied in this order, later ones winning:
- Built-in defaults.
- The config file.
- Environment variables prefixed
ZINGOD_CONFIG_, with__between nested keys. For example,ZINGOD_CONFIG_SYNC__CONCURRENCY=64setsconcurrencyunder[sync].
Every subcommand validates the whole config and refuses to run on an unknown key or invalid value.
Default paths are under the XDG base directories. If there is no home directory (for example,
HOME unset under a service manager), set each path explicitly: serve.state_dir, the path of
every enabled index, and p2p.cache_dir if [p2p] is enabled.
Overview
| Key or table | Purpose |
|---|---|
network | mainnet (default), testnet or regtest |
validator_client | how Zingod talks to validators (below) |
[[trusted_validators]] | one table per validator: address, credentials, timeouts, connection budget, priority |
[submission] | how SendTransaction retries relaying |
[p2p] | Zingod’s own Zcash p2p peers (off by default) |
[serve] | gRPC listen address, TLS, gRPC-web, state directory, drain delay |
[grpc] | connection and stream limits, timeouts, trusted proxies, overload thresholds |
[metrics] | admin listener for metrics and probes (off by default) |
[sync] | block fetching and finality depth |
[index.<name>] | per index: enabled and path |
[snapshot] | bootstrap empty indexes from an index snapshot |
Trusted validators do not vote. Each one adds failover, so two validators survive one going down.
At least one index must be enabled. utxo_set is enabled together with compact_block.
Validator client
validator_client sets how Zingod talks to every trusted validator:
legacy_rpc(default): JSON-RPC for everything. Works with zebrad, zakurad and zcashd.grpc: blocks over zebrad’s indexer gRPC at each validator’sindexer_address, everything else over JSON-RPC. Requires a zebrad build whose indexer servesGetBlockRange(Zingod’s Zebra fork; stock zebrad does not). Do not use it with zakurad, whoseGetBlockRangereturns a different message type.
The indexer gRPC connection is plaintext unless [trusted_validators.indexer_tls] configures
mutual TLS.
Reference
Every key, with its default and a description. This is the
Public Testnet zingod.toml
(download).
# zingod config paired with zebrad.toml (Testnet)
#
# - Env overrides + unknown-key rule: https://zingolabs.github.io/zingod/operators/configuration.html
# - `zingod generate-config` = every key at its default
# mainnet | testnet | regtest (default mainnet)
# - declared, never read off the validator (Zebra on regtest reports "test")
network = "testnet"
# How zingod talks to every [[trusted_validators]] entry (default legacy_rpc)
# - legacy_rpc = JSON-RPC for everything (zebrad, zakurad or zcashd); blocks arrive as hex inside
# JSON
# - grpc = blocks over zebrad's indexer gRPC (GetBlock, GetBlockRange) as stored bytes, no hex
# or JSON; everything else over JSON-RPC. Needs each validator's indexer_address and a zebrad
# serving GetBlockRange: Zingod's zebra fork only (elicbarbieri/zebra perf/indexer-block-range)
# validator_client = "grpc"
# Admin listener (/metrics, /livez, /readyz). Omit listen_address to disable.
# [metrics]
# listen_address = "127.0.0.1:9999"
# Validators Zingod trusts (Zebra or Zakura JSON-RPC), at least one; no vote (`priority` orders who
# is asked)
# - tip = their most-work header (trusted: zebra validated it), served while any of them holds it
# - one listing admits a mempool transaction; submission: see [submission]
# - 2+ = survives one going down (no vote: more never weakens it)
# - down at boot or later = retried, never fatal
[[trusted_validators]]
jsonrpc_address = "127.0.0.1:18232"
# No credentials + a loopback address = no auth until the validator refuses, then its default
# cookie: <cache dir>/zebra/.cookie or <cache dir>/zakura/.cookie (both = the one written last)
# cookie_path = "<PATH_TO_ZEBRA>/.cookie"
# basic auth
# user = "xxxxxx"
# password = "xxxxxx"
# connect_timeout_secs = 2
# Silence before a request fails, never total duration (raise for a slow or lossy link)
# read_timeout_secs = 30
# Link budget to this validator (zingod never exceeds it): at least 5 connections, one for the poll,
# one reserved per lane (control, interactive, bulk) + one shared, the rest to whichever lane
# waits
# max_connections = 32
# Largest JSON-RPC reply read, 4 (one full block) ..= 32; batches are split to fit
# max_response_mib = 32
# zebrad's indexer gRPC (its `indexer_listen_addr`): tip + mempool push streams wake polling at
# once; polling slows to a 15 s reconcile while they are up. Unset = poll every second.
# validator_client = "grpc" fetches blocks here too (then required)
# indexer_address = "127.0.0.1:8230"
# Tier: every 0 asked before any 1 (a farther validator = 1: overflow + hedges only)
# priority = 0
# Mutual TLS to indexer_address (zakurad requires it off loopback: its [rpc.indexer_tls], whose
# client_ca_file signs cert_path). Unset = plaintext.
# [trusted_validators.indexer_tls]
# ca_path = "/etc/zingod/indexer-ca.pem"
# cert_path = "/etc/zingod/indexer-client.pem"
# key_path = "/etc/zingod/indexer-client-key.pem"
# Name on the validator's certificate (unset = the indexer_address host)
# server_name = "zakura-1.internal"
# [[trusted_validators]]
# jsonrpc_address = "127.0.0.1:18242"
# SendTransaction: a trusted validator's checkadmission answers the wallet (refused = that
# refusal, nothing sent); then one relay per attempt, through a random trusted validator, or
# the peers with [p2p] on (defaults shown)
[submission]
# Seconds an accepted transaction gets to be seen beyond the nodes relayed to before relaying again
propagation_threshold_secs = 15
# Relays per transaction at most; without a check, the wallet is answered at the first acceptance
max_attempts = 4
# Zingod's own peers on the Zcash p2p network (zebra-network), off by default: headers and blocks
# (checked by proof of work and merkle root: the tip keeps up while every trusted validator is
# down; finality too, once peers in more than 5 netgroups carry the chain), each peer's mempool
# polled (a transaction > 2/3 of them list from > 5 netgroups is served after Zingod's consensus
# checks: needs index.compact_block), and SendTransaction relays (zebra's own, to a third of the
# peers per attempt; then one trusted validator if still unseen). Zingod serves no peer (listener
# on loopback, no services advertised).
# [p2p]
# enabled = true
# Each peer holds one inbound slot on a public node: keep it modest
# peer_target = 8
# Empty = the network's DNS seeders (regtest has none: list peers)
# initial_peers = []
# cache_dir = "<ZINGOD_DATA>/peers"
[serve]
# CompactTxStreamer gRPC over HTTP/2
grpc_listen_address = "127.0.0.1:8137"
# serve browser (gRPC-web) clients too: permissive CORS (*) on this listener, native gRPC
# untouched; refuse origins with `zingod origin`. off = no CORS, browsers refused
grpc_web = false
# Max transparent receives one address request walks (all its addresses); over = RESOURCE_EXHAUSTED
# max_address_rows = 100000
# zingod's own state, kept across restarts (`zingod hold` writes its marker here);
# default <data dir>/zingod/state
# state_dir = "/var/lib/zingod"
# held: /readyz fails with "held" while still serving this long, then every open gRPC connection
# gets a GOAWAY; >= the balancer's down detection + DNS TTL
hold_goaway_delay_secs = 0
# TLS: unset = "off" on a loopback grpc_listen_address, refused at boot on any other
# - { cert_path, key_path } = PEM files, re-read on change (renewal = no restart)
# - "off" = plaintext (a TLS-terminating proxy in front; warned at boot off loopback)
# - "self_signed" = pair generated under <state_dir>/tls at first boot (fingerprint logged; only a
# client that pins it connects)
# tls = { cert_path = "/etc/zingod/fullchain.pem", key_path = "/etc/zingod/key.pem" }
# Serving caps (defaults shown); every cap refuses rather than queues, except the read lanes
[grpc]
# excess accepts closed; + 1024 must fit the open-file limit or boot fails
max_connections = 4096
# per client: the peer, or the address a trusted proxy's PROXY header names
max_connections_per_ip = 128
# HTTP/2 SETTINGS_MAX_CONCURRENT_STREAMS: every stream on one connection, of any method (as
# lightwalletd's grpc-max-concurrent-streams)
max_streams_per_connection = 100
# work streams (every method but GetMempoolStream) across all connections; excess = UNAVAILABLE +
# retry hint
max_work_streams = 2048
# work streams admitted at once follow measured latency, max_work_streams the ceiling: a saturated
# node refuses new work within seconds (UNAVAILABLE + retry hint); false = always max_work_streams
adaptive_work_streams = true
# GetMempoolStream subscriptions (idle until the next block), counted apart from max_work_streams
max_subscriptions = 4096
# index reads in flight on the blocking pool, per lane; excess waits in its own lane
# - point: one block / tree state / root list; range: one GetBlockRange window; scan: one address
# history
max_point_reads = 64
max_range_reads = 32
max_scan_reads = 4
# no-progress bounds, never a cap on a stream's length (the client's grpc-timeout is its deadline)
# data its client does not read for this long closes its connection
unread_timeout_secs = 300
# a stream with nothing to send for this long ends UNAVAILABLE (GetMempoolStream exempt)
silent_timeout_secs = 300
# GOAWAY after this long (±10% per connection): the client reconnects and re-resolves DNS, so a
# load balancer or a replaced node moves long-held wallet connections; 0 = never
max_connection_age_secs = 1800
# in-flight streams of a GOAWAY'd connection get this long to finish (a whole GetBlockRange sync)
max_connection_age_grace_secs = 600
# GOAWAY a connection with no open stream for this long (frees its per-client slot); 0 = never
max_connection_idle_secs = 1800
# proxies that open every connection with a PROXY header (v1/v2)
# - https://zingolabs.github.io/zingod/operators/network.html#behind-a-proxy
trusted_proxies = []
# SIGTERM/SIGINT closes the listener at once; open connections get this long to finish (GOAWAY
# sent). Out of a load balancer's rotation first = `zingod hold`
# - https://zingolabs.github.io/zingod/operators/maintenance.html#operator-hold
shutdown_grace_secs = 10
# When /readyz reports `Overloaded: <cause>` (0 = that cause off; `zingod overload` overrides live)
[grpc.overload]
# share of each minute zingod's cgroup waited (Linux PSI)
cpu_pressure_percent = 25
io_pressure_percent = 25
# One block-fetch pipeline, shared by every index (defaults shown; all non-zero)
[sync]
# Blocks below the tip kept reorg-able (in memory, served, written once buried); >= 1000 off regtest
finalised_depth = 1000
# Block fetches (and folds) in flight ahead of the next one needed, over every trusted validator
concurrency = 32
# MiB of finalized blocks one index may lag the fetch before it throttles the pipeline
queue_mib = 256
# The disk engine's map tables (one engine per process: every index shares merge_slots)
# [sync.lsm_store]
# Same-tier segments merged into one (>= 2; higher = less rewriting, larger merges)
# fanout = 16
# Merges doing disk I/O at once (the rest wait, smallest first)
# merge_slots = 4
# MiB/s every merge together may read + write (commits are never paced)
# merge_mib_per_sec = 200
# One table per index: `enabled` (default true; off = its methods UNIMPLEMENTED) and `path`
# (default $XDG_DATA_HOME/zingod/indexes/<name>); an omitted table takes both defaults
[index.compact_block]
# GetBlock, GetBlockRange (GetLatestBlock, GetLightdInfo = the served tip, either way)
# - its fee index (each CompactTx.fee) lives beside it, in `utxo_set`
enabled = true
path = "<ZINGOD_DATA>/compact_block"
[index.block_hash]
# GetBlock / GetTreeState by hash (by height unaffected)
enabled = true
path = "<ZINGOD_DATA>/block_hash"
[index.tree_state]
# GetTreeState, GetLatestTreeState, GetSubtreeRoots
enabled = true
path = "<ZINGOD_DATA>/tree_state"
[index.transparent_address]
# GetAddressUtxos(+Stream), GetTaddressBalance(+Stream), GetTaddressTransactions
enabled = true
path = "<ZINGOD_DATA>/transparent_address"
[index.txid_location]
# GetTransaction / GetTaddressTransactions bytes with no validator answering: the block it names,
# fetched from p2p peers
enabled = true
path = "<ZINGOD_DATA>/txid_location"
# Fill empty indexes from a published snapshot before boot (aria2c on PATH)
# [snapshot]
# manifest = "https://snapshots.zingolabs.dev/zingod-snapshot-1.0.0/manifest.json"
# connections = 8 # total across every archive