Grant Application - {Zcash Light Client Privacy Transport Library}

Community Grants Applications
1

Project Summary

We need $18,500 to create a new library for private transport using Rust, and a local proxy to work with the current Zcash lightwalletd system. This will help keep Zcash transactions private and secure. The library will be designed to handle lightwalletd traffic in a way that protects user information.

The project helps wallet and SDK developers reduce selected network metadata leaks by routing sync traffic through SOCKS5/Tor-compatible transport, shaping compact-block range requests, caching fetched windows locally, and generating request-trace repor

Project Description

Zcash shielded transactions protect transaction contents, but light-client network behavior can still leak metadata. ZCG’s funding wishlist explicitly includes network-layer privacy solutions for light-client SDKs and libraries, and the Zcash wallet threat model documents known network-layer weaknesses around lightwalletd traffic.

This project aims to create a reusable library in Rust, along with a reference proxy binary, to support current flows based on lightwalletd. The first version of this project will prioritize optimizing the sync traffic for CompactTxStreamer, particularly for requests that involve retrieving compact block ranges, such as those using the GetBlockRange style. By doing so, it seeks to enhance the efficiency and performance of these specific types of requests.

The project does not claim full wallet anonymity. It reduces selected metadata leaks by routing traffic through privacy transport, normalizing selected range requests into fixed windows, caching windows locally, coalescing nearby requests, and reporting before/after request behavior.

This project doesn’t change anything in Zebra, Zaino, Zallet, lightwalletd, or the official SDK repositories. It’s also important to note that this work is not meant to replace any future efforts to improve network privacy on Z3.

Proposed Problem

Right now, most Zcash light-client flows rely on servers that are not on the user’s device, called lightwalletd servers. These servers are accessed through a secure connection, which keeps the messages safe from people who might be listening in on the network. However, this secure connection doesn’t hide everything - like who is talking to whom, or when and how much data is being sent. This information, known as metadata, can still be seen by the server and by anyone who is watching the network traffic.

The Zcash wallet has some known weaknesses that can be exploited by people watching the network or lightwalletd. These weaknesses include leaks from bandwidth patterns, exposure of IP addresses and locations, detection of active wallets, correlation of users on the same lightwalletd, and inference of wallet birthdays from the size of the initial sync. You can find more information about this in the Zcash Documentation.

Generic Tor/SOCKS5 routing helps with IP exposure, but it does not understand Zcash light-client sync behavior. It does not normalize compact-block request ranges, cache block windows, coalesce nearby requests, or report what metadata changed. The missing piece is a small Zcash-specific transport library for current lightwalletd sync traffic.

Proposed Solution

We are going to create the Zcash Light Client Privacy Transport Library.

V1 will include:

  1. A Rust library for privacy-aware lightwalletd transport.
  2. SOCKS5/Tor-compatible upstream routing.
  3. Fail-closed mode when privacy transport is required.
  4. Compact-block range windowing for selected GetBlockRange traffic.
  5. Local compact-block window cache.
  6. Request coalescing for nearby or repeated range requests.
  7. A reference local proxy binary for testing and integration.
  8. Before/after request-trace reports.
  9. Documentation describing privacy benefits and limitations.

The goal here is to create a local testing endpoint that works with lightwalletd, and the key thing we’re making is a Rust library that can be used again and again.

Solution Format

Open-source software.

Deliverables:

  • Rust library crate.
  • Reference local proxy binary.
  • SOCKS5/Tor transport module.
  • Fail-closed transport mode.
  • Compact-block range window scheduler.
  • Local compact-block window cache.
  • Request coalescing module.
  • Request-trace report generator.
  • Example configuration profiles.
  • Developer integration guide.
  • Privacy behavior and limitations documentation.

Dependencies

Technical dependencies:

  • public lightwalletd protocol documentation;
  • local Rust development environment;
  • local SOCKS5/Tor setup for testing;
  • public or local lightwalletd endpoint for development testing.

Project dependencies:

  • no upstream merge required;
  • no hosted infrastructure required;
  • no vendor approval required;
  • no mobile SDK upstream approval required;
  • There are no changes to Zebra, Zaino, Zallet, or lightwalletd.

Technical Approach

Rust Library and Reference Binary

The project will be implemented as:

  • a Rust library crate that handles transportation, scheduling, caching, and tracking logic;
  • a local proxy that uses the library as a base.

The proxy lets developers point a wallet/devtool at a local endpoint and observe the library behavior without modifying wallet code.

V1 Method Scope

V1 focuses on CompactTxStreamer sync traffic:

  • GetBlockRange: shaped into fixed-size upstream windows where configured.
  • GetLatestBlock: pass-through with trace recording.
  • GetLightdInfo: pass-through with trace recording.
  • Repeated compact-block range requests: served from local cache when available.
  • Nearby range requests: coalesced where configured.

Other methods will be pass-through unless explicitly documented.

The SendTransaction feature isn’t being kept private in the first version. If you use a reference proxy, it might still pass through, but the timing of when transactions are sent isn’t something we’re focusing on for privacy right now. This is just for the initial release, so we’ll have to wait and see what happens next.

Transport Layer

The transport layer will support:

  • SOCKS5 upstream routing;
  • Tor-compatible local SOCKS5 configuration;
  • fail-closed mode;
  • direct mode for developer testing only.

Fail-closed mode means that when privacy transport is required, the library must not silently fall back to direct networking.

Compact-Block Window Scheduler

The scheduler will normalize selected exact range requests into fixed-size upstream windows.

Example:

Wallet request:
GetBlockRange(1,000,123 → 1,000,130)

Upstream request:
GetBlockRange(1,000,000 → 1,000,255)

Local response:
Serve requested subset from cached window

Window size will be configurable.

Local Window Cache

The cache will store fetched compact-block windows locally.

It will support:

  • bounded cache size;
  • configurable retention;
  • cache hit/miss tracking;
  • repeated request avoidance.

Request Coalescing

Nearby or repeated range requests during active sync can be coalesced before being sent upstream.

The goal is not to remove all timing leakage. The goal is to reduce unnecessary exact-range and repeated upstream requests where feasible.

Request-Trace Reports

The tool will generate before/after request-trace reports.

Metrics:

  • original request count;
  • upstream request count after shaping;
  • exact range requests upstream;
  • fixed-window requests upstream;
  • cache hits;
  • cache misses;
  • repeated ranges avoided;
  • SOCKS5/Tor transport status;
  • fail-closed behavior.

Example output:

Request Trace Report

Profile: windowed-sync
SOCKS5 transport: enabled
Fail-closed: enabled

Original wallet requests: 148
Upstream requests after shaping: 37
Exact block-range requests upstream: 0
Fixed-window requests upstream: 37
Cache hits: 111
Repeated upstream ranges avoided: 24

Limits:
- lightwalletd can still observe active sessions.
- transaction submission timing is not hidden in this profile.
- this does not provide full anonymity.

Upstream Merge Opportunities

This project doesn’t need you to change or make copies of the existing Zcash repositories. If the people who take care of the library in the future, or the teams that work on the software development kit, find it helpful, they might decide to use some of its parts, like the way it handles moving data around or how it schedules tasks, at a later time. It’s not necessary for this library to be merged with the main project for it to be useful.

Hardware/Software Costs (USD)

0

Hardware/Software Justification

nil

Service Costs (USD)

$0

Service Costs Justification

N/A

Compensation Costs (USD)

$18,500

Compensation Costs Justification

Compensation covers engineering, transport implementation, request-shaping logic, local cache, trace reporting, tests, documentation, QA, and handoff.

Estimated effort:

  • transport core and SOCKS5/fail-closed mode: 55 hours;
  • CompactTxStreamer request-shaping, cache, and coalescing: 90 hours;
  • reference proxy, reporting, docs, packaging, and QA: 70 hours.

Total estimated effort: 215 hours
Blended rate: ~$86/hour
Total compensation: $18,500

Total Budget (USD)

$18,500

Previous Funding

No

Previous Funding Details

N/A

Other Funding Sources

No

Other Funding Sources Details

No response

Implementation Risks

  1. This project could be confused with a standard Tor proxy, which might lead to some misunderstandings about its actual purpose and how it works.
    Mitigation: the main deliverable is the Zcash-specific request-shaping library: compact-block windowing, caching, coalescing, and trace reports.

This project could be viewed as having some similarities with the work that will be done on the Z3 Tor in the future.
This project is designed to reduce the impact of current lightwalletd traffic without altering any Z3 components. Essentially, it’s a self-contained library for developers, along with a reference proxy, that can be used independently.

  1. ** Privacy benefits may be overstated.**
    Mitigation: documentation and reports will state exactly what is reduced and what remains. The project will not claim full anonymity.

  2. ** Mobile SDK adoption may require future integration work.**
    Mitigation: V1 provides a Rust library, reference proxy, and integration guide. Direct Android/iOS SDK integration is out of scope.

Potential Side Effects

A user could misunderstand the tool as complete anonymity software.

To reduce that risk, the documentation and generated reports will state that the library only reduces selected network metadata leaks and does not hide all wallet activity from lightwalletd.

You don’t need to use your own money or sensitive information like wallet keys, seed phrases, or live wallet data to develop or test something.

Success Metrics

  1. The Rust library supports SOCKS5/Tor-compatible upstream routing.
  2. Fail-closed mode prevents direct fallback when privacy transport is required.
    Some GetBlockRange requests can be standardized to fit within set limits.
  3. The local cache serves repeated compact-block range requests.
  4. Nearby/repeated range requests can be coalesced where configured.
  5. The reference proxy runs locally.
  6. Request-trace reports show before/after upstream request behavior.
  7. Documentation states privacy benefits and limitations clearly.
  8. The project works without upstream merge, hosted infrastructure, or core-team dependency.

Startup Funding (USD)

NIL

Startup Funding Justification

NIL

Milestone Details

  • Milestone: 1
    Amount (USD): 5,000
    Expected Completion Date: 2026-08-15
    User Stories:

  • As someone who develops wallets, I need a transport module that can send lightwalletd traffic through a SOCKS5 or Tor-compatible connection. This way, I can test how private the network is without having to change the underlying infrastructure.

  • When it comes to keeping things private, I think it’s a good idea to have a setting that stops working altogether if it can’t use the private way of sending data. This way, if something goes wrong and it tries to switch to a regular connection without telling us, it just won’t work at all.
    Deliverables:

  • Rust crate repository structure.

  • SOCKS5/Tor-compatible upstream transport.

  • Fail-closed mode.

  • Config profiles: direct-dev, ip-only, windowed-sync.

  • Basic transport tests.
    Acceptance Criteria:

  • You can send traffic through a special kind of connection called a SOCKS5 endpoint.

  • Fail-closed mode prevents direct fallback when enabled.

  • Transport profiles are documented.

  • Tests cover direct mode, SOCKS5 mode, and fail-closed behavior.

  • Milestone: 2
    Amount (USD): 7,000
    Expected Completion Date: 2026-09-05
    User Stories:

  • When I’m working on a light client, I want to be able to take a range of compact block requests and standardize them into fixed-size chunks that get sent upstream. This should help cut down on the number of exact range patterns being used, at least in the areas where I’ve set it up to do so.

  • When creating a wallet, it’s helpful if repeated range requests can be handled using a local cache. This way, we can cut down on unnecessary queries to upstream systems, making things more efficient. By doing this, we can reduce the number of times we need to ask for information from other systems, which should help improve performance.
    Deliverables:

  • Fixed-window scheduler for selected GetBlockRange traffic.

  • Bounded local compact-block window cache.

  • Request coalescing module.

  • Tests for cache, range, and coalescing behavior.
    Acceptance Criteria:

  • Exact range requests can be normalized into fixed windows.

  • Repeated requests can be served from cache.

  • Nearby requests can be coalesced where configured.

  • Tests cover cache hit, cache miss, overlapping range, boundary-window, and coalescing cases.

  • Milestone: 3
    Amount (USD): 6,500
    Expected Completion Date: 2026-09-26
    User Stories:

  • To test the transport library without linking it to a wallet, I need to set up a reference proxy on my local machine, allowing me to verify its behavior and functionality beforehand. This way, I can ensure everything works as expected before integrating it with the wallet.

  • As a developer, I want before/after request-trace reports so that I can see what upstream request behavior changed.
    Deliverables:

  • Reference local proxy binary.

  • Request-trace report generator.

  • Sample before/after trace report.

  • Integration guide.

  • PRIVACY_BEHAVIOR.md.

  • LIMITATIONS.md.

  • Final README.
    Acceptance Criteria:

  • Reviewer can run the reference proxy locally.

  • Sample trace report shows original vs shaped upstream request behavior.

  • Documentation states privacy benefits and limits.

  • The project can be used on its own, without needing to merge it with other projects or relying on external hosting services.

2 Likes
2

I think one of the most valuable aspects of this proposal is that it clearly defines its scope and limitations.

It doesn’t claim to provide perfect anonymity. Instead, it focuses on reducing specific metadata leaks that exist today while documenting exactly what is and isn’t protected.

That kind of transparency is important for security-related projects, and it makes the proposal much easier to evaluate.