lambda-prize/prizes/LP-0005.md

LP-0005: Private Token Balance Attestation [OPEN]

Logos Circle: N/A

Overview

Many access-control mechanisms — governance participation thresholds, protocol fee tiers, allowlist eligibility, token-gated chat rooms — require a user to prove they hold at least N tokens of a given type. On a transparent chain this is trivial: anyone can inspect the balance. On Logos, balances are private by default, which breaks the naive approach but enables a much better one: a user can prove they meet a threshold without revealing their exact balance or linking the proof to their account.

This prize is for a reusable private balance attestation primitive with two verification paths:

• On-chain: A LEZ verifier program gates on-chain actions (governance votes, access grants, etc.).
• Off-chain: The proof is transmitted over Logos Messaging and verified locally by any recipient — enabling privacy-preserving token-gating for applications such as chat group access, without any on-chain transaction.

Motivation

Logos has a token program (LEZ) that already structures private account balances as commitments of the form SHA256(npk || program_owner || balance || nonce || SHA256(data)), committed into an on-chain Merkle tree. The sequencer exposes get_proof_for_commitment, which returns a Merkle membership proof for any private account.

The missing piece is a circuit that takes a private account, its Merkle membership proof, and a public threshold N, and produces a succinct proof that the account's balance satisfies balance >= N — without revealing npk, balance, or any other private field.

Once generated, that proof is a self-contained, verifiable credential. It can be submitted to a LEZ program for on-chain gating, or broadcast over Logos Messaging for off-chain gating — for example, to gain entry to a token-gated chat group. The verifier (on-chain program or off-chain recipient) needs only the proof and the public parameters; it learns nothing else about the prover.

A competitive prize is the right mechanism because the proving strategy, nullifier scheme, context-binding approach, and the integration patterns for both verification paths admit multiple valid approaches.

Success Criteria

Functionality

• A shielded token account holder can generate a client-side proof that their balance meets a public threshold N.
• The proof is verifiable without revealing the account's nullifier public key, exact balance, or account identity — whether verified on-chain or off-chain.
• The proof is bound to a specific context (e.g., a program ID, group ID, or application identifier) to prevent replay across different gates.
• The proof is bound to the presenter's identity — a third party who obtains the proof cannot use it to pass verification without also holding the presenter's private key.
• The circuit correctly targets the existing LEZ private account commitment format: SHA256(npk || program_owner || balance || nonce || SHA256(data)).
• On-chain path: A LEZ verifier program accepts and verifies the proof, gating at least one on-chain action.
• Off-chain path: The proof can be transmitted over Logos Messaging and verified locally by a recipient, demonstrated by a token-gated access flow (e.g., admission to a chat group).
• At least 3 distinct applications integrate the attestation primitive on LEZ testnet (e.g., a governance gate, a token-gated Logos Messaging group, and a third use case), with at least one built by a party outside the submitting team.
• Full documentation and a clean public repository are delivered.

Usability

• Provide a module/SDK that can be used to build Logos modules for interacting with the program.
• Provide a Logos Basecamp app GUI with local build instructions, downloadable assets, and loadable in Logos app (Basecamp).
• Provide an IDL for the LEZ program, using the SPEL framework.

Reliability

• The system handles proof generation failures gracefully and surfaces a clear error to the user.
• Off-chain verification failure (e.g., due to Logos Messaging issues) surfaces a clear error without exposing private account data.
• The verifier program returns deterministic, documented error codes for all invalid-proof scenarios on both verification paths.

Performance

• Document the compute unit (CU) cost of each on-chain operation on LEZ devnet/testnet. Note: LEZ's per-transaction compute budget may change during testnet.

Supportability

• The program is deployed and tested on LEZ devnet/testnet.
• End-to-end integration tests run against a LEZ sequencer (standalone mode) and are included in CI.
• CI must be green on the default branch.
• A README documents end-to-end usage: deployment steps, program addresses, and step-by-step instructions for interacting with the program via CLI and Basecamp app (for both on-chain and off-chain verification paths).
• A reproducible end-to-end demo script is provided and works against a real local sequencer with RISC0_DEV_MODE=0.
• A recorded video demo of the end-to-end flow is included in the submission; the recording must show terminal output (including proof generation) to confirm RISC0_DEV_MODE=0 was active.

Scope

In Scope

• A Risc0 circuit proving balance >= N over the existing LEZ private account commitment format, with Merkle membership verification and context binding.
• A LEZ on-chain verifier program (Rust) that accepts and verifies the proof.
• An off-chain verifier library that validates the same proof format locally, without an on-chain transaction.
• A client-side SDK or CLI for generating proofs from a shielded token account, consuming the sequencer's get_proof_for_commitment output.
• Integration with Logos Messaging for proof transmission in the off-chain path.
• Two reference integrations: one on-chain (LEZ testnet) and one off-chain (e.g., token-gated chat group access via Logos Messaging).
• Documentation covering: circuit design, commitment format used, context-binding scheme, both verification paths, privacy guarantees and limits, and integration guide.

Known Open Problem: Proof Forwarding

A proof generated by Alice is a self-contained credential. Nothing prevents Alice from forwarding her proof to Bob, who then presents it to a verifier as if he were the one holding the tokens. Context binding (see Success Criteria) mitigates replay across different gates, but does not bind the proof to the identity of the presenter. Submissions must address this — for example by requiring the presenter to demonstrate knowledge of a private key corresponding to a public key committed in the proof — and must document the approach and its remaining limitations.

Out of Scope

• Changes to the existing token program or its commitment format — the circuit must work with the format as-is.
• Proving exact balance equality (only threshold proofs are required).
• A polished consumer UI — working demos are sufficient.
• Ongoing maintenance or security audits beyond initial delivery.

Prize Structure

• Total Prize: $1,200
• Effort: Large

Eligibility

Open to any individual or team. Submissions must be original work. Teams must hold the rights to all submitted code and agree to license it under MIT or Apache-2.0.

Submission Requirements

• Public repository with all circuit code, LEZ verifier program, off-chain verifier library, and client-side tooling under MIT or Apache-2.0.
• Verifier program deployed on LEZ testnet with a verified program ID.
• End-to-end demo video in which the builder narrates what they built and why, walks through the architecture and key implementation decisions, and demonstrates both verification paths. The demo must cover the on-chain path (proof generation and on-chain verification against a threshold) and the off-chain path (proof transmitted over Logos Messaging and verified locally to gate access, e.g., chat group admission). A silent screencast is not sufficient (see demo requirements).
• Write-up covering: circuit design, commitment format targeting, context-binding approach, both verification paths, privacy guarantees (including what is and is not hidden), security assumptions, known limitations, and integration instructions.
• Proof generation time and on-chain verification gas cost benchmarks.

Evaluation Process

Submissions are evaluated first-come-first-served against the success criteria. The first submission that satisfies all criteria wins.

Evaluators will independently clone the repository and run the demo script from a clean environment; the script must succeed without modification. Evaluators may also ask technical follow-up questions to verify authorship and understanding of the implementation.

The following policies apply to all prizes (see evaluation policies):

• Submissions: each builder (or team) is allowed a maximum of 3 submissions per prize, with at most one submission/review per week.
• Feedback: initial evaluation feedback is limited to a pass/fail indication against the success criteria.

Resources

• Logos Execution Zone repo
• LEZ token program — reference for the private account commitment format and get_proof_for_commitment API
• Logos Messaging — P2P messaging layer for off-chain proof transmission
• Risc0 proving system
• Range proofs in ZK circuits — background on proving balance >= N
• zk-kit — Merkle tree primitives

Potential for Subsequent λPrizes

This prize targets the current LEZ testnet. Should a future testnet version introduce breaking changes, a subsequent λPrize may be opened to cover the necessary adaptation and redeployment.