Z3G: Zcash Z3 RPC Compatibility Gateway for zcashd Deprecation

Creativesonchain · January 2, 2026, 5:43pm

Project Summary

Z3G is an upstream-first, operator-grade JSON-RPC compatibility gateway that provides a single zcashd-style RPC endpoint for Zebra + Zaino, prioritizing the highest-demand non-wallet methods used by exchanges and mining pools. It reduces migration risk during zcashd deprecation by enforcing explicit compatibility contracts, regression tests, and secure-by-default deployment controls.

Project Description

Z3G is a migration-critical piece of infrastructure for Zcash: a JSON-RPC compatibility gateway that provides a single “zcashd-style” RPC endpoint while operators transition to the Z3 era (Zebra/zebrad for consensus and chain state, and Zaino for RPC services used by non-miner clients; wallet functionality is expected to live in Zallet and is out of scope for this project). Many exchanges, mining pools, explorers, and RPC providers are tightly coupled to the zcashd JSON-RPC interface today. Even with good documentation, upgrades can still fail in production because replacement services may split functionality across components, and some methods differ in response shape, supported fields, or error behavior. Z3G reduces upgrade risk by giving operators a clear, test-backed compatibility layer for a defined set of high-demand, non-wallet RPC methods, so they can migrate more safely and incrementally.

What Z3G does

Z3G runs as a small daemon (plus Docker image) deployed alongside Zebra and Zaino. It:

Exposes a single JSON-RPC endpoint designed to be compatible with common zcashd client expectations for the supported methods.
Routes each supported method to the correct upstream service (Zebra and/or Zaino).
Applies schema and error normalization so callers receive stable, documented outputs.
- Important: Z3G will not claim full parity where upstream support is partial. For any “partial” method, Z3G will explicitly document which fields/behaviors are available and which are not, and it will not fabricate missing data.
Publishes a method-by-method compatibility contract (accepted parameters, guaranteed output fields, intentionally missing fields, and expected error codes) and enforces it with tests.
Ships with a regression test suite that checks these contracts against pinned upstream versions, so compatibility doesn’t drift unnoticed.
Ships with secure-by-default operational controls (localhost bind by default, configurable auth for non-local deployments, rate limiting, request/batch size caps, upstream timeouts, and safe logging defaults).

Goals

Reduce production upgrade risk for economically critical operators (exchanges, pools, explorers, infrastructure RPC providers) during the zcashd → Z3 transition.
Enable incremental migration by allowing operators to keep existing RPC integrations for the supported method set while planning changes for methods that are out of scope or only partially supported.
Strengthen upstream readiness by delivering the missing “spec + tests + reference implementation” needed for a single-interface wrapper workstream (upstream-first delivery).
Avoid fragmentation by being explicit about scope and by prioritizing upstream contributions rather than maintaining a long-lived parallel interface.

Scope (v1)

Z3G intentionally focuses on the highest-demand, non-wallet RPC surface used by operators, starting with core chain/mempool/transaction-broadcast and operational RPCs. The exact method list is tied to the official RPC support tracking and its usage/score signals, rather than “best guesses.”

Out of Scope for this project:

No wallet RPC support (no keys, no signing, no wallet state). Wallet methods will return a deterministic “not supported; use Zallet” style error.
Not a devnet/CI bring-up tool (this project targets production integrations).
Not a new indexer/explorer backend (Z3G routes to upstream services and stabilizes the edge interface).

Upstream-first delivery approach

Z3G is designed to be merged upstream rather than maintained indefinitely as an external proxy. The project will deliver:

A concise design/spec defining routing, compatibility contracts, and test strategy.
A reference implementation of the gateway.
A contract-enforcing test suite suitable for CI and long-term regression protection.
Where small upstream changes are needed to meet a documented compatibility contract (e.g., consistent error shapes), Z3G will propose minimal, reviewable upstream patches rather than carrying forks.

Security and operational readiness

Because RPC endpoints are a real attack surface, Z3G treats operational safety as a first-class deliverable:

Safe defaults (localhost bind, conservative request limits, timeouts, no sensitive logging).
Optional authentication for any non-local deployment.
Rate limiting + concurrency caps to reduce abuse/DoS risk.
Abuse-case tests (burst traffic, oversized payloads, slow/upstream down, batch spam) included in CI.

What success looks like

Operators can deploy Z3G alongside Zebra + Zaino and keep the supported RPC method set functioning with minimal integration churn (often an endpoint/config change plus handling of documented “partial” fields where applicable).
A published compatibility matrix and per-method contracts make limitations explicit and test-enforced.
CI regression tests prevent compatibility drift as upstream evolves.
Early real-world validation through community operator trials (e.g., staging deployments by RPC providers, explorers, pools, or exchange test environments) demonstrates practical usefulness.

Proposed Problem

Zcash is in the middle of a high stakes infrastructure change. zcashd is being deprecated and operators are expected to migrate to the Z3 era stack, with Zebra or zebrad plus supporting services such as Zaino, and wallet functionality moving to Zallet. For economically critical operators such as exchanges, mining pools, explorers, and public RPC providers, this is not an upgrade they can treat as optional. Their production systems are tightly coupled to the zcashd JSON RPC interface and to the exact behaviors they have relied on for years.

The painful reality is that this migration is not always a drop in swap. In the replacement stack, some RPC methods are only partially supported, some fields or arguments differ or are unavailable, and functionality can be split across multiple services. That means an integration that previously worked can start returning different response shapes, missing fields, or different errors. These changes break downstream code in ways that are difficult to predict and difficult to diagnose quickly, especially under production pressure.

Even with good documentation, operators still have to do method by method rewrites and careful testing. The cost shows up immediately as time spent resolving compatibility issues, delayed upgrades because the migration feels risky, and a higher chance of service disruption during the transition. The urgent gap is not more documentation. The urgent gap is a single operator safe compatibility layer that preserves a stable, well defined subset of the highest demand non wallet zcashd RPC methods while the ecosystem completes the transition.

Proposed Solution

Z3G solves this problem by providing a single, operator grade JSON RPC endpoint that supports a clearly defined subset of the highest demand, non wallet zcashd RPC methods while the underlying deployment migrates to Zebra and Zaino. Instead of each operator building their own routing and adaptation layer, Z3G provides a shared, consistent compatibility layer that reduces migration risk by making behavior explicit, testable, and stable for the supported method set.

Z3G works as follows. Operators deploy Z3G alongside Zebra and Zaino and point existing RPC clients to the Z3G endpoint. For each supported method, Z3G forwards the request to the correct upstream service and returns a response that follows a documented compatibility contract. The contract defines the accepted parameters, the output fields that are guaranteed, the fields that are intentionally not provided where upstream support is partial, and the error codes that callers should expect. Z3G does not claim full parity where the replacement stack cannot provide it. Instead, it makes limitations clear and consistent, so integrations can be updated intentionally rather than failing unexpectedly.

To reduce compatibility drift as Zebra and Zaino evolve, Z3G ships with a conformance and regression test suite that checks these compatibility contracts against a pinned set of upstream versions. This helps operators upgrade with more confidence and helps maintainers detect compatibility regressions early. Z3G also ships with secure by default operational controls, including localhost bind by default, configurable authentication for non local deployments, rate limiting, request and batch size caps, upstream timeouts, and safe logging defaults.

Wallet RPC methods are out of scope to avoid overlap and unnecessary security risk. If a wallet method is called, Z3G returns a deterministic not supported response and points operators to Zallet. Finally, Z3G is upstream first. The project delivers a specification, compatibility contracts, and tests tied to the existing Zebra wrapper workstream, so the long term home of the work is upstream rather than a separate tool that must be maintained outside the core transition effort.

Solution Format

1) Z3G gateway software
A small daemon that exposes a single JSON RPC endpoint and routes the supported methods to Zebra and or Zaino while applying the documented compatibility contracts. Delivered as a Linux binary and a Docker image.

2) Method scope and compatibility contracts
A published v1 method list and a method by method compatibility contract defining accepted parameters, guaranteed output fields, fields intentionally not provided where upstream support is partial, and normalized error behavior.

3) Conformance and regression tests
An automated test suite that validates the compatibility contracts against a pinned set of upstream versions. The suite will be runnable in CI and locally by operators.

4) Operator deployment package
A Docker compose example for running Z3G with Zebra and Zaino and a systemd example for non Docker deployments. Includes a short configuration reference covering routing, limits, authentication options, and timeouts.

5) Security focused operational defaults
Secure defaults such as localhost bind by default, configurable authentication for non local deployments, rate limiting, request and batch size limits, upstream timeouts, and safe logging defaults. Includes a small set of abuse case checks covering oversized requests, batch spam, burst traffic, slow upstream, and upstream down behavior.

6) Upstream first contributions
Pull requests tied to the Zebra wrapper workstream that include the design notes, compatibility contracts, and the test harness, with the goal of landing the core work upstream rather than maintaining a long lived separate tool.

Dependencies

Technical

A running Zebra or zebrad node with JSON RPC enabled for the methods Z3G routes to Zebra.
A running Zaino service with JSON RPC enabled for the methods Z3G routes to Zaino.
A pinned Zebra and Zaino version set used for reproducible conformance testing.

Development and release

Standard Rust build tooling and a CI environment capable of running integration tests against the pinned Zebra and Zaino versions.
Container tooling to publish a Docker image and tagged releases.

Collaboration

Upstream review coordination with Zebra and Zaino maintainers to align on method contracts, routing expectations, and the best upstream home for the work.

Technical Approach

Z3G will be implemented as a small, hardened JSON-RPC 2.0 gateway that sits in front of Zebra and Zaino and provides a single endpoint for a defined set of high demand, non wallet zcashd methods. The design goal is to keep the gateway simple, make compatibility guarantees explicit, and use automated tests to prevent unexpected behavior changes across upgrades.

1) Architecture and routing
Z3G runs as an HTTP JSON-RPC server. Each supported RPC method is mapped to one upstream backend, Zebra or Zaino, using a clearly documented routing table. For methods where upstream support is partial, Z3G will return responses that match the published compatibility contract, and it will not attempt to recreate fields or behaviors that the upstream services do not provide.

2) Compatibility contracts
For every supported method, Z3G will publish a compatibility contract that defines:

accepted parameters and the specific parameter forms supported
guaranteed output fields and types
fields intentionally not provided where upstream support is partial
normalized JSON-RPC error codes and messages for common failure cases
These contracts define what callers can rely on, and they will be enforced by tests.

3) Normalization and error mapping
Z3G will normalize response shapes and error handling for the supported method set. Where upstream responses differ from common zcashd client expectations, Z3G will apply minimal, documented transformations needed to meet the contract. Z3G will not fabricate missing data or claim full parity where it cannot be provided.

4) Conformance and regression testing
Z3G will include an automated test suite that runs against a pinned set of Zebra and Zaino versions. Tests will validate the contracts using:

schema checks for field presence and types
behavioral invariants that can be verified without assuming full zcashd parity
The suite will run in CI and will be runnable locally.

5) Operational hardening
Z3G will ship with secure by default operational controls:

binds to localhost by default
configurable authentication for non local deployments (for example HTTP Basic Auth or a token header)
rate limiting and concurrency caps
request size and JSON-RPC batch size limits
upstream timeouts and fail fast behavior when upstream is unavailable
safe logging defaults that avoid sensitive data
A small abuse case test set will validate behavior under oversized requests, burst traffic, batch spam, slow upstream, and upstream down conditions.

6) Implementation and tooling
Z3G will be implemented in Rust and released as a Linux binary and a Docker image. Configuration will control upstream endpoints, supported method modes, limits, and authentication options.

Upstream Merge Opportunities

Z3G is intended to be delivered upstream first through pull requests, not as a long lived external fork. The primary upstream target is the Zebra repository, tied directly to Zebra issue #9392. We will only propose changes to Zaino if a small, clearly scoped adjustment is required to meet a documented compatibility contract for an in scope, non wallet method.

1) Zebra
Repository: ZcashFoundation/zebra
Planned changes:

A concise design and scope document linked to issue #9392 that defines the v1 method set, the routing map between Zebra and Zaino, the per method compatibility contracts, the error mapping rules, the security defaults, and the regression test strategy. This directly addresses the current gaps in #9392 around specifications and testing.
A reference implementation of the JSON RPC gateway as either a small crate or binary in the location Zebra maintainers prefer. This will include configuration for upstream endpoints and operator safe defaults.
A conformance and regression test harness in CI that enforces the published compatibility contracts against a pinned Zebra and Zaino version set.

2) Zaino
Repository: zingolabs/zaino
Planned changes, only if required:

Small, reviewable changes that improve compatibility for the supported non wallet RPC methods, such as making a common error case consistent or aligning a response field where Zaino already has the underlying data and exposing it is reasonable.
Minor test fixtures or hooks that make the Z3G conformance suite reproducible and easier to run in CI.
Z3G will not attempt to take over or duplicate Zaino’s RPC replacement roadmap. Z3G will treat Zaino as the upstream source for those RPC services and will only propose changes when a concrete, scoped gap is identified for an in scope method.

Whether the changes benefit the wider Zcash ecosystem if merged upstream
Yes. If merged upstream, the design spec, compatibility contracts, and CI regression tests become shared infrastructure for the zcashd to Z3 transition work. Operators benefit from a stable, well defined subset of high demand non wallet RPC methods with clear behavior guarantees. Maintainers benefit from automated regression protection that reduces accidental compatibility breaks. This also reduces fragmentation where different operators build and maintain their own ad hoc wrappers.

Coordination needed with upstream maintainers
Coordination is required mainly for correctness and long term maintainability.

Zebra maintainers: confirm preferred repo location for the gateway, naming and configuration conventions, and the routing expectations per method.
Zaino maintainers: only when an in scope compatibility gap requires a targeted fix or when changes are needed to support reliable conformance testing.
Coordination will happen through GitHub issues and PR review, with the design and contracts shared early to reduce rework.

Timeline considerations for upstream merges
Upstream merges depend on review cycles, so the plan is staged to keep each PR small and easy to review.

Weeks 1 and 2
Design and compatibility contracts PR to Zebra linked to #9392, including the final v1 method set, routing map, error mapping rules, security defaults, and the test plan.

Weeks 3 to 6
Gateway implementation PR to Zebra, iterating based on maintainer feedback. If maintainers prefer a different upstream location, we will follow that preference while keeping the work upstream first.

Weeks 6 to 8
Conformance and regression test PR to Zebra, plus any minimal Zaino PRs only if required for in scope compatibility gaps.

If upstream review takes longer than expected, we will still publish tagged releases and a Docker image so operators can adopt Z3G immediately, while the upstream PRs continue through review.

Hardware/Software Costs (USD)

$0

Hardware/Software Justification

n/a

Service Costs (USD)

$1,000

Service Costs Justification

Covers small unavoidable project services such as CI and release support, container image publishing, and minimal documentation hosting if needed. This keeps the project deliverable focused and avoids standing up unnecessary infrastructure.

Compensation Costs (USD)

$29,000

Compensation Costs Justification

Covers engineering time to deliver Z3G end to end, including:

Implementation of the gateway for the defined non wallet method set
Method by method compatibility contracts and error mapping
Conformance and regression test suite and CI integration
Secure by default controls (auth options, rate limits, request caps, timeouts, safe logging)
Upstream first PRs to Zebra (and small Zaino PRs only if required)
Six month critical maintenance for compatibility regressions and security fixes

Total Budget (USD)

$30,000

Previous Funding

No

Previous Funding Details

No response

Other Funding Sources

No

Other Funding Sources Details