Project Summary
Build and validate a testnet recovery CLI that allows a 2-of-3 Konclave vault to make a shielded payment from complete member backups without Konclave’s coordinator or relay. The project connects existing wallet and signing components into a reproducible recovery procedure, with local payment approval and explicit protections against unsafe or repeated signing.
Project Description
This project implements the testnet recovery path tracked in Konclave issue #613: reconstruct the original wallet from complete member backups and complete a shielded payment without Konclave’s coordinator or relay.
The maintainer has welcomed the contribution and provided concrete implementation requirements. PR #1069 already documents two fresh harness-generated vaults, each producing three complete encrypted exports that reopened after helper shutdown. The PR remains open; transaction signing and recovery payments have not yet been demonstrated.
Funding covers the remaining wallet reconstruction, transaction preparation, authenticated manual signing, interruption handling, and recovery drills. The completed export harness is excluded from the request.
The supported scope is a 2-of-3 quorum, harness-generated v2 Private-vault exports, one confirmed Ironwood note, and one agreed shielded testnet destination. The result will give maintainers an executable recovery procedure and reproducible evidence for their subsequent mainnet rehearsal. Production browser-export validation and mainnet deployment remain outside this grant.
Proposed Problem
A treasury can retain enough signing keys to authorize a payment and still lack a working way to make that payment when its coordinating services disappear.
Konclave’s documented recovery gap is concrete: complete Private-vault backups contain the necessary shares and viewing information, but there is no implemented end-to-end workflow for spending from those backups without its services. A group relying on member backups could therefore be unable to pay approved expenses or move its funds during a prolonged outage.
Registering the vault again creates a different on-chain identity; it does not restore access to the original funds. Recovery must preserve the original viewing key and scan height, rebuild the wallet, and safely complete threshold signing.
Issue #613 identifies this missing path, and the maintainer has explicitly invited work on it.
Proposed Solution
Provide a guided CLI workflow:
- Each participating member opens and validates their own encrypted export locally.
- A building participant reconstructs a fresh view-only wallet from the original viewing key and scan height, then builds and proves the transaction.
- Each signer enters the exact destination, amount, and memo locally before accepting incoming messages.
- Two members complete the existing signing process through authenticated copy-and-paste messages, without Konclave’s coordinator or relay.
- The building participant finalizes and broadcasts the transaction, then verifies confirmation.
Each member retains their own share. The signing processes make no network connections; wallet synchronization and broadcasting use a public testnet service.
The CLI rejects unsupported exports, mainnet viewing keys, missing recovery information, and transactions requiring more than one spend.
Solution Format
An open-source Node.js recovery CLI integrated with the Konclave repository, accompanied by:
- Automated acceptance and rejection tests.
- A reproducible Linux testnet drill.
- Operator instructions covering setup, recovery, interruption, and cleanup.
- Machine-readable PASS/FAIL results and sanitized verification evidence.
- Source revision, engine checksum, and network-configuration records.
Dependencies
Technical dependencies:
- Existing Konclave export, wallet, envelope, and signing components.
- Pinned zcash-sign and zcash-devtool builds.
- Public testnet synchronization and broadcast services.
Coordination dependencies:
- Maintainer-owned issue #1045 supplies the reviewed testnet network rules and build configuration.
- The recovery domain and session design require maintainer agreement before signing implementation.
- All upstream PRs require Konclave’s security review before merge.
- Intended-user milestone validators will be confirmed with ZCG; this application does not assume that a particular maintainer has committed to grant validation.
Wallet reconstruction and transaction preparation can proceed before #1045. Dependent signing work waits for the required configuration and design agreement.
Technical Approach
Reuse the existing Konclave components rather than introduce another signing implementation:
- Open each member’s export through scripts/open-export.mjs. Read passphrases only through a hidden terminal prompt. Reject missing or non-testnet viewing keys immediately after decryption, before using the key share.
- Validate the export’s identity and derive the vault’s own receivers locally. Incoming messages cannot supply the member’s approved payment or identify which receivers belong to the vault.
- Reconstruct a fresh view-only wallet from the original UFVK and scan floor. Use the existing konclave-signer transaction-building path and pinned zcash-devtool proving and broadcast tooling.
- Run the existing SigningMachine and konclave-wasm package inside Node, preserving entry points and check ordering. Each signer enters the exact destination, amount, and memo before accepting incoming ceremony messages.
- Place canonical recovery envelopes in konclave-seal. Authenticate senders against the receiver’s own public key package, use a separately agreed recovery domain, and bind messages to fresh participant challenges and the fixed participant set.
- Derive transaction-signing inputs from each signer’s own PCZT. Use the maintainer-provided testnet build and network rules, with no mainnet mode or runtime network selection.
- Keep nonces in memory only, with no session-resume command. Preserve local approval identities and signed records across restarts using approvalDecision and signed-record.ts. A failed record write prevents release of a transaction signature share.
Only the building participant synchronizes a wallet. Other signers check their exact approved payment and the existing fee rules; they do not independently establish the vault’s total balance.
The drill checks the scan floor against its known funding height. An export alone cannot establish that its scan floor includes every historical payment.
New code will be available under MIT, preserving applicable upstream license notices.
Upstream Merge Opportunities
The maintainer has welcomed this contribution under issue #613 and confirmed that it is separate from the backup-format work.
Changes will be submitted as small PRs against staging: wallet reconstruction and transaction preparation; recovery envelopes; signing integration and rejection tests; and drill evidence.
The work gives Konclave a tested foundation for recovery from member backups using its existing signing implementation. Every PR will follow the repository’s contribution and security-review requirements.
Merge timing remains under maintainer control. This grant delivers the bounded testnet contribution; it does not claim to complete issue #613’s broader mainnet acceptance requirements.
Open Source License
MIT
Hardware/Software Costs (USD)
0
Hardware/Software Justification
None.
Service Costs (USD)
0
Service Costs Justification
No paid external services are included. Development and verification use existing infrastructure, locally operated testnet components, and public testnet services.
Compensation Costs (USD)
$12,000
Compensation Costs Justification
200 hours at $60/hour:
- Wallet reconstruction, transaction building and proving: 50 hours / $3,000.
- Authenticated recovery transport and session tests: 40 hours / $2,400.
- Signing integration, durable approval records, and failure handling: 70 hours / $4,200.
- End-to-end drills, documentation, review fixes, and release evidence: 40 hours / $2,400.
Total: $12,000.
The completed export harness in PR #1069 is not charged to this grant. Payments are tied to accepted milestones.
Total Budget (USD)
12000
Previous Funding
No
Previous Funding Details
None.
Other Funding Sources
No
Other Funding Sources Details
No other funding is included for the work proposed in this application.
Implementation Risks
-
Upstream readiness: signing depends on #1045 and agreement on the recovery message design. If these are delayed, affected work pauses and the schedule is revised with ZCG. The project will not bypass signing checks or introduce duplicate network rules.
-
Integration complexity: the existing SigningMachine must operate through manual transport without changing its security checks. Any blocking incompatibility will be raised with maintainers before an alternative is implemented.
-
Testnet availability: synchronization, funding, and confirmation depend on external testnet services. Evidence will distinguish local test failures from service interruptions.
The estimate is eight active development weeks. Dependency and review delays will be reported separately; incomplete milestones will not be presented as delivered.
Potential Side Effects
Recovery messages will be authenticated but unencrypted in this release. Anyone transporting them can read payment details; the CLI and guide will state this clearly.
Viewing keys and wallet files expose transaction history. They will remain in private local working directories and be excluded from published evidence. Temporary wallet and transaction files will be cleaned up while preserving the durable signing record.
Testing uses newly created testnet vaults only. No real member exports, passphrases, or mainnet funds are required.
Success Metrics
-
Complete two fresh 2-of-3 testnet recovery drills. After setup, each drill uses two members’ exports and passphrases, without the third key share, original helper database, or registration file.
-
For each drill, spend one confirmed Ironwood note to the locally approved shielded destination. Verify on-chain confirmation, recipient receipt, and amount/fee reconciliation.
-
Demonstrate that signing processes make no network connections and recovery does not use Konclave’s coordinator or relay.
-
Pass rejection tests covering unsupported or mismatched exports, wrong network, missing local approval, altered payment details, insufficient quorum, invalid or stale messages, reused commitments, conflicting transactions, and signing-record write failures.
-
Publish reproducible instructions, source revisions, binary checksums, the testnet-table reference, and per-check PASS/FAIL evidence. Publish no exports, key shares, passphrases, or viewing keys.
Completion requires intended-user validation of the delivered functionality and evidence, with the validator confirmed through the grant process.
Startup Funding (USD)
0
Startup Funding Justification
None.
Milestone Details
-
Milestone: 1
Amount (USD): 3000
Expected Completion Date: “2 weeks after grant approval”
User Stories:- “As a vault member, I want to reconstruct the original wallet from my backup without relying on the old coordinator’s files.”
Deliverables: - “Recovery-input validation and fresh wallet initialization from the exported UFVK and scan floor.”
- “Transaction building and proving for one confirmed Ironwood note and one agreed shielded testnet destination.”
- “Rejection tests for unsupported exports, missing recovery information, and wrong-network inputs.”
Acceptance Criteria: >
The designated intended-user validator confirms that the reconstructed
wallet discovers the drill’s funded note and produces the expected
proved PCZT without the original helper database or registration file.
The scan floor is checked against the drill’s known funding height.
Required rejection tests pass.
- “As a vault member, I want to reconstruct the original wallet from my backup without relying on the old coordinator’s files.”
-
Milestone: 2
Amount (USD): 2400
Expected Completion Date: “2 development weeks after Milestone 1 and the signing prerequisites are complete”
User Stories:- “As a signing member, I want to exchange authenticated recovery messages without a hosted relay.”
Deliverables: - “Canonical recovery envelopes in konclave-seal wrapping the existing message types.”
- “Manual copy-and-paste transport with sender authentication and fresh-session binding.”
- “Tests for tampering, incorrect senders, wrong sessions, and replay.”
Acceptance Criteria: >
The recovery domain and session design have maintainer agreement.
The designated validator confirms that valid messages are accepted
and invalid or stale messages are rejected. Sender authentication
uses the receiver’s own public key package.
- “As a signing member, I want to exchange authenticated recovery messages without a hosted relay.”
-
Milestone: 3
Amount (USD): 4200
Expected Completion Date: “2 development weeks after Milestone 2”
User Stories:- “As a signing member, I want my exact payment approval enforced and unsafe retries rejected.”
Deliverables: - “Node integration with the existing SigningMachine and testnet konclave-wasm build.”
- “Locally entered payment approval and locally derived vault receivers.”
- “Memory-only nonces and persistent approval and signed-transaction records.”
- “Tests for payment mismatches, insufficient quorum, reused commitments, restart behavior, conflicting transactions, and record-write failure.”
Acceptance Criteria: >
Two offline participant processes complete a valid signing ceremony
using the existing checks in their existing order. A request that
fails the required checks releases no transaction signature share.
Member key shares remain local. Restarting cannot resume old nonces,
and the existing approval rule blocks conflicting transactions.
The designated validator confirms the results. Upstream merge
requires maintainer security review.
- “As a signing member, I want my exact payment approval enforced and unsafe retries rejected.”
-
Milestone: 4
Amount (USD): 2400
Expected Completion Date: “2 development weeks after Milestone 3”
User Stories:- “As a vault user or reviewer, I want a reproducible drill demonstrating recovery from backups through a confirmed payment.”
Deliverables: - “Two fresh 2-of-3 recovery drills within the supported testnet scope.”
- “Operator instructions for setup, manual message exchange, interruption, and cleanup.”
- “Versioned testnet release, source and binary identifiers, transaction IDs, and sanitized PASS/FAIL evidence.”
- “Regression-check results and fixes for defects introduced by this work.”
Acceptance Criteria: >
The designated validator confirms both drills complete with two
member exports, without the third key share or original coordinator
files. Each spends one confirmed Ironwood note to the agreed
shielded destination, with recipient receipt and amount/fee
reconciliation. Signing processes remain offline and Konclave’s
coordinator and relay are unavailable during recovery.
Instructions support repetition with fresh vaults. Published
evidence contains no exports, key shares, passphrases, or viewing keys.
- “As a vault user or reviewer, I want a reproducible drill demonstrating recovery from backups through a confirmed payment.”
Supporting Documents
-
Name: “Recovery gap and maintainer coordination”
URL: “Spend from the members' backups when our servers are gone · Issue #613 · deegalabs/konclave · GitHub” -
Name: “Maintainer technical requirements”
URL: “Spend from the members' backups when our servers are gone · Issue #613 · deegalabs/konclave · GitHub” -
Name: “Revised recovery design”
URL: “Spend from the members' backups when our servers are gone · Issue #613 · deegalabs/konclave · GitHub” -
Name: “Export harness PR and published verification evidence”
URL: “test(ui): add a 2-of-3 recovery export harness (#613) by devfola · Pull Request #1069 · deegalabs/konclave · GitHub” -
Name: “Maintainer-owned testnet signing dependency”
URL: “Testnet build: testnet rules in konclave-seal and a build-time network setting · Issue #1045 · deegalabs/konclave · GitHub” -
Name: “Konclave’s documented service-loss recovery limits”
URL: “konclave/docs/IF_EVERY_SERVICE_DISAPPEARS.md at staging · deegalabs/konclave · GitHub”