Add design doc for retail threshold custody wallet - #1
Open
numbxs wants to merge 4 commits into
Open
Conversation
Draft architecture replacing the signerWIFs model with a consumer-facing threshold wallet: - 2-of-3 shares: user device (passkey-gated, non-exportable, no seed phrase), provider co-signer, user-chosen third share. - Recovery by FROST share refresh rather than backup, so device loss is recoverable and no bearer secret ever exists. - Share diversity requirements, and enrolment that rejects configurations where two shares share a failure domain. - Risk-tiered quorums: the convenient A+B path is the weak one, since the provider also ships the app that drives the user's share. - Zcash specifics: ZIP 312 splits only ask, so co-signers hold full viewing capability; coordinator kept on the user's device for unlinkability. PCZT as transport so a software share can become hardware later. - Staging (transparent plumbing -> shielded FROST -> hardware share), residual risk, and open questions that change the architecture. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LHCbFGfn1LkGunb4hLGmVq
Provider share is recovery-only, share C is user-chosen, shielded Orchard at launch. Consequences worked through: - Everyday quorum is A+C; B appears only in resharing rows. Funds move with zero provider involvement, so provider death costs the user their recovery option rather than their access. - B never joins a signing session, so it never sees a transaction, sighash or randomizer: it holds a share of ask and no viewing key at all. With a hardware share C, nobody but the user has viewing capability. - But the provider still ships the app that renders transactions, so share C's independence is now the whole everyday security model. Adds the hard enrolment rule that C must not run the provider's build, and the specific verification C must perform (recompute sighash, render every output, check change-address ownership, verify fee) — confirmed achievable from a PCZT, per Ledger's Orchard signer. - States honestly that B+C is still a valid spending quorum, and hardens the recovery-only restriction architecturally (HSM permits resharing only; no code path emits a spend signature share). - Shielded at launch pulls draft-spec risk to day one: independent review of the re-randomized FROST path becomes a launch blocker, alongside share-epoch and change-address conformance tests. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LHCbFGfn1LkGunb4hLGmVq
Three open items resolved, plus a correction and a new decision point. Share C menu (§5.3): curated tiers as default, arbitrary C behind an advanced path, three classes refused outright. The refusals matter most — a FIDO/PIV token cannot hold a Pallas scalar or run the FROST protocol, so a YubiKey is an auth factor for share A and not a share C at all; and an offline written share verifies nothing and must be typed into the provider's app to be used, putting both shares in the one place the design exists to avoid. Tier 2 co-signer services get selection criteria and an explicit statement of what they cannot catch. Memo exposure (§4.3): the memo lives in the note plaintext inside enc_ciphertext, so any party with the viewing key reads it, and C cannot avoid outgoing memos because recomputing enc_ciphertext requires them. Incoming memos are avoidable and now excluded by making C a pure signer that never syncs the chain. Adds key-material minimization, retention limits, and a memo-entry warning when C is a third party. Review scope (§9): nonce handling under session abort/crash first, then randomizer binding, conformance to the analyzed scheme, binding factors, epochs, keygen, and cross-implementation differential testing. Notes that reviewer availability is the long pole and that ZF should be engaged early. Correction: hardware wallets have shipped PCZT verification but return ordinary single-key spendAuthSigs, not FROST signature shares. Tier 1 needs FROST-RedPallas participant firmware that does not exist off the shelf, so Phase 1 launches with a Tier 2 software C. New: §5.8 requires DKG over a trusted dealer. Trusted-dealer keygen at the provider would mean it held the full ask at enrolment, making the rest of the design theatre. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LHCbFGfn1LkGunb4hLGmVq
No trusted dealer, no fallback: no party ever holds the full ask, at any moment, including enrolment. The consequence worth the section is that DKG relocates the trusted party rather than removing it. Round 2 distributes secret shares between participants; if those messages ride a provider-relayed channel without end-to-end authentication to each participant's own long-term identity key, the provider can MITM the ceremony and learn both A's and C's shares. That is the full key, and it is the exact failure D4 exists to prevent arriving through the back door. An unauthenticated DKG has not removed the trusted dealer, it has renamed it "the relay". Requires pinned identity keys, enforced PoK and commitment verification, group-key agreement across all three parties, and reinforces that the provider must not be the sole path between A and C. Also adds: - Atomic enrolment (§5.8.2). A partial ceremony is a fund-loss path, so no receiving address may be derived or displayed until all three parties confirm the group verifying key. Failed ceremonies restart from scratch. - DKG-based refresh, since recovery must not reintroduce the full-key moment. Notes that the new device's identity key is unauthenticated when recovery begins, making it the cryptographic face of the social engineering problem that delay and veto gate. - Phase 2 firmware now needs DKG participation alongside signing and PCZT verification; air-gapped QR round-trips are enrolment UX to raise with the hardware partner early. - Review scope asks the reviewer to attack the ceremony as the provider. - Two open questions: whether to adopt frostd or own the transport, and whether out-of-band identity-key verification can beat pinning without reintroducing something phishable. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LHCbFGfn1LkGunb4hLGmVq
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds a comprehensive design document for a consumer-facing 2-of-3 threshold custody wallet that would eventually replace the current
signerWIFsmodel. The design focuses on making threshold custody practical and secure for retail users through architectural decisions that eliminate bearer secrets and maintain genuine thresholds at signing time.Changes
Added
docs/design/threshold-custody.md— A 452-line design document covering:signerWIFsapproach (plaintext key pasting, transparent addresses, public explorer dependency)Updated
README.md— Added a "Design docs" section linking to the new threshold custody design document with a brief description of its scopeNotable Details
https://claude.ai/code/session_01LHCbFGfn1LkGunb4hLGmVq