Skip to content

Update Zaino page for current Zcash stack #2011

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Jeffrey978 wants to merge 1 commit into
base: main
Choose a base branch
from
+72 −9
Open

Update Zaino page for current Zcash stack #2011

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
81 changes: 72 additions & 9 deletions site/Zcash_Tech/Zaino.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,30 +1,93 @@
# Zaino Indexer

Zaino is an Indexer, developed in Rust by the Zingo team, that aims to replace lightwalletd and to push forward the zcashd deprecation project.
Zaino is a Rust indexer for the Zcash blockchain. It reads chain data from a Zebra full node and serves the data that wallets, explorers, faucets, and other services need without making Zebra itself responsible for every client-facing index.

Zaino offers essential features for both light clients, such as wallets and applications that do not require the full blockchain history, and full clients or wallets. It also supports block explorers, granting access to both the finalized blockchain and the non-finalized best chain and mempool managed by a Zebra or Zcashd full validator.
## TL;DR

## Why a new Indexer?
* **Zebra** validates the Zcash chain.
* **Zaino** indexes Zebra's chain data and exposes client-facing APIs.
* **Zallet** is the wallet component in the Z3 stack. In the default Z3 setup, Zallet talks to Zebra directly and does not require the standalone Zaino service.
* The standalone Zaino service is useful when operators need a lightwalletd-compatible gRPC endpoint, a JSON-RPC proxy, or infrastructure for light wallets, explorers, faucets, and similar services.
* Zaino is active infrastructure, but operators should check the official Zaino and Z3 documentation for current deployment details before running it in production.

The main reason is getting ready for the future. Zcashd and lightwalletd were built in 2016 forked from bitcoind code, using C plus. The platform and code used to build both services is starting to get old, difficult to scalate, maintain and to build modern features on.
## What Zaino Does

Rust is a modern, robust and secure language that allows Zcash to be prepared for future development, inviting new developers to build plenty of new functionality on and around the Zcash ecosystem.
Zaino sits between Zebra and client software. Zebra is the consensus node: it downloads, verifies, and follows the Zcash blockchain. Zaino uses Zebra as its source of chain data, then prepares indexed views that client applications can query efficiently.

Still, Zaino aims to be backwards compatible where possible, Providing APIs and interfaces that help to reduce friction in adoption and ensure that the broader Zcash ecosystem can benefit from Zainos enhancements without significant rewrites or learning curves.
This separation keeps the roles clear:

Also, Zaino will allow to separate light client functionality from the full node, via RPC access and a complete client library, allowing developers to integrate Zaino and access chain data directly from their light client application, keeping the sensitive data from Zebra node insulated and secure.
| Component | Role |
|:--|:--|
| Zebra | Full node and validator |
| Zaino | Indexer and client-facing API service |
| Zallet | Wallet service |
| lightwalletd | Older light wallet server that Zaino is designed to replace or complement |

Zaino provides functionality for light clients, full clients or wallets, and block explorers. It gives access to the finalized chain, the non-finalized best chain, and mempool data held by Zebra.

## How It Fits in the Current Zcash Stack

The current Z3 stack is built around Zebra, Zallet, and optional Zaino.

In the default Z3 deployment, Zebra and Zallet run together. Zallet reaches Zebra directly, so an operator running only a local wallet stack does not need to start the standalone Zaino service.

Zaino is added when the operator wants to serve external clients. In Z3, it runs behind the `indexer` Compose profile and adds:

* a lightwalletd-compatible gRPC endpoint for light wallet clients
* a JSON-RPC proxy for explorers, faucets, and service backends
* an indexer database separate from Zebra's chain state

This makes Zaino especially relevant for wallet backends, public infrastructure operators, explorers, faucets, and developers testing services that need indexed Zcash chain data.

## Zaino and lightwalletd

lightwalletd is the original light wallet server. Zaino is the Rust-based successor path for this role. Its goal is to provide compatible APIs where possible so wallets and services can migrate without being fully rewritten at once.

That does not mean every lightwalletd deployment has already moved to Zaino. Operators should treat Zaino as part of the current Zebra-based stack and check the latest project documentation, releases, and service dashboards before choosing what to run.

## Operator Notes

The easiest authoritative deployment path is the Z3 repository. Z3 includes Zaino as an optional service:

```bash
docker compose --env-file .env.<network> --profile indexer up -d
```

Run the normal Z3 setup first and wait for Zebra to sync before starting dependent services on mainnet or testnet.

Zaino exposes two kinds of network service. The gRPC service is the lightwallet-facing API. The JSON-RPC service is intended for loopback or trusted private networks unless an external layer provides protection. Do not expose an unauthenticated or unencrypted JSON-RPC endpoint to the public internet.

## Some diagrams showing how Zaino works

### Zaino Internal Architecture

![Zaino Internal Architecture](/content-images/image-2025-01-02-190143429-3f3cc78fa5.webp)

### Zaino Live Service Architecture

![Zebra Live Service Architecture](/content-images/image-2025-01-02-190349017-892cb409ea.webp)

### Zaino System Architecture

![Zaino System Architecture](/content-images/image-2025-01-02-190448037-1e4e675ccb.webp)

## Common Mistakes

**Treating Zaino as a full node.** Zaino is not the validator. Zebra validates the chain; Zaino indexes data from Zebra.

**Assuming every Z3 deployment needs standalone Zaino.** Zallet can reach Zebra directly in the default Z3 stack. Start Zaino when you need the standalone indexer service for external clients.

**Presenting planned features as already deployed.** Zaino is actively developed, so check the current release notes and docs before describing a feature as available.

**Exposing JSON-RPC carelessly.** Zaino's JSON-RPC interface is for loopback or trusted private networks unless protected by another layer.

## Where can I learn more?

* [Zaino GitHub repository](https://github.com/zingolabs/zaino)
* [Zaino releases](https://github.com/zingolabs/zaino/releases)
* [Zaino generated documentation](https://zingolabs.github.io/zaino/)
* [Z3 deployment repository](https://github.com/ZcashFoundation/z3)
* [Zebra documentation](https://zebra.zfnd.org/)
* [Zaino grant and project discussion](https://forum.zcashcommunity.com/t/zingo-labs-accelerates-zcashd-deprecation-with-zaino/48545)

## Where Can I learn more?
You can read more about Zaino Indexer in the official [Zcash Community Forum thread](https://forum.zcashcommunity.com/t/zingo-labs-accelerates-zcashd-deprecation/48545/38) or in its official [Github page](https://github.com/zingolabs/zaino)
**Last updated:** August 2026
Loading