diff --git a/solutions/LP-0005.md b/solutions/LP-0005.md new file mode 100644 index 0000000..593d9f1 --- /dev/null +++ b/solutions/LP-0005.md @@ -0,0 +1,157 @@ +# Solution: LP-0005 — Private Balance Attestation + +**Submitted by:** Tranquil-Flow + +## Summary + +This submission implements a reusable private token balance attestation primitive for Logos Execution Zone (LEZ) private balance commitments. A presenter can prove that a committed private token balance satisfies `balance >= threshold` without revealing the Nullifier Public Key (`npk`), exact balance, private account identity, or private witness data. + +The package includes: + +- a RISC0 guest circuit and host proof-artifact verification path; +- privacy-preserving public journal and statement types; +- context binding to prevent replay across gates; +- presenter identity binding to prevent proof forwarding/theft; +- an off-chain Logos Messaging verifier path; +- a Rust verifier-program model for LEZ-style on-chain access grants; +- deterministic error codes; +- a Basecamp GUI artifact; +- SPEL/IDL and TypeScript SDK facade; +- three integration contracts and benchmark evidence; +- a narrated demo video. + +## Repository + +- **Repo:** https://github.com/Tranquil-Flow/lp-0005-private-balance-attestation +- **License:** MIT +- **Narrated demo video:** https://youtu.be/x0BYf8bLRII + +## Live-deployment and maintainer-accepted evidence status + +This submission is ready for review as a packaged, testable evaluator bundle. The public repository is published, the narrated demo is attached, and the standalone `consumer-demo/` proves the integration surface from a clean consumer crate. + +The LEZ verifier path is represented by the Rust verifier-program model plus deployment manifest rather than a fabricated public testnet program id. Per maintainer clarification, testable packaged evidence is acceptable for this requirement; if reviewers still require chain-native telemetry or a public testnet id, the repository keeps the deployment manifest fields isolated so those values can be added without changing the proof interface. + +## Approach + +### RISC0 threshold proof + +The proof relation targets the LEZ private account commitment format: + +```text +SHA256(npk || program_owner || balance || nonce || SHA256(data)) +``` + +The private witness contains the balance-side private data. The public statement exposes only threshold, Merkle root, context binding, presenter binding, and proof id. The circuit rejects below-threshold witnesses before journaling. + +Evidence: + +- `methods/guest/` +- `core/` +- `host/` +- `artifacts/lp0005-proof/manifest.txt` +- `submission/deployment/risc0-proof-artifacts.json` +- `scripts/validate-proof-artifacts.sh` + +### Privacy boundary + +The public journal is designed not to reveal raw `npk`, exact balance, account identity, or presenter secret material. Receipt/journal verification checks the public statement and the privacy-preserving journal boundary. + +Evidence: + +- `submission/PRIVACY_SECURITY.md` +- `core/tests/guest_boundary.rs` +- `host/tests/host_boundary.rs` + +### Context and identity binding + +The proof binds to a context id so it cannot be replayed across gates. It also binds to `presenter_pub`, derived as: + +```text +presenter_pub = SHA256("lp0005:presenter-ed25519" || ed25519_verifying_key) +``` + +The off-chain and verifier-program paths require an active Ed25519 presenter challenge signature, preventing a copied proof from being reused by a third party. + +Evidence: + +- `messaging/` +- `verifier-program/` +- `cargo run -q -p lp0005-balance-messaging --bin lp0005-messaging-demo -- --forwarded-attack` + +## Success Criteria Checklist + +- [x] RISC0 circuit for `balance >= N` over the LEZ commitment format. +- [x] Privacy: public outputs do not reveal `npk`, exact balance, or account identity. +- [x] Context binding to prevent replay across gates. +- [x] Identity binding / proof-forwarding resistance. +- [x] Off-chain verifier library and Logos Messaging-style envelope path. +- [x] Rust verifier-program model for LEZ-style on-chain access grants. +- [x] Deterministic error codes for invalid proofs and graceful failures. +- [x] SDK/CLI facade and demo binaries. +- [x] Basecamp GUI artifact with local loadability. +- [x] SPEL/IDL interface artifacts. +- [x] Benchmarks and CU budget estimates. +- [x] Narrated demo video. +- [x] Public GitHub repository URL published. +- [x] Verifier-program evidence accepted as a testable packaged model per maintainer clarification; live LEZ ID can be added if strictly requested. +- [x] Standalone consumer integration demo attached under `consumer-demo/` per maintainer clarification that any demonstrated/testable path is acceptable. + +## FURPS Self-Assessment + +### Functionality + +The primitive supports private threshold access proofs, off-chain recipient-side verification, and LEZ-style verifier-program access grants with idempotent access records and deterministic rejection codes. + +### Usability + +Users and evaluators can run the demo script, inspect the Basecamp GUI artifact, and use the SDK/interface files to understand proof generation and verification flows. + +### Reliability + +Invalid proofs fail with deterministic errors including context mismatch, presenter mismatch, expired challenge, and occupied access record conflicts. The CI safe-lane and validators exercise core, messaging, verifier, GUI, interface, integration, and package checks. + +### Performance + +Benchmark evidence is in `submission/BENCHMARKS.md` and `submission/benchmark-results.json`. The current CU numbers are portable verifier-model estimates; replace them with chain-native sequencer telemetry after live testnet deployment if required. + +### Supportability + +The code is split into small crates/modules: + +- `core/` shared statement/journal/proof relation logic +- `methods/` RISC0 guest package +- `host/` receipt/proof-artifact verification +- `messaging/` off-chain envelope verification +- `verifier-program/` LEZ-style verifier semantics +- `interfaces/` SPEL/IDL/SDK facade +- `basecamp-app/` GUI artifact +- `integrations/` integration contracts +- `submission/` technical write-up, privacy notes, benchmarks, manifests + +## Supporting materials + +- Demo video: https://youtu.be/x0BYf8bLRII +- Technical write-up: `submission/TECHNICAL_WRITEUP.md` +- Privacy/security write-up: `submission/PRIVACY_SECURITY.md` +- Benchmarks: `submission/BENCHMARKS.md`, `submission/benchmark-results.json` +- Integration guide: `submission/INTEGRATIONS.md` +- Final audit: `FINAL_SUBMISSION_AUDIT.md` + +## Reproducibility commands + +```bash +bash scripts/validate-proof-artifacts.sh artifacts/lp0005-proof +cargo test -p lp0005-balance-core --test guest_boundary -- --nocapture +cargo test -p lp0005-balance-messaging -- --nocapture +cargo test -p lp0005-verifier-program -- --nocapture +python3 scripts/benchmark-safe-lane.py +python3 scripts/validate-submission-package.py +python3 scripts/validate-basecamp-gui.py +python3 scripts/validate-interfaces.py +python3 scripts/validate-integrations.py +``` + +## Terms & Conditions + +By submitting this solution, I confirm that I have read and agree to the [Terms & Conditions](../TERMS.md).