# `Envelope` - Specifications
## 1. Autheurs, validations, dates, versions, changement and historique
Cf. [Git SDK COMMON](https://git.4nk.com/4nk/sdk_common/doc)
## 2. Table des matières
* 1. [Autheurs, validations, dates, versions, changement and historique](#Autheursvalidationsdatesversionschangementandhistorique)
* 2. [Table des matières](#Tabledesmatires)
* 3. [1. Objectif](#Objectif)
* 4. [2. Portée](#Porte)
* 5. [Documents de référence](#Documentsderfrence)
* 6. [4. Variable `PeerList` du SDK (Wasm)](#VariablePeerListduSDKWasm)
* 7. [6. Caractéristiques générales des `Envelope` et `EnvelopeConnect`](#CaractristiquesgnralesdesEnvelopeetEnvelopeConnect)
* 7.1. [6.1. PeerList](#PeerList)
* 7.2. [6.2. ProcessList](#ProcessList)
* 7.3. [6.3. Taille des données](#Tailledesdonnes)
* 7.4. [6.4. Preuve de travail](#Preuvedetravail)
* 7.5. [6.5. Adresse SP de faucet](#AdresseSPdefaucet)
* 7.6. [Objets `EnvelopeGeneric` contenu dans les types `Envelope` et `EnvelopeConnect`](#ObjetsEnvelopeGenericcontenudanslestypesEnvelopeetEnvelopeConnect)
* 8. [7. Traitements par les clients](#Traitementsparlesclients)
* 8.1. [7.1. Connexion d'un client à sa liste de relais via les `EnvelopeConnect`](#ConnexiondunclientsalistederelaisvialesEnvelopeConnect)
* 8.1.1. [7.1.1. Récupération et choix des relais](#Rcuprationetchoixdesrelais)
* 8.1.2. [7.1.2. Envoi de l'`EnvelopeConnect` à chaque relais](#EnvoidelEnvelopeConnectchaquerelais)
* 8.2. [7.2. Envoi de `Request` sur les relais via l'`Envelope`](#EnvoideRequestsurlesrelaisvialEnvelope)
* 8.3. [7.4. Traitement des `Envelope` par les clients](#TraitementdesEnvelopeparlesclients)
* 9. [8. Traitements par les relais](#Traitementsparlesrelais)
* 9.1. [8.1. Traitement des `EnvelopeConnect` par les relais](#TraitementdesEnvelopeConnectparlesrelais)
* 9.2. [8.2. Connexion au réseau de relais via `EnvelopeConnect` par les relais](#ConnexionaurseauderelaisviaEnvelopeConnectparlesrelais)
* 10. [9. Traitement des `Envelope` par les relais](#TraitementdesEnvelopeparlesrelais)
* 11. [10. Connexions aux réseaux de noeuds de Bitcoin, de réseaux side chain ou mainnet](#ConnexionsauxrseauxdenoeudsdeBitcoinderseauxsidechainoumainnet)
* 11.1. [10.1. Protocole de Découverte des Pairs](#ProtocoledeDcouvertedesPairs)
* 11.2. [10.2. Protocole de Transmission des Transactions](#ProtocoledeTransmissiondesTransactions)
* 11.3. [10.3. Protocole de Partage des Blocs](#ProtocoledePartagedesBlocs)
* 11.4. [10.4. Validation et relais](#Validationetrelais)
* 11.5. [10.5. Gestion des Forks](#GestiondesForks)
* 11.6. [10.6. Connexion au réseau de nœuds de side chain](#Connexionaurseaudenudsdesidechain)
* 11.6.1. [10.6.1. Clients](#Clients)
* 11.6.2. [10.6.2. Relais](#Relais)
* 11.7. [10.7. Connexion au réseau de nœuds de layer 1](#Connexionaurseaudenudsdelayer1)
* 11.8. [10.8. Horodatage et ancrage des `Prd` via les transactions Silent Payments (SP)](#HorodatageetancragedesPrdvialestransactionsSilentPaymentsSP)
* 12. [11. Transactions mainnet Bitcoin](#TransactionsmainnetBitcoin)
* 12.1. [11.1. Horodatage et ancrage des blocs de la side chain sur Bitcoin](#HorodatageetancragedesblocsdelasidechainsurBitcoin)
* 12.2. [11.2. Remboursement des frais d'horodatage et ancrage](#Remboursementdesfraisdhorodatageetancrage)
* 13. [Exemples de Code](#ExemplesdeCode)
* 14. [Todo](#Todo)
## 3. 1. Objectif
L'objectif de ce document est de décrire les spécifications techniques `Envelope` et `EnvelopeConnect` pour le réseau de relais et les clients.
## 4. 2. Portée
Ce document concerne les `Envelope` et `EnvelopeConnect` pour le réseau de relais et les clients.
## 5. Documents de référence
Voir [_Doc_references.md](_Doc_references.md).
## 6. 4. Variable `PeerList` du SDK (Wasm)
La variable `PeerList` du SDK (Wasm) est une liste de relais partagée avec les relais, constituant la première liste disponible, fournie en dur par le relais auquel on est connecté.
## 7. 6. Caractéristiques générales des `Envelope` et `EnvelopeConnect`
### 7.1. 6.1. PeerList
`PeerList` est une liste de relais partagée entre les relais et les clients, complétée au fur et à mesure de leur découverte de nouveaux relais.
### 7.2. 6.2. ProcessList
`ProcessList` est une liste de `Process` partagée entre les relais et les clients, complétée au fur et à mesure de leur découverte de nouveaux `Process`.
### 7.3. 6.3. Taille des données
Les objets `Peer` spécifient la taille maximale des données pour les `Envelope` et `EnvelopeConnect` dans l'attribut `data_max_size` du sous-attribut `relay`. Les `Envelope` excédant cette taille sont rejetés.
### 7.4. 6.4. Preuve de travail
Les objets `Peer` définissent les caractéristiques de la preuve de travail pour les `Envelope` et `EnvelopeConnect` dans les attributs `pow_difficulty`, `pow_pattern`, `pow_prefix`, `pow_nonce`, `pow_timeout` du sous-attribut `relay`. Les `Envelope` ne respectant pas la preuve de travail sont rejetés.
### 7.5. 6.5. Adresse SP de faucet
L'`User` fournit aux relais une adresse SP (Silent Payments) dite de faucet `faucet_sp_address`. Un portefeuille est généré en mémoire pour chaque relais à la réception des fonds, les fonds sont ensuite transférés vers l'adresse SP de l'`User` et le portefeuille est supprimé.
L'`User` reçoit en retour une transaction Silent Payments (SP) contenant des jetons sur l'adresse dite de faucet `faucet_sp_address`, cette transaction inclut un output supplémentaire avec le hash de l'`Envelope` de type `EnvelopeConnect` ou `Envelope` correspondant.
### 7.6. Objets `EnvelopeGeneric` contenu dans les types `Envelope` et `EnvelopeConnect`
`EnvelopeGeneric` fournit une structure générale pour les `Envelope`, incluant les pairs partagés et les processus, et des détails comme les défis de PoW, soutenant des besoins de communication diversifiés. Les attributs ont les fonctions suivantes :
* **`shared_peer_list`** : Une liste de pairs partagés, représentée par des objets `Peer`. Cette liste sert à partager les pairs entre les relais et les clients et les relais entre eux.
* **`shared_process_list`** : Une liste de processus partagés, représentée par des objets `Process`. Cette liste sert à partager les processus entre les relais et les clients et les relais entre eux.
* **`faucet_sp_address`** : L'adresse pour recevoir les fonds du faucet (indispensable pour pouvoir crééer des requètes Silent Payments).
* **`pow`** : Représente un défi de Preuve de Travail (PoW), représentée par un objet `Pow`.
* **`raw_transaction_list`** : Liste de transactions à diffuser.
La structure `Pow` détaille un défi de Preuve de Travail, incluant le hash des données, le timestamp et le nonce, pour garantir un effort computationnel à des fins de sécurité. Les attributs ont les fonctions suivantes :
* **`data_hash`** : Le hash des données pour lesquelles le PoW est résolu, il s'agit du hash de l'attribut `request_enc` de l'`Envelope` pour les `Envelope` de type `Envelope`, pour les `Envelope` de type `EnvelopeConnect` il s'agit du hash de l'attribut `faucet_sp_address`.
* **`timestamp`** : Un timestamp associé à la solution PoW qui fait parti dans la chaine à résoudre.
* **`nonce`** : Une valeur de nonce utilisée dans le calcul du PoW.
* **`pattern`** : Le motif des premiers caractères qui doivent être répétés autant de fois que la difficulté l'indique.
* **`difficulty`** : Le niveau de difficulté du défi PoW.
La structure `Process` identifie un processus partagé au sein du système, aidant à la gestion et la coordination des processus collaboratifs.
* **`process_list`** : Une liste d'`Process` partagée. Cette liste sert à partager les processus entre les relais et les clients et les relais entre eux.
La structure `Peer` spécifie un pair au sein du réseau. Les attributs ont les fonctions suivantes :
* **`domain`** : Le domaine associé au pair partagé.
* **`address_ip`** : L'adresse IP du pair partagé.
* **`relay`** : Représente un `Relay` dans le réseau.
* **`l1_node`** : Représente un `L1Node` dans le réseau.
* **`l1_miner`** : Représente un `L1Miner` dans le réseau.
* **`l2_node_list`** : Représente des `L2Node` dans le réseau.
Représente un `Relay` dans le réseau. Les attributs ont les fonctions suivantes :
* **`address_port`** : L'adresse du port du relais.
* **`data_max_size`** : Taille maximale des données que le relais peut traiter.
* **`pow_difficulty`** : Le niveau de difficulté pour la Preuve de Travail requise par le relais.
* **`pow_pattern`** : Le motif utilisé pour la Preuve de Travail.
* **`pow_prefix`** : Le préfixe utilisé pour la Preuve de Travail.
* **`pow_timeout`** : Délai d'attente maximum pour consider le pow comme valide.
La structure `L1Node` détaille un nœud blockchain de niveau 1 pour la validation et le relais des transaction. Les attributs ont les fonctions suivantes :
* **`address_port`** : L'adresse du port du nœud.
* **`explorer_base_url`** : L'URL de base de l'explorateur.
* **`l2_mining`** : Représente un `L2Mining` dans le réseau.
* **`l2_certif`** : Représente un `L2Certif` dans le réseau.
* **`reward_received_tx_list`** : Liste des transactions de récompense reçues par ce noeud.
* **`reward_send_tx_list`** : Liste des transactions de récompense dépensées par ce noeud.
* **`anchorage_tx_list`** : Liste des transactions d'ancrage dépensées par ce noeud.
* **`spend_key`** : [PRIVE] cet attribut n'est pas partager dans le `Envelope` , c'est la clé privée pour dépenser les fonds de ce noeud.
* **`scan_key`** : [PRIVE] cet attribut n'est pas partager dans le `Envelope` , c'est la clé privée pour détecter les transaction Silent Payments les fonds de ce noeud.
La structure `L1NodeMining` détaille un nœud blockchain de niveau 1 (Layer 1) se concentrant sur les opérations minières. Les attributs ont les fonctions suivantes :
* **`block_mined_list`** : Liste des blocs extraits.
* **`spend_key`** : [PRIVE] cet attribut n'est pas partager dans le `Envelope` , c'est la clé privée pour dépenser les fonds de ce noeud.
* **`scan_key`** : [PRIVE] cet attribut n'est pas partager dans le `Envelope` , c'est la clé privée pour détecter les transaction Silent Payments les fonds de ce noeud.
La structure `L2Node` représente un nœud blockchain de niveau 2 (Layer 2) pour la validation et le relais des transaction. Les attributs ont les fonctions suivantes :
* **`address_port`** : L'adresse du port du nœud.
* **`explorer_base_url`** : L'URL de base de l'explorateur.
* **`reward_received_tx_list`** : Liste des transactions de récompense reçues par ce noeud.
* **`anchorage_tx_list`** : Liste des transactions d'ancrage dépensées par ce noeud.
* **`nbits`** : Nombre de bits propre de calibrage de la blockchain.
* **`magic_number`** : Le nombre magique propre à la blochain.
* **`challenge`** : Le script de signature des blocs.
* **`spend_key`** : [PRIVE] cet attribut n'est pas partager dans le `Envelope` , c'est la clé privée pour dépenser les fonds de ce noeud.
* **`scan_key`** : [PRIVE] cet attribut n'est pas partager dans le `Envelope` , c'est la clé privée pour détecter les transaction Silent Payments les fonds de ce noeud.
La structure `L2NodeMining` détaille un nœud blockchain de niveau 2 (Layer 2) se concentrant sur les opérations minières. Les attributs ont les fonctions suivantes :
* **`sp_address_minig_reward`** : Adresse de récompense SP pour l'exploitation minière.
* **`sp_address_refunder`** : Adresse SP rembourseur.
* **`block_hash_mined_list`** : Liste des hashes de blocs extraits.
* **`spend_key`** : [PRIVE] cet attribut n'est pas partager dans le `Envelope` , c'est la clé privée pour dépenser les fonds de ce noeud.
* **`scan_key`** : [PRIVE] cet attribut n'est pas partager dans le `Envelope` , c'est la clé privée pour détecter les transaction Silent Payments les fonds de ce noeud.
La structure `L2Certif` spécifie une certification de niveau 2. Les attributs ont les fonctions suivantes :
* **`sp_address_certif_l1`** : Adresse de certification de niveau 1.
* **`block_certified_list`** : Liste des blocs certifiés de types `BlockCertif`.
* **`spend_key`** : [PRIVE] cet attribut n'est pas partager dans le `Envelope` , c'est la clé privée pour dépenser les fonds de ce noeud.
* **`scan_key`** : [PRIVE] cet attribut n'est pas partager dans le `Envelope` , c'est la clé privée pour détecter les transaction Silent Payments les fonds de ce noeud.
La structure `BlockCertif` spécifie un bloc certifié. Les attributs ont les fonctions suivantes :
* **`l2_block_hash_list`** : Liste des hashes de blocs.
* **`l1_tx`** : Transaction de niveau 1.
## 8. 7. Traitements par les clients
### 8.1. 7.1. Connexion d'un client à sa liste de relais via les `EnvelopeConnect`
#### 8.1.1. 7.1.1. Récupération et choix des relais
Pour discuter avec les relais du réseau et faire relayer des `Pcd` et des `Prd` sous forme d'une `Envelope`, l'`User` doit se connecter à un ou plusieurs relais, quatre par défaut.
L'`User` envoie un `Envelope` de type `EnvelopeConnect` à chaque relais pour se connecter. Ensuite, il peut envoyer des `Envelope` à chacun des quatre relais connectés et recevoir des `Envelope` de leur part.
Il y a des doublons d'une `Envelope` pour chaque relais, à la fois envoyés et reçus. Un arbitrage est possible pour confronter les données dans le temps et par origines. Les résultats permettent d'améliorer les listes de Members par un système de réputation calculable de manière autonome en rapport à sa propre expérience. L'arbitrage repose sur une réponse devant satisfaire au moins 80% de la même réponse que celle des relais connectés pour le même `Envelope` . Les valeurs des arbitrages sont stockées dans le cache.
Pour se connecter, l'`User` récupère leurs caractéristiques depuis la liste de relais partagée `PeerList` du SDK (Wasm) et depuis les listes de relais non partagées `private` et `public` du cache.
Un ping (incluant la Preuve de Travail dans le délai) est réalisé sur chaque relais pour vérifier leur disponibilité, et les quatre premiers relais disponibles sont choisis. Les valeurs des pings sont stockées dans le cache pour chaque relais (historique des pings).
Les relais "browsers" possèdent un nom de domaine et un certificat SSL pour satisfaire aux exigences de sécurité des navigateurs. Les autres relais, qui n'ont pas de nom spécifique, peuvent ne pas avoir de nom de domaine ni de certificat SSL et sont utilisés pour relayer les `Envelope` entre les relais.
Les connexions utilisent le protocole WebSocket avec ou sans SSL (URL commençant par `ws://` ou `wss://`), et les `Envelope` sont au format JSON.
#### 8.1.2. 7.1.2. Envoi de l'`EnvelopeConnect` à chaque relais
L'`User` parcourt sa liste de relais et envoie un `Envelope` de type `EnvelopeConnect` au format JSON (voir [Specs-Datamodel.md](Specs-Datamodel.md)) à chaque relais pour se connecter. Il partage ainsi sa liste de relais et sa liste de `Process`. Il n'y a pas de retour attendu pour cette `Envelope` .
Objet de type `EnvelopeConnect`. Les attributs ont les fonctions suivantes :
* ***Envelope** : Contient le `EnvelopeGeneric`
### 8.2. 7.2. Envoi de `Request` sur les relais via l'`Envelope`
Objet de type `Envelope`, Les attributs ont les fonctions suivantes :
* **`Envelope`** : Contient le `EnvelopeGeneric`
* **`request_enc`** : Contient le `Pcd` ou un `Prd` chiffré par la `ProcessKey`
### 8.3. 7.4. Traitement des `Envelope` par les clients
Le client reçoit un nouveau `Envelope` via le socket ouvert avec le relais et effectue divers contrôles, notamment le calcul du hash de l'`Envelope` et sa vérification dans le cache. Les listes de relais (`PeerList`) et de `Process` (`ProcessList`) sont mises à jour en conséquence. Le `Envelope` est ensuite déchiffré avec la `ProcessKey` du `Process`, et d'autres contrôles sont réalisés. Les données pertinentes sont mises à jour dans le cache.
## 9. 8. Traitements par les relais
### 9.1. 8.1. Traitement des `EnvelopeConnect` par les relais
À la réception d'un `Envelope` de type `EnvelopeConnect`, le relais enregistre le socket du client et réalise divers contrôles, y compris la vérification de la preuve de travail et la taille des données. Les listes de relais (`PeerList`) et de `Process` (`ProcessList`) sont mises à jour. En retour, le relais envoie quelques jetons à l'adresse SP de faucet communiquée par le client et met à jour les données dans le cache.
### 9.2. 8.2. Connexion au réseau de relais via `EnvelopeConnect` par les relais
Les relais se connectent à de nouveaux relais en utilisant `EnvelopeConnect`, partageant à leur tour leur liste de relais et de `Process`. Aucun retour n'est attendu pour cette `Envelope` .
## 10. 9. Traitement des `Envelope` par les relais
Le relais reçoit un nouveau `Envelope` de type `Envelope` du client, effectue les contrôles nécessaires, et met à jour ses listes. En retour, le relais envoie quelques jetons à l'adresse SP de faucet du client. Le `Envelope` est ensuite relayé aux autres relais et clients connectés, favorisant ainsi sa propagation.
## 11. 10. Connexions aux réseaux de noeuds de Bitcoin, de réseaux side chain ou mainnet
Pour plus de détails, voir : [Specs-References.md](Specs-References.md).
Bitcoin et les side chains utilisent divers protocoles pour la découverte de pairs, la transmission des transactions, et le partage des blocs, adaptés aux besoins spécifiques de 4NK.
### 11.1. 10.1. Protocole de Découverte des Pairs
Bitcoin facilite la découverte de nouveaux nœuds via des DNS seeds et une liste de nœuds codée en dur. 4NK utilise la `PeerList` comme équivalent pour faciliter la découverte de relais dans le réseau.
### 11.2. 10.2. Protocole de Transmission des Transactions
* **Mempool et Transactions Orphelines** : Les transactions sont ajoutées au mempool en attente de confirmation. Les transactions dépendantes d'autres transactions non confirmées sont considérées comme orphelines jusqu'à résolution.
* **Protocole P2P de Bitcoin** : Définit la communication entre nœuds pour échanger informations sur les transactions et blocs, incluant les `Envelope` `version`, `verack`, `inv`, `getdata`, `tx`, et `block`.
### 11.3. 10.3. Protocole de Partage des Blocs
* **Propagation des Blocs** : Les nouveaux blocs sont rapidement transmis à travers le réseau via un mécanisme de propagation.
* **Compact Blocks** : Optimise la transmission des blocs en utilisant les données déjà présentes dans le mempool des nœuds récepteurs.
### 11.4. 10.4. Validation et relais
Les transactions et les blocs sont validés selon les règles de consensus avant d'être relayés aux autres pairs, assurant l'intégrité et la sécurité du réseau.
### 11.5. 10.5. Gestion des Forks
Bitcoin gère les bifurcations temporaires de la blockchain, permettant une réorganisation basée sur la chaîne avec le plus de travail cumulé.
### 11.6. 10.6. Connexion au réseau de nœuds de side chain
#### 11.6.1. 10.6.1. Clients
Les clients se connectent au réseau de nœuds de side chain pour recevoir les blocs et les transactions, y compris les transactions Silent Payments (SP) liées aux `Prd`.
#### 11.6.2. 10.6.2. Relais
Les relais fonctionnent comme des nœuds complets de la side chain, facilitant la communication et la validation des transactions.
### 11.7. 10.7. Connexion au réseau de nœuds de layer 1
Les relais maintiennent également une connexion au réseau principal (mainnet) pour des opérations d'ancrage et d'horodatage.
### 11.8. 10.8. Horodatage et ancrage des `Prd` via les transactions Silent Payments (SP)
Les `Prd` sont ancrés dans la side chain à travers des transactions SP, offrant une preuve immuable de leur existence et de leur intégrité.
## 12. 11. Transactions mainnet Bitcoin
### 12.1. 11.1. Horodatage et ancrage des blocs de la side chain sur Bitcoin
Les blocs de la side chain sont ancrés sur le mainnet de Bitcoin à intervalles réguliers, fournissant une preuve temporelle et augmentant la sécurité.
### 12.2. 11.2. Remboursement des frais d'horodatage et ancrage
Le processus de minage "vert" de 4NK génère les jetons nécessaires pour couvrir les frais d'horodatage et d'ancrage sur le réseau Bitcoin, assurant ainsi la viabilité financière de ces opérations.
Ces spécifications techniques fournissent une vue d'ensemble de la façon dont 4NK s'intègre avec les réseaux Bitcoin et side chain, utilisant des protocoles éprouvés tout en introduisant de nouvelles méthodes pour améliorer la sécurité, la transparence, et l'efficacité des transactions et des communications au sein du réseau.
## 13. Exemples de Code
## 14. Todo