draft optional
This NIP describes a method for generating Nostr keypairs deterministically based on geographic coordinates and a namespace, creating hierarchical "GeoKeys". It also specifies event tags used by the UPlanet application to associate notes with specific locations and grid levels.
UPlanet extends Nostr by enabling geographically localized communication. It achieves this through:
- Hierarchical GeoKeys: Nostr keypairs (
npub/nsec) are derived from a combination of a fixed namespace string (e.g., "UPlanetV1") and geographic coordinates formatted to specific precision levels (e.g., 0.01°, 0.1°, 1.0°). This creates distinct identities for different geographic grid cells. - Geographic Tags: Events published using these GeoKeys, or referencing a location, include specific tags (
latitude,longitude) to indicate the precise point of interest. - Application Tag: An
applicationtag identifies events specifically intended for or generated by the UPlanet system.
This allows users and applications to subscribe to messages relevant to specific geographic areas by knowing the corresponding GeoKey npub or by filtering events based on location tags within a certain radius.
- Localized Feeds: Create Nostr feeds relevant only to specific neighborhoods (UMAP), sectors (SECTOR), or regions (REGION).
- Geo-fencing: Allow applications to filter or react to events occurring within defined geographic boundaries.
- Mapping Integration: Provide a layer of Nostr events that can be easily displayed on maps.
- Decentralized Location-Based Services: Enable discovery and interaction based on proximity without relying on centralized servers.
- Application-Specific Context: The
applicationtag allows UPlanet messages to be distinguished from general Nostr traffic.
A Nostr keypair (secp256k1) is deterministically derived from a seed string. The seed is constructed by concatenating:
NAMESPACE: A constant string identifying the application and version context (e.g.,UPlanetV1). This prevents collisions with other systems or future versions.FORMATTED_LATITUDE: The latitude, formatted as a string to a specific number of decimal places corresponding to the desired grid level.FORMATTED_LONGITUDE: The longitude, formatted as a string to the same number of decimal places as the latitude, corresponding to the grid level.
Seed Format: "{NAMESPACE}{FORMATTED_LATITUDE}{FORMATTED_LONGITUDE}"
Grid Levels & Formatting:
UPlanet defines the following initial grid levels:
- UMAP (Micro-Area): 0.01° precision.
- Latitude/Longitude Formatting: String representation with exactly two decimal places (e.g.,
sprintf("%.2f", coordinate)in C, or equivalent). Coordinates should likely be truncated or rounded consistently before formatting. - Example Seed:
"UPlanetV148.85-2.34"(for Lat 48.853, Lon -2.341)
- Latitude/Longitude Formatting: String representation with exactly two decimal places (e.g.,
- SECTOR: 0.1° precision.
- Latitude/Longitude Formatting: String representation with exactly one decimal place.
- Example Seed:
"UPlanetV148.8-2.3"(for Lat 48.853, Lon -2.341)
- REGION: 1.0° precision.
- Latitude/Longitude Formatting: String representation with exactly zero decimal places (integer part).
- Example Seed:
"UPlanetV148-2"(for Lat 48.853, Lon -2.341)
Key Generation Algorithm:
The specific algorithm used by the keygen tool mentioned in IA_UPlanet.sh is not defined here, but any standard, deterministic method for deriving a secp256k1 keypair from a unique seed string MUST be used (e.g., using the seed as input to a KDF like HKDF with a fixed salt, or directly using a SHA256 hash of the seed as the private key, ensuring it falls within the valid secp256k1 range). The chosen method MUST be consistent across the UPlanet ecosystem.
Example (Conceptual):
nsec_hex = sha256("UPlanetV148.85-2.34") (Ensure result is valid private key)
pubkey = derive_pubkey(nsec_hex)
Events related to UPlanet locations SHOULD include the following tags:
- Latitude Tag:
["latitude", "FLOAT_STRING"]- Value: The latitude as a string, typically with higher precision (e.g., 6+ decimal places) than the GeoKey grid level. Example:
"48.8534"
- Value: The latitude as a string, typically with higher precision (e.g., 6+ decimal places) than the GeoKey grid level. Example:
- Longitude Tag:
["longitude", "FLOAT_STRING"]- Value: The longitude as a string, typically with higher precision. Example:
"-2.3412"
- Value: The longitude as a string, typically with higher precision. Example:
- Application Tag:
["application", "UPlanet"]or["application", "UPlanet_Component"]- Value: Identifies the event as belonging to the UPlanet system. Allows differentiation (e.g.,
UPlanet_AIResponder).
- Value: Identifies the event as belonging to the UPlanet system. Allows differentiation (e.g.,
Note: While GeoKeys provide identity for grid cells, the latitude and longitude tags specify the precise point of interest within or related to that cell. Events published from a UMAP GeoKey might contain tags pointing to a very specific coordinate within that 0.01°x0.01° cell.
- To post as a specific location grid cell (e.g., an automated bot reporting for a UMAP cell), derive the appropriate GeoKey
nsecusing the method in Specification 1 and publish a kind 1 event signed with it. The event SHOULD include thelatitude,longitude, andapplicationtags. - Regular users posting about a location SHOULD publish from their personal key but include the
latitude,longitude, andapplicationtags to make the event discoverable by UPlanet clients. They MAY also includeptags referencing the relevant GeoKeynpubs (UMAP, SECTOR, REGION) to notify those "location identities".
Clients can discover UPlanet content in several ways:
- Subscribe by GeoKey: Subscribe directly to the
npubof the desired UMAP, SECTOR, or REGION GeoKey(s). - Filter by Tags: Subscribe to
kind: 1events filtered by theapplicationtag (#a:["UPlanet"]) and optionally filter client-side based on thelatitudeandlongitudetags to find events within a specific geographic radius. - Filter by Geo-Reference: Subscribe to events that tag (
#p) specific GeoKeynpubs.
- Key Generation: Implement the deterministic key generation logic specified (or provide access to the
keygentool). Users might need to generate keys for areas they want to monitor or post from (if acting as a location). - Posting: When posting, determine the relevant coordinates. Include
latitude,longitude, andapplicationtags. Optionally derive and includeptags for relevant GeoKeys. If posting as a location, use the derived GeoKeynsecfor signing. - Receiving: Filter incoming events based on subscribed GeoKeys or tags. Display location information, potentially on a map. Parse
latitudeandlongitudetags for precise positioning. - Coordinate Formatting: Strictly adhere to the specified decimal places for each grid level when deriving keys. Use standard functions for formatting (e.g.,
sprintf("%.2f", coord)). Consistency in truncation or rounding is crucial.
Relays MAY implement indexing for the latitude, longitude, and application tags to support efficient filtering (REQ messages with #a, #latitude, #longitude filters), but this is optional. The core mechanism relies on clients knowing or deriving the GeoKey npubs or filtering standard tag queries.
- Local Chat: Alice posts from her phone using her personal key but tags the UMAP GeoKey
npubfor her current block and includeslatitude/longitudetags. Bob, subscribed to that UMAP GeoKey, sees her message. - Automated Weather Alert: An automated service derives the REGION GeoKey for Paris (
"UPlanetV1482"), signs a weather alert using that key'snsec, and includes preciselatitude/longitudetags for the storm's center. Users subscribed to the Paris REGION GeoKey receive the alert. - AI Responder: An AI service monitors messages tagged with
application: UPlanet. When it sees a message from a user (pubkey_A) tagged withlatitude/longitude, it derives the corresponding UMAP GeoKey (pubkey_UMAP), generates a response, signs it with the UMAP GeoKey'snsec, and includeseandptags referencing the original event (event_id) and the user (pubkey_A).
- Location Disclosure: Publishing with precise
latitude/longitudetags reveals location. Users must be aware of this. Using broader grid keys (SECTOR, REGION) for posting offers less precision. - Tracking: Consistent use of GeoKeys or tags could allow tracking of users' movements if they post frequently from different locations using their personal key with geo-tags.
- Namespace Security: Control over the
NAMESPACEstring is important. If compromised or changed, it could disrupt the system or lead to impersonation of locations. - Key Management: Managing potentially many GeoKey
nsecs (if acting as multiple locations) requires secure storage.
This NIP is compatible with existing Nostr concepts:
- Uses standard kind 1 events.
- Uses standard
eandptags for replies and user references (NIP-10). - Can be used alongside other NIPs defining content or tags.
- NIP-01: Basic protocol flow description
- NIP-10: Conventions for use of
eandptags in text events - (Implied): secp256k1, SHA256