add basic protocol description as NIP-01

README.md

@@ -67,6 +67,10 @@ This is a prototype of the most simple open protocol that is able to create an o
 - Data will always be only "eventually consistent" (or sometimes not consistent at all)
 - ...
 
+## How does it work in practice
+
+See the [NIPs](nips) and specially [NIP-01](nips/01.md) for a reasonably-detailed explanation of the protocol spec (hint: it is very small and simple).
+
 ## License
 
 Public domain.

nips/01.md

@@ -0,0 +1,42 @@
+NIP-01
+======
+
+Basic protocol flow description.
+--------------------------------
+
+
+1. Each user has a keypair in the `secp256k1` curve;
+2. Users can publish `events` to any compatible relay by calling `POST /save_update` with `Content-Type: application/json` and a JSON object describing an event:
+
+    ```
+    {
+      id: <32-bytes sha256 of the the serialized event data, optional as will be recomputed by the relay>
+      pubkey: <33-bytes hex-encoded compressed public key of the event creator>,
+      created_at: <unix timestamp>,
+      kind: <integer>,
+      ref: <32-bytes hex of the id of another event, optional>,
+      content: <arbitrary string>,
+      sig: <ECDSA signature of the sha256 hash of the serialized event data, which is the same as the "id" field>,
+    }
+    ```
+3. (The serialization function is strict and standardized, see source code for now)
+4. Upon receiving a call like that, the relay MUST compute the `id`, check the signature over the `id` and store the event so it can serve it later to other clients.
+5. There are 3 kinds of messages a user can publish (for now, these things are extensible and will be extended):
+  - `0`: `set_metadata`: the `content` is set to a stringified JSON object `{name: <string>, about: <string>, picture: <url, string>}` describing the user who created the event. A relay may delete past `set_metadata` events once it gets a new one for the same pubkey.
+  - `1`: `text_note`: the `content` is set to the text content of a note, anything the user wants to say.
+  - `2`: `recommend_server`: the `content` is set to the URL (e.g., `https://somerelay.com`) of a relay the event creator wants to recommend to its followers.
+6. A relay MUST serve an SSE (Server-Sent Events) stream at the path `GET /listen_updates`. As querystring parameters it MUST expect `?session=<arbitrary id chosen by the client>` any number of `&key=<33-bytes hex-encoded pubkey>`.
+7. Immediately upon receiving that request the relay MUST return the recent past events from all the received authors with the event type `history`, then it SHOULD keep the connection open and return new events from these same keys as they are received with the event type `happening`. The format of the messages is just the same event object above, as JSON:
+
+    ```
+    type: history
+    data: {"id": "000...", "pubkey": ... etc.}
+    ```
+
+8. The relay MUST also expect the following calls:
+  - `POST /request_user?session=<session id>` with body `{"pubkey": ...}`
+    Upon receiving this, the relay MUST return in the same SSE stream previously opened identified by the given _session id_ recent past updates from the specified user, including a `set_metadata` event.
+  - `POST /request_note?session=<session id>` with body `{"id": ...}`
+    Same as above, but instead the relay returns the specified `text_note` and/or related notes it has (notes that reference it or notes that it references).
+9. That's it. Knowing that every relay supports this interface should be enough for a client to be written taking these things into account.
+10. New optional features can be implemented by clients and relays, and if they are good they can be included in the main protocol -- which should be written in a series of optional/mandatory NIPs (Nostr Improvement Proposal).

nips/README.md

@@ -0,0 +1,3 @@
+# NIPs
+
+NIPs stand for Nostr Implementation Possibilities. They exist to document what MUST, what SHOULD and what MAY be implemented by Nostr-compatible _relay_ and _client_ software.