diff --git a/README.md b/README.md index 5cb195dc..a5905693 100644 --- a/README.md +++ b/README.md @@ -35,6 +35,7 @@ Prizes are typically defined through an analysis of gaps in the Logos technology | File | Description | Size | Status | |------|-------------|------|--------| | [LP-0000](prizes/LP-0000.md) | Template — use this as the starting point for new prizes | — | — | +| [LP-0018](prizes/LP-0018.md) | OpenStreetMap integration: decentralized map data distribution | Medium | Open | ### Legacy prizes (original scheme) diff --git a/prizes/LP-0018.md b/prizes/LP-0018.md new file mode 100644 index 00000000..185f38bf --- /dev/null +++ b/prizes/LP-0018.md @@ -0,0 +1,206 @@ +--- +dependencies: [] +--- + +# LP-0018: OpenStreetMap Integration — Decentralized Map Data Distribution [OPEN] + +**`Status: Open`** +**`Logos Circle: N/A`** + +## Overview + +This prize funds an **OpenStreetMap (OSM) data distribution system** for the Logos ecosystem. Users can browse available map regions, host map data in Logos Storage, and download map files whose integrity is guaranteed by content-addressing (CID), with import-time checksum verification against Geofabrik. + +Geofabrik publishes regions as a tree: a country extract is the union of its subregions (for example the India country file contains all six India zones; the same bytes appear again in each zone file under a different CID and checksum). Regions in this system are therefore identified at a specific level (country or subregion) and the predefined set is **non-overlapping** (no region contains another) so the same geography is never hosted or counted twice. See [Predefined Regions](#predefined-regions-closed-set) for the closed set. + +The deliverable has two required parts: an **OSM distribution Logos Basecamp app** that hosts and downloads map files (region discovery, host/download workflows, import-time checksum verification, and bulk operations), and an **OSM registry SDK/module** for other Basecamp apps and modules to talk to the on-chain registry. A Basecamp consumer only needs the PBF files available locally and this SDK to discover them and use them in another module, or hosted locally; it does not need the distribution app. For that use, the SDK can be a limited subset: it does not need the host, register, or retrieval functions the distribution app uses. That is why the SDK is independent of the distribution app. Viewers and other apps that actually use the map data are out of scope of this prize and are expected to be built by the community independently. The distribution app uses the full SDK (the UI is packaged with it); the SDK is also published as a separate Basecamp module so other Basecamp apps and modules can depend on it without the distribution app. + +**Requires:** +- Logos Storage module (for storing PBF files) +- LEZ (Logos Execution Zone) program for the on-chain OSM registry + +The **Success Criteria**, **Scope**, and **Submission Requirements** below are the authoritative checklist for evaluators. + +## Motivation + +OpenStreetMap extracts are widely used for offline navigation, GIS tooling, and privacy-preserving map apps — but distribution today depends on central hosts such as Geofabrik. A Logos-native distribution layer lets communities mirror verified map snapshots in decentralized storage and register them on-chain, so users can discover and download authentic data without trusting a single operator. + +This prize complements existing Logos sample apps (notably [LP-0017](LP-0017.md)) by demonstrating a full **fetch → store → register → download** pipeline for large binary assets, with content-addressed integrity anchored to Geofabrik as the canonical source. It also ships a reusable Basecamp SDK/module so other Basecamp apps and modules can discover and use those files locally. + +## Success Criteria + +### Functionality + +- [ ] **Region discovery**: fetch the Geofabrik index and display available regions with version info and their level in the region tree (country / subregion), restricted to the predefined set. +- [ ] **Host workflow**: download PBF from Geofabrik → store to Logos Storage → register on-chain via the OSM registry LEZ program. +- [ ] **Download workflow**: fetch from Logos Storage (if hosted) or Geofabrik (direct fallback). Integrity is guaranteed by the content-addressed CID; no round-trip to Geofabrik is required to trust a downloaded file. +- [ ] **Bulk host**: allow selecting multiple regions to host at once, with opt-out per region. Because the predefined set is a non-overlapping partition, bulk selection stays within that set; if a submission chooses to also expose non-partition regions, it must warn when a selection would host a region already contained in another selected or hosted region (parent/child overlap). +- [ ] **Local import**: user provides a local PBF → verify against Geofabrik's published MD5 (import-time only) → store → register by CID. +- [ ] **Update check**: compare central versions vs registry and notify the user of available updates. Version comparison is per region entry (matched on the region path), so updating a country file and its subregions are tracked independently. +- [ ] **On-chain registry**: an OSM registry LEZ program that: + - stores per-region entries with at minimum: `region`, `parent`, `level`, `cid`, `source_url`, `checksum`, `version`, `hosted`, and `timestamp`, + - identifies each region by its Geofabrik path so that `region` is unique and its position in the tree (`parent`, `level`) is explicit, + - is queryable by region, by parent, and by CID, + - supports registering multiple regions in a single batch transaction when bulk hosting. +- [ ] **Testnet 0.3**: the OSM registry operates end-to-end against the Logos LEZ zone on Logos testnet 0.3. +- [ ] **OSM registry SDK**: a self-contained Basecamp SDK/module with a stable, documented API and a minimal embedding example in another Basecamp module. The distribution app uses the full registry API — discover regions, resolve a region to its CID/metadata, host (store + register), batch-register, query by region/parent/CID, and check for updates — rather than a separate registry client. The SDK is also published as a separate Basecamp module so other Basecamp apps and modules can depend on it without the distribution app. For that consumer use (discover and use map files in another module, or hosted locally), the exposed API can be a limited subset: it does not need host, register, batch-register, or retrieval. + +### Usability + +- [ ] Provide a Logos Basecamp app GUI with local build instructions, downloadable assets, and loadable in Logos app (Basecamp). +- [ ] Provide an SDK/module that can be used to build Logos Basecamp modules and apps for interacting with the OSM registry, with published API documentation and a minimal embedding example that runs as a Basecamp module without the distribution app. +- [ ] Provide a CLI covering host (store + register), batch-register, lookup by region/parent/CID, update check, download, and local import. +- [ ] Clear UX: show hosted/not-hosted status, version numbers, and verification results. + +### Reliability + +- [ ] Storage upload retries on transient failures with exponential back-off and surfaces a clear error after exhausting retries. +- [ ] Import-time checksum verification fails gracefully with clear error messages. +- [ ] Registry entries are ordered by timestamp for version sorting. +- [ ] **No mandatory centralised external services.** Beyond the user's configured sequencer, Logos LEZ node, Logos Storage (or other Logos protocols), and Geofabrik as the canonical snapshot source (index lookup, import-time checksum, and direct-download fallback when a region is not hosted), 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. Hosted regions must remain discoverable and downloadable without Geofabrik. 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, batch-register). + +### 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 Basecamp modules (distribution app and SDK/module) are built with [`logos-module-builder`](https://github.com/logos-co/logos-module-builder) (`mkLogosModule`). +- [ ] The Logos Basecamp modules are 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 modules through the package-manager UI / `lgpd`. +- [ ] Provide an IDL for the OSM registry LEZ program, generated via the [SPEL framework](https://github.com/logos-co/spel). +- [ ] End-to-end integration tests covering host (fetch → store → register) → query → download 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, the region list, and step-by-step usage via CLI and Basecamp app. +- [ ] SDK documentation covers resolving a region to its CID and metadata as a worked example, since that is the integration path most Basecamp consumers will take. + +## Adoption + +> These metrics measure traction attributable to a given submission for this prize. +> +> **The Required criteria below are mandatory 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). Coverage is confirmed from on-chain registry data checked against Geofabrik; ecosystem reuse is confirmed from public forge repositories and code inspection. Evaluators inspect account and 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. **Discretionary signals** are considered in addition, per the same policy. + +**Required:** + +- **Coverage.** At least **15 countries** from the predefined set (see the region list) are covered on the official Logos zone (Logos testnet 0.3) and hosted in Logos Storage, and at least **25 total verified region entries** are covered across the set. A country counts as covered when it is a country-level entry that is registered, or a decomposed country (US, India, China, Russia) for which **at least one of its subregions** is registered. Each contributing entry must verify: the evaluator fetches the CID from Logos Storage, hashes the bytes, and confirms the hash matches Geofabrik's published MD5 for that snapshot. Entries whose stored bytes do not match Geofabrik do not count, and an unverified subregion does not make its country count. The 25-entry floor is above the 15-country minimum and forces some depth in the decomposed countries, so coverage cannot be met by decomposed countries each satisfied with a single small subregion. +- **Ecosystem reuse via the SDK.** At least **5 independent modules**, including at least **3 Logos Basecamp apps (UI modules)**, consume the OSM distribution module to discover or fetch regions. One of the 5 may use only the standalone SDK module, without the distribution one. Each must be 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, and fresh accounts, among other red flags, will not count. Use of the SDK is confirmable by code inspection. + +**Discretionary signals (considered in addition, per Terms & Conditions):** + +- **Redundant mirroring.** A covered region is hosted by more than 5 operators (same CID, distinct hosting accounts). Assessed qualitatively: signaling that these are distinct individuals will be reflected favourably where evident. +- **Community vouching.** Testimonials from people who have actually hosted or used a region (for example, on Discord and on Twitter/X), with account histories inspected. + +## Scope + +### In Scope + +- The on-chain OSM registry (register, batch-register, lookup by region / parent / CID), built with SPEL. +- PBF snapshots in Logos Storage. Geofabrik is the canonical source for the index, import-time checksums, and direct-download fallback when a region is not hosted. +- Host workflow (fetch → store → register), including bulk host and local import. +- Download of hosted regions by CID. +- Region discovery and update check, restricted to the predefined non-overlapping set. +- Distribution Basecamp app, SDK/module, and CLI. + +### Out of Scope + +- **Viewers and other apps that use the map data.** Map rendering, tile servers, geocoding, routing, and navigation are expected to be built by the community independently. This prize distributes verified snapshots; it does not consume them. +- **Live OSM sync.** Snapshots only. Incremental or real-time updates are not part of the deliverable. +- **Custom regions or extra tree levels.** Coverage is measured against the predefined non-overlapping set (see the region list). +- **A hosted relay or backend.** Registry, storage, and app logic run on the Logos stack. Geofabrik is used only as an external canonical snapshot source (index, checksums, unhosted fallback), not as a runtime backend. + +## Prize Structure + +- **Total Prize:** $1500 +- **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 dual-license it under the MIT License and Apache License 2.0. + +## Submission Requirements + +- Public repository with the OSM registry program, SDK/module, CLI, and distribution Basecamp app, dual licensed under the MIT License and Apache License 2.0. +- The registry IDL, and the deployed program ID on Logos testnet 0.3. +- The Logos Basecamp 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 modules through the package-manager UI / `lgpd`. +- Evidence for each required adoption criterion: links to the 5 independent modules and their repositories, and the on-chain coverage (region entries and CIDs so an evaluator can fetch from Logos Storage and check hashes against Geofabrik). +- FURPS self-assessment as part of the solution (see [solution template](../solutions/LP-0000.md)). + +## Evaluation Process + +A solution PR in this repository is required to claim this prize. Submissions are evaluated first-come-first-served against the success criteria and the required **Adoption** criteria. The first solution PR that meets all of them wins. Meeting the criteria without a solution PR does not establish priority. A solution PR is timestamped by its opening date. + +Builders are encouraged to ship early and start accruing coverage and ecosystem reuse while continuing to develop, rather than treating the build and the adoption push as sequential. + +Evaluators will independently clone the repository and follow the README from a clean environment. Evaluators will also independently fetch a sample of covered region CIDs from Logos Storage and confirm the hashes match Geofabrik's published MD5, and inspect the 5 independent modules for genuine SDK use. 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:** a solution PR in this repository is required. 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 and the **Adoption** section. + +## Resources + +- [Geofabrik Downloads](https://download.geofabrik.de/) +- [Geofabrik JSON Index](https://download.geofabrik.de/index-v1-nogeom.json) +- [Geofabrik Checksum Example](https://download.geofabrik.de/europe/germany/berlin-latest.osm.pbf.md5) +- [Logos Basecamp](https://github.com/logos-co/logos-basecamp) +- [Logos Storage Module](https://logos-storage-docs.netlify.app/tutorials/storage-module/) +- [LEZ GitHub repository](https://github.com/logos-blockchain/logos-execution-zone) +- [SPEL framework](https://github.com/logos-co/spel) +- [`logos-module-builder`](https://github.com/logos-co/logos-module-builder) — `mkLogosModule` +- [`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 +- [`cycle_bench`](https://github.com/logos-blockchain/logos-execution-zone/tree/dev/tools/cycle_bench) — LEZ cycle-count benchmarking +- [LP-0017](LP-0017.md) — Whistleblower (reference implementation for storage + registry patterns) +- [LP-0008](LP-0008.md) — Autonomous AI Module (reference for Logos Core module architecture and storage patterns) + +## Potential for Subsequent λPrizes + +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. + +Viewers and other apps that actually use the map data — an offline map viewer, search/POI discovery, routing, or similar — are out of scope of this prize and are expected to be built by the community independently. + +### Predefined Regions (closed set) + +> The coverage criterion is measured against this closed, non-overlapping set. No region here is an ancestor or descendant of another, so each piece of geography is hosted and counted at most once. Full technical design (architecture, registry schema, verification flow) is left to the challenger. + +Countries represented **at country level** (`level: country`, `parent: null`): + +**Europe:** Germany, France, United Kingdom (`great-britain`), Italy, Spain, Poland, Netherlands, Belgium, Switzerland, Austria, Czech Republic, Sweden, Norway, Denmark, Finland, Portugal, Greece, Ireland, Hungary, Romania, Bulgaria, Ukraine, Belarus, Turkey + +**North America:** Canada, Mexico + +**Asia:** Japan, South Korea, Indonesia, Thailand, Vietnam, Malaysia, Philippines, Pakistan, Bangladesh, Iran + +**Oceania:** Australia + +**South America:** Brazil, Argentina, Colombia, Peru, Chile + +**Africa:** South Africa, Egypt, Nigeria, Kenya, Morocco, Ethiopia + +Countries represented **by subregions** (decomposed; the country file itself is **not** in the set). These are the largest extracts, where subregion granularity is more mirror-friendly and closer to how users pull data: + +- **United States** (`us`) -> 8 state extracts: `us/california`, `us/texas`, `us/florida`, `us/new-york`, `us/washington`, `us/illinois`, `us/georgia`, `us/pennsylvania`. `us` as a whole is never in the set. +- **India** (`india`) -> its 6 zones: `india/central-zone`, `india/eastern-zone`, `india/north-eastern-zone`, `india/northern-zone`, `india/southern-zone`, `india/western-zone`. +- **China** (`china`) -> 6 province extracts: `china/guangdong`, `china/jiangsu`, `china/shandong`, `china/zhejiang`, `china/sichuan`, `china/henan`. +- **Russia** (`russia`) -> 4 federal-district extracts: `russia/central-fed-district`, `russia/northwestern-fed-district`, `russia/volga-fed-district`, `russia/siberian-fed-district`. + +These leaf ids are frozen: the closed set is exactly the entries listed above, so a third party can reconstruct it directly from this document. The registry stores each leaf as its own entry with `parent` set to the decomposed country (`us`, `india`, `china`, `russia`). Coverage counts hosted leaf entries, not the decomposed country as a single unit. If Geofabrik renames a leaf, this document is patched to match; the set does not drift with the index. + +--- + +**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). +