Project Summary
This project will deliver a repeatable wallet RPC parity harness that runs a defined suite of calls against zcashd and Zallet, compares the results using wallets prepared with the same keys, and produces normalized reports showing MATCH, DIFF, MISSING, and ERROR outcomes. The tool is meant to give maintainers and downstream integrators a practical way to inspect wallet RPC parity during migration work. We already built an MVP for the foundation of this tool which is already open in zcash/wallet PR #404, and this grant covers the full path to a documented, reviewed, upstream-ready implementation
Project Description
As work moves from zcashd wallet RPC usage toward Zallet, compatibility at the RPC layer becomes a practical migration concern. The question is not only whether a method exists. It is whether the response shape, field values, and error behavior are close enough for existing tooling and operational workflows to keep behaving as expected.
This project adds a maintained parity harness inside zcash/wallet to make those differences visible in a repeatable way. Given two wallet RPC endpoints backed by wallets prepared from the same keys, the tool will run the same cases against both endpoints, compare the results, and write reports that show where behavior matches, where it differs, where a method is missing, and where execution fails.
The current MVP already establishes the base for this work in PR #404. That MVP includes the in-repo tool structure, CLI scaffold, manifest and report schema, baseline diff reporting, and initial automated tests. The remaining scope is the work that turns that base into a tool that other maintainers and integrators can run, review, and extend with confidence.
Proposed Problem
Maintainers and downstream integrators need a clear way to see where wallet RPC behavior in Zallet matches zcashd and where it does not. Without a repeatable harness, those differences are usually found through manual checks or one-off scripts. That makes results harder to reproduce, harder to compare across runs, and weaker as shared evidence when deciding whether a discrepancy should be fixed, documented, or accepted.
This becomes more important during migration work because many compatibility issues show up in response details rather than method names alone. Field-level differences, missing values, and different error behavior can all matter, but they are easy to miss without a tool that runs the same cases in a consistent way and writes the results in one place.
Proposed Solution
We will build a CLI-based wallet RPC parity harness inside zcash/wallet. The tool will:
- load a versioned manifest of wallet RPC methods and parameter sets,
- run the same cases against zcashd and Zallet,
- normalize the responses before comparison,
- classify each result as MATCH, DIFF, MISSING, or ERROR,
- and write both a machine-readable report and a human-readable summary.
The part that is already testable in the current MVP is the foundation of that flow. In PR #404
, the tool already has the repo structure, CLI scaffold, manifest loading, concurrent execution, baseline diff reporting, report generation, and initial automated tests. The remaining work completes the parts that make the harness dependable for repeated use: normalization rules, ignore paths, expected-differences support, method suite v1, real-run documentation, and upstream review polish.
Solution Format
The solution is open-source software delivered in the zcash/wallet repository. It includes:
- a Rust CLI parity harness,
- versioned manifests for parity runs,
- structured JSON and Markdown reports,
- automated tests,
- and a runbook for parity runs against prepared zcashd and Zallet wallets.
Dependencies
- access to a zcashd wallet RPC endpoint,
- access to a Zallet wallet RPC endpoint,
- wallets prepared from the same keys so the comparison is meaningful,
- and normal upstream review and coordination in zcash/wallet.
Technical Approach
The implementation will live under tools/zallet-rpc-diff/ in zcash/wallet and will stay manifest-driven rather than hardcoded.
1. Tool structure and inputs
A versioned manifest file will define the wallet RPC methods to run, the parameter sets for each case, and any case-specific comparison settings.
The CLI will accept two endpoint configurations plus a manifest, then build the same JSON-RPC requests for both sides from that shared input.
The current MVP already establishes this structure in PR #404
.
2. Request execution
The runner will execute the manifest-defined calls against both endpoints with bounded concurrency and per-call timeouts.
Each case will record the method, parameters, endpoint results, and the classification data needed for reporting.
The goal is for a single run to produce a reviewable artifact that can be inspected later without rerunning the same checks immediately.
3. Comparison pipeline
The comparison path will be explicit and small enough to reason about:
parse both responses into structured JSON values,
apply normalization rules for non-semantic differences,
remove any configured ignore paths,
apply expected-differences handling where relevant,
run a deep diff,
classify the result as MATCH, DIFF, MISSING, or ERROR.
This is important because the usefulness of the tool depends less on raw diffing and more on whether the comparison layer can reduce avoidable noise without hiding meaningful differences.
4. Report generation
report.json will store per-case results in a structured form suitable for inspection or follow-up tooling.
report.md will provide a shorter review-friendly summary that groups cases by outcome and highlights the main differences.
Both outputs are already part of the MVP foundation, and this project will carry them through to the final reviewed form.
5. Testing and documentation
Testing will be split into two layers:
Deterministic automated coverage: mocked or fixture-driven tests for manifest handling, execution behavior, normalization, ignore paths, expected differences, classification, and report generation.
Real-run documentation: a runbook for parity runs against prepared endpoints so another reviewer can repeat the workflow without private instructions.
The current MVP already includes initial automated test coverage using wiremock. The funded work expands that coverage around the comparison layer and the final operator workflow.
Upstream Merge Opportunities
The main upstream repository for this work is zcash/wallet.
The planned upstream changes are:
- the tools/zallet-rpc-diff/ CLI,
- manifest files,
- report types and report generation,
- the comparison pipeline,
- automated tests,
- and user-facing documentation.
These changes give the wider Zcash ecosystem a shared way to measure wallet RPC parity instead of relying on local scripts or manual checks. That makes migration testing easier to repeat, easier to review, and easier to discuss using the same artifact.
The MVP is already open as PR #404, so upstream coordination can happen against working code rather than a design-only proposal. The target is to land the full work upstream during the grant window. If final merge timing extends beyond the grant period, the deliverable remains a clean review-ready state with passing tests, complete documentation, and maintainer feedback addressed.
Hardware/Software Costs (USD)
$0
Hardware/Software Justification
n/a
Service Costs (USD)
$0
Service Costs Justification
n/a
Compensation Costs (USD)
$20,000
Compensation Costs Justification
The budget covers the full implementation, testing, documentation, upstream review iteration, and 90 days of limited maintenance.
The work is split across four main stages:
- harness structure, manifest shape, and CLI foundation,
- core runner and report engine,
- normalization, expected differences, and method suite v1,
- runbook, review iteration, and limited maintenance.
Total Budget (USD)
$20,000
Previous Funding
No
Previous Funding Details
No response
Other Funding Sources
No
Other Funding Sources Details
No response
Implementation Risks
- Comparable wallet setup is required. A meaningful parity run depends on both wallets being prepared from the same keys and comparable state. The harness measures differences, but it does not remove that setup requirement.
- Report noise has to be managed carefully. If normalization is too narrow, the report will surface too many harmless differences. If it is too broad, the tool can hide real incompatibilities. That is why normalization, ignore paths, and expected-differences support are part of the core scope.
- Final merge timing depends partly on maintainer bandwidth. The project can complete its engineering scope within the grant period, but final upstream merge timing is not fully under the team’s control.
Potential Side Effects
- MATCH should not be overread. A high number of MATCH results does not mean every downstream workflow behaves identically. The tool measures wallet RPC parity method by method.
- Reports may contain wallet-related response data. The runbook will explain how to handle local report artifacts during testing and review.
Success Metrics
This project will be successful if:
another maintainer or integrator can run the harness against prepared zcashd and Zallet endpoints and get a usable report without manual cleanup,
the tool clearly separates MATCH, DIFF, MISSING, and ERROR outcomes,
method suite v1, normalization, ignore paths, expected-differences support, automated tests, and the runbook are complete and working together in one repo-local tool,
and the work is merged upstream or left in a clear review-ready state with passing tests, complete documentation, and maintainer feedback addressed.
Startup Funding (USD)
$0
Startup Funding Justification
nil
Milestone 1
Amount (USD): 4000
Expected Completion Date: 2026-05-01
User Stories
- As a Zallet maintainer, I want a stable in-repo harness structure and manifest format so parity testing can grow without reworking the tool layout.
- As a contributor, I want a clear CLI entry point and report schema so I can run and review the harness consistently.
Deliverables
- We will finalize the tool layout under tools/zallet-rpc-diff/, including the CLI entry point, configuration loading, and report type definitions.
- We will finalize the manifest format and the example manifest used to describe RPC methods and parameter sets.
- We will align the current MVP foundation in PR #404 with the reviewed structure used for the rest of the project.
Acceptance Criteria
- A reviewer can build the CLI, run it against mocked endpoints using the example manifest, and see report.json and report.md generated from the reviewed schema.
- The repository contains documented manifest and report formats, and the tool structure is settled enough for the remaining milestones.
Milestone 2
Amount (USD): 6000
Expected Completion Date: 2026-05-15
User Stories
-
As a maintainer or integrator, I want the same RPC calls executed against both endpoints and classified consistently so I can see where behavior matches or diverges.
-
As a reviewer, I want repeatable report output so repeated runs are easy to inspect and compare.
Deliverables
- We will complete manifest-driven execution against both endpoints with bounded concurrency, timeouts, and consistent classification into MATCH, DIFF, MISSING, and ERROR.
- We will complete machine-readable and human-readable report generation for each run.
- We will expand automated tests around runner behavior, error handling, and report generation.
Acceptance Criteria
- Using mocked or controlled endpoints, the harness produces consistent classifications and both report formats without manual cleanup.
- The classification behavior is documented and covered by automated tests.
Milestone 3
Amount (USD): 6000
Expected Completion Date: 2026-05-29
User Stories
- As a maintainer, I want non-semantic differences filtered and known differences documented so the report highlights new problems instead of noise.
- As an integrator, I want a reviewed first method suite so I can run a useful parity check without building my own cases from scratch.
Deliverables
- We will add normalization rules for non-semantic response differences, configurable ignore paths, and expected-differences support.
- We will add a reviewed method suite v1 covering a practical initial set of wallet RPC methods and parameter cases.
- We will extend automated tests and fixtures to cover both meaningful-difference and non-meaningful-difference behavior.
Acceptance Criteria
- Repeated runs no longer flag documented non-semantic differences as fresh breakage.
- A reviewer can run method suite v1 and see intentional differences separated cleanly from unexpected ones.
Milestone 4
Amount (USD): 4000
Expected Completion Date: 2026-08-27
User Stories
- As a maintainer or operator, I want a clear runbook so I can run the harness against real zcashd and Zallet wallets prepared with the same keys.
- As an upstream reviewer, I want the project left in mergeable or clearly merge-ready shape so adoption does not depend on undocumented follow-up work.
Deliverables
- We will write the runbook for real parity runs, including required setup, expected inputs, and how to interpret the output.
- We will address maintainer review feedback, polish the code and documentation, and drive the work to merged or clearly review-ready state.
- We will provide 90 days of limited maintenance for high-severity harness defects discovered during early use.
Acceptance Criteria
- Another reviewer can follow the runbook and perform a parity run against prepared endpoints without private instructions.
- By milestone close, the work is either merged upstream or left with passing tests, documented usage, and maintainer feedback addressed to the point that the remaining path to merge is clear.