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

28 KiB
Raw Blame History

# Auth - Specs

1. Objectif

L'objectif de ce document est de décrire les spécifications techniques des messages de type Message et de type MessageConnect pour le réseau de relais et les clients.

2. Portée

Ce document concerne les messages de type Message et de type MessageConnect pour le réseau de relais et les clients.

3. 3. Documents de référence

Voir _Doc_references.md.

4. ## Variable SharedPeerList du SDK (Wasm)

La variable SharedPeerList du SDK (Wasm) est une liste de relais partagée avec les relais, c'est la première liste disponible, en dur fournie par le relais sur lequel on est connecté.

5. Structure du stockage en cache

5.1. Relais

Le cache est constitué de 2 parties :

  1. public :
    • Liste partagée des relais avec les relais (agrégée au fil des relais découverts par le partage des listes de relais dans les messages).
    • L'historique des pings des relais (timestamp, valeur du ping, relais concerné).
    • L'historique de message reçus ne satisfaisant pas à l'arbitrage (timestamp, hash du message, relais concerné).
    • L'historique de message envoyés sans retour d'une transaction Silent Payment (SP).
  2. private :
    • Liste non partagée des relais (agrégée à partir de relais communiqués de façon confidentielle).
    • L'historique des pings des relais (timestamp, valeur du ping, relais concerné).
    • L'historique de message reçus ne satisfaisant pas à l'arbitrage (timestamp, hash du message, relais concerné).
    • L'historique de message envoyés sans retour d'une transaction Silent Payment (SP).

Voir ClientDataModel.md.

5.2. Process

Le cache est constitué de 2 parties :

  1. public :
    • Liste partagée des ItemProcess avec les relais (agrégée au fil des relais découverts par le partage des listes de ItemProcess dans les messages).
    • Liste partagée des ItemProcess complets reçus depuis les mises à jour des parties prenantes.
  2. private :
    • Liste non partagée des ItemProcess (agrégée à partir de ItemProcess communiqués de façon confidentielle).
    • Liste non partagée des ItemProcess complets reçus depuis les mises à jour des parties prenantes.

Voir ClientDataModel.md.

5.3. Liste des hashs des messages reçus

Le cache contient une liste des hashs des messages de type Message et de type MessageConnect reçus, répartie en plusieurs parties :

  • Hashs des objets Message.
  • Hashs des objets MessageConnect (vide pour les clients).
  • Hashs de la donnée encryptée dans les objets Message.
  • Hashs des RequestPcd une fois déchiffrés des objets Message Message, avec le hash du message correspondant (vide pour les relais) et état actuel de la collecte des RequestPrd correspondants.
  • Hashs des RequestPrd une fois déchiffrés des objets Message Message, avec le hash du message correspondant et l'id de la transaction Silent Payment (SP) correspondante (vide pour les relais).
  • Liste des transaction SP du faucet.
  • Liste des transaction SP reçues.

Voir ClientDataModel.md.

5.4. Liste des sockets ouverts

Le cache contient une liste des sockets ouverts, répartie en 2 parties :

  • SocketClientList: liste des sockets ouverts en tant que clients.
  • SocketServerList: liste des sockets ouverts parles clients.

Voir ClientDataModel.md.

6. Caractéristiques générales des messages de type Message et de type MessageConnect

6.1. SharedPeerList

SharedPeerList est une liste de relais. Les relais et les clients partagent cette liste qu'ils complètent au fur et à mesure de leur découverte de relais.

6.2. SharedProcessList

SharedProcessList est une liste de ItemProcess. Les relais et les clients partagent cette liste qu'ils complètent au fur et à mesure de leur découverte de ItemProcess.

6.3. Taille des données

Les objets SharedPeer indiquent la taille maximale des données pour les messages de type Message et de type MessageConnect dans l'attribut data_max_size du sous attribut relay. Les messages plus gros que cette taille sont rejetés.

6.4. Preuve de travail

Les objets SharedPeer indiquent les caractéristiques de la preuve de travail pour les messages de type Message et de type MessageConnect dans les attributs pow_difficulty, pow_pattern, pow_prefix, pow_nonce, pow_timeout du sous attribut relay. Les messages ne satisfaisant pas à la preuve de travail sont rejetés.

6.5. Adresse SP de faucet

L'utilisateur fournit aux relais uneadresse SP (SP) dite de faucet faucet_sp_address. Un wallet est généré en mémoire pour chaque relais, à la réception des fonds les fonds sont transférés vers l'addresse SP de l'utilisateur et le wallet est supprimé.

L'utilisateur reçoit en retour une transaction Silent Payment (SP) contenant des jetons sur l'adresse dite de faucet faucet_sp_address, cette transaction contient un output supplémentaire avec le hash du message de type MessageConnect ou de type Message correspondant.

7. Traitements par les clients

7.1. Connexion d'un client à sa liste relais via les messages de type MessageConnect

7.1.1. Récupération et choix des relais

Afin de pouvoir discuter avec les relais du réseau et faire relayer des RequestPcd et des RequestPrd sous forme de Message, l'utilisateur doit se connecter à un ou plusieurs relais, 4 par défaut.

L'utilisateur enverra un message de type MessageConnect à chaque relais pour se connecter. Puis, il pourra envoyer des Message à chacun des 4 relais connectés et recevoir des Message de chacun d'eux.

Ainsi, il y a des doublons des messages 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 membres par un système de réputation calculable par chacun de façon autonome en rapport à sa propre expérience. À ce stade, l'arbitrage repose sur une réponse devant satisfaire au moins 80% de même réponse que des relais connectés pour le même message. Les valeurs des arbitrages sont stockées dans le cache.

Pour s'y connecter, l'utilisateur récupère leurs caractéristiques depuis la liste de relais partagée SharedPeerList du SDK (Wasm) et depuis la liste de relais non partagée private du cache et depuis la liste de relais non partagée public du cache.

Un ping (PoW incluse dans le délai) est réalisé sur chaque relais pour vérifier leur disponibilité et l'on choisit les 4 premiers relais disponibles. Les valeurs des pings sont stockées dans le cache pour chaque relais (historique des pings).

Les relais dits "navigators" ont un nom de domaine et un certificat SSL afin de satisfaire aux exigences de sécurité des navigateurs. Les autres relais n'ont pas de nom spécifique et n'ont pas nécessairement de nom de domaine et de certificat SSL, ils sont utilisés pour relayer les messages entre les relais.

Les connexions sont en websocket avec ou sans SSL (url commençant par ws:// ou wss://) et les messages sont en JSON.

7.1.2. Envoi du message de type MessageConnect à chaque relais

L'utilisateur parcourt sa liste de relais et envoie un message de type MessageConnect en JSON (voir Specs-Datamodel.md) à chaque relais pour se connecter, il partage sa liste de relais et sa liste de ItemProcess.

Il n'y a pas de retour attendu pour ce message.

7.2. Envoi de RequestPcd sur les relais via les messages de type Message

Une fois le RequestPcd finalisé, il est chiffré par la ProcessKey du ItemProcess. Cette partie chiffrée est la valeur de l'attribut request_enc du Message.

L'utilisateur parcourt sa liste de relais et envoie un message correspondant de type Message en JSON (voir Specs-Datamodel.md) à chaque relais pour se connecter, il partage sa liste de relais et sa liste de ItemProcess.

7.3. Envoi de RequestPrd sur les relais via les messages de type Message

Une fois le RequestPrd finalisé, une transaction SP est réalisée, dans cette transaction plusieurs hashs sont ajoutés (voir Silent-Payment-Specs.md). :

La clé KeyConfidential de cette transaction est utilisée pour chiffrer les champs suivants :

  • RequestPcd_keys_role_confidential_list_enc_by_shared_secret

Pour les RequestPrd de type RequestPrdResponse :

  • payment_method_enc_by_shared_secret
  • deposit_method_enc_by_shared_secret
  • commitment_method_enc_by_shared_secret
  • certif_key_enc_by_shared_secret
  • device_footprint_enc_by_sp_shared_secret
  • pre_id_enc_by_sp_shared_secret
  • shard_enc_by_sp_shared_secret

Pour les RequestPrd de type RequestPrdConfirm :

  • code_confirm_enc_by_shared_secret

Pour les RequestPrd de type RequestPrdList :

  • item_member_enc_by_sp_shared_secret
  • pre_id_enc_by_sp_shared_secret

Puis le RequestPrd est chiffré par la ProcessKey du ItemProcess. Cette partie chiffrée est la valeur de l'attribut request_enc du Message.

L'utilisateur parcourt sa liste de relais et envoie un message correspondant de type Message en JSON (voir Specs-Datamodel.md) à chaque relais pour se connecter, il partage sa liste de relais et sa liste de ItemProcess.

7.4. Traitement des messages de type Message par les clients

Le client reçoit un nouveau message dans le socket ouvert avec le relais.

Le client réalise les contrôles suivants :

  • Calcul du hash du message et vérification de la non-existence du hash dans le cache.

Le client met à jour ses propres listes suivantes :

  • Liste des relais depuis la liste partagée par le relais SharedPeerList.
  • Liste des ItemProcess depuis la liste partagée par le relais SharedProcessList.

Déchiffrement du message avec la ProcessKey du ItemProcess et contrôles suivants :

  • Calcul du hash du RequestPcd ou RequestPrd et vérification de la non-existence du hash dans le cache.
  • Voir [ RequestPrd- RequestPcd-Specs.md]( RequestPrd- RequestPcd-Specs.md) pour les détails des contrôles.

Mises à jour des données du cache.

8. Traitements par les relais

8.1. Traitement des messages de type MessageConnect par les relais

Le relais enregistre le socket du client et lui attribue un index dans l'ordre de création des sockets.

Le relais réalise les contrôles suivants :

  • Calcul du hash du message et vérification de la non-existence du hash dans le cache.
  • Vérification de la preuve de travail.
  • Vérification de la taille des données.

Le relais met à jour ses propres listes suivantes :

  • Liste des relais depuis la liste partagée par le client SharedPeerList.
  • Liste des ItemProcess depuis la liste partagée par le client SharedProcessList.

Voir ClientDataModel.md.

Le relais envoie en retour quelques jetons sur une adresse dite de faucet faucet_sp_address communiquée par le client.

Mises à jour des données du cache.

Envoi de la transaction Silent Payment (SP) contenant des jetons sur l'adresse dite de faucet faucet_sp_address avec un output supplémentaire avec le hash du message de type MessageConnect correspondant.

8.2. Connexion au réseau de relais via les messages de type MessageConnect par les relais

Le relais parcourt la liste de relais mise à jour et se connecte à chacun des nouveaux relais via un MessageConnect en partageant à son tour sa liste de relais et sa liste de ItemProcess.

Envoi vers chaque nouveau relai d'une transaction Silent Payment (SP) contenant des jetons sur l'adresse dite de faucet faucet_sp_address avec un output supplémentaire avec le hash du message de type MessageConnect correspondant.

Il n'y a pas de retour attendu pour ce message.

9. Traitement des messages de type Message par les relais

Le relais reçoit un nouveau message dans le socket ouvert avec le client.

Le relais réalise les contrôles suivants :

  • Calcul du hash du message et vérification de la non-existence du hash dans le cache.
  • Vérification de la preuve de travail.
  • Vérification de la taille des données.

Le relais met à jour ses propres listes suivantes :

  • Liste des relais depuis la liste partagée par le client SharedPeerList.
  • Liste des ItemProcess depuis la liste partagée par le client SharedProcessList.

Voir ClientDataModel.md.

Le relais envoie en retour quelques jetons sur une adresse dite de faucet faucet_sp_address communiquée par le client.

Mises à jour des données du cache.

Envoi de la transaction Silent Payment (SP) contenant des jetons sur l'adresse dite de faucet faucet_sp_address avec un output supplémentaire avec le hash du message de type MessageConnect correspondant.

9.1. Broadcast des messages de type Message vers les relais

Le relais parcourt la liste de relais mise à jour et se connecte à chacun des nouveaux relais via un MessageConnect en partageant à son tour sa liste de relais et sa liste de ItemProcess.

Envoi vers chaque nouveau relai d'une transaction Silent Payment (SP) contenant des jetons sur l'adresse dite de faucet faucet_sp_address avec un output supplémentaire avec le hash du message de type MessageConnect correspondant.

Envoi vers chaque relai d'une transaction Silent Payment (SP) contenant des jetons sur l'adresse dite de faucet faucet_sp_address avec un output supplémentaire avec le hash du message de type Message correspondant.

Le relais parcourt la liste de relais mise à jour et envoie le Message reçu à chaque relai connecté en partageant à son tour sa liste de relais et sa liste de ItemProcess (sans modifier la Preuve de Travail mais en contrôlant la taille du message et les caractéristiques de la preuve de travail avant d'envoyer au relai).

Il n'y a pas de retour attendu pour ce message.

9.2. Broadcast des messages de type Message vers les clients connectés

Le relais parcourt la liste des sockets ouverts et envoie le Message reçu à chaque client connecté en partageant à son tour sa liste de relais et sa liste de ItemProcess.

Envoi vers chaque client d'une transaction Silent Payment (SP) contenant des jetons sur l'adresse dite de faucet faucet_sp_address avec un output supplémentaire avec le hash du message de type Message correspondant.

Il n'y a pas de retour attendu pour ce message.

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.

10.1. Protocole de Découverte des Pairs

Bitcoin utilise un mécanisme de découverte de pairs pour que les nouveaux nœuds puissent trouver d'autres nœuds du réseau. Cela peut être réalisé via des "DNS seeds" (des serveurs DNS qui retournent une liste d'adresses IP de nœuds Bitcoin actifs) ou via une liste de nœuds connus codée en dur dans le logiciel.

  • Gossip Protocol : Bitcoin utilise un protocole de type "gossip" pour la propagation des transactions. Lorsqu'un nœud reçoit une transaction valide qu'il n'a pas encore vue, il la valide puis la retransmet à tous ses pairs, ce qui permet une propagation rapide et efficace à travers le réseau.

Dans le cas de 4NK, l'équivalent des DNS est la liste de relais partagée SharedPeerList.

10.2. Protocole de Transmission des Transactions

  • Mempool et Transactions Orphelines : Lorsqu'un nœud reçoit une nouvelle transaction, il l'ajoute à son pool de transactions en attente (mempool) avant de la transmettre à ses pairs. Si une transaction fait référence à des entrées inexistantes (par exemple, si elle dépend de transactions non confirmées), elle peut être traitée comme orpheline jusqu'à ce que ses dépendances soient résolues.

Le protocole P2P de Bitcoin définit la manière dont les nœuds communiquent entre eux pour partager les informations sur les transactions et les blocs. Il inclut plusieurs types de messages :

  • version / verack : Utilisés lors de l'établissement de la connexion entre deux nœuds pour échanger les informations de version et confirmer la connexion.

  • Protocole inv (inventaire) : Un nœud annonce de nouvelles transactions à ses pairs en utilisant des messages inv, qui contiennent des identifiants de transaction. Les nœuds qui n'ont pas ces transactions peuvent alors les demander en utilisant des messages getdata.

  • getdata : Utilisé par un nœud pour demander les données spécifiques (transactions ou blocs) annoncées via un message inv.

  • tx : Utilisé pour transmettre les détails d'une transaction.

  • block : Utilisé pour transmettre les détails d'un bloc.

  • getblocks / getheaders : Utilisés pour récupérer des blocs ou des en-têtes de blocs depuis un nœud, généralement dans le processus de synchronisation de la blockchain.

  • headers : Utilisé pour transmettre des en-têtes de blocs en réponse à un message getheaders, facilitant la vérification et la synchronisation de la blockchain sans télécharger tous les blocs complets.

10.3. Protocole de Partage des Blocs

  • Propagation des Blocs : Lorsqu'un nœud mine un nouveau bloc, il le transmet immédiatement à ses pairs. Comme pour les transactions, la propagation utilise un mécanisme similaire au protocole "gossip" pour assurer une distribution rapide du bloc à travers le réseau.

  • Compact Blocks : Introduit par BIP 152, ce mécanisme permet de transmettre des blocs de manière plus efficace en utilisant les informations déjà disponibles dans le mempool des nœuds récepteurs. Cela réduit la quantité de données nécessaires pour transmettre un nouveau bloc, accélérant ainsi sa propagation.

  • Protocole inv pour les blocs : Similaire aux transactions, un nœud utilise des messages inv pour annoncer de nouveaux blocs à ses pairs. Les nœuds qui ne connaissent pas ce bloc peuvent demander le bloc complet en utilisant getdata.

  • Transaction Relay Protocol : Bitcoin Core a implémenté des améliorations telles que le "Transaction Relay Protocol" pour optimiser la manière dont les transactions sont relayées entre les nœuds, réduisant la bande passante nécessaire et améliorant la confidentialité.

  • Compact Block Relay : Ce protocole permet une propagation plus efficace des nouveaux blocs en utilisant les informationsque les nœuds ont probablement déjà en leur possession, réduisant ainsi la quantité de données nécessaires à transmettre pour relayer un bloc complet.

Dans le cas de 4NK, les block relay, compact blocks, et les blocs filters permettent de travailler rapidement et côté client directement sur les données des blocs et transactions du réseau.

10.4. Validation et relais

  • Validation : Les nœuds valident les transactions et les blocs selon les règles de consensus de Bitcoin et les règles de filtrage local avant de les relayer à d'autres nœuds. Cela inclut la vérification des signatures, la conformité des structures de données, et d'autres critères spécifiques à Bitcoin.

  • Relais : Après validation, les transactions et les blocs sont relayés aux autres pairs, favorisant ainsi la propagation rapide et la redondance des données à travers le réseau.

10.5. Gestion des Forks

Lorsque deux blocs sont minés presque simultanément, cela peut créer une bifurcation temporaire dans la blockchain. Les nœuds choisissent le premier bloc qu'ils reçoivent et continuent à construire dessus, mais ils gardent aussi une trace de la branche alternative. Si la branche alternative devient plus longue (c'est-à-dire qu'elle devient la chaîne avec le plus de travail cumulé), les nœuds basculent sur cette chaîne, réorganisant ainsi leur blockchain locale.

10.6. Connexion au réseau de nœuds de side chain

10.6.1. Clients

Les clients se connectent comme un nœud depuis le SDK au réseau de nœuds de side chain via les protocoles p2p de Bitcoin. Ils reçoivent les blocs et les transactions (mempool) de la side chain et scannent les transactions de la side chain pour trouver les transactions Silent Payment (SP) correspondantes aux RequestPrd, puis les RequestPcd correspondant aux RequestPrd.

10.6.2. Relais

Les relais hébergent un nœud complet de la side chain, connecté aux autres membres de ce réseau. Voir Specs-Deployment.md pour les détails de déploiement.

10.7. Connexion au réseau de nœuds de layer 1

Les relais hébergent un nœud complet du mainnet, connecté aux autres membres de ce réseau. Voir Specs-Deployment.md pour les détails de déploiement.

10.8. Horodatage et ancrage des RequestPrd via les transactions Silent Payment (SP)

Les RequestPrd sont horodatés et ancrés sur la side chain via des transactions Silent Payment (SP) contenant les hashs des messages et des signatures associées ( RequestPrd). Ces transactions sont ajoutées aux blocs, eux-mêmes signés par les nœuds "certificator" de la side chain pour être ajoutés à cette timechain. La dépense des UTXO de la transaction Silent Payment (SP) vaut pour signature (validation de la possession de la clé privée associée). Voir Specs-Deployment.md pour les détails de déploiement.

11. Transactions mainnet Bitcoin

11.1. Horodatage et ancrage des blocs de la side chain sur Bitcoin

Le temps de référence est en blocs. Tous les hashs de blocs de la side chain sont historisés par lots de 6 * 24 blocs. À toutes les hauteurs de blocs multiples de 144, chaque lot de hashs de blocs est l'objet lui-même d'un hash qui est inscrit dans un output de transaction sur Bitcoin (mainnet).

11.2. Remboursement des frais d'horodatage et ancrage des blocs de la side chain sur Bitcoin

Le minage "vert" de 4NK permet de produire les jetons nécessaires au remboursement des frais d'horodatage et ancrage des blocs de la side chain sur Bitcoin. La dépense des UTXO de la transaction Silent Payment (SP) vaut pour signature (validation de la possession de la clé privée associée).

12. Exemples de Code

13. Todo

  • Extraits de code illustrant l'utilisation des RequestPcd et RequestPrd dans des scénarios réels.
  • Diagrammes de séquences