Project Summary
ZIG is a small CLI and CI-friendly tool that reads a project’s Zcash configs and RPC usage, compares them against a chosen target stack (e.g. moving from zcashd to a Zebra-based setup), and highlights any incompatibilities before you upgrade. It gives integrators a fast, automated way to see what will break and what needs to change, reducing migration risk and manual compatibility checks.
Project Description
ZIG – Zcash Integration Guardrail is a small, practical tool for teams who are tired of doing Zcash stack upgrades “by hand.” Right now, if a project wants to move from a zcashd-based deployment to a more modern Zebra-based stack with an indexer, someone has to dig through docs and spreadsheets, guess which config options still matter, grep the code or logs for RPC usage, and hope they didn’t miss a call that disappears or changes behaviour. It’s slow, easy to get wrong, and every team repeats the same work for their own integration.
Concretely, ZIG is a command-line program (with optional CI integration) that takes three inputs:
- a --from / --to pair describing the current and target stack,
- a Zcash configuration file (for example zcash.conf, and optionally zebrad.toml),
- a plain-text file listing the RPC methods the project uses.
It then compares those inputs against a versioned compatibility profile for the chosen target stack and produces:
a human-readable report explaining which config keys are safe, which have changed semantics, which are obsolete, and which might be unsafe on the target stack, and
a JSON report plus exit code that CI can use to block or allow migrations based on the presence of blocking incompatibilities.
The main goals of the project are:
- Reduce migration risk : Give integrators a clear, project-specific view of breaking changes (missing RPCs, incompatible config options) so they can address them in advance rather than discovering issues in staging or production.
- Standardise compatibility analysis: Replace repeated manual cross-checking of the same deprecation tables and documentation with one shared tool that can be run locally or in CI across many different projects.
- Support future upgrades, not just one migration: Structure ZIG around data-driven “profiles” so that compatibility descriptions for future node versions or stack combinations can be added without changing the engine, allowing the same tool to be reused for later network upgrades.
- Keep v1 small and realistic: Limit v1 strictly to static analysis of configs and RPC usage. ZIG will not start nodes, connect to any network, or handle wallet data; it’s a lightweight linter that projects can run in a few seconds and easily drop into their CI pipelines.
Proposed Problem
For any serious Zcash integration today – a wallet backend, exchange, explorer, or payment service – changing your node stack has become a high-risk, manual job. The ecosystem is intentionally moving away from the legacy zcashd node towards a more modular, Zebra-based stack with separate services for indexing and light-client access.That shift is healthy long-term, but it also means that JSON-RPC methods and configuration options people have relied on for years are no longer guaranteed to behave the same way, or even be present, on the new stack.
Core developers already recognize this and have published an RPC compatibility spreadsheet and thread asking integrators to describe how they use zcashd’s JSON-RPC interface – explicitly saying “we are collecting information about how zcashd users are currently using the existing JSON-RPC methods” and asking projects to provide feedback “as soon as possible” (forum post). In practice, though, the work of migration for most projects still looks like this: read through long deprecation and compatibility documents, logs to guess which RPCs you actually depend on, closely compare zcash.conf to new config formats, and then do a trial upgrade to see what fails. When a method that an explorer or backend relies on has been removed or now requires a separate indexer, that mismatch is often only noticed late in testing or, worse, in production.
The general Network Upgrade guidance already tells wallets, exchanges, and clients that they should actively prepare and validate their systems ahead of each upgrade (NU Developer Guide), but there is still no simple, shared tool that can take your configuration and your list of RPC calls and tell you, in concrete terms, “if you move from stack A to stack B, these specific settings and methods will stop working or need to change.” Because of that gap, people either delay necessary upgrades or push ahead and risk discovering missing RPCs, changed responses, or misconfigured nodes at the most expensive and dangerous point in the process. That missing compatibility “guardrail” is what this project is aimed at fixing.
Proposed Solution
The project will build ZIG – Zcash Integration Guardrail, a small, reusable tool that automates the compatibility checks teams are currently doing manually when they change their Zcash node setup.
ZIG is a command-line program (with optional CI integration) that takes three inputs:
- a --from / --to pair describing the current and target setup (for example, from a zcashd-based deployment to a specific Zebra-based stack),
- a Zcash configuration file (for example zcash.conf, and optionally zebrad.toml),
- a plain-text file listing the JSON-RPC methods the project uses in its code (one method name per line).
Internally, ZIG loads versioned “profiles” for the source and target setups. Each profile describes:
- which config options are recognised and how they are interpreted,
- which RPC methods are available, and any important notes about their behaviour or dependencies (for example, methods that only exist when an indexer is present).
When you run zig check, it parses your config and RPC list, compares them against those profiles, and then produces:
- a human-readable report that explains, in straightforward language, which config keys are safe, which have changed meaning, which are obsolete on the target setup, and which RPC calls are fully supported, changed, or unsupported,
- an optional JSON report and exit code (0/1/2) so you can run the same check in CI and automatically block changes that introduce new incompatibilities.
This directly addresses the current pain: instead of each team manually reading compatibility tables, scanning their own code or logs for RPC usage, and trying to guess what might break, they can run one tool that understands both sides of the migration and get a clear, project-specific answer. Because ZIG’s profiles are data-driven, new node versions or stack combinations can be supported over time by adding or updating profile files, without changing the core engine. That makes it useful not only for the current shift away from zcashd, but also for future upgrades where external developers need a quick way to check “are we still compatible?” before rolling out changes.
Solution Format
he solution is a software project, delivered as:
A small command-line application (“ZIG”) that runs locally on a developer machine or in CI, distributed as a static binary (and optionally a container image).
A reusable compatibility engine and profile format (JSON or YAML files) that describe configuration and RPC behaviour for different Zcash stacks, so new versions can be supported by updating data rather than changing the core code.
A minimal library interface (in the same language as the CLI) for projects that prefer to call ZIG programmatically instead of shelling out to the binary.
CI integration examples, including a ready-to-use GitHub Actions workflow and a generic script snippet that can be adapted for other CI systems.
Documentation, including a short design note, a “Quickstart” guide, example zcash.conf and RPC manifest files, and a description of the JSON report format and exit codes.
Dependencies
Technical dependencies
- A standard development environment for building CLI tools (for example, the Rust toolchain and common open-source libraries for parsing configuration files and JSON/YAML).
- Access to public Zcash documentation and compatibility information (for example, zcashd deprecation notes and RPC status tables, and current Zebra/indexer documentation), which will be used to define the initial compatibility profiles so projects can move away from older setups safely.
- Standard tooling for reproducible builds and security hygiene (for example, Docker for reproducible builds, an SBOM generator such as Syft or cargo auditable, and GPG for signing releases).
Resources
- Development time from the applicant/team to design, implement, test, and document the tool.
- Basic CI infrastructure (for example, GitHub Actions or an equivalent service) to run tests, build binaries, and verify reproducible builds.
Collaborations
- No formal collaborations or letters of intent are required.
- The project will be implemented based on public information and can be completed independently.
- Informal feedback from Zcash node and wallet developers (via public forum threads or issue comments) would be welcome to refine the set of config keys and RPC methods covered, but this feedback is optional and not a dependency for delivering v1.
Technical Approach
1. Implementation language and packaging
- Use a language suited to building cross-platform CLI tools (for example, Rust) so we can ship a single binary per platform.
- Optionally provide a minimal container image for teams that prefer to run tools from Docker in CI.
2. CLI and core engine
- Implement a zig CLI with a check subcommand and flags for:
- –from / --to (source/target stack identifiers),
- –zcash-conf (path to zcash.conf),
- –zebrad-toml (optional, path to a Zebra config),
- –rpc-manifest (path to a text file listing RPC methods),
- –json (optional path for JSON output).
- The CLI passes these inputs into a core engine that performs static checks only – it will not start nodes, connect to networks, or touch wallet data.
3. Config parsing and mapping
- Implement parsing for zcash.conf, handling:
- comments and whitespace,
- duplicate keys,
- common options such as rpcuser, rpcpassword, rpcport, rpcbind, rpcallowip, txindex, addnode, connect, and basic mining/metrics flags.
- Implement a minimal parser for zebrad.toml to read keys that are relevant to RPC/API behaviour and connectivity.
- Define mapping rules (expressed in data files where practical) that, for each relevant config key in a given --from/–to context, classify it as:
- “supported / OK”,
- “supported but changed” (for example, different default or meaning),
- “obsolete / not recognised”, or
- “potentially unsafe” (for example, overly permissive RPC exposure).
4. RPC manifest and compatibility profiles
- Use a simple, line-based format for the RPC manifest (rpc-usage.txt), with one JSON-RPC method name per line. Projects can maintain this file themselves or generate it from their logs/scripts.
- Define a JSON or YAML schema for stack profiles that describes, for each stack identifier:
- which RPC methods are present,
- whether they are fully supported, partially supported, or absent,
- any notes on changed behaviour or additional components required (such as an indexer).
- For v1, create a small set of profiles for clearly defined stacks (for example, a current zcashd profile as a source, and one or two Zebra-based targets) based on public compatibility information and documentation.
- Implement an engine that loads these profiles, matches each method in the manifest against them, and classifies methods accordingly.
5. Reporting and CI integration
- Implement a report generator that:
- produces a clear text summary with separate sections for config findings and RPC findings,
- can optionally write a JSON report with a documented schema, and
- uses exit codes (0 / 1 / 2) to distinguish “no blocking issues”, “blocking incompatibilities”, and “warnings only”.
- Provide a ready-to-copy GitHub Actions workflow and a generic shell snippet to show how to run zig check in CI as a pre-migration or pre-release step.
6. Testing, security, and reproducibility
- Add unit tests for:
- config parsing,
- RPC manifest parsing,
- profile loading and compatibility matching.
- Add basic fuzz or property tests around parsing and matching logic to reduce the likelihood of crashes or unexpected behaviour when inputs are malformed.
- Set up a simple reproducible build process:
- pin the compiler/toolchain and dependencies,
- document how to rebuild the CLI and verify checksums.
- Generate a software bill of materials (SBOM) for releases and sign git tags and binaries with GPG so users can verify authenticity.
Upstream Merge Opportunities
For this project there are no upstream merge opportunities.
Hardware/Software Costs (USD)
$0
Hardware/Software Justification
nil
Service Costs (USD)
$0
Service Costs Justification
nil
Compensation Costs (USD)
$25,000
Compensation Costs Justification
The entire budget is for development and maintenance time. This covers roughly 10–12 weeks of focused work for one experienced engineer (design, implementation, tests, documentation, CI setup, reproducible builds, signing, and 90 days of post-release support), at an effective blended rate that stays within the requested total.
Total Budget (USD)
$25,000
Previous Funding
Yes
Previous Funding Details
n/a
Other Funding Sources
No
Other Funding Sources Details
No response
Implementation Risks
- Profile accuracy : The first compatibility profiles will be derived from public deprecation and stack documentation. If that source information is incomplete or unclear, some RPCs or config keys could be mislabelled or omitted in v1 and would need correction once real users exercise the tool.
- Real-world config edge cases: Different projects use zcash.conf (and other config files) in slightly different ways. Writing parsers and rules that handle comments, duplicated keys, and unusual combinations reliably may take iteration as we encounter more examples.
- Keeping v1 scope tight: It would be easy to try to support too many stack combinations or rare RPCs in the first release. If that happens, the project could drift beyond the planned schedule. The main mitigation is to limit v1 to a clearly defined set of stacks, config options, and commonly used methods, and treat everything else as future work.
- Cross-platform packaging: Producing a single binary that behaves consistently across the main target platforms (Linux/macOS, and possibly Windows) can surface build or linking issues, especially when setting up reproducible builds. This risk is mitigated by using standard tooling and keeping dependencies minimal.
- Tracking evolving compatibility information: While v1 is being built, details about RPC support and recommended stacks may continue to evolve. The profiles and documentation will need to follow those updates closely, particularly during the 90-day maintenance period after release.
Potential Side Effects
- False sense of safety: If a project’s RPC list or the compatibility profile is incomplete, ZIG could report “no blocking issues” while a real incompatibility still exists. Documentation will make clear that ZIG is a helper, not a replacement for testing in staging.
- Over-reliance on the tool: Some teams might treat ZIG as the only step they need, instead of one check among several. We will explicitly recommend using ZIG alongside existing practices (reading upgrade guidance and running real test migrations).
- Profile drift over time: If profiles are not updated as the ecosystem evolves, results may become less accurate or useful. To reduce this risk, profiles will be data files in the repo (open to contributions), and the grant includes a 90-day maintenance window to keep them aligned with current compatibility information.
Success Metrics
Success will be measured by whether external projects actually use ZIG to check their integrations and catch issues before upgrading. Concretely:
Usage in real projects
Within about 90 days of v1.0, at least 2–3 public repositories (wallets, services, explorers, or tooling) using zig check in a CI job or migration script.
Within about 180 days, around 5–6 public repos with ZIG integrated into their workflow in a similar way.
Evidence of practical benefit
At least one public note or short write-up (for example, a forum post or GitHub issue) where an integrator reports that ZIG helped them identify a specific config or RPC incompatibility before a stack change.
Basic adoption signal
Download or installation numbers (binary downloads, crate installs, or container pulls) showing that the tool has been tried by more than just the initial pilot users.
Shared ownership
At least two pull requests from external contributors improving or extending compatibility profiles or small parts of the engine, indicating that others see ZIG as shared infrastructure worth maintaining.
If, within the first six months, ZIG is being run in several real CI setups, has helped at least one project catch a concrete issue early, and has attracted some external contributions, the project will be considered successful.
Startup Funding (USD)
n/a
Startup Funding Justification
n/a
Milestone Details
Milestone: M1 – Design & Profile Schema
Amount (USD): 3,000
Expected Completion Date: 2025-03-31
User Stories:
-
As a Zcash integrator, I want a clear description of what ZIG will check, so that I can tell whether it fits my migration needs before I try it.
-
As a future contributor, I want profiles and configuration rules to be defined in a simple data format, so that I can add or update stack definitions without changing core code.
Deliverables:
-
A design document in the ZIG repository describing:
-
the zig check CLI interface and expected inputs/outputs,
-
the JSON/YAML schema for compatibility profiles,
-
the initial set of config keys and RPC methods to be covered in v1.
-
At least one example profile file stubbed out for a current zcashd-based stack identifier.
Acceptance Criteria:
-
A reader can understand from the design document how they would run zig check for their own project and which configs/RPCs v1 will cover.
-
The example profile file validates against the documented schema (e.g. via a simple test in the repo).
Milestone 2: CLI & Config Parsing
Amount (USD): 6,000
Expected Completion Date: 2025-04-21
User Stories:
-
As an integrator, I want ZIG to understand my zcash.conf, so that I can see which of my configuration options remain valid or need review when I change stacks.
-
As a CI engineer, I want a single CLI command I can run with a config file, so that I can add ZIG to a job without extra scripting.
Deliverables:
-
A working zig CLI with a check subcommand and flags for --from, --to, --zcash-conf, and basic output options.
-
A parser for zcash.conf that handles comments, duplicate keys, and common options, plus a minimal parser for zebrad.toml for relevant keys.
-
Mapping logic to classify parsed config keys (OK / changed / obsolete / potentially unsafe) for the initial profiles.
-
Unit tests and basic fuzz/property tests covering config and toml parsing.
Acceptance Criteria:
- Running zig check --from … --to … --zcash-conf ./examples/zcash.conf produces a config-only report that matches the expected classifications for the example file (as documented in test cases).
- All config parsing tests and fuzz/property tests pass in CI.
Milestone 3: RPC Engine & Reporting
Amount (USD): 7,000
Expected Completion Date: 2025-05-12
User Stories:
-
As an integrator, I want ZIG to tell me which of the RPC calls I rely on will still be available on the target stack, so that I can adjust or replace ones that will not.
-
As a developer, I want a clear, structured report of config and RPC findings, so that I can share it with my team and turn it into a list of migration tasks.
Deliverables:
-
RPC manifest parsing for a line-based rpc-usage.txt format.
-
Profile loading and RPC compatibility matching against the initial stack profiles.
A report generator that outputs:
-
a text summary with separate sections for config and RPC findings,
-
an optional JSON report with a documented schema,
-
exit codes (0/1/2) for “no blocking issues”, “blocking issues”, and “warnings only”.
-
Unit tests for RPC matching and report generation, plus basic fuzz/property tests around manifest parsing.
Acceptance Criteria:
-
Running zig check with both a sample zcash.conf and rpc-usage.txt produces a report that correctly flags at least one example unsupported/changed RPC and one example supported RPC, according to the sample profiles included in the repo.
-
JSON output matches the documented schema, and exit codes behave as described in the documentation, with tests verifying this.
Milestone 4: CI Integration & Documentation
Amount (USD): 4,000
Expected Completion Date: 2025-06-02
User Stories:
-
As a CI engineer, I want a ready-made example workflow for ZIG, so that I can add a compatibility check job with minimal effort.
-
As a developer, I want concise documentation and examples, so that I can try ZIG without having to read through the code first.
Deliverables:
- A GitHub Actions example (and/or generic shell script) showing how to run zig check in CI using example config and RPC manifest files.
Updated README and a “Quickstart” guide covering:
-
how to prepare rpc-usage.txt,
-
how to run zig check locally,
-
how to interpret reports and exit codes.
-
Example configs and manifest files in the repo that users can copy as templates.
Acceptance Criteria:
-
The example CI configuration runs in the ZIG repository’s own CI and produces a report on each run using the example files.
-
A new user can follow the Quickstart instructions to run ZIG on the provided examples and obtain a report without needing extra information.
Milestone 5: Release, Security & Maintenance Setup
Amount (USD): 5,000
Expected Completion Date: 2025-06-30
User Stories:
-
As an integrator, I want to be confident the tool I download is authentic and reproducible from source, so that I can use it in my CI pipeline with confidence.
-
As a user, I want to know there is at least initial maintenance in place, so that early issues will be addressed and profiles will not immediately go stale.
Deliverables:
-
Reproducible build instructions (for example, pinned toolchain and a Dockerfile) and an SBOM for the v1.0.0 binary.
-
A signed git tag and signed release binaries for v1.0.0.
-
Fuzz/property test results for parsing and matching logic.
-
A short maintenance plan describing how bugs and profile updates will be handled during the 90-day support window.
Acceptance Criteria:
-
The v1.0.0 release is published with signed artifacts, an SBOM, and build instructions that allow a reviewer to rebuild the binary and check its checksum.
-
All unit and fuzz/property tests pass in CI.
-
The maintenance plan is documented in the repository so users know what to expect during the initial support period.