Merge pull request #107 from AstralProtocol/design-repo-structure

Design repo structure

package.json

@@ -1,9 +1,9 @@
 {
-  "name": "AstralProtocol",
-  "description": "Create extendible, modular spatial assets registries in a smart contract environment.",
+  "name": "@AstralProtocol/astralprotocol",
+  "description": "Tools and infrastructure for onchain location-based apps.",
   "version": "1.0.0",
   "author": {
-    "name": "The Astral Protocol Team",
+    "name": "AstralProtocol",
     "url": "https://github.com/AstralProtocol"
   },
   "dependencies": {

src/contracts/location-proof-protocol/locations/README.md

@@ -0,0 +1,35 @@
+# Location Proof Protocol v0.1: `locationType`
+
+To ensure location proofs are as versatile as possible, we are giving users / developers the option of creating proofs that adhere to any
+location type.
+
+This requires creating a standardized set of categories for "location types" that include various ways of representing locations such as
+different coordinate systems, H3 strings, geohashes, and more. The purpose of this is to ensure interoperability and clarity in geospatial
+data management, while still offering flexibility for different proof types.
+
+Here is a v0.1 proposed categorization.
+
+### Categories of Location Types
+
+1. **Geographic Coordinates (Lat/Long)**
+   - **Decimal Degrees**: Standard longitude and latitude (e.g., `[-122.4194, 37.7749]`).
+   - **Degrees, Minutes, Seconds (DMS)**: Latitude and longitude in degrees, minutes, and seconds (e.g., `37°46'30" N, 122°25'10" W`).
+2. **Projected Coordinates**
+   - **Universal Transverse Mercator (UTM)**: Uses a series of zones for global coverage (e.g., `10S 551000 4182000`).
+   - **State Plane Coordinate System (SPCS)**: Used in the United States (e.g., `X: 2000000, Y: 500000` in a specific state plane zone).
+3. **Geohashes**
+   - **Geohash**: A hierarchical spatial data structure which subdivides space into buckets of grid shape (e.g., `9q8yyz`).
+4. **H3 Hexagons**
+   - **H3**: A hierarchical hexagonal grid system used for spatial indexing (e.g., `85283473fffffff`).
+5. **Plus Codes**
+   - **Open Location Code (OLC)**: Developed by Google, it's a code that represents an area anywhere on Earth (e.g., `7FG8V4VC+G7`).
+6. **Grid References**
+   - **Military Grid Reference System (MGRS)**: Used by NATO militaries for locating points on the Earth (e.g., `33TWN8382558454`).
+   - **British National Grid (OSGB)**: Used in Great Britain (e.g., `TQ 298828`).
+7. **Place Names / Addresses**
+   - **Postal Address**: Standard mailing address (e.g., `1600 Amphitheatre Parkway, Mountain View, CA`).
+   - **Named Locations**: Known place names (e.g., `Eiffel Tower`).
+8. **What3Words References**
+   - **W3W**: A geocoding system that encodes geographic coordinates into three dictionary words (e.g., ///filled.count.soap).
+
+Formal specification of the location types and how they are represented is in development, and will be documented here.

src/contracts/location-proof-protocol/schema/README.md

@@ -0,0 +1,25 @@
+# Location Proof Protocol: Core Data Model v0.1
+
+## Core Layer
+
+The core layer of the Location Proof Protocol includes a standard data model. v0.1 of the data model is described in this document. The
+current working schema is deployed on Ethereum Sepolia testnet, UID `0xd928da08c10180b639e31c5f46acf4ea011d88ec7ac44bd95f32385e2d66032b`
+([view on EASScan](https://sepolia.easscan.org/schema/view/0xd928da08c10180b639e31c5f46acf4ea011d88ec7ac44bd95f32385e2d66032b)).
+
+| Field                    | Description                                                                                                                                                                                             | Key              | Data Type  | Source                                                                                                           |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------------------------------- |
+| Identifier               | Unique ID for the location proof.                                                                                                                                                                       | `uid`            | `bytes32`  | EAS provides this                                                                                                |
+| Prover Address           | Address of the prover.                                                                                                                                                                                  | `from`           | `address`  | Sender address, as specified by EAS                                                                              |
+| Subject Identifier       | Unique ID for the subject/event.                                                                                                                                                                        | `subject`        | `address`  | EAS provides this, however future iterations may require IDs that are not Ethereum addresses (DIDs, for example) |
+| Timestamp                | Time the location proof was created.                                                                                                                                                                    | `timestamp`      | `uint256`  | EAS                                                                                                              |
+| Event Timestamp          | Time of the event referenced by the location proof.                                                                                                                                                     | `eventTimestamp` | `uint256`  | User input                                                                                                       |
+| Spatial Reference System | Coordinate system within which the object is positioned.                                                                                                                                                | `srs`            | `string`   | in v0.1, hard coded to "EPSG:4326"                                                                               |
+| Location Type            | A string defining how the location field is structured.                                                                                                                                                 | `locationType`   | `string`   | Depends on the `recipe` / strategy, or user input                                                                |
+| Location                 | The location of the object/event.                                                                                                                                                                       | `location`       | `bytes`    | Depends on the `recipe` / strategy, or user input                                                                |
+| Proof Recipe Identifier  | Indicates the proof recipe used.                                                                                                                                                                        | `recipeType`     | `string[]` | Defined from a set of registered recipes, to be stored in the @/recipes directory                                |
+| Proof Recipe Payload     | Encoded data specific to the proof recipe, which could include encrypted location data, a zero-knowledge proof, or references to other verification data.                                               | `recipePayload`  | `bytes[]`  | Specified in recipe definition                                                                                   |
+| Media Type               | A unique string referring to the media to be included in a `bytes` field, Media Data. This pattern is similar to OpenGraph Protocol’s `type` definition.                                                | `mediaType`      | `string[]` | Defined from a set of supported media types, to be stored in the @/media directory                               |
+| Media Data               | A `bytes` field allowing the attachment of arbitrary data to a location proof. This data is intended to be irrelevant to the location proof and not required/utilized in the proof recipe verification. | `mediaData`      | `bytes[]`  | Specified in media type definition                                                                               |
+| Memo                     | An arbitrary message                                                                                                                                                                                    | `memo`           | `string`   | User input                                                                                                       |
+
+Note that this design supports location proofs that include multiple recipe types / recipe payloads and media type / media data.