From fce8d360f5f527cd219243130916a6d1a7088298 Mon Sep 17 00:00:00 2001 From: mart1n <20109376+mart1n-xyz@users.noreply.github.com> Date: Thu, 28 May 2026 13:23:25 +0200 Subject: [PATCH 1/4] Add LP-0018 draft: OpenStreetMap decentralized map data distribution. Restates success criteria in the appendix alongside technical design so builders and evaluators have a single combined specification. Co-authored-by: Cursor --- README.md | 1 + prizes/LP-0018.md | 263 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 264 insertions(+) create mode 100644 prizes/LP-0018.md diff --git a/README.md b/README.md index 39f9913..6349ca6 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-0018](prizes/LP-0018.md) | OpenStreetMap integration: decentralized map data distribution | Medium | Draft | ### Proposing a New Prize diff --git a/prizes/LP-0018.md b/prizes/LP-0018.md new file mode 100644 index 0000000..b8a4e5e --- /dev/null +++ b/prizes/LP-0018.md @@ -0,0 +1,263 @@ +--- +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) +- Logos Blockchain module (for Zone SDK inscriptions — registry) + +These may connect to an external Logos node until built-in modules are 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 Zone SDK. +- [ ] **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. +- [ ] **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 the OSM registry module as a library/SDK with a README covering its API and integration steps. +- [ ] 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). + +### Supportability + +- [ ] The system is deployed and functional on Logos testnet/development environment. +- [ ] End-to-end integration tests covering host → verify → query → download are included in CI. +- [ ] CI is green on the default branch. +- [ ] A README documents: build steps, usage instructions, region list, and troubleshooting. +- [ ] A reproducible demo script works against a local Logos environment. +- [ ] A recorded video demo of the end-to-end flow is included in the submission. + +## 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. +- Zone SDK on-chain registry. +- Basecamp UI with bulk host/download. +- OSM registry module extracted from the app, with documented API. + +### 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)). + +## 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: + - Basecamp app source with build instructions, + - OSM registry module/SDK with API documentation, + - integration tests runnable in CI. +- 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)): + - hosting a region (fetch from Geofabrik → store → register), + - verifying checksum from the app, + - downloading and verifying a hosted region. +- 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/) +- [LP-0017](LP-0017.md) — Whistleblower (reference implementation for storage + registry 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 → Zone SDK on-chain 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. +- [ ] Standalone OSM registry module/SDK with documented API. + +**Usability** + +- [ ] Logos Basecamp app with build instructions and loadable assets. +- [ ] Registry module README with API and integration steps. +- [ ] 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). + +**Supportability** + +- [ ] Deployed and working on Logos testnet/development environment. +- [ ] CI green; integration tests cover host → verify → query → download. +- [ ] README, reproducible demo script, and recorded end-to-end video demo. + +**In scope (technical)** + +- Geofabrik index integration; PBF storage in Logos Storage; Zone SDK registry; Basecamp UI for bulk host/download; extracted registry module. + +**Out of scope (technical)** + +- Tile servers, map rendering, live OSM sync, geocoding/routing/navigation, custom regions outside [A.4](#a4-predefined-regions). + +### 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 Zone SDK Geofabrik + (PBF by CID) (inscriptions) Index API +``` + +### A.2 Registry schema (Zone SDK inscription) + +```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 `.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. From d96975e27f2b777ce4ae6607997e7bfec15abae2 Mon Sep 17 00:00:00 2001 From: mart1n <20109376+mart1n-xyz@users.noreply.github.com> Date: Thu, 28 May 2026 13:30:07 +0200 Subject: [PATCH 2/4] Align LP-0018 draft with template and live Basecamp prize conventions. Mirror LP-0017 registry, supportability, submission, and usability patterns; expand appendix checklist to match updated criteria. Co-authored-by: Cursor --- prizes/LP-0018.md | 63 ++++++++++++++++++++++++++++++++++++----------- 1 file changed, 48 insertions(+), 15 deletions(-) diff --git a/prizes/LP-0018.md b/prizes/LP-0018.md index b8a4e5e..de768b9 100644 --- a/prizes/LP-0018.md +++ b/prizes/LP-0018.md @@ -1,3 +1,5 @@ + + --- dependencies: [] --- @@ -38,12 +40,17 @@ This prize complements existing Logos sample apps (notably [LP-0017](LP-0017.md) - [ ] **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**: the submitter chooses the anchoring approach — either (a) a LEZ program or (b) a direct submission to the consensus layer via the Zone SDK — and provides a brief justification for the choice. Note that decentralised sequencers for zones are not yet shipped: the Zone SDK approach requires a single designated actor to perform consensus inscription, which affects the trust model. The registry must: + - store per-region entries with at minimum: `region`, `cid`, `source_url`, `checksum`, `version`, `hosted`, and `timestamp` (see [Appendix A.2](#a2-registry-schema-zone-sdk-inscription)), + - be queryable by region and by CID, + - support 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 the OSM registry module as a library/SDK with a README covering its API and integration steps. +- [ ] Provide a module/SDK that can be used to build Logos modules for interacting with the OSM registry. +- [ ] Provide an IDL for the LEZ program (if the LEZ program approach is chosen), using the [SPEL framework](https://github.com/logos-co/spel). - [ ] Clear UX: show hosted/not-hosted status, version numbers, and verification results. ### Reliability @@ -56,15 +63,16 @@ This prize complements existing Logos sample apps (notably [LP-0017](LP-0017.md) - [ ] 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 (if the LEZ program approach is chosen). Note: LEZ's per-transaction compute budget may change during testnet. ### Supportability -- [ ] The system is deployed and functional on Logos testnet/development environment. -- [ ] End-to-end integration tests covering host → verify → query → download are included in CI. +- [ ] The on-chain registry 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 (if the LEZ program approach is chosen) or against a local Logos environment with Storage and Blockchain modules connected, and are included in CI. - [ ] CI is green on the default branch. -- [ ] A README documents: build steps, usage instructions, region list, and troubleshooting. -- [ ] A reproducible demo script works against a local Logos environment. -- [ ] A recorded video demo of the end-to-end flow is included in the submission. +- [ ] A README covers: build steps, deployment or inscription configuration, 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` (LEZ program path) or a local Logos environment with Storage and Blockchain modules connected (Zone SDK path). +- [ ] A recorded video demo of the end-to-end flow is included in the submission; the recording must show terminal output to confirm the demo ran against the claimed environment. If the LEZ program approach is chosen, the recording must also show proof-generation output to confirm `RISC0_DEV_MODE=0` was active. ## Scope @@ -74,9 +82,12 @@ This prize complements existing Logos sample apps (notably [LP-0017](LP-0017.md) - Host workflow (fetch + store + register). - Download from Logos Storage or Geofabrik central source. - Verification against Geofabrik checksums. -- Zone SDK on-chain registry. +- On-chain OSM registry: LEZ program or Zone SDK (submitter chooses and justifies). - 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 @@ -84,6 +95,7 @@ This prize complements existing Logos sample apps (notably [LP-0017](LP-0017.md) - 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 @@ -99,14 +111,22 @@ Open to any individual or team. Submissions must be original work. Teams must ho ## Submission Requirements - Public repository (MIT or Apache-2.0) containing: - - Basecamp app source with build instructions, - - OSM registry module/SDK with API documentation, + - the OSM Basecamp app, + - the OSM registry module with API documentation, + - the on-chain registry program or Zone SDK integration, - integration tests runnable in CI. +- Deployed registry on LEZ devnet/testnet with documented program address or Zone SDK inscription configuration. - 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. + - 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 (if the LEZ program approach is chosen). +- 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 @@ -127,7 +147,10 @@ The following policies apply to all prizes (see [evaluation policies](../README. - [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 @@ -152,12 +175,14 @@ The items below mirror the main-body success criteria and scope. A submission mu - [ ] 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. +- [ ] On-chain registry (LEZ program or Zone SDK): stores schema fields from [A.2](#a2-registry-schema-zone-sdk-inscription); queryable by region and CID; supports batch registration; submitter documents approach and trust model. - [ ] Standalone OSM registry module/SDK with documented API. **Usability** - [ ] Logos Basecamp app with build instructions and loadable assets. -- [ ] Registry module README with API and integration steps. +- [ ] Module/SDK for building Logos modules that interact with the OSM registry. +- [ ] IDL for LEZ program if that approach is chosen (SPEL). - [ ] UI shows hosted/not-hosted status, versions, and verification outcomes. **Reliability** @@ -170,20 +195,28 @@ The items below mirror the main-body success criteria and scope. A submission mu - [ ] 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 (LEZ program path). **Supportability** -- [ ] Deployed and working on Logos testnet/development environment. +- [ ] Registry deployed and tested on LEZ devnet/testnet. - [ ] CI green; integration tests cover host → verify → query → download. -- [ ] README, reproducible demo script, and recorded end-to-end video demo. +- [ ] README with deployment/inscription config, app usage, registry queries, region list, troubleshooting. +- [ ] Reproducible demo script (LEZ sequencer with `RISC0_DEV_MODE=0` or local Logos environment with Storage + Blockchain modules). +- [ ] Narrated video demo with terminal output; RISC0 proof output if LEZ program path. + +**Submission (technical)** + +- [ ] Public MIT/Apache-2.0 repo with app, module, registry integration, 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; Zone SDK registry; Basecamp UI for bulk host/download; extracted registry module. +- Geofabrik index integration; PBF storage in Logos Storage; LEZ program or Zone SDK registry; 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). +- 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 From 7ef7104ff3fe5d3c4d582f48c95818fcdd33b0c5 Mon Sep 17 00:00:00 2001 From: mart1n <20109376+mart1n-xyz@users.noreply.github.com> Date: Thu, 28 May 2026 13:39:41 +0200 Subject: [PATCH 3/4] Require LEZ program for OSM registry instead of Zone SDK. Aligns LP-0018 with standard on-chain prize patterns: mandatory LEZ deployment, SPEL IDL, sequencer tests, and RISC0 demo requirements. Co-authored-by: Cursor --- prizes/LP-0018.md | 66 +++++++++++++++++++++++------------------------ 1 file changed, 32 insertions(+), 34 deletions(-) diff --git a/prizes/LP-0018.md b/prizes/LP-0018.md index de768b9..e48430a 100644 --- a/prizes/LP-0018.md +++ b/prizes/LP-0018.md @@ -1,5 +1,3 @@ - - --- dependencies: [] --- @@ -17,9 +15,9 @@ The deliverable has two required parts: a **Logos Basecamp app** (region discove **Requires:** - Logos Storage module (for storing PBF files) -- Logos Blockchain module (for Zone SDK inscriptions — registry) +- LEZ (Logos Execution Zone) program for the on-chain OSM registry -These may connect to an external Logos node until built-in modules are available. +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. @@ -34,23 +32,23 @@ This prize complements existing Logos sample apps (notably [LP-0017](LP-0017.md) ### 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 Zone SDK. +- [ ] **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**: the submitter chooses the anchoring approach — either (a) a LEZ program or (b) a direct submission to the consensus layer via the Zone SDK — and provides a brief justification for the choice. Note that decentralised sequencers for zones are not yet shipped: the Zone SDK approach requires a single designated actor to perform consensus inscription, which affects the trust model. The registry must: - - store per-region entries with at minimum: `region`, `cid`, `source_url`, `checksum`, `version`, `hosted`, and `timestamp` (see [Appendix A.2](#a2-registry-schema-zone-sdk-inscription)), - - be queryable by region and by CID, - - support registering multiple regions in a single batch transaction when bulk hosting. +- [ ] **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 LEZ program (if the LEZ program approach is chosen), using the [SPEL framework](https://github.com/logos-co/spel). +- [ ] 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 @@ -63,16 +61,16 @@ This prize complements existing Logos sample apps (notably [LP-0017](LP-0017.md) - [ ] 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 (if the LEZ program approach is chosen). Note: LEZ's per-transaction compute budget may change during testnet. +- [ ] 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 on-chain registry 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 (if the LEZ program approach is chosen) or against a local Logos environment with Storage and Blockchain modules connected, and are included in CI. +- [ ] 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, deployment or inscription configuration, 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` (LEZ program path) or a local Logos environment with Storage and Blockchain modules connected (Zone SDK path). -- [ ] A recorded video demo of the end-to-end flow is included in the submission; the recording must show terminal output to confirm the demo ran against the claimed environment. If the LEZ program approach is chosen, the recording must also show proof-generation output to confirm `RISC0_DEV_MODE=0` was active. +- [ ] 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 @@ -82,7 +80,7 @@ This prize complements existing Logos sample apps (notably [LP-0017](LP-0017.md) - Host workflow (fetch + store + register). - Download from Logos Storage or Geofabrik central source. - Verification against Geofabrik checksums. -- On-chain OSM registry: LEZ program or Zone SDK (submitter chooses and justifies). +- 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. @@ -113,9 +111,9 @@ Open to any individual or team. Submissions must be original work. Teams must ho - Public repository (MIT or Apache-2.0) containing: - the OSM Basecamp app, - the OSM registry module with API documentation, - - the on-chain registry program or Zone SDK integration, + - the OSM registry LEZ program, - integration tests runnable in CI. -- Deployed registry on LEZ devnet/testnet with documented program address or Zone SDK inscription configuration. +- 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), @@ -125,7 +123,7 @@ Open to any individual or team. Submissions must be original work. Teams must ho - 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 (if the LEZ program approach is chosen). +- 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)). @@ -169,20 +167,20 @@ The items below mirror the main-body success criteria and scope. A submission mu **Functionality** - [ ] Region discovery from Geofabrik JSON index with version info displayed per region. -- [ ] Host workflow: Geofabrik PBF download → Logos Storage upload → Zone SDK on-chain registration. +- [ ] 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. -- [ ] On-chain registry (LEZ program or Zone SDK): stores schema fields from [A.2](#a2-registry-schema-zone-sdk-inscription); queryable by region and CID; supports batch registration; submitter documents approach and trust model. +- [ ] 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 LEZ program if that approach is chosen (SPEL). +- [ ] IDL for OSM registry LEZ program (SPEL). - [ ] UI shows hosted/not-hosted status, versions, and verification outcomes. **Reliability** @@ -195,24 +193,24 @@ The items below mirror the main-body success criteria and scope. A submission mu - [ ] 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 (LEZ program path). +- [ ] CU benchmarks for single and batch registry operations on LEZ devnet/testnet. **Supportability** -- [ ] Registry deployed and tested on LEZ devnet/testnet. -- [ ] CI green; integration tests cover host → verify → query → download. -- [ ] README with deployment/inscription config, app usage, registry queries, region list, troubleshooting. -- [ ] Reproducible demo script (LEZ sequencer with `RISC0_DEV_MODE=0` or local Logos environment with Storage + Blockchain modules). -- [ ] Narrated video demo with terminal output; RISC0 proof output if LEZ program path. +- [ ] 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, module, registry integration, and CI tests. +- [ ] 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; LEZ program or Zone SDK registry; Basecamp UI for bulk host/download; extracted registry module; Geofabrik as canonical checksum source only. +- 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)** @@ -238,11 +236,11 @@ The items below mirror the main-body success criteria and scope. A submission mu ┌────────────────┼────────────────┐ │ │ │ ▼ ▼ ▼ - Logos Storage Zone SDK Geofabrik - (PBF by CID) (inscriptions) Index API + Logos Storage OSM registry Geofabrik + (PBF by CID) LEZ program Index API ``` -### A.2 Registry schema (Zone SDK inscription) +### A.2 Registry schema (LEZ program account) ```json { From 394dfd650c666a8ebe88bfbe9c6bc93c03a02e29 Mon Sep 17 00:00:00 2001 From: mart1n <20109376+mart1n-xyz@users.noreply.github.com> Date: Fri, 21 Aug 2026 11:22:28 +0200 Subject: [PATCH 4/4] Rework LP-0018 region model, add adoption criteria, freeze region set. Introduce a country/subregion region model with a non-overlap invariant and Geofabrik-path keys, add parent/level to the registry schema, and thread the model through success criteria, scope, and the appendix. Add an Adoption section with independently verifiable coverage, redundant mirroring, freshness, and sustained-activity criteria plus a testnet-reset contingency. Freeze the decomposed-country leaf ids (US, China, Russia; India already fixed) so the closed set is reconstructable from the document, and add a 25 verified-entry floor alongside the 15-country bar so coverage cannot be met by tiny single subregions. Reference LP-0020 (OSM Map Viewer) as the complementary usage layer. Co-authored-by: Cursor --- prizes/LP-0018.md | 105 +++++++++++++++++++++++++++++++++++++++------- 1 file changed, 90 insertions(+), 15 deletions(-) diff --git a/prizes/LP-0018.md b/prizes/LP-0018.md index e48430a..a0dbb0a 100644 --- a/prizes/LP-0018.md +++ b/prizes/LP-0018.md @@ -11,6 +11,8 @@ dependencies: [] 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. +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 [Appendix A.4](#a4-predefined-regions) for the region model and the closed set. + 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:** @@ -31,16 +33,17 @@ This prize complements existing Logos sample apps (notably [LP-0017](LP-0017.md) ### Functionality -- [ ] **Region discovery**: fetch the Geofabrik index and display available regions with version info. +- [ ] **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). - [ ] **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. +- [ ] **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 checksum → store → register. -- [ ] **Update check**: compare central versions vs registry and notify the user of available updates. +- [ ] **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`, `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, + - stores per-region entries with at minimum: `region`, `parent`, `level`, `cid`, `source_url`, `checksum`, `version`, `hosted`, and `timestamp` (see [Appendix A.2](#a2-registry-schema-lez-program-account)), + - 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. - [ ] **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. @@ -72,6 +75,36 @@ This prize complements existing Logos sample apps (notably [LP-0017](LP-0017.md) - [ ] 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. +## Adoption + +> These criteria measure traction attributable to a given submission for this prize: not that the system was built (that is FURPS, above), but that it is actually serving as a **decentralized distribution layer** with real, independently mirrored map data. +> +> The **Required** criteria below are all mandatory in addition to the FURPS criteria, and are written so that an evaluator can confirm each one directly from on-chain registry data and Geofabrik, without trusting the submitter. The **Discretionary signals** are considered in addition, per the evaluation policy that applies to all prizes (see [Terms & Conditions](../TERMS.md)); evaluators inspect account and commit histories, and volume that is clearly manufactured (fresh accounts, purchased engagement) does not count regardless of the headline number. + +**Required (independently verifiable):** + +- **Coverage.** At least **15 countries** from the predefined set (see [Appendix A.4](#a4-predefined-regions)) are covered on-chain 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. +- **Redundant mirroring.** Each **covered region entry** (a country-level region, or a registered subregion of a decomposed country) is registered by **at least 3 distinct accounts**, so no single operator is the sole source for any region. This is verifiable directly from registry entries. (The *count* of distinct accounts is objective; whether those accounts are genuinely independent operators is assessed under Discretionary signals below.) +- **Freshness.** At least **5** registered region entries have had their version advanced to a newer Geofabrik snapshot after initial registration, via the update-check flow. This is confirmable from on-chain version/timestamp history checked against Geofabrik, and demonstrates the mirrors are maintained rather than a one-time dump. +- **Sustained activity.** Registration and re-hosting activity is spread over **at least 2 months**, verifiable from on-chain timestamps. A single burst of registrations does not qualify, however large. + +**Discretionary signals (considered in addition, per Terms & Conditions):** + +- **Operator independence.** The accounts behind the mirror counts are genuinely independent hosts with real account history, not one team spinning up accounts to satisfy the redundancy bar. Evaluators inspect on-chain and account histories. +- **Ecosystem reuse.** At least a few independent applications or modules consume the OSM registry module/SDK to discover or fetch regions. Use of the SDK is confirmable by code inspection; whether the consuming projects are genuine and independent of the submitting team is discretionary. +- **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. + +**Testnet reset / chain data loss contingency:** + +This prize targets a live Logos testnet. Testnets may be reset, redeployed, or replaced by a newer version, and on-chain registry data (entries, versions, timestamps) may be lost in the process. The adoption criteria above are cumulative and time-windowed, so a reset can break them through no fault of the builder. If a testnet reset or data loss occurs during an active submission, the following applies: + +- **The prize continues.** A reset does not disqualify in-progress work or reset a builder's eligibility to submit. +- **All criteria are measured only on the current live chain.** Adoption is always evaluated against the testnet that is live at evaluation time. Data that existed only on a wiped chain does not count toward any criterion and will not be credited from off-chain records (explorer exports, screenshots, CI logs, or the builder's own claims): none of those are independently verifiable, which is the whole point of these criteria. A submission cannot qualify on the strength of a chain that no longer exists. +- **The adoption clock restarts at the reset.** The 2-month sustained-activity window is measured from the later of the builder's first registration on the current chain or the most recent testnet reset. A builder is never asked to show on-chain history spanning a reset, and equally cannot carry forward history from before one. In practice this means a reset restarts the sustained-activity window from zero on the new chain. +- **Re-hosting after a reset is expected.** Builders re-register and re-host coverage on the new chain. Because the underlying bytes are still verifiable against Geofabrik, re-establishing coverage is fast; but the sustained-activity and freshness windows genuinely begin again, since the on-chain evidence for them begins again. + +> **Note on usage/download metrics.** This prize deliberately does **not** set a download or retrieval count. Logos Storage is a peer-to-peer filesharing layer with no verifiable retrieval accounting, and its roadmap adds provider and downloader anonymity; a download count could only ever be a self-reported number that no third party can audit. Adoption is therefore measured by *verified, redundantly mirrored, maintained coverage* — what can be objectively confirmed — rather than by unverifiable retrieval figures. + ## Scope ### In Scope @@ -92,7 +125,7 @@ Geofabrik is the **canonical source of truth** for snapshot bytes and MD5 checks - 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)). +- Custom regions or arbitrary levels outside the predefined partition (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 @@ -154,6 +187,8 @@ The following policies apply to all prizes (see [evaluation policies](../README. 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. +[LP-0020: OSM Map Viewer](https://github.com/logos-co/lambda-prize/pull/82) is a complementary prize expected to land shortly after this one. It consumes the PBF snapshots distributed here (from Logos Storage and the on-chain LEZ registry) to provide offline map rendering, search, and POI discovery, turning the distributed data into an end-user experience. LP-0018 delivers verified, decentralized distribution of the map data; LP-0020 delivers usage of that data. The two are designed to fit together, with LP-0020 depending on the registry and storage layer built here. + --- ## Appendix: Technical Design and Requirements @@ -166,14 +201,14 @@ The items below mirror the main-body success criteria and scope. A submission mu **Functionality** -- [ ] Region discovery from Geofabrik JSON index with version info displayed per region. +- [ ] Region discovery from Geofabrik JSON index with version info and region level (country / subregion) displayed per region, restricted to the predefined set. - [ ] 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. +- [ ] OSM registry LEZ program: stores schema fields from [A.2](#a2-registry-schema-lez-program-account) including `region` (Geofabrik path), `parent`, and `level`; queryable by region, parent, and CID; supports batch registration. - [ ] Standalone OSM registry module/SDK with documented API. **Usability** @@ -244,9 +279,11 @@ The items below mirror the main-body success criteria and scope. A submission mu ```json { - "region": "berlin", + "region": "us/california", + "parent": "us", + "level": "subregion", "cid": "Qm...", - "source_url": "https://download.geofabrik.de/europe/germany/berlin-latest.osm.pbf", + "source_url": "https://download.geofabrik.de/north-america/us/california-latest.osm.pbf", "checksum": "md5:6485e3b66007593f36574c2bbb51c24f", "version": "2026-05-27", "hosted": true, @@ -254,6 +291,13 @@ The items below mirror the main-body success criteria and scope. A submission mu } ``` +Field notes: + +- `region` is the region's Geofabrik path (for example `germany`, `germany/berlin`, `us/california`). It is the unique key for an entry and disambiguates a subregion from a same-named entity elsewhere in the tree. +- `parent` is the `region` path of the containing region, or `null`/empty for a top-level (continent-level country) entry. It lets the registry and evaluators reconstruct the tree and detect parent/child overlap. +- `level` is one of `country` (top-level national extract) or `subregion` (any Geofabrik subdivision of a country: zone, province, federal district, or state). Coverage and mirror counts are computed per entry; a country entry and a subregion entry that geographically overlap are distinct entries and must not both appear in the predefined set. +- `source_url`, `checksum`, and `version` are taken from Geofabrik for that exact region path, so verification stays a direct comparison against the canonical source at the same level. + ### A.3 Checksum verification flow 1. Registry entry contains: `source_url` + `checksum`. @@ -271,17 +315,48 @@ This blocks spoofing: an attacker cannot produce a file matching Geofabrik's pub ### A.4 Predefined regions -Closed set from Geofabrik (~55 regions): +#### A.4.1 Region model -**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 +Geofabrik is a tree. Every extract exists at a level, and a parent extract is the byte-for-byte union of its children: -**North America:** USA, Canada, Mexico, California, Texas, New York, Florida, Ontario, Québec +- `country` — a national extract, e.g. `germany`, `india`, `us`. +- `subregion` — any Geofabrik subdivision of a country (zone, province, federal district, or US state), e.g. `india/southern-zone`, `china/guangdong`, `russia/volga-fed-district`, `us/california`. +- Some countries have no subregions in Geofabrik and exist only at `country` level, e.g. `bangladesh`, `kenya`, `nigeria`. -**Asia:** Japan, China, India, South Korea, Indonesia, Thailand, Vietnam, Malaysia, Philippines, Australia +Each region is identified by its **Geofabrik path** (the `region` field), carries its `parent` path and `level`, and resolves to one `source_url` (`https://download.geofabrik.de/-latest.osm.pbf`) with a matching `.md5` checksum. + +**Non-overlap invariant.** No region in the predefined set is an ancestor or descendant of another region in the set. In practice this means: if a country is represented by any of its subregions, its country file is not in the set, and vice versa. This guarantees each piece of geography is hosted and counted at most once, so coverage and mirror counts in the adoption criteria are well defined and a submission cannot inflate coverage by registering a country plus its children. + +Partial coverage of a decomposed country is allowed: representing the United States by a chosen subset of high-demand state extracts (and not `us`) is valid; the states outside the subset are simply out of scope, not double-counted. What is not allowed is holding both a region and something it contains. + +A country is listed as **decomposed** (represented by subregions) when its country file is large enough that a single extract is impractical to mirror; otherwise it is listed at country level. The choice is fixed per country below so the set stays non-overlapping. + +#### A.4.2 Closed set + +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 +**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. + +> Rationale: the original flat list mixed `USA` with individual states (California / Texas / New York / Florida), double-counting those states' geography. Under the non-overlap rule the United States is represented by state extracts only, removing the overlap; the same rule decomposes India, China, and Russia, whose country files are too large to mirror as a single blob. ### A.5 Third-party app compatibility