lambda-prize/prizes/LP-0003.md

# LP-0003: Private Allowlist / Airdrop Distributor [OPEN]

**`Status: Open`**
**`Logos Circle: N/A`**

## Overview

Token airdrops and allowlist distributions today require recipients to expose their wallet address — and, by extension, their full on-chain history — at the moment of claim. The distributor must either publish the full eligibility list publicly or run a centralised gating service. Neither is acceptable for a privacy-first ecosystem.

This prize is for a private airdrop and allowlist primitive for LEZ: a contract where the distributor commits to a hidden set of eligible accounts, recipients can claim without revealing they were on the list, and no on-chain observer can link a claim to a specific eligible address.

## Motivation

Airdrops are a primary token distribution mechanism for new protocols. Allowlists gate access to launches, NFT mints, and governance participation. In both cases the current pattern — publish a Merkle root, let users submit inclusion proofs — reveals eligibility and links pseudonymous identities to participation. For a community built around freedom and censorship-resistance, this creates real risks: eligible addresses can be targeted, excluded, or front-run.

Any commitment-based eligibility scheme involves trade-offs between distributor knowledge, claim-time privacy, and verifiability. Different approaches sit at different points in this space, and there is no single correct answer. The design space — commitment scheme, claim uniqueness mechanism, recipient UX, and integration with shielded token transfers — admits multiple valid approaches, which is exactly why a competitive prize is the right mechanism.

Logos' shielded account model offers a richer design surface than standard EVM environments. Submissions are expected to take advantage of this and explain how their design improves on the public Merkle airdrop baseline — and where the remaining trade-offs lie.

## Success Criteria

### Functionality

- [ ] A distributor can commit to an eligibility set on-chain without revealing individual addresses.
- [ ] An eligible recipient can claim their allocation without revealing which address in the set they hold.
- [ ] A recipient cannot claim more than once (double-claim prevention via nullifiers or equivalent).
- [ ] An on-chain observer cannot link a completed claim to any specific address in the eligibility set.
- [ ] The submission documents its full privacy model: what on-chain observers learn, what the distributor learns, at which points in the claim flow identity information is revealed or withheld, and where trade-offs or residual leakage remain. Claims of privacy must be precise — "unlinkable" must be defined relative to a stated threat model.
- [ ] A reference integration is delivered: a working demo of a private airdrop or allowlist gate on LEZ testnet.
- [ ] At least 3 distinct distributions are deployed on LEZ testnet by parties outside the submitting team, with a combined total of at least 30 unique claims completed across them.
- [ ] 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](https://github.com/logos-co/spel).

### Reliability

- [ ] The system handles proof generation failures gracefully and surfaces a clear error to the claimant.
- [ ] A failed or rejected claim does not mark the claimant as having claimed, allowing a retry.
- [ ] The verifier program returns deterministic, documented error codes for all invalid-proof and double-claim scenarios.

### 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.
- [ ] 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 LEZ program (Rust) implementing the commitment, claim, and distribution logic.
- ZK circuit(s) for eligibility and claim-uniqueness proofs, targeting the Risc0 proving stack.
- A client-side SDK or CLI for generating and submitting claims from shielded accounts.
- A reference integration on LEZ testnet: either a private token airdrop or a token-gated allowlist registration.
- Documentation covering: commitment scheme, claim-uniqueness mechanism, privacy model, trusted setup (if any), and integration guide.

### Out of Scope

- Dynamic eligibility updates after commitment (the eligible set is fixed at distribution setup).
- Hiding the total number of eligible addresses or total allocation amount.
- Ongoing maintenance or security audits beyond initial delivery.

## Prize Structure

- **Total Prize:** $600
- **Effort:** Medium

## 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 program code, and client-side tooling under MIT or Apache-2.0.
- 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 a private claim from a shielded account. A silent screencast is not sufficient (see [demo requirements](../README.md#evaluation-policies)).
- Write-up covering: commitment scheme, claim-uniqueness mechanism, privacy model (what on-chain observers and the distributor learn at each stage, stated threat model, and any residual leakage or limitations), LEZ account model compatibility, security assumptions, known limitations, and integration instructions.
- Proof generation time and on-chain verification compute unit benchmarks.
- GitHub issues open for any problem encountered with Logos technology.
- **FURPS self-assessment** as part of the solution (see [solution template](../solutions/LP-0000.md)).

## 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](../README.md#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](https://github.com/logos-blockchain/logos-execution-zone/)
- [Risc0 proving system](https://dev.risczero.com/)
- [Semaphore — nullifier and group membership design](https://semaphore.pse.dev/)
- [Merkle airdrop reference (public baseline)](https://github.com/Uniswap/merkle-distributor)
- [zk-kit — Merkle tree and nullifier primitives](https://github.com/privacy-scaling-explorations/zk-kit)

## Potential for Subsequent λPrizes

Testnet 0.3/0.4 compatibility, mainnet deployment and adoption.