Vocabulaire de base pour comprendre Duniter-v2s (lecture fortement recommandée pour tous)

:arrow_heading_down:
Ce sujet liste du vocabulaire de base pour comprendre les concepts de Duniter-v2s, sa lecture est vivement recommandée, cela vous aidera beaucoup à comprendre les discussions autour de Duniter-v2s (la réimplémentation de Duniter basée sur Substrate).

:warning: Rédaction inachevée, les termes vont être ajoutés au fur et à mesure. :warning:

:white_check_mark: Vous pouvez lire dans n’importe-quel ordre, tous les termes se font référence les uns aux autres, il n’y a pas d’ordre plus facile où plus logique.

La description de chaque terme commence par une définition courte et une explication superficielle, puis est suivie par des explications plus détaillées et plus techniques, il est recommandé de tout lire si ce n’est pas inconfortable pour vous, vous apprendrez beaucoup, comprendrez mieux, et cela devrait améliorer sensiblement la qualité de vos interventions et contributions :slight_smile:

Cliquez sur un terme pour dérouler sa description :

AccountId

AccountId

Quelque chose qui identifie un compte, dans la plupart des runtimes substrate il s’agit de 32 octets libres qui encode une clé publique. Et c’est le cas également dans Duniter-v2s. Notez bien que cet identifiant de compte n’indique pas le type de cryptographie de la clé publique qu’il contient, cette information ne servant que pour vérifier une signature, elle n’est associée qu’à cette dernière.

Authority / Autorité

Authority / Autorité

Une authorité est un compte qui est inscrit dans la « Session » actuelle, ce qui signifie qu’il participe actuellement à la co-création des blocs, le nœud « Validateur » associé doit impérativement être en ligne et correctement synchronisé au réseau, sinon quoi des sanctions automatiques s’appliquent, dont éventuellement l’exclusion des « Session » suivantes.

Call

Call

Une fonction d’une pallet (voir section « pallet ») qui est « appelable » ("dispatchable" in english) et ses paramètres d’entrées.

Par exemple, un simple virement de Ğ1 correspond au call balances.transfer(dest, value)dest est le destinataire et value le montant en centimes de G1.

Un call est toujours exécuté par une « Origine » (voir section « Origine »).

L’exécution d’un call peut être déclenchée par :

  • Un Extrinsic signé, l’origine sera alors nécessairement Signed(account_id)
  • Un Extrinsic non signé, l’origine sera alors None
  • Un Hook (voir section hook)
  • Un autre call

Généralement, les extrinsic non-signés sont interdits, ou limités à des cas bien particuliers, comme quelque chose qui est soumis par l’auteur du bloc lui-même, voir section « Inhérent ».

Une grande partie de la puissance et de la simplicité de susbtrate viens du fait qu’un call peut en exécuter un autre, et qu’un call peut contenir d’autres call en paramètre !

Par exemple, le call utility.batch_all(calls) prend en paramètre un tableau de calls, et permet de les exécuter tous dans l’ordre fourni de manière atomique, si l’un des call échoue, ils sont tous annulés comme si rien ne s’était produit.

Par exemple, dans Duniter-v2s, le call identity.create_identity exécute le call cert.add_cert, ce qui permet d’implémenter facilement le fait que « Le créateur de l’identité est également sont premiers certificateur ».

Client

Client

Le binaire livré et installé par les gestionnaires de nœuds. Le Client est aussi parfois nommé « Binary » ou « Node ».
Le client désigne tout ce qui ne se trouve pas dans le Runtime.

Le logiciel duniter-v2s contient à la fois un Client substrate ET des runtimes (un par monnaie).

Extrinsic

Extrinsic

Un Extrinsic est l’équivalent de ce que l’on nommait un « document » dans Duniter v1.

Un Extrinsic contient les cinq éléments suivants, tous sérialisés au format SCALE :

  1. La clé publique de l’émetteur (32 octets libres)
  2. Des SignedExtra : métadonnées configurables.
  3. Un Call
  4. Le type de cryptographie sur un octet (0x00: Ed25519, 0x01=sr25519)
  5. La signature des quatre éléments ci-dessus (64 octets)

Les SignedExtra sont détaillés dans ce sujet : [lien à venir]

Externalities / Externalités

Externalities / Externalités

Ensemble des « host fonction » que le Client(=host) met à disposition du runtime.
Par exemple, les fonctionnalités de cryptographie sont fournies via des externalités.

Le runtime déclare la liste des externalités dont il a besoin, et elle sont toutes checkées lors du chargement du runtime, si le client ne les définit pas toutes, le runtime ne peut pas être utilisé.

En fonction du contexte d’exécution du runtime, certaines externalités ne sont pas activées, mais elles doivent tout de même être toutes définies et déclarées coté Client pour que le runtime puisse être lancé.

Par exemple, les offchain worker ont accès à des externalités permettant d’obtenir des données du monde extérieur (nombre aléatoire, requete http, etc), ces externalités sont bien évidemment désactivées dans le contexte de l’exécution d’un bloc (on parle de « contexte onchain »).

Full node / Full client

Full node / Full client"]

Un « full node » (où « full client ») est un nœud duniter-v2s qui exécute tous les blocs (ce qui revient à les vérifier intégralement), et qui stocke l’entièreté du storage onchain.

Certains « full node » peuvent en plus créer des blocs, on dit alors que ce sont des nœuds ayant le rôle « Authority ».

Un « full node » peut exposer où non une API RPC.

Un « full node » doit toujours exposer une API libp2p, afin de communiquer avec les autres fulls node et de fournir des informations aux light nodes (Voir « Light node »).

Light Node / Light client

Light Node / Light client

Un « light node » est un nœud qui récupère uniquement les headers des blocs. Les headers contienent le numéro du bloc, sont hash, la signature de l’auteur et les merkle root hash du storage et des extrinsic.

Généralement, un « light node » est installé localement sur la machine de l’utilisateur final, et expose une API RPC locale consommée directement par les applications et wallet.

Lorsqu’une application (un wallet par exemple), demande au light node une donnée du onchain storage, le light node va récupérer cette donnée auprès d’un full node, avec une merkle proof, et comme le light node connaît le merkle root, il peut vérifier l’authenticité de la donnée.

Avoir un light node en local garanti à l’utilisateur un niveau maximal de décentralisation, car il n’a alors pas besoin de faire confiance à un nœud installé sur un autre ordinateur auquel il n’a pas accès.

Origin

Origin

À comprendre comme « L’origine d’un call ». Cela désigne en quelque sorte « qui » est l’émetteur du call, ça permet de gérer les droits.
La liste des origines possibles est définie par le runtime (voir section « Runtime »). Par défaut un runtime substrate contient au moins trois origines :

  • Signed(account_id)
  • Root
  • None

Mais on peut en définir d’autres, dans duniter-v2s on aura par exemple l’origine SmithsMembers(a, b) qui désigne une proportion des membres forgerons (a membres forgerons à l’origine du call sur b membres forgerons au total).

Généralement, le code d’un « Call » commence par vérifier que l’« Origin » est autorisée à exécuter ce « Call », et si ce n’est pas le cas, l’exécution du call échoue avec l’erreur BadOrigin.

RPC

RPC

RPC est un acronyme anglais qui signifie litéralement « Remote Procedure Call », que l’on pourrait traduire en français par « Appel de Méthode Distante ».

Dans le contexte de Substrate (et de Duniter-v2s), le terme « RPC » désigne plus précisément l’API JSON-RPC exposée par le « Client » Substrate.

Cette API expose un unique endpoint HTTP et un unique endpoint WS. On lui indique la « méthode » RPC que l’on souhaite appeler, avec ses paramètres d’entrée. Le client substrate va alors exécuter cette méthode puis renvoyer le résultat via l’API.

C’est cette API qui est utilisée par les « Wallet » pour soumettre des « Transactions ».
Cette API RPC permet également de lire le contenu du « onchain storage », et bien d’autres choses encore.

Il existe 2 modes différents pour l’API RPC du substrate, le mode Safe (qui peut être exposé publiquement), et le mode Unsafe (qui ne doit pas àtre exposé pulbiquement).

Le node Unsafe contient des méthodes permettant d’administrer un nœud « Validateur », ainsi que des méthodes coûteuses en calcul qui ne doivent être exposés qu’a des partenaires privés identifiés.

Runtime

Runtime

C’est la partie de code qui contient les « Pallet » et leurs « Call », elle est compilée en webassembly et le code webassembly du runtime est inclus dans le storage onchain, ce qui permet de mettre à jour le code du runtime via… des règles onchain définies par le runtime.

Plus précisément c’est le call system.set_code(code) qui met à jour le Runtime, il doit être exécuté avec l’Origine Root.
Cela permet de faire des mises à jour dites « forkless », c’est dire que lorsqu’un bloc contient le call set_code, le prochain bloc va automatiquement utiliser le nouveau runtime, sans que les gestionnaires de nœud n’aient besoin de mettre à jour leur nœud.

SCALE

SCALE

Format d’encodage des données propre à substrate et utilisé notamment pour encoder les extrinsic, les blocs, les évènements, les entrées dans le storage onchain… à peu près tout quoi!

Retrouvez sur de site de substrate la définitaion de ce format ainsi qu’une liste le bibliothèques permettant de le gérer: https://docs.substrate.io/v3/advanced/scale-codec/

Session

Session

Durée pendant laquelle la liste des autorités ne peut pas changer. La liste des authorités pour la session N est déterminée au 1er bloc de la session N-1.
Une Session à généralement une durée fixe de l’ordre de quelques heures.

Storage onchain

Storage onchain

L’ensemble des informations permettant de décrire l’état courant du système.
La partie du runtime qui exécute un bloc peut être théorisée comme une Fonction de Changement d’État (State Transition Function in English), qui prend en entrée l’état actuel(=le « onchain storage » du dernier bloc) ainsi que le prochain bloc. Cette fonction produit en sortie un nouvel état (un nouveau « onchain storage »).

Toute exécution d’un « Call » ne peut in finé produire que 2 choses: des changements dans le onchain storage et des « Évènements ».

On peut également définir le onchain storage comme l’ensemble des informations nécessaires et suffisantes pour vérifier la validité d’un bloc, dans subtrate c’est strictement équivalent.

Cela correspond à ce que l’on nommait les « index » dans Duniter v1.

L’intégralité du contenu de ce onchain storage est récupérable via l’API RPC.

De plus, ce onchain storage est stocké par bloc. Par défaut, un nœud conserve en base de donnée les onchain storage des 256 derniers blocs. Mais certains nœuds, dits nœuds d’archive, conservent tout les onchain storage de tout les blocs, il est donc possible de connaître l’état passé à n’importe-quel bloc, et ceux directement via l’API RPC.

Transaction

Transaction

:warning: Aucun rapport avec une transaction au sens d’un « transfert de monnaie », c’est beaucoup plus large que ça !

Nom que l’on donne à un « Extrinsic » lorsque l’on se situe côté « Client ».

Ce qui est une « Transaction » côté « Client » devient un « Extrinsic » côté « Runtime ». C’est la même chose, mais donner un nom différent permet de savoir si on parle côté Runtime où côté Client.

Validateur

Validateur

Un validateur est un nœud Substrate qui à vocation à participer à la co-création des blocs, il ne doit pas exposer d’API RPC publique, et doit impérativement être déployé sur une machine dont les ressources sont supérieures où égale à la machine de référence utilisée pour le « Weight Benchmarking » étalonnage des poids.

Concrètement c’est le même logiciel, mais lancé avec l’option --validator.

Wallet

Wallet

Logiciel permettant aux utilisateurs générer des transactions, de les signer et de les soumettre au réseau (généralement via l’API RPC).

Généralement, les wallet se chargent également de récupérer des informations dans le storage onchain (via l’API RPC) pour les afficher aux utilisateurs, par exemple le solde de leur compte, le nombre de certifications qu’ils ont reçues, etc

De plus, certains wallet se chargent également de récupérer des données passées auprès d’indexeurs afin de fournir des informations utiles aux utilisateurs mais qui ne se trouve plus dans le storage onchain, par exemple l’historique des transferts de monnaie passés dont le compte est émetteur ou récepteur.

9 « J'aime »

Des questions ? Où des suggestions d’amélioration ? Merci de poster sur ce sujet :

:arrow_right: Discussions autour du sujet "vocabulaire de base pour comprendre Duniter-v2s"