diff --git a/README.md b/README.md index fad8bd34..e9fa3e76 100644 --- a/README.md +++ b/README.md @@ -31,6 +31,7 @@ All prizes live in the `[prizes/](prizes/)` directory. Each prize is a markdown | File | Description | Size | Status | |------|-------------|------|--------| | [LP-0000](prizes/LP-0000.md) | Template — use this as the starting point for new prizes | — | — | +| [LP-0023](prizes/LP-0023.md) | LEZ Program Registry | Small | Open | ### Legacy prizes (original scheme) diff --git a/prizes/LP-0023.md b/prizes/LP-0023.md new file mode 100644 index 00000000..ea3ba855 --- /dev/null +++ b/prizes/LP-0023.md @@ -0,0 +1,179 @@ + + +--- +dependencies: [] +--- + +# LP-0023: LEZ Program Registry [OPEN] + +**`Logos Circle: N/A`** + +## Overview + +This prize is for a program registry for the Logos Execution Zone (LEZ): a product that lets developers publish their deployed programs together with human-readable metadata and a pointer to the program's IDL and source code, and lets anyone browse, search, and verify those entries through a CLI, an SDK, and a Logos Core Module. + +A LEZ program is identified on-chain by an opaque program ID. Nothing about that ID tells a user what the program does, who wrote it, what its interface looks like, or whether the bytecode matches any published source. The registry closes that gap: it turns an opaque program ID into a discoverable entry with a name, a version, an author, a description, tags, and a resolvable IDL, so that both humans and tooling can make sense of what they are about to interact with. + +## Motivation + +Every part of the LEZ developer experience currently assumes you already know which program you want and already have its IDL on disk. A wallet showing a transaction can only render raw calldata. A block explorer can show a program ID and its raw bytecode, but nothing that makes either one meaningful to a human: no name, no author, no interface, no way to tell what source, if any, produced it. A developer looking for an existing token or governance program has no place to look. Each tool that needs this information ends up shipping its own hardcoded list, and those lists drift apart. + +Metadata alone is only half the problem. Anyone can claim anything about a program they register, so a registry that records unverified assertions moves the trust problem rather than solving it. What carries real weight is proving that a deployed program's bytecode was built from the source it claims: that is what lets a wallet show "verified, built from `github.com/x/y` at commit `abc`" next to a program a user is about to sign for, links an audit report to the artifact actually deployed, and lets integrators pin against verified code rather than an address someone handed them. The closest analogue is Solana's verified-builds ecosystem and Etherscan source verification. + +A registry is the kind of shared substrate that benefits from being built once and consumed by everything else. The prize therefore requires both a working product and a genuine base of registered programs and integrating tools. + +The wallet prizes ([LP-0021](LP-0021.md), [LP-0022](LP-0022.md)) explicitly anticipate this work: they allow, but do not require, a wallet to surface registry metadata when previewing a smart-contract interaction. Landing this registry makes that possible. + +## Success Criteria + +### Functionality + +- [ ] **On-chain registry**: entry metadata is stored on-chain as a LEZ program built with the [SPEL framework](https://github.com/logos-co/spel), with a published IDL. Source code and the entry's own IDL live off-chain on Logos Storage; on-chain storage is limited to metadata and pointers, mindful of gas cost. +- [ ] **Register**: any account may register a program it deployed, supplying at minimum a **name**, **version**, **author**, **description**, an **IDL pointer**, a **code pointer**, and a **registration timestamp**. Lookup of an entry must not depend on a centralized indexer. +- [ ] **Deployer vs third-party entries**: the registry may hold both an entry from the program's own deployer and entries from third parties. The deployer's entry must be signed by the account that deployed the program, and clients must be able to tell it apart from a third-party entry without trusting an off-chain service. Either way, source verification (below) should be used to confirm the recorded claim actually matches the deployed program. The demo must show an unauthorised attempt to create a deployer entry being rejected. +- [ ] **Update**: only the original registering author may update an existing entry (version, IDL pointer, description). Authorship transfer is optional; if implemented, it must require signatures from both parties. +- [ ] **IDL publishing**: the IDL is stored on **Logos Storage**. +- [ ] **Discovery**: look up an entry by program ID, enumerate the full set of registered entries, and search by name and author, using only the submitted software. +- [ ] **Source verification**: an entry must additionally record a pointer to source (code stays off-chain), a commit, and a build configuration sufficient to reproduce the deployed bytecode. A user may choose to rebuild the recorded source locally (via CLI, GUI, or any other tooling); if the resulting byte code matches, the user can mark that program as "locally verified" for themselves. Alternative adequate strategies for bytecode verification may be accepted. +- [ ] **Testnet 0.3**: the registry operates end-to-end against the Logos LEZ zone on Logos testnet 0.3. + +### Usability + +- [ ] Provide a module/SDK usable by other Logos modules and third-party applications to register entries, resolve a program ID to its metadata and IDL, and run searches. This is the primary integration surface: wallets, explorers, and developer tools are the intended consumers. +- [ ] Provide a CLI covering register, update, lookup, search, and source verification. + +### Reliability + +- [ ] Clients degrade gracefully when an IDL identifier is unresolvable or the stored IDL fails to parse: the entry's on-chain metadata still displays, with the IDL surfaced as unavailable rather than the view failing. +- [ ] **No mandatory centralised external services.** Beyond the user's configured sequencer, Logos LEZ node, and Logos Storage (or other Logos protocols), the registry and its tooling must not depend on any third-party web service to function. If one is used, it is disclosed, the user can disable it, and the registry remains fully functional with it disabled. Any analytics must be strictly opt-in. + +### Performance + +- [ ] Document [cycle count](https://github.com/logos-blockchain/logos-execution-zone/tree/dev/tools/cycle_bench) usage for each on-chain operation (register, update). + +### Supportability + +- [ ] Deployed and tested against Logos testnet 0.3 (the canonical Logos LEZ zone). +- [ ] The submission builds and runs end-to-end on both **macOS (Apple Silicon)** and **Linux (x86_64)**. +- [ ] The Logos Core Module is built with [`logos-module-builder`](https://github.com/logos-co/logos-module-builder) (`mkLogosModule`). +- [ ] Provide an IDL for the registry program itself, generated via the [SPEL framework](https://github.com/logos-co/spel): the registry must be registered in itself. +- [ ] End-to-end integration tests run against a real sequencer (standalone mode) and are included in CI; CI is green on the default branch. +- [ ] README documents setup, the deployed program ID, and step-by-step usage via CLI and Logos Core Module. +- [ ] SDK documentation covers resolving a program ID to metadata and IDL as a worked example, since that is the integration path most consumers will take. + +### Adoption + +> These metrics measure traction attributable to a given submission for this prize. +> +> **All of the following are required in addition to the FURPS criteria above.** We publish the dimensions we look at, but hitting a raw number is not by itself sufficient (see [Terms & Conditions](../TERMS.md) for the evaluation policy that applies to all prizes). Evaluators will inspect commit histories and the posting history of vouching accounts. Volume that is clearly manufactured (fresh accounts, purchased engagement) does not count, regardless of the headline number. + +- [ ] **5 third-party Logos apps** (Logos UI Modules) integrate the registry SDK to resolve program metadata or IDLs, for example a wallet, an explorer, or a developer tool. Each must ship as a Logos UI Module, publicly hosted on a mainstream forge (GitHub, GitLab, Codeberg, etc.) with a clear, genuine commit history: development spread over time by a real contributor, not a single bulk import. The 5 must be independent of each other and of the submitting team. The owning developer or organisation's history on the forge will be inspected; fresh accounts, among other red flags, will not count. +- [ ] **50 registered programs** on the official Logos zone, registered by **at least 20 distinct author accounts** independent of the submitting team. Entries must point at genuinely deployed programs with resolvable, parseable IDLs; placeholder or duplicate entries pointing at the same underlying program do not count. Accounts with no prior unrelated testnet activity carry little weight. +- [ ] **20 entries carry a verified source claim**: a recorded source repository and commit that an evaluator can independently rebuild to byte code matching the deployed program ID. Registering metadata is cheap; proving the bytecode matches published source is the part that makes the registry trustworthy, so it is counted separately. +- [ ] **Sustained registration activity**: the 50 registrations must be spread over **at least 2 months**, with **at least 10 new registrations in each of those months**. A single burst of activity does not qualify, however large. Each entry is timestamped on-chain, so this is verified directly from chain data. +- [ ] **20 testimonials on Discord** vouching for the registry. Testimonials should describe what the person actually used the registry for; account history will be checked. +- [ ] **20 testimonials on Twitter/X** vouching for the registry, subject to the same standard and the same account-history check. Sharing screenshots of the registry in use is encouraged. + +## Additional Design Choices Left to the Submitter + +The following are deliberately not set out in the Success Criteria, as they are additional design choices which the submitter should decide upon. A submission must pick a position on each, document it, and justify it: the reasoning is part of what is evaluated. + +- **What lives on-chain?** Source code and the IDL must live off-chain, on Logos Storage; the on-chain entry holds pointers, not the content itself. Beyond that minimum, a submission decides how much attestation data to keep on-chain versus off-chain, and should account for the gas cost of what it chooses to store on-chain. +- **How is verified source hosted?** The registry proves a byte code match, but something must host the code being matched against. A submission may point at a third-party repository, mirror source to Logos Storage, or both, but should say why. A repository URL alone is a liveness dependency on a third party: a deleted GitHub repo makes re-verification impossible, which is a weakness Solana's registry inherits. +- **Is there a trusted-signer overlay?** Solana's explorer hardcodes a small list of trusted third-party verifiers (OtterSec, the Explorer itself) that rank above other non-authority signers. This is pragmatic but reintroduces a centralised trust root. A submission may implement something similar, omit it, or make the trusted set user-configurable, but if it ships one, the list must be user-inspectable and overridable. + +## Scope + +### In Scope + +- The on-chain LEZ registry (register, update), built with SPEL. +- IDL publishing to Logos Storage and resolution from the on-chain entry. +- Reproducible builds for LEZ programs, and the source-verification tooling and on-chain fields backing it. +- A claim-authorisation model distinguishing a program's own deployer from third-party registrants. +- Discovery: lookup by program ID, plus search by name and author (including a self-hostable indexer if search requires one). +- SDK, CLI, Logos Core Module. + +### Out of Scope + +- **Curation, moderation, or a trust score.** The registry records what authors assert plus objectively checkable verification status. Deciding which programs are "good" or delisting entries is a governance question, not needed for this prize. +- Hosting a public indexer as a service. The indexer must be self-hostable, but running one as infrastructure is not part of the deliverable. +- Payment, licensing, or monetisation of registered programs. + +## Prize Structure + +- **Total Prize:** $2000 +- **Effort:** Small + +## 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 both MIT and Apache-2.0. + +## Submission Requirements + +- Public repository with the registry program, SDK, CLI, and Logos Core Module dual-licensed under both MIT and Apache-2.0. +- The registry's own IDL, and the deployed program ID on Logos testnet 0.3. +- The Logos Core modules published to a module catalog: a fork of [`logos-modules-release-base`](https://github.com/logos-co/logos-modules-release-base), publishing releases via [`logos-modules-release-action`](https://github.com/logos-co/logos-modules-release-action). The catalog's `logos-repo.json` URL must be included so evaluators can install the module through the package-manager UI / `lgpd`. +- Evidence for each adoption criterion: links to the 5 third-party integrations and their repositories, the registry repository, the on-chain entries (with per-month counts so the sustained-activity criterion can be verified, and the subset carrying verified source claims), and the Discord and Twitter/X testimonials. +- 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 meets all criteria wins. + +Because the adoption criteria require sustained activity over at least two months, a submission cannot qualify until that window has elapsed. Builders are encouraged to ship early and start accruing adoption while continuing to develop, rather than treating the build and the adoption push as sequential. + +Evaluators will independently clone the repository and run the demo script from a clean environment; the script must succeed without modification. Evaluators will also independently rebuild a sample of the entries claiming verified source and confirm the bytecode hashes match. Evaluators may 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 + +- [SPEL framework](https://github.com/logos-co/spel) — Anchor-inspired developer framework for LEZ programs, used for the program and its IDL +- [Logos Execution Zone repo](https://github.com/logos-blockchain/logos-execution-zone/) +- [LEZ programs repo](https://github.com/logos-blockchain/lez-programs/) +- [`logos-modules-release-base`](https://github.com/logos-co/logos-modules-release-base) and [`logos-modules-release-action`](https://github.com/logos-co/logos-modules-release-action) — module catalog publishing +- [`logos-module-builder`](https://github.com/logos-co/logos-module-builder) — `mkLogosModule` +- [`cycle_bench`](https://github.com/logos-blockchain/logos-execution-zone/tree/dev/tools/cycle_bench) — LEZ's cycle-count benchmarking tool, the unit to use when documenting compute cost + +Solana prior art: + +- [Solana verified builds documentation](https://solana.com/docs/programs/verified-builds) and the [verification guide](https://solana.com/developers/guides/advanced/verified-builds) +- [`solana-foundation/solana-verifiable-build`](https://github.com/solana-foundation/solana-verifiable-build) — the `solana-verify` CLI +- [`otter-sec/otter-verify`](https://github.com/otter-sec/otter-verify) — on-chain verification program, and [`otter-sec/solana-verified-programs-api`](https://github.com/otter-sec/solana-verified-programs-api) — the verification service +- [`solana-program/program-metadata`](https://github.com/solana-program/program-metadata) — canonical/non-canonical metadata PDAs +- [`solana-foundation/idl-spec`](https://github.com/solana-foundation/idl-spec) — the standard IDL format +- ["How We Hacked Solana Verified Builds"](https://accretion.xyz/blog/verified-builds) — Accretion, on the `build.rs` provenance attack +- [Solana Explorer verification UI](https://deepwiki.com/solana-foundation/explorer/3.3-program-verification-system) + +Logos: + +- [LP-0011](LP-0011.md) — Program development tooling: Rust SDK +- [LP-0021](LP-0021.md) — LEZ Zone Wallet and SDK, a natural consumer of this registry for human-readable transaction previews +- Prior art: [`jimmy-claw/spelbook`](https://github.com/jimmy-claw/spelbook) (formerly `lez-registry` — Rust core, on-chain program, CLI, and the `lez-registry-ffi` workspace member) and [`jimmy-claw/logos-lez-registry-module`](https://github.com/jimmy-claw/logos-lez-registry-module) (Logos Core Qt6 module). Together these implement register, author-gated update, lookup by program ID, IDL upload/download against Logos Storage, a CLI, and a browse/detail/register GUI. They do **not** implement enumeration, name or tag search, claim authorisation, or any form of source verification. Listing and name lookup are explicitly stubbed as "requires an off-chain indexer in v1", and `registered_at` is currently always zero. Submissions may build on this prior work subject to its licence, but must credit it clearly and cannot present it as original; the criteria above are written so that the unimplemented parts are where the work actually lies. + +## Potential for Subsequent λ Prizes + +This prize covers the **first adoption tranche** for the registry. A follow-up λPrize is expected with higher adoption thresholds, adapted to the phase the network is in at that time, and may extend the registry toward areas explicitly out of scope here: notably curation and trust signals, once there is enough registry content for those questions to be meaningful. + +This prize also targets Logos testnet 0.3. Should a future testnet version (e.g., V0.4) introduce breaking changes to program IDs, PDA derivation, or the SPEL IDL format, a subsequent λ Prize may be opened to cover adaptation. + +--- + +**Note:** The Specification in this Prize describes an outcome that Logos intends to benefit the Logos ecosystem. It sets out criteria and certain requirements a Participant should fulfill in order to potentially be eligible to be awarded a Prize amount, and is not intended to be an instruction or to direct a Participant's initiative or approach. They are guided by existing approaches and implementations in other mature blockchain systems and their ecosystems, as well as by functional requirements particular to the Logos technology stack or perceived usefulness to such stack or the wider community building on it. + +Logos makes no representation as to the legal or regulatory treatment of this Specification or any implementation of it in any jurisdiction. + +Participants act independently, voluntarily and at their own initiative in connection with their Submissions and are solely responsible for: + +1. assessing the risks and implications of their Participation in the Program and of any Artefacts that form part of their Submission; +2. determining whether to obtain independent professional advice; +3. complying with all applicable laws to them and in connection with the Program, including, where relevant, any licensing, registration, sanctions or anti-money laundering obligations that may arise from operating any software-as-a-service or business. + +Artefacts developed by Participants in connection with the Program are published and maintained by Participants and not by Logos or its Affiliates. Logos and its Affiliates do not build, host, maintain, deploy, operate, use or control any Artefacts arising out of any Submission. + +Participants or other persons who choose to build upon, host, maintain, deploy, operate, use or publicly promote any Artefacts, do so at their own risk and as a principal and in their own name. Any such persons are further solely responsible for complying with any legal or regulatory requirements that apply to them with such use. Logos does not make any representation, provide any advice or assume any responsibility regarding the use of such Artefacts, or any determination of compliance with applicable law or regulation. + +For further details of the above and what terms and conditions apply to a Participant, please refer to the [λPrize Program – Terms & Conditions](../TERMS.md).