4nk/sdk_common
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Principles of Messaging added (doc)

Browse Source
This commit is contained in:
NicolasCantu 2024-03-19 13:28:36 +01:00
parent 445928cff7
commit d61b3355a7
4 changed files with 101 additions and 72 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
doc/Item-Specs.md
View File

@ -12,11 +12,7 @@
* 5. [Exemples de Code](#ExemplesdeCode)
* 6. [Todo](#Todo)
<!-- vscode-markdown-toc-config
numbering=true
autoSave=true
/vscode-markdown-toc-config -->
<!-- /vscode-markdown-toc --># Item - Specs
# Item - Specs
## 1. <a name='Objectif'></a>Objectif

160
doc/PRD-PCD-Specs.md
View File

@ -2,40 +2,42 @@
* 1. [Objectif](#Objectif)
* 2. [Portée](#Porte)
* 3. [Documents de référence](#Documentsderfrence)
* 4. [Encryption](#Encryption)
* 5. [Définitions](#Dfinitions)
* 6. [Principe de messagerie](#Principedemessagerie)
* 6.1. [Création et envoi](#Crationetenvoi)
* 6.2. [Réception](#Rception)
* 4. [Définitions](#Dfinitions)
* 5. [Principes de messagerie](#Principesdemessagerie)
* 5.1. [`RequestPrdConfirm`](#RequestPrdConfirm)
* 5.2. [`RequestPrdResponse`](#RequestPrdResponse)
* 6. [Encryption](#Encryption)
* 6.1. [Création et envoi](#Crationetenvoi)
* 6.2. [Réception](#Rception)
* 7. [Fonction des RequestPcd](#FonctiondesRequestPcd)
* 7.1. [Schéma des flux](#Schmadesflux)
* 7.2. [Création et envoi](#Crationetenvoi-1)
* 7.3. [Réception](#Rception-1)
* 7.1. [Schéma des flux](#Schmadesflux)
* 7.2. [Création et envoi](#Crationetenvoi-1)
* 7.3. [Réception](#Rception-1)
* 8. [Fonction des`RequestPrd`](#FonctiondesRequestPrd)
* 8.1. [Schéma des flux](#Schmadesflux-1)
* 8.2. [Fonctionnalités optionnelles](#Fonctionnalitsoptionnelles)
* 8.3. [Création et envoi](#Crationetenvoi-1)
* 8.4. [Réception](#Rception-1)
* 8.1. [Schéma des flux](#Schmadesflux-1)
* 8.2. [Fonctionnalités optionnelles](#Fonctionnalitsoptionnelles)
* 8.3. [Création et envoi](#Crationetenvoi-1)
* 8.4. [Réception](#Rception-1)
* 9. [RequestPrdList - Demande de Listes ( RequestPcd)](#RequestPrdList-DemandedeListesRequestPcd)
* 9.1. [Schéma des flux](#Schmadesflux-1)
* 9.2. [Création : Datas spécifiques](#Cration:Datasspcifiques)
* 9.3. [Réception : Datas spécifiques](#Rception:Datasspcifiques)
* 9.1. [Schéma des flux](#Schmadesflux-1)
* 9.2. [Création : Datas spécifiques](#Cration:Datasspcifiques)
* 9.3. [Réception : Datas spécifiques](#Rception:Datasspcifiques)
* 10. [RequestPrdMessage - Envoi de Messages](#RequestPrdMessage-EnvoideMessages)
* 10.1. [Schéma des flux](#Schmadesflux-1)
* 10.2. [Création : Datas spécifiques](#Cration:Datasspcifiques-1)
* 10.3. [Réception : Datas spécifiques](#Rception:Datasspcifiques-1)
* 10.1. [Schéma des flux](#Schmadesflux-1)
* 10.2. [Création : Datas spécifiques](#Cration:Datasspcifiques-1)
* 10.3. [Réception : Datas spécifiques](#Rception:Datasspcifiques-1)
* 11. [RequestPrdUpdate - Mises à Jour de RequestPcd](#RequestPrdUpdate-MisesJourdeRequestPcd)
* 11.1. [Schéma des flux](#Schmadesflux-1)
* 11.2. [Création : Datas spécifiques](#Cration:Datasspcifiques-1)
* 11.3. [Réception : Datas spécifiques](#Rception:Datasspcifiques-1)
* 11.1. [Schéma des flux](#Schmadesflux-1)
* 11.2. [Création : Datas spécifiques](#Cration:Datasspcifiques-1)
* 11.3. [Réception : Datas spécifiques](#Rception:Datasspcifiques-1)
* 12. [RequestPrdConfirm - Confirmation de Réception](#RequestPrdConfirm-ConfirmationdeRception)
* 12.1. [Schéma des flux](#Schmadesflux-1)
* 12.2. [Création : Datas spécifiques](#Cration:Datasspcifiques-1)
* 12.3. [Réception : Datas spécifiques](#Rception:Datasspcifiques-1)
* 12.1. [Schéma des flux](#Schmadesflux-1)
* 12.2. [Création : Datas spécifiques](#Cration:Datasspcifiques-1)
* 12.3. [Réception : Datas spécifiques](#Rception:Datasspcifiques-1)
* 13. [RequestPrdResponse - Répondre à une Demande](#RequestPrdResponse-RpondreuneDemande)
* 13.1. [Schéma des flux](#Schmadesflux-1)
* 13.2. [Création : Datas spécifiques](#Cration:Datasspcifiques-1)
* 13.3. [Réception : Datas spécifiques](#Rception:Datasspcifiques-1)
* 13.1. [Schéma des flux](#Schmadesflux-1)
* 13.2. [Création : Datas spécifiques](#Cration:Datasspcifiques-1)
* 13.3. [Réception : Datas spécifiques](#Rception:Datasspcifiques-1)
* 14. [Exemples de Code](#ExemplesdeCode)
* 15. [Todo](#Todo)
@ -53,7 +55,76 @@ La spécification couvre la conception, le développement, et l'application prat
Voir [_Doc_references.md](_Doc_references.md).
## 4. <a name='Encryption'></a>Encryption
## 4. <a name='Dfinitions'></a>Définitions
* **Portable Contract Document (`RequestPcd`)**: Un format `JSON` chiffré conçu pour contenir des listes d'éléments d'un type spécifique, attachées à un processus (`process_hash`) et soumises aux règles de validation décrites dans le rôle correspondant à ce type d'`Item` dans le `ItemProcess` (`item_type`).
* **Portable Request Document (`RequestPrd`)**: Format `JSON` chiffré contenant les valeurs de signatures et les clés de déchiffrement nécessaires à l'exploitation (requêtes et validation) des `RequestPcd`. Les `RequestPrdResponse` sont collectés pour vérifier le respect des conditions de l'`ItemProcess`. D'autres types de `RequestPrd` incluent :
* `RequestPrdList`: Demande de listes d'`Item`. En réponse, une `RequestPcd` est reçue avec les `RequestPrdResponse` correspondants.
* `RequestPrdMessage`: Envoi de messages publics, confidentiels ou privés et/ou de transactions Silent Payments des autres `RequestPrd` à diffuser sur le réseau des nœuds de la side chain. Les `RequestPrdMessage` peuvent répondre les uns aux autres.
* `RequestPrdUpdate`: Demande de mise à jour d'une liste d'`Item` (publiée via un `RequestPCD`), qui sera déchiffrée et validée ou non par des `RequestPrdResponse` en retour.
* `RequestPrdConfirm`: Confirmation de la réception des `RequestPrd` (à l'exception de `RequestPrdConfirm` eux-même).
* `RequestPrdResponse`: Réponse aux autres types de `RequestPrd` (à l'exception de `RequestPrdConfirm`, `RequestPrdResponse` et `RequestPrdMessage`).
* **Message**: Enveloppe commune pour les `RequestPrd` et `RequestPcd` lors de leur transmission aux relais et de leur réception depuis les relais. Dans cette enveloppe les `RequestPrd` et `RequestPcd` sont chiffrés par la `ProcessKey` de l'`ItemProcess` (cf. [Specs-Definition](SpecsDefinition.md)) et ajoutés au champs `RequestEnc`.
* **KeyConfidential**: Clé AES-GCM-256 issue du `Diffie-Hellman` de la transaction Silent Payment correspondant à un `RequestPrd`.
* **ProcessKey**: La clé publique de chiffrement d'un `ItemProcess` (trouvée dans un `ItemProcess`, dans son attribut `Item`, dans son attribut `metadata_contract_public`, dans son attribut `meta_data`, dans son attribut `key_list` au premier élément).
* **KeyRecover**: La clé privée de dépense de `recover` du signet, utilisée comme référence pour l'identité.
* **pre-id**: Pré-identifiant des utilisateurs, constitué du hash de la partie 1 de la `KeyRecover`.
## 5. <a name='Principesdemessagerie'></a>Principes de messagerie
Les `RequestPcd` sont envoyés à tous les participants connectés sans attente de retour spécifique et ne sont pas associés à une `transaction SP`.
Les `RequestPrd` sont toujours accompagnés d'une `transaction SP`, transmise dans l'attribut `raw_transaction_list` d'un `RequestPrdMessage` associé (à l'exception des `RequestPrdMessage` eux-mêmes).
Les `RequestPrd` sont des demandes d'actions ou des réponses à ces demandes, interagissant de la manière suivante :
* `RequestPrdList` : Constitue généralement la première requête d'un workflow et ne répond pas à un autre `RequestPrd`.
* `RequestPrdMessage`, avec 2 cas de figure :
* Demande de relais d'une `transaction SP`, dans ce cas, le `RequestPrdMessage` ne répond pas à un autre `RequestPrd`.
* Envoi de message, pouvant initier un échange de messagerie ou répondre à un autre `RequestPrdMessage`.
* `RequestPrdUpdate` : Souvent la première requête d'un workflow, un `RequestPrdUpdate` ne répond pas à un autre `RequestPrd`.
* `RequestPrdConfirm` : Répond à tous les autres types de `RequestPrd` (à l'exception des `RequestPrdConfirm` eux-mêmes).
* `RequestPrdResponse` : Répond à tous les autres types de `RequestPrd` (à l'exception des `RequestPrdConfirm`, `RequestPrdMessage` et `RequestPrdResponse` eux-mêmes). Dans le cas d'une réponse à un `RequestPrdList` ou d'un `RequestPrdUpdate`, le `RequestPrdResponse` doit obligatoirement être accompagné d'un `RequestPcd`.
On fonction des `RequestPrd` les demandes vont d'adresser à tous les membres de l'`ItemProcess`, ou aux gestionnaires du type d'`Item` concerné ou simplement à l'émetteur, selon :
* `RequestPrdList` : Envoyé aux gestionnaires du type d'`Item` concerné
* `RequestPrdMessage`, avec 2 cas de figure :
* Demande de relais d'une `transaction SP`, dans ce cas, le destinaire du `RequestPrd`assiocié.
* Envoi de message au destinaire du message.
* `RequestPrdUpdate` : Envoyé aux gestionnaires du type d'`Item` concerné
* `RequestPrdConfirm` : Envoyé à l'emetteur du `RequestPrd`assiocié.
* `RequestPrdResponse`, avec 2 cas de figure :
* Réponse à un `RequestPrdList`: envoie à l'emetteur du `RequestPrdList`
* Réponse à un `RequestPrdUpdate`: envoue à tous les membres et à l'émetteur du `RequestPrdUpdate`
Les traitements des `RequestPrd` varient selon leur type, principalement autour des aspects suivants :
* **Notification utilisateur** : Nécessité de notifier l'utilisateur courant, ou non.
* **`transaction SP` + `RequestPrdMessage`** : Envoi d'une `transaction SP` dans un `RequestPrdMessage`, ou non.
* **`RequestPcd` à envoyer** : Envoi d'un `RequestPcd` en complément du `RequestPrd`.
* **`request_type` envoyé à** : Membres qui recevront les `transaction SP` et les `RequestPrdMessage` correspondants, avec les clés de déchiffrement pour les champs confidentiels.
* **Attente d'une réponse `RequestPcd`** : Attente d'un `RequestPcd` en retour, ou non.
* **Attente d'une réponse `RequestPrdResponse`** : Attente d'un ou de plusieurs `RequestPrdResponse` en retour, ou non.
* **Attente d'une réponse `RequestPrdConfirm`** : Attente d'un `RequestPrdConfirm` en retour, ou non.
Ce qui est résumé ici :
| `request_type` | Notification user | `transaction SP` + `RequestPrdMessage` | `RequestPcd` to send | `request_type` send to | `RequestPcd` reply waiting | `RequestPrdResponse` reply waiting | `RequestPrdConfirm` reply waiting |
|----------------------|-----------------------------------------------------------------------------------|----------------------------------------|----------------------|-----------------------------------------------------------------|----------------------------|------------------------------------|-----------------------------------|
| `RequestPrdList` | No | Yes | No | all the members of the `item_name` `Role` into to `ItemProcess` | Yes | Yes | Yes |
| `RequestPrdUpdate` | waiting `sig_value` | Yes | Yes | all the members of all `Role` into to `ItemProcess` | No | Yes | Yes |
| `RequestPrdMessage` | waiting `sig_value` + `message_public`, `message_confidential`, `message_private` | if no `raw_transaction_list` | No | a member of the `ItemProcess` | No | No | if no `raw_transaction_list` |
| `RequestPrdResponse` | waiting `sig_value` | Yes | No | See Received | No | No | Yes |
| `RequestPrdConfirm` | (option) Waiting `code_confirm_enc_by_shared_secret` | Yes | No | See Received | No | No | No |
## 6. <a name='Encryption'></a>Encryption
Schema :
@ -69,31 +140,6 @@ Les `Metadata` des `Item` des `RequestPcd` et les attributs des `RequestPcd` et
* **Données privées** : Chiffrées symétriquement en utilisant la clé de dépense de connexion (`recover`) du signet (voir Login - Specs).
## 5. <a name='Dfinitions'></a>Définitions
* **Portable Contract Document (`RequestPcd`)**: Un format `JSON` chiffré conçu pour contenir des listes d'éléments d'un type spécifique, attachées à un processus (`process_hash`) et soumises aux règles de validation décrites dans le rôle correspondant à ce type d'`Item` dans le `ItemProcess` (`item_type`).
* **Portable Request Document (`RequestPrd`)**: Format `JSON` chiffré contenant les valeurs de signatures et les clés de déchiffrement nécessaires à l'exploitation (requêtes et validation) des `RequestPcd`. Les `RequestPrdResponse` sont collectés pour vérifier le respect des conditions de l'`ItemProcess`. D'autres types de `RequestPrd` incluent :
* `RequestPrdList`: Demande de listes d'`Item`. En réponse, une `RequestPcd` est reçue avec les `RequestPrdResponse` correspondants.
* `RequestPrdMessage`: Envoi de messages publics, confidentiels ou privés et/ou de transactions Silent Payments à diffuser sur le réseau des nœuds de la side chain. Les `RequestPrdMessage` peuvent répondre les uns aux autres.
* `RequestPrdUpdate`: Demande de mise à jour d'une liste d'`Item` (publiée via un `RequestPCD`), qui sera déchiffrée et validée ou non par des `RequestPrdResponse` en retour.
* `RequestPrdConfirm`: Confirmation de la réception des `RequestPrd` (à l'exception de `RequestPrdConfirm` eux-même).
* `RequestPrdResponse`: Réponse aux autres types de `RequestPrd` (à l'exception de `RequestPrdConfirm` et `RequestPrdResponse`).
* **Message**: Enveloppe commune pour les `RequestPrd` et `RequestPcd` lors de leur transmission aux relais et de leur réception depuis les relais. Dans cette enveloppe les `RequestPrd` et `RequestPcd` sont chiffrés par la `ProcessKey` de l'`ItemProcess` (cf. [Specs-Definition](SpecsDefinition.md)) et ajoutés au champs `RequestEnc`.
* **KeyConfidential**: Clé AES-GCM-256 issue du `Diffie-Hellman` de la transaction Silent Payment correspondant à un `RequestPrd`.
* **ProcessKey**: La clé publique de chiffrement d'un `ItemProcess` (trouvée dans un `ItemProcess`, dans son attribut `Item`, dans son attribut `metadata_contract_public`, dans son attribut `meta_data`, dans son attribut `key_list` au premier élément).
* **KeyRecover**: La clé privée de dépense de `recover` du signet, utilisée comme référence pour l'identité.
* **pre-id**: Pré-identifiant des utilisateurs, constitué du hash de la partie 1 de la `KeyRecover`.
## 6. <a name='Principedemessagerie'></a>Principes de messagerie
### 6.1. <a name='Crationetenvoi'></a>Création et envoi
Les `RequestPcd` et les `RequestPrd` sont envoyés sous forme de messages (`JSON`) via les `websockets` des relais.
@ -209,14 +255,6 @@ La création d'un `RequestPrd` suit plusieurs étapes :
Voir [Silent-Payment-Specs.md](Silent-Payment-Specs.md).
| `request_type` | Notification user | `transaction SP` + `RequestPrdMessage` | `RequestPcd` to send | `request_type` send to | `RequestPcd` reply waiting | `RequestPrdResponse` reply waiting | `RequestPrdConfirm` reply waiting |
|----------------------|-----------------------------------------------------------------------------------|----------------------------------------|----------------------|-----------------------------------------------------------------|----------------------------|------------------------------------|-----------------------------------|
| `RequestPrdList` | No | Yes | No | all the members of the `item_name` `Role` into to `ItemProcess` | Yes | Yes | Yes |
| `RequestPrdUpdate` | waiting `sig_value` | Yes | Yes | all the members of all `Role` into to `ItemProcess` | No | Yes | Yes |
| `RequestPrdMessage` | waiting `sig_value` + `message_public`, `message_confidential`, `message_private` | if no `raw_transaction_list` | No | a member of the `ItemProcess` | No | No | if no `raw_transaction_list` |
| `RequestPrdResponse` | waiting `sig_value` | Yes | No | See Received | No | No | Yes |
| `RequestPrdConfirm` | (option) Waiting `code_confirm_enc_by_shared_secret` | Yes | No | See Received | No | No | No |
### 8.4. <a name='Rception-1'></a>Réception
La réception d'un `RequestPcd` suit plusieurs étapes :

5
doc/Specs-Datamodel.md
View File

@ -110,11 +110,6 @@
* 14.6. [PartialOrd, Ord](#PartialOrdOrd)
* 15. [Todo](#Todo)
<!-- vscode-markdown-toc-config
numbering=true
autoSave=true
/vscode-markdown-toc-config -->
<!-- /vscode-markdown-toc -->
# Specs - Datas
## 1. <a name='Documentsderfrence'></a>Documents de référence

2
doc/Specs-Definition.md
View File

@ -25,7 +25,7 @@ Voir [_Doc_references.md](_Doc_references.md).
* **Portable Request Document (`RequestPrd`)**: Format `JSON` chiffré contenant les valeurs de signatures et les clés de déchiffrement nécessaires à l'exploitation (requêtes et validation) des `RequestPcd`. Les `RequestPrdResponse` sont collectés pour vérifier le respect des conditions de l'`ItemProcess`. D'autres types de `RequestPrd` incluent :
* `RequestPrdList`: Demande de listes d'`Item`. En réponse, une `RequestPcd` est reçue avec les `RequestPrdResponse` correspondants.
* `RequestPrdMessage`: Envoi de messages publics, confidentiels ou privés et/ou de transactions Silent Payments à diffuser sur le réseau des nœuds de la side chain. Les `RequestPrdMessage` peuvent répondre les uns aux autres.
* `RequestPrdMessage`: Envoi de messages publics, confidentiels ou privés et/ou de transactions Silent Payments des autres `RequestPrd` à diffuser sur le réseau des nœuds de la side chain. Les `RequestPrdMessage` peuvent répondre les uns aux autres.
* `RequestPrdUpdate`: Demande de mise à jour d'une liste d'`Item` (publiée via un `RequestPCD`), qui sera déchiffrée et validée ou non par des `RequestPrdResponse` en retour.
* `RequestPrdConfirm`: Confirmation de la réception des `RequestPrd` (à l'exception de `RequestPrdConfirm` eux-même).
* `RequestPrdResponse`: Réponse aux autres types de `RequestPrd` (à l'exception de `RequestPrdConfirm` et `RequestPrdResponse`).