Project Summary
Authenticated Shielded Sync Gateway verifies confirmed Zcash compact scanning data before a wallet receives it, checking transaction contents and completeness against explicitly trusted block headers. This grant will develop the working MVP into a reusable Rust verification library and hardened reference gateway, with wider transaction coverage, mainnet measurements and reproducible integration instructions.
Project Description
Shielded Sync Gateway checks the blockchain data a Zcash light wallet receives from its server. It sits between the wallet and the server, checking the information the wallet uses to find incoming payments and track spent funds.
I have built a working prototype and tested it with Zingo CLI on a local test network. In these tests, altered server data caused the wallet to miss payments or spends. The gateway rejected the altered data, and the wallet recovered once correct data became available.
This grant will fund further testing, better handling of errors and network interruptions, and measurements using real mainnet data. I will also publish a reusable Rust library and clear setup instructions so other developers can use the verification code in their applications.
The first release will rely on a trusted Zebra node to check the server’s data against the blockchain.
Proposed Problem
A wallet can show the wrong balance even when the blockchain is correct. An incoming payment may be missing, or funds already spent may still appear available. This makes two basic questions hard to answer: “Have I been paid?” and “How much can I spend?”
Light wallets rely on servers to supply the data they scan for payments and spends. Checking note commitments alone does not authenticate every scanning field supplied alongside them. The need to verify both transaction completeness and contents is also described in lightwalletd issue #527.
The prototype’s controlled Zingo CLI tests demonstrated the consequence. Altered ciphertexts or ephemeral keys caused the wallet to report 1.4999 ZEC instead of 2.7499 ZEC. Altered spend nullifiers caused it to report 3.75 ZEC. In these cases, the wallet completed syncing without reporting a sync error. The comparisons are recorded in the machine-readable results
For users, this can mean uncertainty over payments, failed spending attempts and time spent switching servers or rescanning wallets. Developers and support staff then have to investigate why a wallet that appears fully synced is reporting incorrect information.
Proposed Solution
Shielded Sync Gateway will check confirmed compact-block data before a light wallet uses it to discover payments and recognise spends. The aim is to detect altered scanning fields and missing transactions before they affect the wallet’s view of its funds.
The verification works in three steps:
- A producer creates verification records from public blockchain blocks.
- The verifier combines those records with the compact scanning fields to reconstruct transaction IDs.
- It checks the complete, ordered transaction list against the transaction commitment in a block header obtained from a trusted Zebra node.
The gateway will construct compact responses from the checked fields. If verification fails, it will return an explicit error rather than serve the affected block. Synchronisation will resume only when verification succeeds and any required chain-state recovery is complete.
The existing prototype demonstrates specific tampering and recovery cases with Zingo CLI on a local test network. Grant funding will support broader transaction coverage, corrected checkpoint handling, stronger reorg and failure recovery, representative mainnet measurements and a focused external technical review.
I will publish the verifier as a reusable Rust library with tests and integration instructions for other wallet developers.
The first release will rely on a trusted Zebra source. Its protection covers confirmed compact scanning data; mempool responses and transparent-address history remain outside that guarantee.
Solution Format
The solution will be delivered as MIT-licensed open-source software, with the following deliverables:
- Rust verification library: Reusable code for checking compact scanning fields and transaction completeness against trusted block headers.
- Producer and local gateway: Command-line software that generates verification records and serves checked compact data through wallet-compatible RPCs.
- Record specification: Documentation of the verification-record format, supported transaction versions and security assumptions.
- Tests and fixtures: Transaction examples and automated tests covering altered data, missing transactions, checkpoint invalidation, restarts and reorgs.
- Versioned Linux release: Release files with checksums, setup instructions, examples and a tested compatibility matrix.
- Validation reports: Mainnet measurements of network traffic, processing time, memory and storage, plus findings and responses from a focused external technical review.
Source code, documentation and reproducible evidence will be published in the [project repository
Dependencies
The project requires Rust, protobuf tooling, existing Zcash transaction libraries and SQLite. Integration tests will use pinned versions of Zebra, Zaino and Zingo CLI.
The gateway requires a trusted Zebra node and checkpoint. Mainnet testing also needs access to full blocks, a Linux environment, CI, compute and storage.
I will handle development independently. The budget includes a focused external technical review. Delivery does not require upstream merges, private APIs or formal partnerships.
Technical Approach
I will build on the existing Rust prototype, using tonic/prost for gRPC and protobuf, and SQLite for atomic updates to verified state.
The verifier will reconstruct transaction IDs from compact fields and verification records, then compare the complete transaction list’s Merkle root with the root in a trusted Zebra header. Wallet responses will be built from checked fields.
I will document the record format and Rust API, add missing v6 Sapling-spend and Orchard fixtures, and compare reconstructed IDs with Zcash transaction-library results. Tests will cover altered data, checkpoint invalidation, cached old-fork responses, reorgs, restarts and network failures, using the pinned Zingo CLI test build where applicable.
Mainnet benchmarks will include traffic from all components, verification time, memory and storage. I will publish the tested block ranges, versions, commands and results so reviewers can reproduce the measurements.
Upstream Merge Opportunities
No upstream forks or modifications are required. Optional integration examples or regression tests could be proposed to Zaino and zingolib maintainers to help others adopt the verifier. These would require maintainer review, but upstream merging would not be a dependency of the eight-week delivery schedule.
Open Source License
MIT
Hardware/Software Costs (USD)
$0
Hardware/Software Justification
None.
Service Costs (USD)
$4,000
Service Costs Justification
-
$1,000: Temporary compute and storage for mainnet replay, integration testing and performance measurements.
-
$3,000: A focused external technical review of the verification boundary and gateway failure handling.
Compensation Costs (USD)
$21,000
Compensation Costs Justification
350 hours at $60 per hour.
This covers the remaining engineering, fixtures, testing, documentation, release preparation and 30 days of support for reproducible bugs within the delivered scope. The existing MVP is the starting point; its completed development is not being charged to this grant.
Total Budget (USD)
$25,000
Previous Funding
No
Previous Funding Details
I have no previously approved Zcash Community Grants projects.
Other Funding Sources
No
Other Funding Sources Details
No other funding has been received or is currently planned for the work covered by this application.
Implementation Risks
-
Checkpoint and recovery handling: The MVP can continue serving cached blocks after detecting a checkpoint-invalidating reorg. This must be corrected and covered by regression tests before release.
-
Transaction coverage: Nonempty v6 Sapling-spend and Orchard cases need additional fixtures and comparison against a reference implementation.
-
Operating costs: The current local benchmark does not establish mainnet performance or overall bandwidth savings. Measurements must include traffic to the trusted Zebra node.
-
Wallet compatibility: Compatibility has been demonstrated with a specific Zingo CLI test configuration. Additional wallet versions and configurations require testing.
-
External review: Reviewer availability and the scope affordable within $3,000 remain uncertain. Any necessary change will be reported and agreed before changing this deliverable.
Potential Side Effects
Rejected data, unavailable dependencies or recovery checks can interrupt wallet syncing. Running the gateway and its trusted-node connection also adds bandwidth, storage and processing costs.
Users could overestimate the protection provided. Documentation will explain the trusted Zebra dependency, the supported confirmed-data checks, and the unauthenticated mempool and transparent-address-history endpoints. Transaction effect verification does not authenticate every raw signature or proof byte.
Success Metrics
-
Publish a versioned verifier, producer and Linux reference gateway with documented interfaces and supported transaction formats.
-
Demonstrate that detected checkpoint invalidation blocks affected cached responses, with reproducible restart, reorg, timeout and recovery tests.
-
Add the missing v6 fixture coverage, document fixture provenance, and match transaction IDs and block transaction roots against a reference implementation.
-
Reproduce rejection and recovery for the five recorded gateway tampering scenarios.
-
Benchmark at least 10,000 mainnet blocks across published ranges. Report transaction counts, verification time, CPU, peak memory, storage and all inbound traffic.
-
Publish the external review’s scope, findings and responses. Resolve release-blocking findings before publishing the release.
-
Provide instructions that allow a developer or reviewer to reproduce the wallet demonstration in a fresh Linux environment.
Startup Funding (USD)
$0
Startup Funding Justification
Existing equipment and the completed MVP allow work to begin without an advance. Funding is requested through milestone payments.
Milestone Details
-
Milestone: 1
Amount (USD): 7000
Expected Completion Date: 2026-11-24
User Stories:- “As a wallet developer, I want documented verification guarantees and predictable failure handling so I can assess whether the gateway suits my application.”
Deliverables: - “Versioned verifier interface and verification-record specification.”
- “Fix for cached responses after detected checkpoint invalidation, including stale-cache checks at startup.”
- “Request limits, timeouts and documented behavior during trusted-node outages.”
- “Automated regression tests, CI checks and updated trust-boundary documentation.”
Acceptance Criteria: >
Published test commands pass. Tests use a non-genesis checkpoint
with cached descendants and demonstrate that detected checkpoint
invalidation blocks affected cached responses until trusted state
is restored. Oversized requests, timeouts and outages have tested,
documented outcomes. - “As a wallet developer, I want documented verification guarantees and predictable failure handling so I can assess whether the gateway suits my application.”
-
Milestone: 2
Amount (USD): 10000
Expected Completion Date: 2026-12-15User Stories:
- “As a gateway operator, I want evidence of transaction coverage and operating costs so I can evaluate deployment.”
Deliverables: - “Nonempty v6 Sapling-spend and Orchard fixtures with documented provenance.”
- “Reference comparisons and malformed-input tests for supported transaction formats.”
- “Reproducible setup separating the trusted validator from the producer and indexer.”
- “Measurements covering at least 10,000 mainnet blocks across identified ranges.”
Acceptance Criteria: >
Transaction IDs and block transaction roots match the reference
implementation across the published corpus, including the added
v6 cases. Fixture origins and networks are clearly labelled.
Published measurements include traffic from every gateway data
source, resource use, versions and reproduction commands. - “As a gateway operator, I want evidence of transaction coverage and operating costs so I can evaluate deployment.”
-
Milestone: 3
Amount (USD): 8000
Expected Completion Date: 2027-02-04User Stories:
- “As a wallet developer or operator, I want a reviewed release and reproducible setup instructions so I can evaluate and use the software.”
Deliverables: - “Focused external technical review, published findings and documented responses.”
- “Versioned Linux release with checksums, targeted for 5 January 2027.”
- “Setup instructions, compatibility matrix and reproducible wallet tampering demonstrations.”
- “Final results report and 30 days of bug-fix support within the delivered scope.”
Acceptance Criteria: >
Release-blocking review findings are corrected and retested.
A fresh Linux environment can reproduce honest syncing and the
five recorded gateway tampering rejection and recovery scenarios.
The review scope, remaining limitations and supported configurations
are published. The 30-day support period is completed, with any
outstanding reported issues documented. - “As a wallet developer or operator, I want a reviewed release and reproducible setup instructions so I can evaluate and use the software.”
Supporting Documents
These documents describe the existing MVP and its recorded results.
-
Source code and README: Implementation, setup and current limitations.
-
Wallet tampering results: Machine-readable controlled test results.
-
Restart and reorg checks: Recorded recovery tests.
-
Benchmark report: Existing local measurements and limitations.
-
Verification-record specification: Current record format and verification rules.
-
MVP demonstration: Recorded demonstration