logos-co · dubzn · May 30, 2026
diff --git a/solutions/LP-0005.md 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/<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 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).