Project Summary
A zcashd emergency recovery phrase can be the last backup a user has after losing wallet.dat, yet legacy derivation rules can leave that user holding a valid 24-word phrase without a direct way to recover the corresponding legacy Sapling and phrase-derived transparent funds through Argos. We already built a working MVP that adds this recovery path to Argos, and the Argos maintainers have publicly confirmed they are open to reviewing the implementation; this grant will turn that MVP into a rigorously validated, end-to-end tested, documented, and upstream-ready recovery feature. Demo video
Project Description
Argos already supports recovery from legacy Zcash wallet files, seed phrases, and standalone spending keys. Crackdevs is extending that recovery path to cover a difficult case: users who still have a zcashd emergency recovery phrase but no longer have the original wallet.dat.
We have already built an MVP that adds zcashd emergency-phrase handling to Argos, including the legacy Sapling and phrase-derived transparent derivation paths and compatibility tests against zcashd-generated reference data. The Argos maintainers have also publicly confirmed that they are open to reviewing an implementation of these features.
This grant will fund the remaining work needed to turn the MVP into a well-validated upstream contribution: independently verify the supported historical derivation cases, prove funded phrase-only recovery and confirmed sweeps on regtest, test bounded-search and failure cases, document exactly what the phrase can and cannot recover, and submit a focused upstream pull request.
The result will be a tested recovery path inside Argos for supported legacy zcashd funds, without requiring the original wallet database and without creating a separate wallet or recovery application.
Proposed Problem
A zcashd emergency recovery phrase can be the only backup left after a user loses wallet.dat, but having the phrase does not automatically mean the user can recover every phrase-derived legacy key correctly.
The difficulty comes from how zcashd handled wallet seeds over time. For wallets upgraded from before zcashd 4.7, some legacy Sapling keys must be reconstructed from the mnemonic’s original entropy rather than through normal BIP-39 seed derivation. Newer zcashd wallets use a different derivation path for legacy Sapling and phrase-derived transparent addresses. If recovery software applies the wrong path, it can still accept the phrase and complete a scan, but search keys that were never used by the wallet.
That creates a serious recovery problem: an empty result may mean there are no funds on the searched keys, or it may mean the wrong derivation path, address range, or scan range was used. A user who has already lost the original wallet database has very little room for that ambiguity.
The phrase also has clear limits. It cannot recreate independently generated Sprout keys, imported private keys, pre-4.7 random transparent keys, or other secrets that existed only in wallet.dat. A recovery tool therefore needs to do two things correctly: recover the key families that the phrase can actually reproduce, and clearly tell the user what was not covered.
This work is timely because zcashd is no longer the wallet software where new recovery support is likely to be added, while Argos already has the scanning, balance detection, and sweep infrastructure needed to handle recovered keys. The missing piece is a reliable zcashd phrase-recovery path with tested historical derivation rules, clear search boundaries, and results that users can understand and verify.
Proposed Solution
We are adding a dedicated zcashd emergency recovery phrase path to Argos so users can recover the legacy keys that can actually be reproduced from the phrase, without needing the original wallet.dat.
The MVP already implements the core derivation logic for the supported zcashd cases: pre-4.7 legacy Sapling recovery from the phrase’s original entropy, post-4.7 legacy Sapling derivation, and post-4.7 phrase-derived transparent receiving and change keys. These keys are passed into Argos’s existing recovery flow, so we do not need to build a new scanner, transaction builder, or wallet.
The remaining work is to make that recovery path fully verifiable. We will test the supported derivations against independent zcashd-generated reference data, create funded regtest cases, recover those funds using only the phrase, and complete confirmed sweep transactions to prove the full recovery flow works beyond key derivation alone.
The recovery flow will also make its limits clear. It will show the derivation range and scan range being searched, allow users to widen the search when necessary, and state which funds cannot be recovered from the phrase alone, such as independently generated Sprout keys, imported private keys, and pre-4.7 random transparent keys.
The final deliverable will be a tested, documented Argos contribution with reproducible fixtures, recovery tests, clear limitations, and an upstream pull request. The Argos maintainers have already confirmed that they are open to reviewing the implementation.
Solution Format
The solution will be delivered as an open-source software contribution to Argos, not as a separate wallet or standalone recovery application.
The deliverables will include the zcashd emergency recovery phrase implementation, support for the covered legacy Sapling and phrase-derived transparent paths, compatibility fixtures against zcashd reference data, funded regtest recovery tests, confirmed sweep tests, user-facing recovery documentation, and a focused upstream pull request to Argos.
The final submission will also include a tagged tested revision, reproducible test commands, a clear support-and-limitations matrix, and the evidence needed for reviewers to verify the recovery flow independently.
Dependencies
The project depends on the existing Argos codebase and its current key-import, scanning, balance detection, transaction-building, sweep, and confirmation components. Our work adds the zcashd emergency recovery phrase path on top of those existing recovery flows rather than replacing them.
Technical dependencies include the Zcash Rust libraries already used by Argos, archived zcashd releases and wallet exports for historical compatibility checks, and the project’s local regtest environment for funded recovery and confirmed sweep testing.
For upstream coordination, the Argos maintainers have already confirmed that they are open to reviewing the implementation. We will submit the completed work as a focused upstream contribution and respond to review feedback during the grant period. Upstream merge is not required for us to complete the grant deliverables and remains under the maintainers’ control.
The work does not depend on private wallet data, access to real user recovery phrases, paid APIs, commercial infrastructure, or commitments from external organizations. All validation can be performed using synthetic phrases, test funds, public source code, and reproducible local test environments.
Technical Approach
We will complete the MVP as a Rust contribution to Argos’s existing core library and command-line interface. The implementation already derives the covered legacy keys and passes them into Argos’s imported-key recovery workflow. The remaining work focuses on historical compatibility, funded recovery, failure handling, and reproducible validation.
1. Build on Argos’s maintained recovery stack
We will use the Zcash libraries already integrated into upstream Argos, including zcash_keys, sapling-crypto, zcash_transparent, zcash_client_backend, and zcash_client_sqlite. We will reuse the existing scanning, transaction-building, fee-checking, and confirmation components rather than introduce new cryptographic primitives or a separate recovery engine. Dependency versions will remain compatible with upstream, with the tested Rust toolchain and Cargo.lock recorded for reproducible builds.
Archived zcashd releases will be used only in isolated test environments to generate historical reference data. They will not be required for users to run recovery or used as the node for current-consensus acceptance tests. This distinction matters because zcashd is deprecated and does not support NU6.3.
2. Verify each supported historical derivation
We will independently validate the three derivation cases covered by the MVP:
| Recovery case | Seed interpretation | Derivation path |
|---|---|---|
| Older Sapling keys in wallets upgraded to zcashd 4.7.0 | Original seed reconstructed from mnemonic entropy | m/32'/coin_type'/account' |
| Post-4.7 legacy Sapling keys | BIP-39-derived seed | m/32'/coin_type'/0x7FFFFFFF'/address_index' |
| Post-4.7 legacy transparent keys | BIP-39-derived seed | m/44'/coin_type'/0x7FFFFFFF'/change/index |
The transparent tests will cover both receiving and change branches. These paths are implemented in the MVP; the separate entropy-based reconstruction for older Sapling keys is documented in zcashd’s release notes.
We will compare derived key bytes against zcashd-generated exports, including non-zero indices, and add an upgraded-wallet fixture covering keys created before and after the upgrade. When the wallet’s history is unknown, the recovery path will test both supported seed interpretations rather than guess from the phrase.
The existing reference tests establish key compatibility, not funded recovery. We will preserve that distinction and add separate acceptance tests for discovery and spending.
3. Prove recovery using only the phrase
We will extend Argos’s existing Docker Compose test environment, which uses Zebra and lightwalletd, with phrase-specific funded fixtures. The test configuration will record node versions, activation settings, and the consensus rules used to construct and validate transactions.
Each fixture will contain known funds at documented legacy Sapling and transparent indices, including transparent change addresses and funded addresses separated by unused indices. Recovery will run in a clean workspace without access to the source wallet.dat or exported private keys.
The acceptance run must find every planted in-scope balance within the configured search. It will then produce a sweep preview without broadcasting, explicitly authorize the required recovery transactions, mine confirmations, and verify receipt at a fresh compatible Unified Address. The published results will reconcile the recovered amounts, destination receipts, and fees, with every transaction ID recorded.
4. Test search boundaries and failure handling
Each recovery report will identify the network, derivation cases, index ranges, and block range searched. We will test deliberately narrow bounds and late scan starts, then repeat recovery with the correct settings to demonstrate that previously excluded fixture funds are found.
Widening the key range must not reuse a narrower scan as though it covered the additional keys. The implementation and documentation will describe an explicit bounded search, not automatic or exhaustive address discovery.
Tests will also cover invalid phrases, network mismatches, empty results, and transaction failures. Phrase input, error messages, routine logs, and exported reports will be checked for secret exposure. Existing workspace protections and explicit sweep authorization will be preserved, and a later failure must not erase transaction IDs already broadcast.
5. Deliver reproducible tests and an upstream contribution
We will run the applicable Rust build, formatting, lint, unit-test, and dependency checks, alongside the separately documented funded integration tests. Results will be tied to exact source revisions and reproducible commands.
The final handoff will include a focused upstream pull request preserving Argos’s history, a tagged tested revision, fixture-generation instructions, recovery commands, and a supported-case and exclusions matrix. We will submit the contribution early enough for review during the grant period and record review responses and outstanding maintainer decisions.
Upstream Merge Opportunities
The upstream target is Argos: GitHub - sovright/argos: ZECK ZecWallet Lite recovery tool · GitHub. Our MVP is currently available at GitHub - OlamideAfunsho/argos · GitHub and will be prepared as a focused upstream contribution.
The changes add zcashd emergency recovery phrase support for the covered legacy Sapling and phrase-derived transparent paths, together with compatibility fixtures, funded recovery tests, recovery-limit handling, and documentation.
If merged, the feature would become part of Argos’s existing recovery workflow instead of remaining in a separate fork. We have already contacted the Argos maintainers, and they publicly confirmed that they are open to reviewing an implementation of these features.
We plan to open the upstream pull request during the first milestone and address review feedback during the grant period. Merge timing remains under the maintainers’ control, so the grant deliverable is a tested, reviewable upstream contribution rather than a guaranteed merge.
Hardware/Software Costs (USD)
$0
Hardware/Software Justification
N/A
Service Costs (USD)
$0
Service Costs Justification
N/A
Compensation Costs (USD)
$10,000
Compensation Costs Justification
| Work area | Estimated hours | Cost |
|---|---|---|
| Historical compatibility validation and upstream baseline | 50 | $2,500 |
| Funded phrase-only recovery and confirmed sweep testing | 90 | $4,500 |
| Search-bound, failure-handling, and regression fixes | 35 | $1,750 |
| Documentation, review responses, and final handoff | 25 | $1,250 |
| Total | 200 | $10,000 |
Compensation covers the remaining engineering and validation work only. The completed MVP is not being billed again, and there is no separate project-management, marketing, or contingency fee.
Total Budget (USD)
$10,000
Previous Funding
No
Previous Funding Details
Nil
Other Funding Sources
No
Other Funding Sources Details
No response
Implementation Risks
The main implementation risks are historical compatibility, recovery-range configuration, and keeping the contribution aligned with upstream Argos.
We will mitigate these by validating every supported derivation case against independent zcashd reference data, testing funded recovery at non-zero indices and transparent change paths, and making recovery bounds explicit so wider searches can be repeated when needed. The work will also stay aligned with Argos’s current supported Zcash stack, with build, test, lint, and dependency checks completed before final delivery.
Potential Side Effects
The main potential side effect is an incomplete recovery result if the wrong historical derivation case, scan start, or search range is used. To reduce this risk, the recovery flow will clearly show what was searched, support wider repeat scans, and avoid presenting a bounded empty result as proof that no funds exist.
Recovery phrases and private keys are also sensitive, so the implementation will avoid exposing them in normal logs, reports, or public test evidence. Sweep actions will remain explicit and separate from read-only scanning and dry-run review.
Success Metrics
Success will be measured by the following outcomes:
- All supported zcashd derivation cases match independently generated reference data, including non-zero indices and transparent change paths.
- Funded regtest fixtures are recovered using only the emergency recovery phrase, without relying on the original
wallet.dator exported private keys. - Recovery transactions are successfully previewed, broadcast, confirmed, and reconciled against expected balances and fees.
- Search bounds, invalid inputs, and incomplete scan conditions behave as documented and do not produce misleading recovery results.
- The final implementation passes the applicable build, test, lint, and dependency checks.
- A documented upstream pull request is submitted to Argos with reproducible test instructions, supported-case documentation, and review-ready code.
Startup Funding (USD)
$0
Startup Funding Justification
N/A
Milestone Details
- Milestone: 1
Amount (USD): 2500
Expected Completion Date: 2026-10-16
User Stories:
- "As an Argos reviewer, I want independent evidence that the supported zcashd emergency recovery phrase derivations match the keys produced by zcashd, so that the recovery implementation can be reviewed against known reference data."
Deliverables:
- "Compatibility tests covering pre-4.7 legacy Sapling, post-4.7 legacy Sapling, and post-4.7 phrase-derived transparent receiving and change keys."
- "Reference fixtures covering non-zero derivation indices."
- "A focused upstream pull request to Argos containing the phrase-recovery contribution."
- "Passing applicable build, test, lint, and dependency checks for the milestone revision."
Acceptance Criteria: >-
The published tests reproduce the expected key material for every supported
derivation case, including non-zero indices and transparent change paths.
The test commands and reference fixtures are publicly reproducible, and the
upstream pull request is available for review.
- Milestone: 2
Amount (USD): 4500
Expected Completion Date: 2026-10-30
User Stories:
- "As a user recovering a zcashd wallet, I want Argos to find and recover supported funds using only my emergency recovery phrase, so that loss of wallet.dat does not prevent recovery of phrase-derived funds."
Deliverables:
- "Funded regtest fixtures covering supported legacy Sapling and transparent recovery cases."
- "Phrase-only recovery from a clean environment without the original wallet.dat or exported private keys."
- "Recovery tests covering non-zero indices, transparent change addresses, and deliberately unused indices."
- "Dry-run and confirmed recovery transactions with recorded transaction IDs, recovered amounts, and fees."
Acceptance Criteria: >-
Using only the synthetic emergency recovery phrase and documented recovery
settings, Argos finds the expected funded Sapling and transparent outputs.
The dry-run broadcasts nothing, and the authorized recovery transactions
are successfully broadcast, confirmed, and reconciled against the expected
balances and fees.
- Milestone: 3
Amount (USD): 3000
Expected Completion Date: 2026-11-13
User Stories:
- "As an Argos user or maintainer, I want the recovery path to clearly state what was searched, what is supported, and what is not recoverable from the phrase, so that recovery results can be interpreted correctly."
Deliverables:
- "Tests for search bounds, wider repeat searches, invalid input, scan-start handling, and relevant regressions."
- "User documentation covering supported wallet histories, recovery limits, search settings, and phrase-only exclusions."
- "Final tested revision with reproducible build and acceptance-test instructions."
- "Responses to applicable upstream review feedback and a final handoff of the contribution."
Acceptance Criteria: >-
The documented recovery workflow can be reproduced from the published
instructions. Tests demonstrate correct handling of supported derivations,
bounded searches, wider repeat searches, and invalid inputs. The final
revision passes the applicable checks and clearly records the supported
cases, known limitations, and upstream review status.
Supporting Documents
- File Name: Demo Video
Link: https://drive.google.com/file/d/1zWo2r95AnwryF-LWUa577wThS1tJxNG2/view?usp=sharing
Description: Demo of the current Argos zcashd emergency recovery phrase MVP.
- File Name: MVP Repository
Link: https://github.com/OlamideAfunsho/argos
Description: Public repository containing the implemented zcashd emergency recovery phrase support and test coverage.
- File Name: Upstream Argos Repository
Link: https://github.com/sovright/argos
Description: Upstream Argos repository targeted for the final contribution.