Grant Application - Konclave Recovery CLI: From Member Backups to a Verified Testnet Payment

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:

  1. Each participating member opens and validates their own encrypted export locally.
  2. A building participant reconstructs a fresh view-only wallet from the original viewing key and scan height, then builds and proves the transaction.
  3. Each signer enters the exact destination, amount, and memo locally before accepting incoming messages.
  4. Two members complete the existing signing process through authenticated copy-and-paste messages, without Konclave’s coordinator or relay.
  5. 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.

deegalabs/konclave#1045

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

Target repository: GitHub - deegalabs/konclave: The vault that decides together. A local-first, browser-native collective Zcash treasury using FROST threshold signatures. Private on the outside, transparent on the inside. · GitHub

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

  1. 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.

  2. For each drill, spend one confirmed Ironwood note to the locally approved shielded destination. Verify on-chain confirmation, recipient receipt, and amount/fee reconciliation.

  3. Demonstrate that signing processes make no network connections and recovery does not use Konclave’s coordinator or relay.

  4. 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.

  5. 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.
  • 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.
  • 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.
  • 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.

Supporting Documents

A note from the Konclave side. The title carries our name, so this can read as our own application. It isn’t.

@Devfola is an independent contributor and is not part of DeegaLabs, the team that builds Konclave. We didn’t write the application with him or see it before it was filed. In our own grant ( Grant Application - Konclave: taking the viewing key off the coordinator · Issue #486 · ZcashCommunityGrants/zcashcommunitygrants · GitHub ) we said we would make no new funding request until that grant is delivered. That still holds. Our grant does not pay for this work either. It names issue 613 as something it does not address.

What the application says about our exchange is fair. On 16 November he offered to work on one of our open issues, Spend from the members' backups when our servers are gone · Issue #613 · deegalabs/konclave · GitHub , and I accepted with conditions (design first, testnet only, reuse of the existing signing code, our security review on every PR). On 18 November he opened test(ui): add a 2-of-3 recovery export harness (#613) by devfola · Pull Request #1069 · deegalabs/konclave · GitHub . It is open, and our review is on it. The application is also right that we have not committed to validating its milestones, and that the mainnet drill that closes issue 613 stays with us.

One thing only we can say. The signing work in the application waits for a testnet build on our side, Testnet build: testnet rules in konclave-seal and a build-time network setting · Issue #1045 · deegalabs/konclave · GitHub . That issue hasn’t started yet. It’s scheduled after Milestone 1 of our own grant, which is nearly done, so it has no date yet. We review the PRs on issue 613 as they come, and I can’t commit to review dates.

I’m not endorsing or opposing the application. That decision is ZCG’s. Outside contributions to Konclave are welcome with or without funding.