* 1. [Objectif](#Objectif) * 2. [Portée](#Porte) * 3. [3. Documents de référence](#Documentsderfrence) * 4. [Commun aux `RequestPcd` et RequestPrd](#CommunauxRequestPcdetRequestPrd) * 4.1. [Création et envoi](#Crationetenvoi) * 4.2. [Réception](#Rception) * 5. [Fonction des RequestPcd](#FonctiondesRequestPcd) * 5.1. [Schéma des flux](#Schmadesflux) * 5.2. [Création et envoi](#Crationetenvoi-1) * 5.3. [Réception](#Rception-1) * 6. [Fonction des RequestPrd](#FonctiondesRequestPrd) * 6.1. [Schéma des flux](#Schmadesflux-1) * 6.2. [Fonctionnalités optionnelles](#Fonctionnalitsoptionnelles) * 6.3. [Création et envoi](#Crationetenvoi-1) * 6.4. [Réception](#Rception-1) * 7. [RequestPrdList - Demande de Listes ( RequestPcd)](#RequestPrdList-DemandedeListesRequestPcd) * 7.1. [Schéma des flux](#Schmadesflux-1) * 7.2. [Création : Datas spécifiques](#Cration:Datasspcifiques) * 7.3. [Réception : Datas spécifiques](#Rception:Datasspcifiques) * 8. [RequestPrdMessage - Envoi de Messages](#RequestPrdMessage-EnvoideMessages) * 8.1. [Schéma des flux](#Schmadesflux-1) * 8.2. [Création : Datas spécifiques](#Cration:Datasspcifiques-1) * 8.3. [Réception : Datas spécifiques](#Rception:Datasspcifiques-1) * 9. [RequestPrdUpdate - Mises à Jour de RequestPcd](#RequestPrdUpdate-MisesJourdeRequestPcd) * 9.1. [Schéma des flux](#Schmadesflux-1) * 9.2. [Création : Datas spécifiques](#Cration:Datasspcifiques-1) * 9.3. [Réception : Datas spécifiques](#Rception:Datasspcifiques-1) * 10. [RequestPrdConfirm - Confirmation de Réception](#RequestPrdConfirm-ConfirmationdeRception) * 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. [RequestPrdResponse - Répondre à une Demande](#RequestPrdResponse-RpondreuneDemande) * 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. [Exemples de Code](#ExemplesdeCode) * 13. [Todo](#Todo) # `RequestPrd` et `RequestPcd` - Specs ## 1. Objectif Le but de cette section est d'introduire les Portable Contract Document (`RequestPcd`) et Portable Request Document (`RequestPrd`) comme éléments fondamentaux du système 4NK. Ces documents jouent un rôle crucial dans la sécurisation des échanges de données et la gestion des identités numériques au sein d'un réseau décentralisé. Ils permettent de définir des contrats numériques, de gérer les permissions d'accès, et de faciliter les communications et les opéraations sécurisées entre les différents acteurs du réseau. ## 2. Portée La spécification couvre la conception, le développement, et l'application pratique des `RequestPcd` et `RequestPrd`.Elle vise à expliquer leur fonctionnement, leur structure, et la manière dont ils contribuent à l'écosystème 4NK en offrant une méthode sécurisée et efficace pour le partage d'informations et la validation des transactions. Les `RequestPcd` et `RequestPrd` encapsulent les données contractuelles et les requêtes dans un format standardisé, assurant l'intégrité, la confidentialité, l'authenticité et la validation des informations échangées. ## 3. 3. Documents de référence Voir [_Doc_references.md](_Doc_references.md). ## 4. Commun aux `RequestPcd` et RequestPrd Encryption :  ### 4.1. Création et envoi Les `RequestPcd` et les `RequestPrd` sont envoyés sous forme de `message` (JSON) depuis les websockets des relais. Les messages contiennent des `RequestPrd` ou des `RequestPcd` encapsulés dans l'attribut `request_enc`, chiffré par la clé `ProcessKey` du `ItemProcess` concerné. **Création du message et envoi**: voir [Message-SP-Specs.md](Message-SP-Specs.md). ### 4.2. Réception Les `RequestPcd` et les `RequestPrd` sont reçus sous forme de `message` (JSON) depuis les websockets des relais. Les messages contiennent des `RequestPrd` ou des `RequestPcd` encapsulés dans l'attribut `request_enc`, chiffré par la clé `ProcessKey` du `ItemProcess` concerné. A la réception des messages, ils sont tous déchiffrés puis conservés ou non en fonction du `process hash` du `RequestPcd` ou du `RequestPrd` (dans l'attribut `request`). Si le `process hash` n'est pas reconnu, le message est ignoré. Les `RequestPrd` et `RequestPcd` sont au format JSON. Voir [Specs-Datamodel.md](Specs-Datamodel.md). Les types `RequestPrd` et `RequestPcd` sont distingués par l'attribut `request_type` dans le `message`. En cas de `RequestPcd` ou `RequestPrd` en relation via `RequestPcd_reference_hash` ou `request_prd_reference_hash` ou `RequestPcd_origin_hash` ou `request_prd_origin_hash` ou `item_reference_hash` (dans des RequestPcd), il avoir reçu ou attendre ces documents pour traiter le message. **Réception du message**: voir [Message-SP-Specs.md](Message-SP-Specs.md). Pour les `RequestPcd` et les `RequestPrd` il faut vérifier que le hash du document n'est pas déjà en cas, si c'est le cas, le message est ignoré. ## 5. Fonction des RequestPcd Les Portable Contract Documents ( RequestPcd) sont des documents JSON qui encapsulent les listes versionnées d'`Item` dont les attributs sont chiffrés soit en public, soit en confidentiel par rôles soit en privé (cf. [Specs-Security.md](Specs-Security.md)). Les `Item` ainsi échangés via les `RequestPcd` sont vérifiés par les `RequestPrdResponse` afin de vérifier les validations de ces données et leurs conformités avec les `ItemProcess` et les `members` concernés. ### 5.1. Schéma des flux  ### 5.2. Création et envoi La création d'un `RequestPcd` suit plusieurs étapes : 1. Récupération de la dernière version de la liste du type d'`Item` à partir de la source de données, telle qu'une base de données ou un système de stockage. 2. Ajouts et modifications eventuelles des `Item` 3. Chiffrement des attributs de chaque Item selon les règles de confidentialité et de partage des clés (cf. [Specs-Security.md](Specs-Security.md)). 4. Chiffrement du `RequestPcd` avec la clé `ProcessKey` du `ItemProcess` concerné. 5. Traitements communs aux `RequestPcd` et RequestPrd ### 5.3. Réception La réception d'un `RequestPcd` suit plusieurs étapes : 1. Traitements communs aux `RequestPcd` et RequestPrd 2. Recherche des `RequestPrd` en relation via `RequestPcd_reference_hash` et `RequestPcd_origin_hash` de ces `RequestPrd` et attente si nécessaire. 3. Déchiffrage des attributs publics des `Item` des `RequestPcd` avec la `ProcessKey` du `ItemProcess` concerné. 4. Déchiffrage des attributs confidentiels des `Item` des `RequestPcd` avec les clés de déchiffrement depuis l'attribut `RequestPcd_keys_role_confidential_list_enc_by_shared_secret` des RequestPrd. 5. Déchiffrage des attributs privés des `Item` des `RequestPcd` avec la clé privée `KeyRecover` 6. Mise à jour du cache pour les traitement des RequestPrd. ## 6. Fonction des RequestPrd Les Portable Request Documents ( RequestPrd) sont des documents JSON qui encapsulent les valeurs de signatures et les clés de déchiffrement nécessaires à l'interprétation des `RequestPcd` via l'attribut `RequestPcd_keys_role_confidential_list_enc_by_shared_secret`. Ils sont utilisés pour demander des actions spécifiques, telles que l'envoi de messages, la mise à jour des informations contractuelles, ou la confirmation de transactions. Les clés de chiffrement des attributs confidentiels par rôles des `Item` des `RequestPcd` sont chiffrées dans les `RequestPrd` avec le chiffrement du `RequestPrd` par la clé `KeyConfidential` d'une`transaction SP` (cf. [Specs-Security.md](Specs-Security.md)). Ces clés ne sont distribués qu'aux `members` concernés par les `Item` des `RequestPcd` (rôles dans les `ItemProcess` ). Les `RequestPrd` sont de plusieurs types tels que `RequestPrdList`, `RequestPrdMessage`, `RequestPrdUpdate`, etc.: Variations de `RequestPrd` pour différentes actions, telles que l'envoi de messages, la mise à jour des informations contractuelles, ou la confirmation de transactions. ### 6.1. Schéma des flux Pour simplifier les RequestPrdConfirm n'ont pas été représentés dans le schéma.  ### 6.2. Fonctionnalités optionnelles L'attribut `sig_value` permet de donner une valeur aux signatures. Les valeurs des signatures sont définies par rôles dans les `ItemProcess` avec des valeurs valant pour `OK` ou `KO` pour `none` pour les validations des `RequestPrd`. Lorsque que la réponse fait référence à un `RequestPcd` il est précisé dans `RequestPcd_reference_hash`, idem pour les `RequestPrd` avec `request_prd_reference_hash`. Lorsque que la réponse fait suite directement à un `RequestPcd` il est précisé dans `RequestPcd_origin_hash`, idem pour les `RequestPrd` avec `request_prd_origin_hash`. Les `RequestPrdResponse` signalent de façon confidentielle : * soient des conditions ad'hoc déjà remplies via l'attribut `payment_method_enc_by_shared_secret`, `deposit_method_enc_by_shared_secret`, `commitment_method_enc_by_shared_secret`, `commitment_request_pcd_hash_list` pour les paiements et preuves ad'hoc éventuellements associés aux `RequestPcd` de la nouvelle version. * soient des appels pour recevoir les moyens de satisfaire ces conditions via les attributs `ask_payment_method_enc_by_shared_secret`, `ask_deposit_method_enc_by_shared_secret`, `ask_commitment_method_enc_by_shared_secret`. Les `Item` associés sont référencés dans des `RequestPcd` identifiés par `payment_request_pcd_hash_list_enc_by_shared_secret`, `cap_request_pcd_hash_list_enc_by_shared_secret` (cas des payments temporaires en l'attente du passage d'un cap), `deposit_request_pcd_hash_list_enc_by_shared_secret` et `commitment_request_pcd_hash_list_enc_by_shared_secret`. Des champs messages peuvent accompagner les `RequestPrd` via `message_public`, `message_confidential`, `message_private`. Il est aussi possible de partager des clés de chiffrement ad'hoc via `certif_key_enc_by_shared_secret`. En plus des horodatages automatique, il est possible de déclarer un timestamp dans `timestamp_declared` qui ne sera pas pris en compte dans le traitement mais qui est ainsi tracé dans les éléments de preuves. Les adresses et les roles sont précisés en cas d'utilisateurs ayant plusieurs roles dans les `ItemProcess` et pour préciser les adresses de réponses en cas d'utilisations en multi-devices. Tous les échanges sont complétés de l'empreinte du device de l'emetteur envoyée de façon confidentielle via `device_footprint_enc_by_shared_secret`. ### 6.3. Création et envoi La création d'un `RequestPrd` suit plusieurs étapes : 1. Récupération des clés de chiffrement confidentiel des attributs des items d'un RequestPcd. 2. Chiffrement du `RequestPrd` avec la clé `ProcessKey` du `ItemProcess` concerné. 3. Création d'une`adresse SP` SP pour le partage de la `KeyConfidential` et pour l'horodatage du hash du `RequestPrd` dans la side chain. 4. Création du `message` contenant le `RequestPrd` chiffré, la preuve de travail, l'adresse de faucet 5. Sélection de 4 relais pour le message selon l'historique des pings et des réponses retournées. 6. Sélection de 4 noeuds de signet pour l'envoi de la`transaction SP`. 7. Chiffrement des données confidentielles du `request_prd` avec la `KeyConfidential` de la`transaction SP`. 8. Envoi du message aux relais 9. Envoi de la transaction aux noeuds de signet à travers un `RequestPrdMessage` pour la publication de la`transaction SP` avec le hash du `RequestPrd` dans l'attribut `request_prd_reference_hash`. 10. Mis à jour du cache avec les nouveaux `RequestPrd` envoyé (pas de mis en cache du `RequestPrdMessage`) 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 | ### 6.4. Réception La réception d'un `RequestPcd` suit plusieurs étapes : 1. Traitements communs aux `RequestPcd` et RequestPrd 2. Recherche des `RequestPcd` en relation via `RequestPcd_reference_hash` et `RequestPcd_origin_hash` et attente si nécessaire et traitement de ceux ci. 3. Vérification de la conformité des `RequestPcd` en relation. 4. Recherche des `RequestPrd` en relation via `request_prd_reference_hash` et `request_prd_origin_hash` et attente si nécessaire et traitement de ceux ci. 5. Vérification de la conformité des `RequestPrd` en relation. 6. Recherche de l'`Item` associé via `item_reference_hash` et attente si nécessaire et traitement de celui ci. 7. Déchiffrage des attributs confidentiels notés `_enc_by_shared_secret` depuis la `KeyConfidential` de la`transaction SP` correspondante via hash du `RequestPrd` dans l'output `2` de la transaction. 8. Mise à jour du cache pour les traitement des RequestPrd. 9. Voir `RequestPrdConfirm` création et envoi. 10. Validation des conditions définies dans le `ItemProcess` pour ce d'`Item` avec le `Role` correspondant dans le `ItemProcess` et dans ce rôles les conditions pour ce type de `RequestPrd` (dans l'attribut `request_prd_type`) telles que définies dans [Specs-Process-Roles-Specs.md](Specs-Process-Roles-Specs.md). 11. Traitements spécifiques au type de RequestPrd. | `request_type` | Notification user | `RequestPrdConfirm` to send | `RequestPcd` to send | `RequestPrdResponse` to send | `RequestPrdResponse` reply waiting | `RequestPrdConfirm` reply waiting (from `RequestPrdResponse` send ) | |----------------------|-----------------------------------|------------------------------|----------------------|-----------------------------------------------------------------|------------------------------------|---------------------------------------------------------------------| | `RequestPrdList` | No | Yes | Yes | all the members of the `item_name` `Role` into to `ItemProcess` | No | Yes | | `RequestPrdUpdate` | Info | Yes | No | all the members of all `Role` into to `ItemProcess` | Yes (other members) | Yes | | `RequestPrdMessage` | Waiting `RequestPrdMessage` reply | if no `raw_transaction_list` | No | No | No | No | | `RequestPrdResponse` | Info | Yes | No | No | No | No | | `RequestPrdConfirm` | Info | No | No | No | No | No | ## 7. RequestPrdList - Demande de Listes ( RequestPcd) Utile pour les utilisateurs cherchant à consulter ou à explorer des listes de contrats, de membres, ou d'autres items dans le résweau. Chaque `RequestPcd` liste des `Item` d'un même type, par exemple les `ItemProcess`, les `ItemMember`, les `ItemPeer`, les `ItemPayment`, etc. ### 7.1. Schéma des flux Pour simplifier les RequestPrdConfirm n'ont pas été représentés dans le schéma.  ### 7.2. Création : Datas spécifiques 1. Traitements des `RequestPrd`, avec le `type_request` 2. `item_member_enc_by_sp_shared_secret` en cas de création d'un nouveau ItemMember (création d'un identité numérique), uniquement vers les gestionnaires des membres 3. `pre_id_sp_enc_by_shared_secret` en cas de connexion avec une identité numérique existante, uniquement ver les gestionnaires des membres ### 7.3. Réception : Datas spécifiques La réception d'un `RequestPrdList` suit plusieurs étapes : 1. Traitements des `RequestPrd` 2. Recherche en cache de la dernière version de la liste du type d'`Item` concerné (voir `RequestPcd` Création et envoi vers l'émetteur du `RequestPrdList`) 3. Si `item_member_enc_by_sp_shared_secret` en cas de création d'un nouveau ItemMember (création d'un identité numérique), uniquement vers les gestionnaires des membres et ajout en cache sans modifier la liste des membres et associé au `pre_id` contenu dans l'`ItemMember` créé. 4. Si `pre_id_sp_enc_by_shared_secret` en cas de connexion avec une identité numérique existante, uniquement ver les gestionnaires des membres pour renvoi du shard correspondant dans le `RequestPrdResponse` ## 8. RequestPrdMessage - Envoi de Messages Le `RequestPrdMessage` facilite l'envoi de messages sécurisés entre utilisateurs ou entre utilisateurs et processus/contrats. Permet la communication : * directe et sécurisée au sein du réseau, supportant des échanges d'informations critiques ou des notifications entre parties. * des`transaction SP` au format `raw` dans l'attribut `raw_transaction_list` pour la publication de la transaction dans la side chain. Les `RequestPrdMessage` répondent aux `RequestPrdMessage` sauf en cas d'envoi de `raw_transaction_list` (cas d'utilisation du afin de transaférer la `transaction SP` d'un autre `RequestPrd`). ### 8.1. Schéma des flux Pour simplifier les RequestPrdConfirm n'ont pas été représentés dans le schéma. Cas d'un RequestPrdMesage avec `raw_transaction_list` vide (et son RequestPrdMessage avec `raw_transaction_list` non vide).  ### 8.2. Création : Datas spécifiques 1. Traitements des `RequestPrd`, avec le `type_request` spécifique à `RequestPrdMessage` 2. Cas de la transmission d'une `Transaction SP` d'un autre vRequestPrd` au format `raw` dans l'attribut `raw_transaction_list` pour la publication de la transaction dans la side chain. ### 8.3. Réception : Datas spécifiques 1. Traitements des `RequestPrd` ## 9. RequestPrdUpdate - Mises à Jour de RequestPcd `RequestPrdUpdate` est conçu pour demander des mises à jour des listes via des nouvelles versions de `RequestPcd`. Basé sur le `RequestPrd`. avec des additions pour spécifier les modifications demandées, y compris de nouveaux attributs ou valeurs à mettre à jour : Essentiel pour les utilisateurs ou les processus nécessitant de mettre à jour des informations contractuelles ou des attributs d'items, assurant la pertinence et l'actualité des données dans le système. Par exemple, mettre à jour la liste des membres permet d'ajouter de nouveaux utilisateurs sur un `ItemProcess` , la mise à jour de la liste des `ItemProcess` permettra de leur affecter un nouveau `Role`. Les `RequestPrdUpdate` signalent au réseau via l'attribut `RequestPcd_new_version_hash` les nouvelles version des RequestPcd. ### 9.1. Schéma des flux Pour simplifier les RequestPrdConfirm n'ont pas été représentés dans le schéma.  ### 9.2. Création : Datas spécifiques 1. Traitements des `RequestPrd`, avec le `type_request` spécifique à `RequestPrdUpdate` 2. Pas de data spécifiques. ### 9.3. Réception : Datas spécifiques La réception d'un `RequestPrdUpdate` suit plusieurs étapes : 1. Traitements des `RequestPrd` 2. Comparaison de la dernirère version du `RequestPcd` en cache et de nouvelle version du `RequestPcd` associé via `RequestPcd_new_version_hash` et attente si nécessaire. ## 10. RequestPrdConfirm - Confirmation de Réception Le `RequestPrdConfirm` est utilisé pour confirmer la réception et le traitement de demandes ou de transactions, jouant un rôle crucial dans la validation des actions au sein du réseau. Les `RequestPrdList`, `RequestPrdUpdate`, `RequestPrdMessage`, `RequestPrdResponse` et `RequestPrdKeyHello` reçoivent systématiquement un `RequestPrdConfirm` depuis leur réception par le destinataire. `code_confirm_enc_by_shared_secret`: Un code de confirmation chiffré qui valide l'authenticité et l'intégrité de la réponse, assurant que la confirmation est sécurisée et provient de la source attendue. Dans ce cas un output spécifique chiffré par la clé `KeyConfidential` précise ce code, à confirmer dans le RequestPrdConfirm. ### 10.1. Schéma des flux  ### 10.2. Création : Datas spécifiques 1. Traitements des RequestPrd, avec le `type_request` spécifique à `RequestPrdConfirm` 2. Communication éventuelle d'un `code_confirm_enc_by_shared_secret` à confirmer dans le `RequestPrdConfirm`. ### 10.3. Réception : Datas spécifiques 1. Traitements des `RequestPrd`, pas de traitement suppplémentaire. 2. Vérification du `code_confirm_enc_by_shared_secret` dans le `RequestPrdConfirm` reçu. ## 11. RequestPrdResponse - Répondre à une Demande Le `RequestPrdResponse` permet de répondre spécifiquement à des `RequestPrd` reçus, facilitant un échange interactif d'informations ou de décisions entre les parties. Les `RequestPrdResponse` répondent aux `RequestPrdList`, `RequestPrdUpdate`. Utilisé pour fournir des feedbacks, des confirmations, ou des instructions supplémentaires en réponse à des demandes initiales, supportant une communication bidirectionnelle sécurisée et vérifiable. Aussi le moyen de demander des moyens de paiement ou de dépot ou de preuve, puis de partager le payload de ces actions. ### 11.1. Schéma des flux Pour simplifier les RequestPrdConfirm n'ont pas été représentés dans le schéma.  ### 11.2. Création : Datas spécifiques 1. Traitements des RequestPrd, avec le `type_request` spécifique à `RequestPrdResponse` 2. Attente de la valeur de la signature de l'utilisateur `sig_value` (si non automatique) 3. En cas de réponse à `RequestPrdKeyList` :`pre_id_enc_by_sp_shared_secret` avec les shards correspondants à la `pre-id` demandée. 4. (option) `shared_secret_key` paratage d'une clé de chiffrement ad'hoc ### 11.3. Réception : Datas spécifiques 1. Traitements des `RequestPrd` 2. Vérification des conditions de validation des RequestPcd associés. 3. En cas de réponse reçue à `RequestPrdList` : Récupération des shards correspondants à la `pre-id` demandée et génération de la clé `KeyRecover` ## 12. Exemples de Code ## 13. Todo * [ ] Diagrammes de séquences