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.
This NIP describes how UPlanet integrates Nostr identities with IPFS storage, building upon the geographic key derivation.
UPassport services (54321.py) leverage Nostr for user authentication for privileged operations such as file uploads, deletions, and synchronization. This is achieved by:
- Client-side Authentication Event: When a user attempts a privileged action, their UPlanet web interface (or client) interacts with a Nostr extension (NIP-07) or directly with their
nsecto sign an event ofkind: 22242(NIP-42: Authentication). This event asserts the user's public key (pubkey) and typically includes arelaytag indicating the relay it was sent to, and achallengetag. - Server-side Verification: The UPlanet UPassport backend (
54321.py) connects to a local Nostr relay (e.g.,ws://127.0.0.1:7777). Upon receiving an authenticated request from a user (npub), the backend queries the relay for recent (e.g., last 24 hours)kind: 22242events authored by thatnpub. If a valid, recent event is found, the user's identity is authenticated. This mechanism ensures the user is indeed the owner of thenpubwithout the server ever holding the private key.
UPlanet's core innovation lies in its "Twin-Key" mechanism, which inextricably links a user's Nostr identity to their personal IPFS drive and other digital assets (G1, Bitcoin keys, as described in Specification 1: GeoKey Derivation).
- Deterministic Drive Association: Each UPlanet user is associated with a unique IPFS drive located in their home directory (e.g.,
~/.zen/game/nostr/<user_email>/APP). Themanifest.jsonfile within this drive explicitly records theowner_hex_pubkey. - Ownership Enforcement:
- When a user attempts to modify their IPFS drive (uploading, deleting files), the UPlanet backend verifies that their authenticated Nostr
npub(converted tohex_pubkey) matches theowner_hex_pubkeydeclared in the target drive'smanifest.json. - If the
npubmatches, the operation proceeds, and the IPFS drive is regenerated, yielding a new CID. - If the
npubdoes not match (i.e., it's a "foreign drive"), write operations are strictly disallowed. However, users can "sync" files from a foreign drive to their own authenticated drive, effectively copying public content.
- When a user attempts to modify their IPFS drive (uploading, deleting files), the UPlanet backend verifies that their authenticated Nostr
- Structured IPFS Content: Unlike general blob storage, UPlanet organizes files into a hierarchical structure within the IPFS drive (
Images/,Music/,Videos/,Documents/), and generates a human-readable web interface (_index.html) for exploration. This provides a user-friendly "drive" experience rather than just raw blob access.
While sharing the fundamental use of Nostr for authentication, UPlanet differentiates itself from more generic Nostr-based blob storage specifications like Blossom (BUDs) in its scope and approach:
- Blossom: Focuses on a low-level HTTP API for storing and retrieving arbitrary "blobs" addressed by SHA256 hashes on media servers. It is a fundamental building block for content distribution on Nostr.
- UPlanet: Operates at a higher application layer. It is a structured "Personal IPFS Drive" system that uses IPFS for storage and uses Nostr for identity and authentication. Its "Twin-Key" mechanism (NIP-101 GeoKeys and other associated keys) provides a holistic, unified identity across geographic data, IPFS content, and potential other blockchain assets. It provides a complete user experience with a pre-built web interface and specific features like incremental updates and structured content organization.
UPlanet leverages a dedicated strfry Nostr relay, configured with custom write policies to integrate seamlessly with the UPlanet ecosystem, enabling authenticated actions and AI-driven responses.
The install_strfry.sh script automates the setup of the strfry Nostr relay:
- Dependency Installation: It ensures all necessary system dependencies (e.g.,
git,g++,make,libssl-dev,liblmdb-dev) are installed on Debian/Ubuntu-based systems. - Source Management: The script clones the
strfryrepository from GitHub into~/.zen/workspace/strfryor updates it if already present. - Compilation: It compiles
strfryfrom source, ensuring the latest features and optimizations. - Installation: The compiled
strfrybinary and its defaultstrfry.confare copied to~/.zen/strfry/, with the configuration adapted for broader network access (bind = "0.0.0.0"). This setup allowsstrfryto be a local relay dedicated to the UPlanet instance.
After strfry is compiled, the setup.sh script configures the strfry relay and prepares it for Systemd management:
- Configuration Generation: It dynamically generates the
strfry.conffile in~/.zen/strfry/strfry.confbased on variables from the UPlanet environment (e.g.,UPLANETG1PUB,IPFSNODEID,CAPTAINHEX,CAPTAINEMAIL). - Relay Information: The
strfry.confincludes NIP-11 metadata such as the relay'sname(e.g., "♥️ BOXIPFSNODEID"),description(highlighting its role in UPlanet),pubkey(the UPlanet Captain's public key for administration), and aniconURL. - Write Policy Plugin: Crucially, it sets the
writePolicy.pluginparameter instrfry.confto point to"$HOME/.zen/workspace/NIP-101/relay.writePolicy.plugin/all_but_blacklist.sh". This delegates the event acceptance/rejection logic to a custom script, enabling UPlanet's specific filtering rules.
UPlanet's relay implements several layers of filtering to manage events and trigger AI responses:
-
relay.writePolicy.plugin/all_but_blacklist.sh(Main Write Policy):- This is the primary script executed by
strfryfor every incoming event. - Its core function is to implement a "whitelist by default, with blacklist exceptions" policy: it accepts all events unless the
pubkeyof the event's author is found in~/.zen/strfry/blacklist.txt. - For
kind 1(text) events, it dynamically callsfilter/1.shto apply more specific UPlanet-related logic. - Events from blacklisted public keys are immediately rejected.
- This is the primary script executed by
-
relay.writePolicy.plugin/filter/1.sh(Kind 1 Event Filter):- This script specifically handles
kind 1Nostr events, which are primarily text notes. - Visitor Management: For
pubkeys not registered as UPlanet "players," it implements a "Hello NOSTR visitor" mechanism. New visitors receive a warning message from the UPlanet Captain's key, explaining the system and limiting the number of messages they can send before being blacklisted. This encourages users to join the UPlanet Web of Trust. - Memory Management: It uses
short_memory.pyto store conversation history for Nostr players, allowing the AI to maintain context. - AI Triggering: It acts as an orchestrator for the
UPlanet_IA_Responder.shscript. If theUPlanet_IA_Responder.shis already running, it queues incoming messages (especially those with#BROor#BOTtags) to prevent overwhelming the AI. If the AI is not active, it directly invokesUPlanet_IA_Responder.shwith a timeout.
- This script specifically handles
-
Astroport.ONE/IA/UPlanet_IA_Responder.sh(AI Backend):- This is the core AI logic script, responsible for generating responses based on incoming
kind 1messages, typically triggered byfilter/1.sh. - Tag-Based Actions: It parses specific hashtags within the message content to trigger various AI functionalities:
#search: Integrates with a search engine (e.g., Perplexica) to retrieve information.#image: Commands an image generation AI (e.g., ComfyUI) to create images based on the prompt.#video: Utilizes text-to-video models (e.g., ComfyUI) to generate short video clips.#music: Triggers music generation.#youtube: Downloads YouTube videos (or extracts audio with#mp3tag) viaprocess_youtube.sh.#pierre/#amelie: Converts text to speech using specific voice models (e.g., Orpheus TTS).#mem: Displays the current conversati 8000 on history.#reset: Clears the user's conversation memory.
- Ollama Integration: For general questions without specific tags, it uses Ollama with a context-aware
question.pyscript to generate conversational AI responses, leveraging the stored memory. - Response Publishing: AI-generated responses are signed by the UPlanet Captain's key (or the
KNAME's key if specified and available) and published back to the Nostr relay askind 1events, specifically tagging the original event and public key to maintain thread context (eandptags).
- This is the core AI logic script, responsible for generating responses based on incoming
This integrated system allows UPlanet to provide a dynamic, interactive experience where user actions and queries on Nostr can trigger complex AI operations and content generation, all while maintaining the integrity and ownership model of the IPFS drives.
A Nostr keypair (secp256k1) is deterministically derived from a seed string. The seed is constructed by concatenating:
UPLANETNAME: A secret string identifying the application and used as~/.ipfs/swarm.keyand creates the private IPFS swarm dedicated to UPlanet Application.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: "{UPLANETNAME}_{FORMATTED_LATITUDE}" "{UPLANETNAME}_{FORMATTED_LONGITUDE}" used as libsodium salt & pepper
Key Generation: Implement the deterministic key generation logic specified (access to the keygen tool code).
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 used in IA_UPlanet.sh is "Astroport" tool, providing deterministic method for deriving a secp256k1 keypair from a unique seed string (and other twin keys: IPFS, G1, Bitcoin). The chosen method IS consistent across the UPlanet ecosystem.
Events related to UPlanet locations SHOULD include the following tags:
- Latitude Tag:
["latitude", "FLOAT_STRING"]- Value: The latitude as a string, optionnaly with higher precision (e.g., 6+ decimal places) than the GeoKey grid level. Example:
"48.8534"
- Value: The latitude as a string, optionnaly 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, optionnaly with higher precision. Example:
"-2.3412"
- Value: The longitude as a string, optionnaly with higher precision. Example:
- Application Tag:
["application", "UPlanet*"]- Value: Identifies the event as belonging to the UPlanet system. Allows differentiation (e.g.,
UPlanet_AppName).
- 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 ahve a default a location recorded with their personal key provided during Astroport registration. This location is used when geo data is found in event.
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.
- 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.
- 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
UPLANETNAMEstring is important. If compromised or changed, it could disrupt the system or lead to impersonation of locations. - Key Management: Managing potentially 654 Millions GeoKey
nsecs, Astroport storage can choose the closest node.
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