diff --git a/solutions/LP-0005.md b/solutions/LP-0005.md new file mode 100644 index 0000000..92e7415 --- /dev/null +++ b/solutions/LP-0005.md @@ -0,0 +1,286 @@ +# Solution: LP-0005 — Private Token Balance Attestation + +**Submitted by:** dubzn / caravana + +**Status:** Submission candidate for evaluator review. The implementation is +complete enough to run locally, and this PR asks evaluators to decide which of +the implemented on-chain paths should be treated as the final LP-0005 path. + +## Summary + +`logos-private-balance-attestation` is a Rust workspace for proving: + +```text +private LEZ account balance >= public threshold +``` + +without revealing the private account id, `npk`, exact balance, nonce, or +account data. + +The current implementation includes a RISC Zero balance-attestation circuit, +client-side witness/proof tooling that consumes real local wallet state and the +real LEZ `getProofForCommitment` path, an off-chain verifier, CLI tooling, a +deployable LEZ gate-state program, a PPE-native LEZ gate candidate, a +backend-backed Basecamp MVP, standalone consumer integration demos, an IDL +artifact, CI, and local E2E scripts. + +The most important evaluation question is the on-chain path. The local LEZ +version tested by this submission does not currently expose a working +public-program path for verifying an external RISC Zero receipt inside a LEZ +guest. The repository therefore includes two implemented candidates: + +- a Workable public LEZ gate where host-side proof verification is mandatory + before transaction submission, and the LEZ program records/deduplicates the + admitted nullifier in program-owned account state +- a PPE-native LEZ gate where private execution checks `balance >= threshold` + and writes public gate/nullifier state + +The repository documents the trust boundary for both paths and asks evaluators +to confirm which model satisfies LP-0005's on-chain requirement. + +## Repository + +- **Repo:** https://github.com/dubzn/logos-private-balance-attestation +- **Current implementation branch:** `master` +- **License:** MIT +- **Primary benchmark doc:** `docs/BENCHMARKS.md` +- **Prize checklist:** `docs/PRIZE_CHECKLIST.md` + +## Approach + +The implementation is split into small, independently testable layers: + +1. `crates/attestation-core` + Shared public types, proof envelope, journal schema, LEZ commitment helpers, + context binding, context nullifier derivation, presenter binding helpers, + Merkle helpers, and deterministic error codes. + +2. `methods/` + Production RISC Zero circuit. The circuit reconstructs the private LEZ + account commitment, verifies Merkle membership, checks `balance >= threshold`, + binds the proof to a context, derives a context nullifier, and binds the + proof to a presenter identity derived from a BIP-340 Schnorr public key. + +3. `crates/attestation-prover` + Builds a private witness from local wallet state plus sequencer membership + proof data, then generates a public proof envelope. Sanitized reports avoid + printing private witness material. + +4. `crates/attestation-verifier` + Verifies the same public envelope locally: receipt, image id, journal match, + context, exact threshold, presentation challenge, presenter pubkey hash, and + Schnorr presentation signature. + +5. `crates/attestation-cli` + Exposes `prove`, `verify`, `inspect-private`, `gate-register-presenter`, + `gate-init`, and `gate-admit`. `gate-admit` runs the off-chain verifier + precheck before submitting an admit transaction. + +6. `lez-verifier/program` + Deployable LEZ guest program for the current Workable gate path. It supports + `RegisterPresenter`, `InitGate`, and `Admit`, and persists/deduplicates + context nullifiers in gate account state. + +7. `spikes/spike-09-ppe-gate` + PPE-native gate candidate. It runs through LEZ privacy-preserving execution, + checks private `balance >= threshold`, and writes public `BAP1` + gate/nullifier state. Local `RISC0_DEV_MODE=0` runs passed positive admit, + duplicate rejection, and insufficient-balance rejection. + +8. `examples/governance-gate`, `examples/chat-gate`, and + `examples/fee-tier-gate` + Standalone consumer integration demos for an on-chain-style governance gate, + an off-chain token-gated chat/admission flow, and a local fee-tier gate. + +Key design decisions and rejected paths are documented in the repo: + +- The circuit targets the existing LEZ commitment format and uses compatibility + tests against local LEZ helpers instead of inventing a parallel format. +- The witness builder calls the real wallet/sequencer membership-proof path + instead of invented HTTP endpoints. +- Direct external receipt verification inside a public LEZ guest was tested and + found unsupported in the local stack because `env::verify` has no available + receipt-assumption channel in that execution path. +- Presenter binding uses a public presenter key committed in the proof plus a + challenge-bound presentation signature. Verifiers must use fresh presentation + challenges for live sessions. + +## Success Criteria Checklist + +- [x] **Generate client-side proof for `balance >= N`.** + Implemented by `attestation-prover` over the `methods/` RISC Zero circuit. + The local-sequencer E2E builds a witness from real wallet private state and + the real `getProofForCommitment` path. + +- [x] **Verify without revealing `npk`, exact balance, or account identity.** + The public journal exposes only public gate parameters, root, image id, + presenter id, and nullifier. Private witness fields remain in `witness.json` + and are redacted from reports. + +- [x] **Context binding.** + The proof binds to a derived context id over chain/gate/verifier/image + parameters and exact threshold. + +- [x] **Presenter binding.** + V1 binds the journal to `presenter_id = H(pubkey)` and requires a + challenge-bound BIP-340 Schnorr presentation signature. Remaining limitation: + verifiers must use fresh challenges or authenticated sessions to prevent + first-use forwarding of a captured envelope. + +- [x] **Existing LEZ commitment format.** + The repo contains compatibility tests/scripts that compare local helper output + against the local LEZ checkout. + +- [ ] **On-chain LEZ verifier accepts and verifies the proof.** + Partial / evaluator decision. The Workable public LEZ program gates state + updates and deduplicates nullifiers, but cryptographic proof verification is + host-side before transaction submission. The PPE-native gate candidate checks + the private balance condition inside LEZ private execution and writes public + gate/nullifier state. The PR asks evaluators which path satisfies the + on-chain requirement. + +- [x] **Off-chain verification path.** + Implemented by `attestation-verifier` and demonstrated by + `examples/chat-gate` using a transport-agnostic wire envelope. Logos + Messaging-specific wiring remains planned. + +- [x] **Standalone consumer integration demo.** + Implemented locally. The repository includes governance, chat/admission, and + fee-tier examples that exercise the attestation primitive through runnable + tests and demo paths. + +- [x] **Documentation and clean public repository.** + README, architecture, setup, security model, error codes, IDL, benchmark + notes, modular test plan, Basecamp MVP docs, and prize checklist are + included. Final testnet, CU, and video artifacts remain pending. + +- [x] **SDK/module.** + `crates/attestation-sdk` provides an umbrella crate for integrations. + +- [x] **Basecamp GUI MVP.** + `apps/basecamp/` contains a backend-backed `ui_qml` module that wraps + wallet/sequencer preflight, proof generation, envelope verification, and the + current Workable gate admit flow. Final UX polish and recorded-demo pass are + still pending. + +- [x] **IDL artifact.** + `idl/balance-attestation-verifier.json` plus `docs/IDL_DRAFT.md`. + +- [x] **Clear failure handling and deterministic errors.** + `VerifyError`, `ProveError`, and LEZ gate errors map to documented BAxxx + codes. + +- [ ] **CU costs on devnet/testnet.** + Pending. Local timing benchmarks are documented, but they are not CU metrics. + +- [ ] **Devnet/testnet deployment.** + Pending. Local standalone sequencer deployment has been tested. + +- [x] **CI green on default branch.** + The implementation repository has CI for workspace tests and deployable LEZ + program checks. Local clean-room, Basecamp package, and workspace test checks + passed before opening this PR. + +- [x] **Reproducible local E2E with `RISC0_DEV_MODE=0`.** + `scripts/demo-local-full-e2e.sh` passed locally against a real local sequencer + and wallet private account. Clean-room rerun and video are pending. + +- [ ] **Narrated demo video.** + Pending. + +## FURPS Self-Assessment + +### Functionality + +The core off-chain primitive is functional: proof generation, envelope +verification, context binding, presenter binding, and nullifier derivation are +implemented. The local live gate flow also works in the Workable model: register +presenter, initialize gate, admit after host-side verification, and reject +duplicate nullifier application. + +The on-chain cryptographic verifier remains the main unresolved issue. The repo +keeps this explicit and does not claim that the current LEZ program verifies the +RISC Zero receipt by itself. + +### Usability + +The CLI supports both low-level inspection and full demo flows. The most useful +operator commands are: + +```sh +PRIVATE_ACCOUNT=Private/ RISC0_DEV_MODE=0 scripts/demo-local-full-e2e.sh +cargo run -p attestation-cli -- verify --envelope --gate +cargo run -p attestation-cli -- gate-admit --envelope --gate --gate-account Public/ --presenter-account Public/ +``` + +The Basecamp GUI is an MVP rather than a polished product. It is intentionally +limited to public/sanitized proof state and delegates to the same CLI/scripts as +the terminal E2E. + +### Reliability + +The repo includes unit tests, integration-style examples, local E2E scripts, +sanitized private-account inspection, duplicate nullifier checks, and structured +error codes. `witness.json` is explicitly treated as private and excluded from +published artifacts. + +### Performance + +Latest documented local full E2E with `RISC0_DEV_MODE=0`: + +| Phase | Duration | +| --- | ---: | +| Proof phase | 00:01:48 | +| Gate phase | 00:01:42 | +| Total | 00:03:30 | + +Proof substeps from the same run: + +| Step | Duration | +| --- | ---: | +| Build witness | 00:01:17 | +| Prove | 00:00:24 | +| Verify | 00:00:03 | + +These are local wall-clock timings. Devnet/testnet CU measurements are still +open and tracked in `docs/BENCHMARKS.md`. + +### Supportability + +The repository is structured as a Rust workspace with small crates and +reproducible scripts. The root README, `docs/LOCAL_SETUP.md`, +`docs/ARCHITECTURE.md`, `docs/SECURITY_MODEL.md`, `docs/BENCHMARKS.md`, and +`docs/PRIZE_CHECKLIST.md` are the main evaluator entry points. + +## Supporting Materials + +- Implementation repository: + https://github.com/dubzn/logos-private-balance-attestation +- Local benchmark doc: + https://github.com/dubzn/logos-private-balance-attestation/blob/master/docs/BENCHMARKS.md +- Prize checklist: + https://github.com/dubzn/logos-private-balance-attestation/blob/master/docs/PRIZE_CHECKLIST.md +- Local setup guide: + https://github.com/dubzn/logos-private-balance-attestation/blob/master/docs/LOCAL_SETUP.md +- Basecamp MVP: + https://github.com/dubzn/logos-private-balance-attestation/tree/master/apps/basecamp +- Architecture: + https://github.com/dubzn/logos-private-balance-attestation/blob/master/docs/ARCHITECTURE.md + +## Open Items Before Final Evaluation + +- Confirm the expected on-chain verification model with Logos evaluators: + direct public receipt verification, native LEZ private execution, or the + current host-preverified Workable model. +- Polish the Basecamp MVP and include it in the narrated demo flow. +- Add Logos Messaging-specific transport adapter or documented accepted + equivalent. +- Deploy on LEZ devnet/testnet and record program id. +- Measure CU costs on devnet/testnet. +- Run clean-room E2E from a fresh checkout. +- Record narrated video with terminal output showing `RISC0_DEV_MODE=0`. + +## Terms & Conditions + +By submitting this solution, I confirm that I have read and agree to the +[Terms & Conditions](../TERMS.md).