diff --git a/README.md b/README.md index 39f9913..5edd33f 100644 --- a/README.md +++ b/README.md @@ -41,6 +41,7 @@ All prizes live in the `[prizes/](prizes/)` directory. Each prize is a markdown | [LP-0015](prizes/LP-0015.md) | General cross-program calls via tail calls | Large | Closed | | [LP-0016](prizes/LP-0016.md) | Anonymous Forum with Threshold Moderation | Large | Open | | [LP-0017](prizes/LP-0017.md) | Whistleblower: document upload and indexing Basecamp app | Medium | Open | +| [LP-0019](prizes/LP-0019.md) | Tokenized Vault Standard for LEZ | Large | Draft | ### Proposing a New Prize diff --git a/prizes/LP-0019.md b/prizes/LP-0019.md new file mode 100644 index 0000000..3892675 --- /dev/null +++ b/prizes/LP-0019.md @@ -0,0 +1,217 @@ +--- +dependencies: + - id: RFP-001 + reason: Standardised admin authority library used for vault authority operations (pause, sync, authority transfer). + - id: LP-0013 + reason: Mint authority support in the LEZ token program is required for the vault to mint and burn share tokens. +--- + +# LP-0019: Tokenized Vault Standard for LEZ [DRAFT] + +**`Status: Draft`** +**`Logos Circle: N/A`** + +## Overview + +This prize funds a tokenized vault standard for the Logos Execution Zone (LEZ): a canonical interface and reference implementation for vaults that accept a single underlying token and issue transferable share tokens representing proportional ownership. + +The interface semantics follow [ERC-4626](https://eips.ethereum.org/EIPS/eip-4626) (deposit/mint/withdraw/redeem, binding preview functions, vault-favoring rounding), while the architecture follows LEZ's Solana-style account model (stateless programs, external state accounts, PDAs, share tokens minted via cross-program calls). On top of this, the standard defines privacy variants that exploit LEZ's native private execution: the same vault logic can serve fully public vaults and vaults whose depositor positions are shielded. Neither EVM nor Solana offers position privacy at the protocol level; LEZ does, and this standard is designed around it from day one. + +The deliverable is a vault standard specification, reference LEZ programs for the public and shielded-depositor variants, a vault factory, a conformance test suite, an SDK, SPEL IDLs, and a Basecamp demo app. + +## Motivation + +Vault standards are among the most successful composability primitives in crypto. ERC-4626 unified yield-bearing vault interfaces on EVM and now anchors billions in TVL across yield aggregators, lending markets, and liquid staking. The [Solana Vault Standard (SVS)](https://github.com/solanabr/solana-vault-standard) translated the same semantics to Solana's account model across 12 variants. LEZ has no equivalent: every protocol would otherwise implement custom vault logic, fragmenting integrations and duplicating audit effort. + +A LEZ-native standard fills this gap and adds something neither predecessor can: + +- **Composability anchor:** any app, aggregator, or Basecamp module integrates against one interface for all vaults. +- **Battle-tested semantics:** ERC-4626's accounting rules and its well-documented attack literature (inflation/first-depositor attacks, donation repricing, rounding drain) are adopted as normative requirements rather than rediscovered by each builder. +- **Architecture fit:** LEZ's stateless-program/PDA model maps almost one-to-one onto SVS patterns, so the structural design is proven, not speculative. +- **Position privacy as a standard feature:** LEZ executes the same program binary publicly or privately, with per-account privacy granularity inside a single instruction. This enables a shielded-depositor vault — public pool, private positions — where nobody can enumerate who holds how much, and deposits are unlinkable from withdrawals. SVS approximates this only via Token-2022 confidential transfer extensions plus an external ElGamal proof backend; on LEZ it falls out of the protocol. + +A competitive prize is the right mechanism because the design space (share accounting details, fee hooks, privacy envelope design, SDK ergonomics) admits multiple valid approaches that competition will surface, and because the deliverable is a self-contained artifact that is straightforward to evaluate against conformance tests. + +### Design Decisions (Normative Summary) + +The following decisions are part of the standard and bind implementations: + +1. **Stored-balance accounting.** The vault tracks `total_assets` in its state account; external yield is recognized via an authority-gated `sync` instruction. Live-balance accounting (reading the pool token account directly) is rejected as the baseline because it cannot extend across privacy variants and exposes a donation-repricing surface. The public variant MAY offer live-balance mode behind a flag, but invariants are defined against stored accounting. +2. **Shares are LEZ-standard tokens.** Vault shares MUST be fungible tokens of the canonical [LEZ token program](https://github.com/logos-blockchain/lez-programs/tree/main/programs/token), minted/burned via cross-program calls with the vault PDA as mint authority. The underlying asset MUST likewise be an LEZ-standard token. This is what makes shares transferable, wallet-visible, and composable (vault-of-vaults, shares as collateral) without vault-specific integration — and in LVS-SD it is what lets share positions live in the token program's private accounts. +3. **Inflation protection is mandatory.** Share conversion math must use virtual shares/assets with a configurable decimals offset (default ≥ 3), following the [OpenZeppelin virtual-offset defense](https://docs.openzeppelin.com/contracts/5.x/erc4626). Conversion: `shares = assets * (total_shares + 10^offset) / (total_assets + 1)` with operation-appropriate rounding. This is enforced by conformance tests, not prose. +4. **Vault-favoring rounding.** deposit→floor, mint→ceiling, withdraw→ceiling, redeem→floor. A solvency invariant, verified by tests. +5. **Slippage bounds on all mutating instructions.** `min_shares_out` / `max_assets_in` style parameters are required interface elements (ERC-4626 omits these; SVS added them; LEZ inherits the fix). +6. **Previews as real instructions.** `preview_*` and `convert_to_*` are on-chain instructions (CPI-composable from other programs), mirrored as SDK functions for clients. Preview results are binding bounds on the corresponding mutating operation. +7. **Two privacy variants in scope:** + - **LVS-P (public):** all state public; the composability baseline and integration target. + - **LVS-SD (shielded depositor):** vault aggregate state and pool account remain public; individual share positions are held in private accounts (commitments). Deposits mint shares into a private holding via the protocol's private account mechanics; redemptions prove ownership via nullifier and can pay out to a fresh, unlinkable account. Hidden: who holds what, position lifecycles, per-user yield. Visible: aggregate TVL, share price, per-transaction amounts. + - A `privacy_mode` field in vault state tags the variant and reserves values for future variants; a fully private pooled vault is explicitly out of scope (see Out of Scope). +8. **One canonical vault per (asset, strategy) via the factory** is encouraged, to concentrate the anonymity set for private positions. + +### Vault State Schema (Reference) + +```rust +// PDA: [program_id, "vault", asset_definition, vault_id] +struct VaultState { + asset_definition: Address, // underlying token definition + share_definition: Address, // share token definition (vault holds mint authority) + total_assets: u64, // stored-balance accounting + total_shares: u64, // shares outstanding + virtual_offset: u8, // inflation-protection decimals offset + authority: Address, // admin: pause, sync, fees, authority transfer + paused: bool, + privacy_mode: u8, // 0 = LVS-P, 1 = LVS-SD (others reserved) + last_update: u64, +} +``` + +## Success Criteria + +### Functionality + +- [ ] **Core vault interface** — a LEZ program implementing, with ERC-4626-equivalent semantics: + - `initialize_vault(asset_definition, vault_id, virtual_offset, privacy_mode)` + - `deposit(assets, min_shares_out)` — deposit exact assets, mint shares (floor) + - `mint(shares, max_assets_in)` — mint exact shares, charge assets (ceiling) + - `withdraw(assets, max_shares_in)` — withdraw exact assets, burn shares (ceiling) + - `redeem(shares, min_assets_out)` — burn exact shares, pay assets (floor) + - `preview_deposit / preview_mint / preview_withdraw / preview_redeem` — binding simulations, callable on-chain (CPI) and via SDK + - `convert_to_shares / convert_to_assets` — exchange-rate views + - `max_deposit / max_mint / max_withdraw / max_redeem` — capacity discovery; for private positions, owner-specific values are computed client-side by the wallet (the chain cannot read encrypted balances) and on-chain instructions return vault-level bounds + - `sync` — authority-gated recognition of externally accrued yield + - `pause / unpause / transfer_authority` — admin controls +- [ ] **Inflation-attack protection** — virtual shares/assets offset implemented in conversion math; demonstrated by a test reproducing the first-depositor donation attack and showing it unprofitable +- [ ] **Vault-favoring rounding** — all four mutating operations round in the vault's favor; verified by tests +- [ ] **Token standard conformance** — both the underlying asset and the share token MUST be tokens of the canonical [LEZ token program](https://github.com/logos-blockchain/lez-programs/tree/main/programs/token). Shares are minted/burned exclusively via cross-program calls to the token program (the vault PDA holds the share mint authority) and are fully transferable, holdable, and composable like any other LEZ-standard token — no bespoke balance ledger inside the vault program +- [ ] **Vault factory** — a factory program deploying vaults with configurable underlying asset, vault_id, virtual offset, and privacy mode +- [ ] **LVS-P public vault** — full interface working with all accounts public +- [ ] **LVS-SD shielded-depositor vault** — full deposit/redeem lifecycle with private share positions: deposit mints shares into a private account; position discovered via wallet sync; redeem proves ownership and burns privately-held shares, paying out to a public or fresh private account; deposit and withdrawal are unlinkable on-chain +- [ ] **Atomicity** — the binding between burned shares and released assets (and vice versa) happens in a single instruction; partial failures revert the whole transaction +- [ ] **Example strategy** — at least one working yield flow (e.g., authority deposits rewards + `sync`) demonstrating share-price appreciation end to end +- [ ] **Conformance test suite** — a runnable suite encoding the rounding table, inflation-attack resistance, preview-binding invariants, and slippage enforcement, usable against any claimed implementation of the standard + +### Usability + +- [ ] Provide a module/SDK that can be used to build Logos modules for interacting with vault programs, including client-side preview/max computation for private positions +- [ ] Provide an IDL for the vault and factory programs, using the [SPEL framework](https://github.com/logos-co/spel) +- [ ] Provide a Logos Basecamp app GUI demonstrating: vault creation, deposit, withdraw, share balance checking — for both the public and shielded-depositor variants + +### Reliability + +- [ ] Vault operations are atomic — partial failures revert the entire transaction +- [ ] Share conversion uses safe arithmetic (no overflow/underflow; mul-div with explicit rounding direction) +- [ ] Slippage bounds and pause state are enforced deterministically +- [ ] Invalid operations (withdraw exceeding balance, paused vault, stale previews) return clear error codes +- [ ] All mutating instructions carry timestamp validity windows so slow private-proof generation cannot replay into stale-price execution + +### Performance + +- [ ] Document compute unit (CU) costs for each core operation (deposit, mint, withdraw, redeem, sync) on LEZ devnet/testnet +- [ ] Document client-side proof generation time for LVS-SD deposit and redeem on commodity hardware +- [ ] Document share conversion behavior for varying vault sizes (10, 100, 1000 depositors) + +### Supportability + +- [ ] The vault and factory programs are 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, vault creation, and step-by-step interaction instructions 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; the recording must show terminal output (including proof generation) to confirm `RISC0_DEV_MODE=0` was active +- [ ] GitHub issues filed for any problems encountered with Logos technology + +## Scope + +### In Scope + +- Vault standard specification (interface, accounting rules, rounding, error codes, privacy variant definitions) +- LVS-P (public) and LVS-SD (shielded depositor) reference implementations +- Vault factory program +- Share tokens and underlying assets as LEZ-token-standard tokens; share minting/burning via CPI to the token program +- Example yield recognition flow via `sync` +- Conformance test suite +- SDK/module, SPEL IDLs, Basecamp demo app +- Integration tests and CI + +### Out of Scope + +- **Fully private pooled vaults** (private aggregate state: hidden TVL/share price). This requires shared private state, which current LEZ does not support — private accounts are bound to a single nullifier key, so a multi-depositor private pool would require operator custody or key sharing. The `privacy_mode` field reserves variant tags so such a vault can be added once protocol support exists, without breaking this interface. +- Per-user private sub-vaults (per-depositor private strategy accounts without pooling) — viable on LEZ today but a different primitive; candidate follow-up prize +- Complex fee structures (performance/withdrawal fees) — keep minimal for v1 +- Multi-asset vaults ([ERC-7575](https://eips.ethereum.org/EIPS/eip-7575) style) — future prize +- Asynchronous vault operations ([ERC-7540](https://eips.ethereum.org/EIPS/eip-7540) style) — future prize +- Streaming yield distribution (mitigates sync front-running) — future prize +- Vault-to-vault composability (allocator/vault-of-vaults) — future prize +- Production yield strategies (lending, DEX LP) — example flow only +- Mitigations for deposit/withdraw amount correlation in LVS-SD (standard denominations, batched epochs) — documented as a known limitation; future work + +## Prize Structure + +- **Total Prize:** $X +- **Effort:** L + +> Leave prize pool blank — this will be determined by the Logos team. Single winner by default. + +## 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 (MIT or Apache-2.0) containing: + - Vault standard specification document + - Vault LEZ program (LVS-P and LVS-SD) and factory program + - Conformance test suite + - SDK/module for vault interaction + - Integration tests runnable in CI +- Deployed programs on LEZ devnet/testnet with documented program addresses +- README with: build steps, program addresses, vault deployment, deposit/withdraw workflows for both variants, and troubleshooting +- A narrated video walkthrough in which the builder explains what they built and why, walks through the architecture and key implementation decisions, and demonstrates (see [demo requirements](../README.md#evaluation-policies)): + - end-to-end setup and deployment (or local environment configuration), + - creating a new vault via the factory, + - public variant: deposit, withdraw, share balance and share-price checks, + - shielded-depositor variant: deposit into a private position, wallet-sync position discovery, redeem with proof generation visible in terminal output, + - the inflation-attack test demonstrating protection, + - error handling for invalid operations (slippage violation, paused vault, over-withdrawal), + - integration with the LEZ token program for share minting/burning +- Compute unit benchmarks for all core operations and proof-time benchmarks for private operations +- GitHub issues filed for any problems encountered with Logos technology +- Submissions must include a FURPS self-assessment as part of the solution (see [solution template](../solutions/LP-0000.md)) + +## Evaluation Process + +By default, submissions are evaluated first-come-first-served against the success criteria. The first submission that meets 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 + +- [EIP-4626: Tokenized Vault Standard](https://eips.ethereum.org/EIPS/eip-4626) — interface semantics, rounding requirements +- [OpenZeppelin ERC-4626 guide](https://docs.openzeppelin.com/contracts/5.x/erc4626) — virtual-offset inflation defense +- [A Novel Defense Against ERC4626 Inflation Attacks](https://www.openzeppelin.com/news/a-novel-defense-against-erc4626-inflation-attacks) — attack and mitigation analysis +- [Solana Vault Standard (SVS)](https://github.com/solanabr/solana-vault-standard) — ERC-4626 on Solana's account model; structural reference +- [SVS-2](https://github.com/solanabr/solana-vault-standard/tree/main/programs/svs-2) — stored-balance public vault (closest structural analogue to LVS-P) +- [SVS-3](https://github.com/solanabr/solana-vault-standard/tree/main/programs/svs-3) / [SVS-4](https://github.com/solanabr/solana-vault-standard/tree/main/programs/svs-4) — confidential-transfer private vaults (contrast for LVS-SD) +- [EIP-7540: Asynchronous ERC-4626 Vaults](https://eips.ethereum.org/EIPS/eip-7540) — future extension shape +- [EIP-7575: Multi-Asset ERC-4626 Vaults](https://eips.ethereum.org/EIPS/eip-7575) — future extension shape +- [SPEL framework](https://github.com/logos-co/spel) — LEZ program framework and IDL tooling +- [Logos Execution Zone](https://github.com/logos-blockchain/logos-execution-zone) — runtime, private execution mechanics (commitments, nullifiers, account identities) +- [LEZ token program](https://github.com/logos-blockchain/lez-programs/tree/main/programs/token) — the canonical token standard; shares and underlying assets must conform to it +- [LEZ programs repo](https://github.com/logos-blockchain/lez-programs) — AMM, ATA, stablecoin, oracle reference programs +- [LP-0013](LP-0013.md) — Token program authorities (mint authority prerequisite) + +## Potential for Subsequent λ Prizes + +This prize targets v1 of the standard on the current LEZ testnet; LEZ is under active development and a follow-up prize may cover adaptation to later protocol versions. Natural extensions: + +- **Streaming yield** — linear yield distribution over a time window, eliminating sync front-running (SVS-5 analogue) +- **Async vaults** — request→fulfill→claim lifecycle for illiquid strategies (ERC-7540 analogue) +- **Multi-asset vaults** — ERC-7575 analogue +- **Private sub-vaults** — per-depositor private strategy accounts under a common program (full per-user privacy without pooling) +- **Allocator vaults** — vault-of-vaults composition +- **Amount-privacy upgrade for LVS-SD** — hiding per-transaction deposit/withdraw amounts, pending protocol-level support for batched/aggregated private flows