Zingod is a Zcash indexer written in Rust. zingod follows the chain from one or more trusted
validators (Zebra or
Zakura) and, optionally, Zcash p2p peers,
builds its own indexes, and serves light wallets over the lightwalletd-compatible
CompactTxStreamer gRPC service.
Validation stays in the validator and indexing moves to Zingod: the two run as separate processes, on separate hosts if you like, and a new index needs no change to the validator (who owns what).
You need a Zebra or Zakura node with JSON-RPC enabled ([rpc] listen_addr in zebrad.toml or
zakurad.toml). Zingod trusts it for validation and reads every block from it, through the
Zcash JSON-RPC interface that https://zcash.github.io/rpc/ specifies
(the methods Zingod calls).
1. Write a config. Every key at its default:
docker run --rm zingodevops/zingod generate-config -o /dev/stdout > zingod.tomlSet network (mainnet, testnet or regtest) and point [[trusted_validators]]
jsonrpc_address at your validator. Everything else can stay as it is; the
annotated config explains each key.
2. Run it. The image runs as UID 1000, keeps its indexes under /var/lib/zingod and serves
gRPC on 8137:
docker run -d --name zingod -p 8137:8137 \
-v ./zingod.toml:/etc/zingod/zingod.toml:ro \
-v zingod-data:/var/lib/zingod \
zingodevops/zingod3. Wait for the indexes. The first start builds every index from the validator: about an hour
on NVMe with the validator on the same host, longer over a network. Or skip the sync and
bootstrap from a snapshot. The gRPC port also answers plain HTTPS
(self-signed by default): /status reports the state (syncing,
then serving) and the tip, and /readyz is 200 once wallets can be served:
curl -sk https://localhost:8137/status
curl -skf https://localhost:8137/readyz && echo servingPoint a light wallet at localhost:8137. Running zingod covers the rest:
TLS, the admin listener and metrics, p2p peers, zingod hold for maintenance, systemd, and what
to expose to the internet. Docker covers volumes, TLS mounts and Compose.
Without a container (protoc on PATH):
cargo install --locked --git https://github.com/zingolabs/zingod zingod
zingod generate-config # writes $XDG_CONFIG_HOME/zingod/zingod.toml; edit it
zingod startDeveloping: cargo nextest run --workspace runs the unit tests with no validator; see
CONTRIBUTING.md and Testing.
Zingod reads nothing from a previous indexer's install: its config, data directory and metrics are its own. The changelog lists every config key and metric family.
-
Write a config with
zingod generate-configand set your validator's address and credentials. An unknown key refuses to start. -
Give it an empty data directory:
/var/lib/zingodin the image,$XDG_CACHE_HOME/zingodon a host. Zingod keeps one directory per index underindexes/. -
Either let the first start sync from your validator, or download the indexes: with a fast connection, a published snapshot bootstraps every index before boot. Add to
zingod.toml:[snapshot] manifest = "https://snapshots.zingolabs.dev/mainnet/manifest.json"
The image ships the downloader (
aria2c); on a host install it must be onPATH. Only empty index directories are filled, each archive's hash is checked, and a restart resumes (index snapshot). -
Point dashboards at the
zingod_*families. Zingod serves gRPC only; node JSON-RPC goes to the validator.
- Architecture: start here. How the pieces fit and why.
- Running zingod: configuration, states, hold, systemd, network exposure.
- RPC API: the methods served and the status codes a client must tell apart.
- What the clients actually call: the two wallet sync engines.
- Docker, Testing, Updating Zebra, Glossary.
- CONTRIBUTING.md, RELEASING.md, live-test guidelines.
Report security issues privately, never in a public issue: see CONTRIBUTING.md.
Apache License 2.0; see LICENSE.