diff --git a/package.json b/package.json index 5e4c164..e10c16d 100644 --- a/package.json +++ b/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": { diff --git a/src/contracts/location-proof-protocol/locations/README.md b/src/contracts/location-proof-protocol/locations/README.md new file mode 100644 index 0000000..f26e46b --- /dev/null +++ b/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. diff --git a/src/contracts/location-proof-protocol/media/README.md b/src/contracts/location-proof-protocol/media/README.md new file mode 100644 index 0000000..e69de29 diff --git a/src/contracts/location-proof-protocol/recipes/CONTRIBUTING.md b/src/contracts/location-proof-protocol/recipes/CONTRIBUTING.md new file mode 100644 index 0000000..e69de29 diff --git a/src/contracts/location-proof-protocol/recipes/README.md b/src/contracts/location-proof-protocol/recipes/README.md new file mode 100644 index 0000000..e69de29 diff --git a/src/contracts/location-proof-protocol/recipes/sample-recipe/README.md b/src/contracts/location-proof-protocol/recipes/sample-recipe/README.md new file mode 100644 index 0000000..e69de29 diff --git a/src/contracts/location-proof-protocol/recipes/sample-recipe/SampleRecipe.sol b/src/contracts/location-proof-protocol/recipes/sample-recipe/SampleRecipe.sol new file mode 100644 index 0000000..e69de29 diff --git a/src/contracts/location-proof-protocol/recipes/sample-recipe/offchain-peripherals/sample-recipe.ts b/src/contracts/location-proof-protocol/recipes/sample-recipe/offchain-peripherals/sample-recipe.ts new file mode 100644 index 0000000..e69de29 diff --git a/src/contracts/location-proof-protocol/schema/README.md b/src/contracts/location-proof-protocol/schema/README.md new file mode 100644 index 0000000..f0877ad --- /dev/null +++ b/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. diff --git a/src/contracts/spatial-registry/README.md b/src/contracts/spatial-registry/README.md new file mode 100644 index 0000000..e69de29 diff --git a/src/contracts/RegistryFactory.sol b/src/contracts/spatial-registry/RegistryFactory.sol similarity index 100% rename from src/contracts/RegistryFactory.sol rename to src/contracts/spatial-registry/RegistryFactory.sol diff --git a/src/contracts/SpatialRegistry.sol b/src/contracts/spatial-registry/SpatialRegistry.sol similarity index 100% rename from src/contracts/SpatialRegistry.sol rename to src/contracts/spatial-registry/SpatialRegistry.sol diff --git a/src/contracts/Coordinates.sol b/src/contracts/utils/Coordinates.sol similarity index 100% rename from src/contracts/Coordinates.sol rename to src/contracts/utils/Coordinates.sol diff --git a/src/contracts/utils/README.md b/src/contracts/utils/README.md new file mode 100644 index 0000000..e69de29