diff --git a/solutions/LP-0005.md b/solutions/LP-0005.md new file mode 100644 index 0000000..5460fd3 --- /dev/null +++ b/solutions/LP-0005.md @@ -0,0 +1,161 @@ +# 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 library/envelope path with Delivery-module dependency/install evidence; +- a deployed public LEZ testnet NSSA wrapper for proof-backed on-chain access grants; +- deterministic error codes; +- a LogosBasecamp `.lgx` GUI module with M4 build/install evidence; +- SPEL/IDL and TypeScript SDK facade; +- three integration contracts and benchmark evidence; +- a fresh narrated demo video attached: https://youtu.be/Je0UMNslAT4. + +## Repository + +- **Repo:** https://github.com/Tranquil-Flow/lp-0005-private-balance-attestation +- **License:** MIT +- **Narrated demo video:** https://youtu.be/Je0UMNslAT4 — final resubmission walkthrough showing current Basecamp `.lgx` activation, public LEZ testnet evidence, and Delivery send/receive flow. The older https://youtu.be/x0BYf8bLRII recording is historical only. + +## Live-deployment and maintainer-accepted evidence status + +This submission has **public LEZ testnet evidence attached**. The corrected NSSA wrapper program is deployed on `https://testnet.lez.logos.co/`, and a proof-backed execute transaction writes an access-grant PDA whose `program_owner` decodes to the wrapper ImageID. The final demo video is attached at https://youtu.be/Je0UMNslAT4; the older demo remains historical only. + +Canonical testnet evidence is in `TESTNET_PROOF.md`. The historical localnet verifier-model evidence is superseded and must not be cited as final proof. + +## 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-native/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 with Delivery-module dependency/install evidence; send/receive walkthrough is fresh-video gated. +- [x] Public LEZ testnet NSSA wrapper for proof-backed on-chain access grants. +- [x] Deterministic error codes for invalid proofs and graceful failures. +- [x] SDK/CLI facade and demo binaries. +- [x] Basecamp `.lgx` GUI artifact with M4 build/install evidence under `submission/deployment/basecamp-install-evidence.json`. +- [x] SPEL/IDL interface artifacts. +- [x] Benchmarks and wrapper cycle measurement (`559,639` RISC0 user cycles). +- [x] Fresh narrated demo video attached: https://youtu.be/Je0UMNslAT4. +- [x] Public GitHub repository URL published. +- [x] Public LEZ testnet wrapper deployed: `387946247c625f13046cf56fa184f4a3c1fc6612bf1e1bc497476a340cbbc4eb`; deploy tx `8b0f740679a16e45832ed467fbb0367d6987123bc483e1b82a8d5fd2a7c4fd18`; execute tx `e6b480cde3b31dc4c274c491c3c88f2cb2c7a1edb4d93f2c1bbb4af86a1745dd`. +- [x] Standalone consumer integration demo attached under `consumer-demo/` under the current criteria: standalone demonstrated/testable consumer integration path. + +## 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/build/install the Basecamp `.lgx` 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 corrected wrapper simulator measures `559,639` RISC0 user cycles for the submitted public NSSA instruction; the testnet RPC does not expose per-transaction CU receipts. + +### 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-module/` LogosBasecamp `.lgx` GUI module; `flake.nix`/`scaffold.toml` package it and `submission/deployment/basecamp-install-evidence.json` records install evidence +- `integrations/` integration contracts +- `submission/` technical write-up, privacy notes, benchmarks, manifests + +## Supporting materials + +- Demo video: https://youtu.be/Je0UMNslAT4; old https://youtu.be/x0BYf8bLRII is historical only +- 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-native +python3 scripts/ci-verify-testnet.py +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). + + +Note: old PR #60 video https://youtu.be/x0BYf8bLRII is stale historical video only; final video evidence is https://youtu.be/Je0UMNslAT4.