Retroactive Grant Application - {Zallet RPC Parity Harness}

Community Grants Retroactive Grants
1

Project Summary

Zallet RPC Parity Harness is a completed standalone Rust CLI that compares results from operator-supplied zcashd and Zallet JSON-RPC endpoints and generates normalized JSON and Markdown reports. The repository includes a 24-entry comparison manifest, six result classifications, automated tests, mock-node end-to-end validation, CI, example configuration, and an operator runbook.

Project Description

Zallet is being developed to replace wallet functionality currently provided by zcashd. The zcashd deprecation guidance explains that the JSON-RPC transition will not be uniform: some methods may support similar usage, some may require modified usage, and some may not be supported.

Compatibility testing therefore involves more than checking whether two endpoints expose methods with the same names. Differences may also appear in returned fields, response structures, missing methods, and RPC error behavior.

The comparison use case was publicly described in zcash/zallet issue #16, which requested tooling capable of comparing outputs from a fully synced zcashd wallet and a Zallet wallet containing the same keys.

We completed the Zallet RPC Parity Harness as a standalone command-line tool. It runs independently from the Zallet source repository and does not require an upstream merge or source-code changes to either implementation.

After our work was completed, issue #16 was closed with a maintainer pointing to zcash/integration-tests as satisfying the upstream testing requirement. We therefore do not present this project as a replacement for that repository or as the canonical Zallet test suite.

The tools provide different workflows:

zcash/integration-tests provides broad functional and integration testing for Zcash components through its test framework, regtest environments, and CI.
Zallet RPC Parity Harness provides a standalone, black-box comparison workflow for two reachable JSON-RPC endpoints and produces per-case normalized diff reports.

The completed harness:

  • Loads RPC methods, parameters, tags, and ignore paths from a TOML manifest.
  • Runs selected calls against operator-supplied zcashd and Zallet endpoints.
  • Normalizes successful JSON results before comparison.
  • Reports differences using RFC 6901 JSON Pointer paths.
  • Separates unexpected differences from differences covered by an operator-provided expected-differences file.
  • Separates unexpected missing methods from methods configured as expected missing.
  • Produces machine-readable JSON and human-readable Markdown reports.
    Includes automated tests, mock JSON-RPC endpoints, CI, example configurations, a design note, and an operator runbook.

The v1 manifest contains 24 comparison entries. The entries are grouped under blockchain, network, wallet, mining, and utility sections, with tags for focused subsets such as balances, addresses, transactions, shielded operations, and UTXOs.

The harness is observational. It does not implement missing RPC methods, modify either wallet implementation, migrate wallet keys, decide that every reported difference is a defect, or certify complete application-level compatibility.

A MATCH means only that the two successful results for one configured case were equal after the tool applied that case’s normalization and ignore-path rules.

EXPECTED_DIFF and EXPECTED_MISSING mean that the result was covered by the supplied expected-differences configuration. These labels do not by themselves mean that the behavior has been reviewed or approved by Zallet maintainers.

Meaningful live comparisons of wallet-state methods require both endpoints to use the same Zcash network, have reasonably comparable chain state, and contain the same relevant wallet keys. Preparing those environments remains the operator’s responsibility.

Technical Approach (how you did it)

1. Standalone Rust workspace

We organized the repository as a three-crate Rust workspace:

zallet-parity-core contains the JSON-RPC client, execution engine, manifest parser, normalization logic, recursive diff engine, expected-difference handling, and report types.
zallet-parity-cli provides the zallet-rpc-diff command, command-line configuration, tag filtering, dry-run behavior, progress output, report writing, and exit-code handling.
zallet-parity-testkit provides reusable mock JSON-RPC nodes and test helpers.

This separates the comparison engine from the command-line interface and test infrastructure.

2. Manifest-driven comparison cases

Comparison cases are defined in manifest.toml rather than being hardcoded in the execution engine.

Each entry can define:

A JSON-RPC method name.
Positional parameters.
Tags used to include or exclude groups of cases.
Optional RFC 6901 ignore paths.

The completed v1 manifest contains 24 entries. Additional cases can be introduced by editing the manifest without changing the core runner.

The CLI supports:

--manifest to select a manifest file.
–tags to run selected groups.
–exclude-tags to omit selected groups.
–dry-run to display selected cases without making RPC calls.
–concurrency to set the maximum number of comparison tasks in flight.
–expected-diffs to select an expected-differences file.
–save-raw to retain unnormalized parsed results from non-matching cases for local debugging.

3. JSON-RPC request execution

The CLI accepts:

An upstream zcashd JSON-RPC endpoint.
A target Zallet JSON-RPC endpoint.
A comparison manifest.
An optional expected-differences file.

For each selected manifest entry, the tool sends the same method and parameter set to both endpoints.

Manifest parameters are encoded as follows:

  • An absent or null value is sent as an empty parameter list.
  • An array is sent as positional parameters.
  • A scalar or object is sent as one positional parameter.

The JSON-RPC client applies a 30-second timeout to each request. Cases are processed with bounded concurrency, with a default limit of eight comparison tasks. The operator can lower the limit for slower environments or serial debugging.

4. Normalization and diff generation

When both endpoints return successful JSON values, the tool:

Recursively canonicalizes object-key ordering.
Removes fields listed in the manifest’s RFC 6901 ignore paths.
Recursively compares objects, arrays, scalar values, and keys present on only one side.
Records differences using JSON Pointer paths.
Passes the resulting paths to the classification layer.

This produces focused paths such as /private, /version, or /softforks/0/id rather than including complete response payloads in the default report.

Ignore paths and expected differences serve separate purposes:

Ignore paths remove selected fields before comparison.
Expected differences leave configured differences visible but classify them separately from unexpected differences.

5. Expected-difference handling

The optional expected_diffs.toml file can describe:

A method-level expected difference.
Specific expected JSON Pointer paths.
A method expected to be missing.

A case is classified as EXPECTED_DIFF only when the applicable configuration covers all reported difference paths. If an additional path is not covered, the case remains DIFF.

A method-not-found result is classified as:

MISSING when the absence is not configured as expected.
EXPECTED_MISSING when the method is explicitly listed with expected_missing = true.

These labels reflect the supplied configuration rather than an authoritative upstream decision about the RPC behavior.

  1. Result classifications

Each comparison case receives one of six results:

MATCH — both successful results were equal after normalization.
DIFF — successful results differed at one or more paths not fully covered by the expected-differences configuration.
EXPECTED_DIFF — all reported difference paths were covered by an expected-differences entry.
MISSING — one or both endpoints returned JSON-RPC method-not-found and the absence was not configured as expected.
EXPECTED_MISSING — method-not-found was returned and the absence was configured as expected.
ERROR — another RPC error or transport failure prevented normal comparison.

7. Reports and exit codes

Each completed run writes:

report.json, containing a schema version, generation timestamp, aggregate counts, and per-case results.
report.md, containing a shorter table for human review.

Per-case entries are ordered by method name to make the report structure stable and easier to compare.

The CLI uses three exit-code groups:

Exit code 0 when the report contains only MATCH, EXPECTED_DIFF, or EXPECTED_MISSING.
Exit code 1 when at least one unexpected DIFF, MISSING, or ERROR is present.
Exit code 2 when the tool cannot complete because of a configuration, manifest, or file-output failure.

Complete endpoint results are not included in the default JSON or Markdown reports. Optional diagnostic persistence is enabled through --save-raw.

8. Automated testing and CI

The repository includes tests covering:

Manifest parsing.
JSON-RPC parameter encoding.
Object-key normalization.
Ignore-path processing.
Scalar, nested-object, array, missing-key, and root-level differences.
All six result classifications.
Method-level and field-level expected differences.
Partially covered expected differences.
Deterministic report ordering.
CLI report creation.
Exit-code behavior for clean runs, unexpected differences, missing methods, and configuration failures.

The GitHub Actions workflow contains jobs for:

Formatting checks.
Clippy linting with warnings denied.
Workspace tests.
Release builds.
End-to-end mock validation.

The end-to-end workflow starts two mock JSON-RPC endpoints and runs the standalone CLI against them. This validates the executable comparison and reporting workflow without requiring synchronized live Zcash nodes in CI.

The workflow run on the completion-state commit completed successfully.

9. Documentation

The completed documentation includes:

A README with installation and quick-start instructions.
A design note describing classifications, report structure, parameter encoding, concurrency, and diagnostic output.
An operator runbook covering endpoint setup, same-key requirements, configuration, execution, result interpretation, suite extension, and troubleshooting.
Example endpoint and expected-difference configurations.
Mock-generated example reports.

Time Period of Work Completion

March 26, 2026 – May 16, 2026

Total Budget (USD)

$20,000

Budget Breakdown

  • Compensation:

  • $(USD): $20,000

  • Justification: Retroactive compensation for the completed engineering, testing, technical review, QA, documentation, and project coordination required to deliver the standalone Zallet RPC Parity Harness. The allocation is $4,000 for the Rust workspace, CLI foundation, manifest format, and report schema; $6,000 for JSON-RPC execution, result classification, and the report engine; $6,000 for normalization, ignore paths, expected differences, expected-missing support, and method suite v1; and $4,000 for the testkit, regression testing, mock-node validation, CI, documentation, and project coordination.

  • Technology/Software: - $(USD): $0 - Justification: The work used open-source development tools and existing local development environments.

  • Infrastructure/Hosting: - $(USD): $0 - Justification: The completed tool does not require a hosted service. Automated validation uses repository CI and local mock JSON-RPC nodes.

  • Services/Contractors: - $(USD): $0

  • Justification: No separately billed external service or contractor cost is included. - Other: - $(USD): $0 - Justification: N/A

  • Total $(USD): $20,000

Previous Funding

No

Previous Funding Details

No previous funding.

Other Funding Sources

No

Other Funding Sources Details

N/A

Success Metrics

The completed and verifiable outputs are:

  • A standalone Rust workspace containing core, CLI, and testkit crates.
  • A 24-entry v1 RPC comparison manifest.
  • Six implemented result classifications: MATCH, DIFF, EXPECTED_DIFF, MISSING, EXPECTED_MISSING, and ERROR.
  • Structured difference paths using RFC 6901 JSON Pointer notation.
  • Separate configuration for ignore paths, expected differences, and expected missing methods.
  • JSON and Markdown report generation.
  • Report schema versioning, generation timestamps, aggregate counts, and ordered per-case entries.
  • Configurable concurrency and per-request timeouts.
  • Tag selection, tag exclusion, and dry-run support.
  • Opt-in diagnostic output for non-matching cases.
  • Unit, engine, CLI, fixture, and mock-node tests.
  • A successful GitHub Actions run covering formatting, linting, workspace tests, release builds, and mock-node end-to-end execution.
  • A README, design note, operator runbook, and example configurations.
  • A standalone installation and execution path that does not depend on an upstream merge.

The project provides a separately runnable workflow for converting results from two supplied JSON-RPC endpoints into a consistent report that identifies the affected case and the response paths that differ.

This application does not claim external production adoption, third-party live-node validation, acceptance as the canonical Zallet test suite, replacement of zcash/integration-tests, or complete application-level compatibility certification.

Proof of completion

Proof of Completion:

Repository/Commit:

Publication:

  • README — installation, quick start, outputs, and project overview.
  • Operator Runbook — endpoint preparation, configuration, execution, report interpretation, suite extension, and troubleshooting.
  • Design Note — architecture, result classifications, report schema, parameter encoding, concurrency, and diagnostic behavior.
  • Method Suite v1 — the 24-entry comparison manifest.
  • Expected-Differences Example — example operator configuration for expected differences and missing methods.

Deployment/Release:

  • This is a source-distributed command-line tool rather than a hosted application. A web deployment is not part of the completed scope.
  • Successful GitHub Actions run — formatting, linting, tests, release build, and mock-node end-to-end validation.
  • Mock-generated JSON report — example structured report produced from the mock workflow.
  • Mock-generated Markdown report — example human-readable report produced from the mock workflow.

The linked reports were generated from mock endpoints. They demonstrate the report format and classification workflow; they are not presented as results from live zcashd and Zallet nodes.

Call For Proposals: Coinholder-Directed Retroactive Grants Program Q3