Project Summary
I have already completed real-node verification, agreed the implementation approach with a GraphSense maintainer, and submitted PR #163 with the parser correction, mainnet fixtures and regression tests.
I am requesting $8,000 to complete upstream review and required fixes, deliver reproducible GraphSense accounting validation, and prepare the operator handoff for correcting historical Zcash data.
Project Description
GraphSense issue #126 documents missing Orchard and Ironwood value balances in its Zcash ingestion pipeline. These omissions produce incorrect transaction totals and fees across fully shielded transactions, pool migrations and mixed transparent/shielded transactions.
My implementation is open in PR #163 and remains unmerged. This grant covers the remaining review, regression hardening, reproducible validation and operator handoff—not reimbursement for completed work.
GraphSense will handle production re-ingestion and re-transformation. My deliverables will remain public and usable without access to its hosted service.
Proposed Problem
GraphSense’s existing parser accounts for Sprout and Sapling shielded values but omits the values inside Orchard and Ironwood bundles. Consequently, transactions can have missing inputs or outputs, zero or incorrect fees, and incomplete accounting for transfers between pools.
For example, the transaction reproduced in PR #163 moves 89,000 zatoshis out of Sapling and 88,000 into Orchard. Its fee is 1,000 zatoshis, but the existing parser counts only the Sapling leg and reports 89,000.
Fixing the parser does not repair previously ingested records. The affected history must also be re-ingested and the derived data rebuilt.
Proposed Solution
I will complete the upstream review process, resolve compatibility and regression issues identified during review, and deliver a repeatable validation procedure for the final correction.
The validation will compare the existing and corrected GraphSense accounting against the same public transaction evidence. It will check signed pool balances, transaction totals, fees and the documented effects on derived data.
I will provide an operator guide and a defined regression-support period. GraphSense will remain responsible for operating its node, production cluster and historical rebuild.
Solution Format
I will deliver:
- The final reviewed GraphSense patch and required regression-test updates.
- A GraphSense-specific validation command, evidence manifest and machine-readable comparison report.
- An operator guide for validating the historical correction.
- A 14-day correction period for confirmed regressions caused by the funded changes.
My code and documentation contributions will be public under the MIT licence.
Dependencies
I will use graphsense-lib, its existing Python testing environment, Zebra RPC data and public Zcash transaction evidence.
GraphSense maintainers control upstream workflow approval, code acceptance and merge timing. The maintainer discussion confirms the implementation direction and assigns production re-ingestion and re-transformation to GraphSense.
GraphSense also owns the separate parquet-schema update needed to persist the new pool-balance fields. I am not requesting funding for that work.
Technical Approach
The existing patch uses signed integer-zatoshi balances for Sapling, Orchard and Ironwood, preserves the generic shielded input/output representation, and validates bundle, action and flag keys explicitly.
The remaining technical work will cover:
Maintainer-requested changes and targeted regression tests for accounting and RPC compatibility.
Explicit handling of missing or malformed required values without silently producing incorrect totals.
A pinned evidence manifest identifying node versions, block hashes, transaction IDs and expected results.
Before-and-after checks for signs, units, multi-pool accumulation and transaction totals.
Resolution of transparent previous outputs before asserting fees for transactions with transparent inputs.
Repeatable validation of the final reviewed GraphSense revision.
The agreed Spark analysis indicates that no Scala change is required. I will flag any contrary finding before expanding the scope
Upstream Merge Opportunities
My contribution targets graphsense/graphsense-lib through PR #163.
The maintainer response records the accepted findings, implementation decisions and rollout responsibilities.
I will address blocking feedback and seek public technical acceptance of the final patch. Merge and release dates remain under GraphSense’s control. Opening a PR alone will not satisfy a paid milestone.
Hardware/Software Costs (USD)
$0
Hardware/Software Justification
Nil
Service Costs (USD)
$0
Service Costs Justification
N/A
Compensation Costs (USD)
$8,000
Compensation Costs Justification
My proposed budget is based on an estimated 160 hours at $50 per hour:
Upstream review, compatibility fixes and regression hardening: 60 hours — $3,000.
Reproducible GraphSense accounting validation: 60 hours — $3,000.
Operator handoff, representative validation and regression support: 40 hours — $2,000.
Total Budget (USD)
$8,000
Previous Funding
No
Previous Funding Details
None
Other Funding Sources
No
Other Funding Sources Details
No response
Implementation Risks
Maintainer availability may delay CI approval, review or acceptance. I will report delays and will not treat an unreviewed patch as complete.
RPC differences may expose missing fields or unsupported transaction shapes. I will document the versions actually tested and add regression coverage for issues found during review.
The amount of review remediation is not yet known. I will agree any material scope or budget change with ZCG rather than introduce unrelated features.
Potential Side Effects
Corrected shielded inputs can change transaction totals, fees, transparent relation estimates and coinjoin classifications. These changes can affect cluster membership when GraphSense rebuilds its derived data, as explained in the PR’s downstream analysis.
I am not adding clustering algorithms, identity enrichment, viewing-key processing or wallet fingerprinting. The operator guide will explain the effects on GraphSense’s existing analysis.
It will also distinguish a positive shielded balance from an unshielding transaction: the balance may represent a fee paid from a shielded pool.
Success Metrics
I will measure completion through:
- Passing applicable upstream checks and resolving blocking review comments.
- Public maintainer acceptance of the final patch.
- Reproducible validation from a clean checkout against a fixed dataset.
- Exact expected balances, transaction totals and fees, with no unexplained mismatches.
- A reviewed operator guide covering historical correction and downstream effects.
- Completion of the agreed regression-support period.
Startup Funding (USD)
$0
Startup Funding Justification
None
Milestone Details
Milestone 1 — Upstream Review and Regression Hardening
Amount: $3,000
Expected Completion Date: Two weeks after the agreed grant start.
User Story:
As a GraphSense maintainer, I want the correction to pass upstream checks and resolve review findings before accepting it.
Deliverables:
I will address CI failures and blocking review comments, implement required compatibility fixes, add targeted regression coverage, and provide a final review record linking the code revision and test results.
Coverage will address issues identified during review, including required-value handling, optional bundles, strict field validation and multi-pool accounting.
Acceptance Criteria:
All applicable upstream checks pass, blocking review comments are resolved, and a GraphSense maintainer publicly confirms technical acceptance or approval for merge. The focused Zcash tests and applicable repository test suite pass.
Milestone 2 — Reproducible GraphSense Accounting Validation
Amount: $3,000
Expected Completion Date: Four weeks after the agreed grant start.
User Story:
As a GraphSense operator, I want to reproduce the corrected accounting without relying on someone else’s local test results.
Deliverables:
I will deliver a GraphSense-specific comparison command, a versioned evidence manifest, expected results and a machine-readable before-and-after report.
The dataset will cover shielding, unshielding, fully shielded fee payments, Sapling/Orchard combinations, non-zero Ironwood balances and three-pool transactions. I will reuse existing evidence and add any missing previous-output data required for complete fee checks.
Acceptance Criteria:
A reviewer can run the documented command from a clean checkout after dependency installation. Every listed case matches its expected signed pool balances, transaction totals and fee.
The report identifies the code revisions and evidence used. Required mismatches return a failure rather than a successful result.
A GraphSense maintainer or technical reviewer agreed with ZCG confirms that the results are reproducible.
Milestone 3 — Operator Handoff and Regression Support
Amount: $2,000
Expected Completion Date: Six weeks after the agreed grant start, including 14 days of support following acceptance of the validation package.
User Story:
As a GraphSense operator, I want clear checks for the historical repair and its effects on existing derived data.
Deliverables:
I will provide an operator guide covering re-ingestion from NU5 height 1,687,104, Ironwood accounting from height 3,428,143, and the full re-transformation requirement.
The guide will include representative before-and-after results, expected changes to transaction accounting and relation estimates, and checks for coinjoin and cluster effects. It will distinguish parser outputs from fields that require GraphSense’s separate storage-schema update.
During the support period, I will reproduce and fix confirmed regressions caused by the funded changes in the documented environment.
Acceptance Criteria:
The guide and representative validation results are public and reviewed by a GraphSense maintainer or technical reviewer agreed with ZCG. The support period is complete, and no confirmed blocking in-scope regression remains unresolved.
GraphSense’s production re-ingestion, cluster rebuild and release timing are outside this milestone