LP-0018: OpenStreetMap integration — decentralized map data distribution

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-0018](prizes/LP-0018.md) | OpenStreetMap integration: decentralized map data distribution | Medium | Draft  |
 
 ### Proposing a New Prize
 

prizes/LP-0018.md

@@ -0,0 +1,294 @@
+---
+dependencies: []
+---
+
+# LP-0018: OpenStreetMap Integration — Decentralized Map Data Distribution [DRAFT]
+
+**`Status: Draft`**
+**`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 verified map files with checksum guarantees.
+
+The deliverable has two required parts: a **Logos Basecamp app** (region discovery, host/download workflows, checksum verification, and bulk operations) and a standalone **OSM registry module/SDK** for programmatic interaction with the on-chain registry.
+
+**Requires:**
+- Logos Storage module (for storing PBF files)
+- LEZ (Logos Execution Zone) program for the on-chain OSM registry
+
+Logos Storage may connect to an external Logos node until the built-in module is available.
+
+The **Success Criteria**, **Scope**, and **Submission Requirements** below are the authoritative checklist for evaluators. The same requirements are **restated in the [Appendix](#appendix-technical-design-and-requirements)** alongside architecture diagrams, registry schema, verification flow, and the predefined region list — use both sections together when building or reviewing a submission.
+
+## 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 → verify → download** pipeline for large binary assets, with checksum guarantees anchored to Geofabrik as the canonical source.
+
+## Success Criteria
+
+### Functionality
+
+- [ ] **Region discovery**: fetch the Geofabrik index and display available regions with version info.
+- [ ] **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).
+- [ ] **Checksum verification**: verify a downloaded file against Geofabrik's published MD5 checksum.
+- [ ] **Bulk host**: allow selecting multiple regions to host at once, with opt-out per region.
+- [ ] **Local import**: user provides a local PBF → verify checksum → store → register.
+- [ ] **Update check**: compare central versions vs registry and notify the user of available updates.
+- [ ] **On-chain registry**: an OSM registry LEZ program that:
+  - stores per-region entries with at minimum: `region`, `cid`, `source_url`, `checksum`, `version`, `hosted`, and `timestamp` (see [Appendix A.2](#a2-registry-schema-lez-program-account)),
+  - is queryable by region and by CID,
+  - supports registering multiple regions in a single batch transaction when bulk hosting.
+- [ ] **OSM registry module**: extract registry interaction logic into a self-contained module with a documented API, reusable by other Logos apps without depending on the Basecamp app itself.
+
+### Usability
+
+- [ ] Provide a Logos Basecamp app GUI with local build instructions, downloadable assets, and loadable in Logos app (Basecamp).
+- [ ] Provide a module/SDK that can be used to build Logos modules for interacting with the OSM registry.
+- [ ] Provide an IDL for the OSM registry LEZ program, using the [SPEL framework](https://github.com/logos-co/spel).
+- [ ] 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.
+- [ ] Checksum verification fails gracefully with clear error messages.
+- [ ] Registry entries are ordered by timestamp for version sorting.
+
+### Performance
+
+- [ ] Document a sample file size (e.g., Berlin ~93 MB) and measured download/verify times.
+- [ ] Document time to verify checksum (fetching `.md5` file only, not full download).
+- [ ] Document and measure the compute unit (CU) cost of a single-region registration and a multi-region batch registration on LEZ devnet/testnet. Note: LEZ's per-transaction compute budget may change during testnet.
+
+### Supportability
+
+- [ ] The OSM registry LEZ program is deployed and tested on LEZ devnet/testnet.
+- [ ] End-to-end integration tests covering host → verify → query → download run against a LEZ sequencer in standalone mode and are included in CI.
+- [ ] CI is green on the default branch.
+- [ ] A README covers: build steps, program addresses, running the Basecamp app, querying the registry, region list, and troubleshooting.
+- [ ] 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
+
+- Region discovery from Geofabrik index.
+- Host workflow (fetch + store + register).
+- Download from Logos Storage or Geofabrik central source.
+- Verification against Geofabrik checksums.
+- On-chain OSM registry LEZ program.
+- Basecamp UI with bulk host/download.
+- OSM registry module extracted from the app, with documented API.
+- Integration tests and CI.
+
+Geofabrik is the **canonical source of truth** for snapshot bytes and MD5 checksums. Hosted copies in Logos Storage are verified against Geofabrik; Geofabrik is not a runtime backend for the app beyond index lookup, checksum fetch, and direct-download fallback.
+
+### Out of Scope
+
+- Map rendering or tile server.
+- Real-time OSM synchronization (snapshots only).
+- Geocoding, routing, or navigation features.
+- Custom regions outside the predefined list (see [Appendix A.4](#a4-predefined-regions)).
+- A hosted relay or backend service — registry, storage, and app logic run on the Logos stack; Geofabrik is used only as an external canonical snapshot source.
+
+## Prize Structure
+
+- **Total Prize:** $X
+- **Effort:** Medium
+
+> Leave prize pool blank — this will be determined by the Logos team.
+
+## 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:
+  - the OSM Basecamp app,
+  - the OSM registry module with API documentation,
+  - the OSM registry LEZ program,
+  - integration tests runnable in CI.
+- Deployed OSM registry LEZ program on LEZ devnet/testnet with documented program address.
+- README with: build steps, region list, workflow, 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),
+  - hosting a region (fetch from Geofabrik → store → register),
+  - verifying checksum from the app,
+  - downloading and verifying a hosted region,
+  - integration with the Logos stack (Logos Storage and on-chain registry),
+  - error handling for checksum mismatch and transient storage failures.
+  A silent screencast without explanation is not sufficient.
+- Compute unit benchmarks for single and batch registry 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
+
+- [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)
+- [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 targets snapshot-based distribution from Geofabrik. A follow-up prize may cover incremental updates, additional region sources, or deeper integration once built-in Logos Storage and Blockchain modules ship in Basecamp.
+
+---
+
+## Appendix: Technical Design and Requirements
+
+This appendix **restates the prize requirements** from the sections above in technical context. Evaluators and builders should treat the **Success Criteria**, **Scope**, and **Submission Requirements** in the main body and the checklist below as a single combined specification — the appendix adds architecture, schemas, and implementation detail; it does not relax or replace any main-body requirement.
+
+### A.0 Requirements checklist
+
+The items below mirror the main-body success criteria and scope. A submission must satisfy **both** this checklist and the corresponding sections above.
+
+**Functionality**
+
+- [ ] Region discovery from Geofabrik JSON index with version info displayed per region.
+- [ ] Host workflow: Geofabrik PBF download → Logos Storage upload → OSM registry LEZ program registration.
+- [ ] Download workflow: Logos Storage when hosted; Geofabrik direct when not.
+- [ ] MD5 checksum verification against Geofabrik-published checksums.
+- [ ] Bulk host with per-region opt-out.
+- [ ] Local PBF import with checksum verification before store and register.
+- [ ] Update check comparing Geofabrik central versions against on-chain registry entries.
+- [ ] OSM registry LEZ program: stores schema fields from [A.2](#a2-registry-schema-lez-program-account); queryable by region and CID; supports batch registration.
+- [ ] Standalone OSM registry module/SDK with documented API.
+
+**Usability**
+
+- [ ] Logos Basecamp app with build instructions and loadable assets.
+- [ ] Module/SDK for building Logos modules that interact with the OSM registry.
+- [ ] IDL for OSM registry LEZ program (SPEL).
+- [ ] UI shows hosted/not-hosted status, versions, and verification outcomes.
+
+**Reliability**
+
+- [ ] Storage upload retries with exponential back-off; clear errors on failure.
+- [ ] Checksum mismatch reported clearly; file rejected.
+- [ ] Registry entries sortable by timestamp for version ordering.
+
+**Performance**
+
+- [ ] Documented sample size and measured download/verify times (e.g., Berlin ~93 MB).
+- [ ] Documented checksum-only verification time (`.md5` fetch, no full PBF download).
+- [ ] CU benchmarks for single and batch registry operations on LEZ devnet/testnet.
+
+**Supportability**
+
+- [ ] OSM registry LEZ program deployed and tested on LEZ devnet/testnet.
+- [ ] CI green; integration tests cover host → verify → query → download against a LEZ sequencer in standalone mode.
+- [ ] README with program addresses, app usage, registry queries, region list, troubleshooting.
+- [ ] Reproducible demo script against a local LEZ sequencer with `RISC0_DEV_MODE=0`.
+- [ ] Narrated video demo with terminal output including proof generation (`RISC0_DEV_MODE=0`).
+
+**Submission (technical)**
+
+- [ ] Public MIT/Apache-2.0 repo with app, OSM registry LEZ program, module, and CI tests.
+- [ ] FURPS self-assessment; GitHub issues for Logos technology problems filed where applicable.
+
+**In scope (technical)**
+
+- Geofabrik index integration; PBF storage in Logos Storage; OSM registry LEZ program; Basecamp UI for bulk host/download; extracted registry module; Geofabrik as canonical checksum source only.
+
+**Out of scope (technical)**
+
+- Tile servers, map rendering, live OSM sync, geocoding/routing/navigation, custom regions outside [A.4](#a4-predefined-regions), hosted relay/backend beyond Logos stack + Geofabrik canonical source.
+
+### A.1 Architecture
+
+```
+                    Geofabrik (central source)
+                          │
+          ┌───────────────┼───────────────┐
+          │               │               │
+    PBF file        .md5 checksum    JSON index
+          │               │               │
+          ▼               ▼               ▼
+    ┌─────────────────────────────────────────┐
+    │         User (Basecamp app)             │
+    │  - Host: fetch → store → register       │
+    │  - Verify: fetch .md5 → compare hash    │
+    │  - Download: from Storage or central    │
+    └─────────────────────────────────────────┘
+                          │
+         ┌────────────────┼────────────────┐
+         │                │                │
+         ▼                ▼                ▼
+   Logos Storage    OSM registry     Geofabrik
+   (PBF by CID)    LEZ program       Index API
+```
+
+### A.2 Registry schema (LEZ program account)
+
+```json
+{
+  "region": "berlin",
+  "cid": "Qm...",
+  "source_url": "https://download.geofabrik.de/europe/germany/berlin-latest.osm.pbf",
+  "checksum": "md5:6485e3b66007593f36574c2bbb51c24f",
+  "version": "2026-05-27",
+  "hosted": true,
+  "timestamp": "2026-05-28T12:00:00Z"
+}
+```
+
+### A.3 Checksum verification flow
+
+1. Registry entry contains: `source_url` + `checksum`.
+2. User downloads file (from Logos Storage or Geofabrik).
+3. Compute hash of downloaded file.
+4. Fetch `<source_url>.md5` from Geofabrik.
+5. Compare:
+
+```
+✅ MATCH    → file is authentic (matches Geofabrik)
+❌ MISMATCH → file rejected (spoofed or corrupted)
+```
+
+This blocks spoofing: an attacker cannot produce a file matching Geofabrik's published checksum without control of Geofabrik's servers.
+
+### A.4 Predefined regions
+
+Closed set from Geofabrik (~55 regions):
+
+**Europe:** Germany, France, UK, Italy, Spain, Poland, Netherlands, Belgium, Switzerland, Austria, Czech Republic, Sweden, Norway, Denmark, Finland, Portugal, Greece, Ireland, Hungary, Romania, Bulgaria, Ukraine, Belarus, Russia, Turkey
+
+**North America:** USA, Canada, Mexico, California, Texas, New York, Florida, Ontario, Québec
+
+**Asia:** Japan, China, India, South Korea, Indonesia, Thailand, Vietnam, Malaysia, Philippines, Australia
+
+**South America:** Brazil, Argentina, Colombia, Peru, Chile
+
+**Africa:** South Africa, Egypt, Nigeria, Kenya, Morocco
+
+### A.5 Third-party app compatibility
+
+PBF files produced by this system are identical to Geofabrik downloads. Compatible apps include:
+
+- **OsmAnd**: import via OsmAndMapCreator (PBF → OBF).
+- **Organic Maps**: import via built-in tools (PBF → `.mwm`).
+- **Others**: most GIS tools accept PBF directly.
+
+The Basecamp app serves as a download manager; map rendering and navigation happen in third-party apps.