diff --git a/solutions/LP-0005.md b/solutions/LP-0005.md new file mode 100644 index 0000000..177b2a1 --- /dev/null +++ b/solutions/LP-0005.md @@ -0,0 +1,262 @@ +# Solution: LP-0005 — Private Token Balance Attestation + +**Submitted by:** dubzn / caravana + +**Status:** Draft technical review. This PR should not be treated as a final +award-ready submission until the open items below are completed or explicitly +accepted by evaluators. + +## 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, two reference integrations, an IDL artifact, +CI, and local E2E scripts. + +The most important caveat 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 current on-chain +path is therefore a Workable model: host-side proof verification is mandatory +before submitting a LEZ transaction, and the LEZ program records/deduplicates +the admitted nullifier in program-owned account state. The repository documents +this limitation rather than marking the cryptographic on-chain verifier as +complete. + +## Repository + +- **Repo:** https://github.com/dubzn/logos-private-balance-attestation +- **Current implementation commit:** `1805078` +- **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. `examples/governance-gate` and `examples/chat-gate` + Reference integrations for an on-chain-style governance gate and an + off-chain token-gated chat/admission flow. + +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. The deployable LEZ program gates state updates and deduplicates + nullifiers, but cryptographic proof verification is currently host-side + before transaction submission. The direct receipt-verification path is + documented as unsupported in the tested local LEZ version. + +- [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. + +- [ ] **Three distinct applications on LEZ testnet, one external.** + Partial. Two reference integrations exist locally. A third integration and + external integrator are still pending. + +- [x] **Documentation and clean public repository.** + README, architecture, setup, security model, error codes, IDL, benchmark + notes, modular test plan, and prize checklist are included. Final Basecamp, + testnet, and video artifacts remain pending. + +- [x] **SDK/module.** + `crates/attestation-sdk` provides an umbrella crate for integrations. + +- [ ] **Basecamp GUI.** + 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. + +- [ ] **CI green on default branch.** + CI workflow is present; remote GitHub run should be checked after this draft. + +- [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 intentionally not marked done yet. + +### 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 local full E2E with `RISC0_DEV_MODE=0`: + +| Phase | Duration | +| --- | ---: | +| Proof phase | 00:02:20 | +| Gate phase | 00:02:49 | +| Total | 00:05:09 | + +Proof substeps from the same run: + +| Step | Duration | +| --- | ---: | +| Build witness | 00:01:09 | +| Prove | 00:00:23 | +| 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 +- 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. +- Add Basecamp GUI. +- Add Logos Messaging-specific transport adapter or documented accepted + equivalent. +- Add third reference integration and external integrator. +- 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).