immortal docs.

docs/immortal/code/config.md

@@ -0,0 +1,32 @@
+---
+sidebar_position: 2
+---
+
+# Config
+
+The Immortal relay has 2 type of configs:
+
+1. Local file config: this config comes from a yaml file which is dedicated for each immortal instance. [Example](https://github.com/dezh-tech/immortal/blob/main/config/config.yml).
+2. Global config (or parameters) : this comes from a [manager service](../managment/intro.md) and is same trough all immortal instances. [Example](https://github.com/dezh-tech/immortal/blob/main/config/parameters.go).
+
+
+## Local file config
+
+You can find an up to date version of this [file here](https://github.com/dezh-tech/immortal/blob/main/config/config.yml).
+
+This file generally contains the connection information to the redis and mongo db instances such as database names, timeouts and more. the connection secrets are kept in the environment variables.
+
+Also there is a section called `kraken` which is the information of a manager (default is [kraken](https://github.com/dezh-tech/kraken)) which the immortal instance will connects to it instantly after initializing the modules and receive the parameters from the manager.
+
+
+## Parameters
+
+The Parameters come from a manager and currently immortal don't support hot reload for this config as well as file config.
+
+The Parameters are a set of limitations and information that relay needs to perform. You can find the example [here](https://github.com/dezh-tech/immortal/blob/887ea62f9edeec7e51e71eeac3f967761c31b576/client/proto/kraken.proto#L80).
+
+
+### Notes
+
+There is more data shared between relay and manager such as white/black listed pubkeys. they are shared using a cuckoo filter on the redis instance.
+

docs/immortal/code/database.md

@@ -0,0 +1,19 @@
+---
+sidebar_position: 5
+---
+
+# Database
+
+The database used in immortal is mongo db since it supports json documents which is a proper way to store nostr events. Also, its easy to scale mongo db as well.
+
+Each nostr event kind has a different collection on mongo db database. This helps to keep events more organized, query based on kinds and have less event in each collection instead of keeping whole events in one place such as all short notes and reactions in the same collection which is inefficient.
+
+## Queries
+
+When immortal wants to query something from mongo db, its basically a filter. The immortal turns the normal filter and makes `n` mongo queries. `n` is the number of kind numbers in filter. it would attach the whole conditions of filter to each query and execute the queries. Currently queries are sent separately which is inefficient, we are working on it to support batch queries or increase the performance.
+
+> The special case is when someone requests a filter without kinds field, in this case immortal makes a request to some papular collections like reactions, short text notes, zaps and some more.
+
+## Deleting
+
+To delete some document for a NIP-09 request or Expiration or operator order from manager, we make ALL fields removed (not empty!) and we only keep the id of event. this helps us to prevent an deleted event be rewritten.

docs/immortal/code/intro.md

@@ -0,0 +1,7 @@
+---
+sidebar_position: 1
+---
+
+# Introduction
+
+This section will talk about the Immortal code base and how it perform important actions to prevent spams, have better performance and be configurable.

docs/immortal/code/sessions.md

@@ -0,0 +1,12 @@
+---
+sidebar_position: 4
+---
+
+# Sessions
+
+The Immortal keeps a set of information with each websocket connection called client session.
+
+
+## NIP-42 Information
+
+The first information is `pubkey` which is a string of user pubkey in hex format and `isKnown` which is a boolean showing wether this session is passed the NIP-42 process. If `isKnown` was false, it means pubkey is empty.

docs/immortal/code/spam-protection.md

@@ -0,0 +1,18 @@
+---
+sidebar_position: 3
+---
+
+# Spam Protection
+
+Since the Nostr is an open system and there is no need to provide any information for users, there is a high chance to get spammed. 
+
+Immortal performs different actions and validations to prevent this kind of spam attacks.
+
+## Bloom Filter
+
+Immortal writes the ID of any successfully received events into a shared Redis bloom filter. When an immortal instance receives new event it checks the event ID existence on the shared bloom filter to prevent double processing of one event. 
+
+This bloom filter is persist.
+
+> If we don't do this check, the whole validation process will be done and event will be passed to databases layer and then we find out this is duplicated. using this check we make sure this event is new on the system.
+

docs/immortal/managment/apis.md

@@ -0,0 +1,150 @@
+---
+sidebar_position: 3
+---
+
+# Management APIs
+
+Here is a list of APIs between manager and immortals. All of these APIs are through [gRPC](https://grpc.io/) and [proto files](https://protobuf.dev/overview/).
+
+
+## Relay to Manager
+
+Here is a list of APIs which is provided by manager and relay calls them:
+
+###  registerService
+
+The relays call this endpoint to receive an ID (a unique id between all relays in the same system for manager to identify them). 
+
+Here is an example of register request:
+
+```proto
+// Request to register a service.
+message registerServiceRequest {
+  string port = 1;                        // Service grpc port.
+  uint32 heartbeat_duration_in_sec = 2;   // Heartbeat interval in seconds for calling Status endpoint of relay.
+  ServiceTypeEnum type = 3;               // Type of the service. (e.g., RELAY)
+  string region = 4;                      // Region of the service.
+}
+```
+
+Response example:
+
+```proto
+// Response after registering a service.
+message registerServiceResponse {
+  bool success = 1;                      // Indicates if registration was successful.
+  optional string message = 2;           // Optional message with additional information.
+  string token = 3;                      // Token assigned to the registered service.
+}
+```
+
+> Relay will send the id in the header of `x-identifier` in each request to manager. this helps the manager to know who is talking with and take different actions for same request but different relays.
+
+### getConfig
+
+Relays will call this endpoint to get the parameters config from manager which requires the `x-identifier` header as well.
+
+Request example:
+
+```proto
+// Empty request used for methods that do not require parameters.
+message EmptyRequest {}
+```
+
+Response example:
+
+```proto
+// Response containing configuration details.
+message getConfigResponse {
+  limitations limitations = 1;           // Configuration limitations.
+  string url = 2;                        // Relay public URL.
+}
+```
+
+Types used:
+
+```proto
+// Configuration limitations.
+message limitations {
+  int32 max_message_length = 1;          // Maximum allowed message length.
+  int32 max_subscriptions = 2;           // Maximum number of subscriptions allowed.
+  int32 max_filters = 3;                 // Maximum number of filters allowed.
+  int32 max_subid_length = 4;            // Maximum length of a subscription ID.
+  int32 min_pow_difficulty = 5;          // Minimum proof-of-work difficulty.
+  bool auth_required = 6;                // Indicates if authentication is required.
+  bool payment_required = 7;             // Indicates if payment is required.
+  bool restricted_writes = 8;            // Indicates if writes are restricted.
+  int32 max_event_tags = 9;              // Maximum number of event tags allowed.
+  int32 max_content_length = 10;         // Maximum length of content allowed.
+  int64 created_at_lower_limit = 11;     // Lower limit for creation timestamps.
+  int64 created_at_upper_limit = 12;     // Upper limit for creation timestamps.
+  uint32 default_query_limit = 13;       // Default of query limit.
+  uint32 max_query_limit = 14;           // Maximum of query limit.
+}
+
+
+// Types of services that can be registered.
+enum ServiceTypeEnum {
+  UNKNOWN = 0;                           // Unknown service type.
+  RELAY = 1;                             // Relay service type.
+}
+```
+
+
+### shutdown
+
+> TODO.
+
+### addLog
+
+> TODO.
+
+## Relay to Manager
+
+Here is a list of APIs provided by relays which would be called by managers:
+
+### Status
+
+This API will return the health status of the immortal instance beside status of services the relay use such as database and more.
+
+Request example:
+
+```proto
+message StatusRequest {}
+```
+
+Response example:
+
+```proto
+message StatusResponse {
+    repeated Service services = 1;
+    int64 uptime = 2;
+    string version = 3;
+}
+```
+
+Types used:
+
+```proto
+enum Status {
+    UNKNOWN = 0;
+    CONNECTED = 1;
+    DISCONNECTED = 2;
+}
+
+message Service {
+    string name = 1;
+    Status status = 2;
+    string message = 3;
+}
+```
+
+The manager can show the response in a monitoring system, make notifications, shutdown the relays with specific kind of issues and more.
+
+### SetConfig
+
+> TODO.
+
+### Shutdown
+
+> TODO.

docs/immortal/managment/intro.md

@@ -0,0 +1,11 @@
+---
+sidebar_position: 1
+---
+
+# Introduction
+
+One of the benefits of immortal relay for big services, clients and operators is that it can have multiple instances running at the same time with a load balancer in different servers, regions, providers and more. Which helps immortal to be scalable.
+
+For this purpose these instances would require a service which manages them, checks their health status, updates the global states and more. 
+
+This document will talk about hwo this manager works and uses the [Kraken](https://github.com/dezh-tech/kraken) as an example of manager implementation.

docs/immortal/managment/manager.md

@@ -0,0 +1,26 @@
+---
+sidebar_position: 2
+---
+
+# Manager
+
+This section contains the information about the manager rules and responsibilities. To findout how relays interact with manager and vice versa you can check the [APIs](./apis.md) section.
+
+## White/Black Listing
+
+The immortal implementation supports the white list and black list model to have the ability to be a paid relay or ban users based on the operator decision.
+
+The list won't be passed to relays using APIs; instead the manager writes this into a cuckoo filter on redis and relays read it there and they check events `pubkey` on these filters.
+
+## NIP-11
+
+Since immortal supports multi-instance model, we can't provide the NIP-11 on document on each relay. Instead of this the web server routes NIP-11 requests to manager and manager will return the document:
+
+Example nginx config:
+
+> TODO.
+
+## Reports
+
+The report events will be stored on different mongo db collection (see: [database](../code/database.md)). This database is shared between manager and relays. manager will read reports from this collection and list them for operator  to take actions on them.
+

docs/immortal/nips/NIP-86.md

@@ -0,0 +1,7 @@
+---
+sidebar_position: 5
+---
+
+# NIP-86
+
+The relay management is supported in immortal but this will happen trough a manager with gRPC APIs defined [here](../managment/intro.md).

docs/immortal/nips/intro.md

@@ -0,0 +1,7 @@
+---
+sidebar_position: 1
+---
+
+# Introduction
+
+Beside the list of supported list of NIPs on NIP-11 document, some of NIPs are implemented with different models in immortal. This section talks about these NIPs and their difference on immortal.

docs/immortal/nips/nip-09.md

@@ -0,0 +1,7 @@
+---
+sidebar_position: 2
+---
+
+# NIP-09
+
+The NIP-09 follows normal NIP-09 from NIPs repository and also supports filter tag requests from this document: https://github.com/nostr-protocol/nips/pull/1509.

docs/immortal/nips/nip-40.md

@@ -0,0 +1,7 @@
+---
+sidebar_position: 3
+---
+
+# NIP-40
+
+The expiration events with a `expiration` tag with a value of `"0"`  not stored on database and only broadcasted.

docs/immortal/nips/nip-56.md

@@ -0,0 +1,8 @@
+---
+sidebar_position: 4
+---
+
+# NIP-56
+
+Reports are supported on immortal but it won't be processed by relays code and relays only store and broadcast them. The manager will read the report events from database and list them for operator review. There is no support for trusted moderators at the moment.
+

docs/immortal/start.md

@@ -0,0 +1,5 @@
+---
+sidebar_position: 1
+---
+
+This section contains information and documents about [Immortal relay implementation](https://github.com/dezh-tech/immortal).