Solution: LP-0005 — Private Token Balance Attestation

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:** `44cf628`
+- **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/<id> RISC0_DEV_MODE=0 scripts/demo-local-full-e2e.sh
+cargo run -p attestation-cli -- verify --envelope <envelope.json> --gate <gate.json>
+cargo run -p attestation-cli -- gate-admit --envelope <envelope.json> --gate <gate.json> --gate-account Public/<gate> --presenter-account Public/<presenter>
+```
+
+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).