4nk/sdk_common
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
sdk_common/doc/Envelope-Specs.md

23 KiB
Raw Blame History

Envelope - Specifications

1. Autheurs, validations, dates, versions, changement and historique

Cf. Git SDK COMMON

2. Table des matières

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.

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

EnvelopeConnectSend.png

PeerSendScore.png

L'User parcourt sa liste de relais et envoie un Envelope de type EnvelopeConnect au format JSON (voir 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

EnvelopeSend.png

PeerSendScore.png

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

PeerReceivedScore.png

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

RelayEnvelopeReceived

9.1. 8.1. Traitement des EnvelopeConnect par les relais

RelayEnvelopeConnectReceived

À 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

RelayEnvelopeEnvelopeReceived

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.

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