Comment bâtir un produit sur un gateway Label 309

Pour intégrer une fonction de preuve d'existence sans exploiter vous-même une blockchain, vous bâtissez sur un gateway. Un gateway Label 309 est le moteur de publication d'un produit de preuve d'existence : il accomplit le gros du travail opérationnel — devis, téléversements, soumission des transactions Cardano, confirmation, gestion des réorganisations, indexation des records, soldes de compte, financement du stockage, clés API et webhooks — et expose le tout via du HTTP standard. Votre produit appelle ces points de terminaison et garde la maîtrise de tout ce que vos utilisateurs voient vraiment : l'interface, la relation de facturation, le flux métier et la marque.

Le cœur du gateway est open source, et CardanoWall en est le produit de référence. Ce qui est utile pour les développeurs, c'est qu'il n'existe aucune porte dérobée : CardanoWall atteint le gateway par les mêmes points de terminaison publics que vous utiliseriez, si bien que tout schéma qui fonctionne pour le produit de référence fonctionne aussi pour vous.

Qui devrait bâtir sur un gateway ?

Bâtissez sur un gateway si vous voulez intégrer la preuve d'existence au sein d'un produit, et non comme une action manuelle qu'un utilisateur effectue sur un site web.

Voici quelques cas d'usage adaptés :

produits de notarisation de documents ;
archives de pièces de conformité ;
plateformes de provenance de l'IA et de gouvernance des jeux de données ;
systèmes de preuve d'intégration continue ;
outils de preuve juridique ;
portails de divulgation chiffrée ;
services d'authenticité des médias ;
outils internes d'audit en entreprise ;
pages de preuve pour éditeurs.

Dans tous ces cas, les utilisateurs ne veulent pas avoir à penser à la construction des transactions Cardano, au financement des UTxO, aux crédits de stockage ou aux confirmations sur la chaîne. Ils veulent un flux de travail qui produit des preuves durables et vérifiables. Le gateway rend ce flux possible sans que votre équipe ait à devenir un opérateur d'infrastructure Cardano.

Que possède le gateway, et que possède votre produit ?

Cette répartition est l'essentiel du propos, alors autant l'énoncer clairement. Le gateway possède le plan de base — le pipeline de publication et tout l'état monétaire, sur la chaîne et de stockage qui le sous-tend :

devis, téléversement et publication ;
construction, soumission, confirmation et gestion des réorganisations des transactions Cardano, ainsi que les remboursements en cas d'échec définitif ;
téléversement du contenu et du texte chiffré vers le stockage, et le financement du stockage qui les rend possibles ;
un index partagé des records sur la chaîne, couvrant chaque record Label 309 du réseau ;
les soldes de compte et les écritures de grand livre qui les font évoluer ;
la tarification de change et les marges ;
les identifiants API et la livraison des webhooks.

C'est un travail d'infrastructure. En production, il doit être précis, observable et sans surprise. Votre application ne devrait pas le réimplémenter, sauf si exploiter un gateway est précisément votre métier — et si c'est le cas, voyez exploiter votre propre gateway.

Votre produit possède le plan fournisseur — tout ce qui relève du fournisseur :

les comptes et les sessions des utilisateurs ;
l'intégration et la facturation ;
les autorisations produit ;
votre interface et vos courriels ;
la tarification que vous présentez à vos clients ;
des concepts métier tels que « dossier », « version », « jeu de données » ou « lot de pièces » ;
des modèles de lecture construits à partir des événements du gateway ;
les flux de support.

Le gateway n'a pas besoin de savoir qu'une preuve se rapporte à un procès, à une session d'entraînement de modèle, à un lot de conformité trimestriel ou à un numéro de magazine. Il lui suffit de publier des records Label 309 corrects et de maintenir l'état opérationnel qui les entoure. Cette séparation garde les deux systèmes plus propres : votre produit peut être reconstruit ou rebaptisé sans toucher à l'état de la chaîne ou de la monnaie, et le gateway peut être mis à niveau sans connaître l'existence de votre produit.

Comment appeler le plan de données pour le compte d'un utilisateur ?

Le plan de données (/api/v1/*) est l'API tournée vers le compte. Utilisez-le chaque fois que l'action s'effectue pour le compte d'un utilisateur ou d'un compte :

établir le devis d'une publication ;
téléverser du contenu ou du texte chiffré ;
publier un record ;
lire un solde ou le grand livre du compte ;
lister, récupérer ou vérifier des records publics ;
enregistrer des webhooks à portée de compte.

Dans un produit qui enveloppe le gateway, votre backend émet un token de compte de courte durée pour le compte gateway de l'utilisateur, et le client appelle le plan de données avec uniquement les portées dont il a besoin. Les portées constituent la frontière des autorisations : un écran de publication a besoin de poe:create, un widget de solde a besoin de account:read, et les points de terminaison des records publics n'ont besoin d'aucun identifiant — ils répondent aux appelants anonymes, ce qui fait de l'index un bien public plutôt qu'une vue propre à chaque client.

Les tokens sont de courte durée par conception (une heure par défaut). Émettez-en un par session et réémettez-le à l'expiration : un token compromis devient ainsi un problème d'une heure plutôt qu'un incident. Et n'envoyez jamais d'identifiants d'opérateur au navigateur — c'est la règle que la section suivante existe pour protéger.

Comment appeler le plan de contrôle en tant qu'opérateur ?

Le plan de contrôle (/control/v1/*) est réservé aux backends de confiance et aux opérateurs. Utilisez-le pour :

créer des comptes gateway, et les activer ou les désactiver ;
appliquer des ajustements de grand livre une fois que votre système de facturation a encaissé l'argent ;
définir des marges par compte ;
émettre des tokens de compte et des clés API ;
enregistrer le firehose de webhooks de l'opérateur ;
enregistrer et gérer les portefeuilles et les sources de financement du stockage ;
lire l'état d'audit et l'état opérationnel.

Ce plan vit derrière votre backend. Traitez les identifiants d'opérateur comme des secrets de production dotés d'un pouvoir de dépense — car c'est le cas. Un token d'opérateur de courte durée (24 heures par défaut) gère l'administration courante ; un unique secret racine, conservé dans un coffre à secrets, est réservé aux quelques opérations qui enregistrent les portefeuilles et les sources de stockage.

Le plan de contrôle est ce qui maintient le lien entre votre système de facturation et le solde prépayé du gateway. Un paiement aboutit dans votre système, puis votre backend applique un ajustement de grand livre idempotent au compte gateway. C'est là tout le rail de crédit, et les deux sections suivantes expliquent pourquoi il est conçu exactement ainsi.

Pourquoi ne devriez-vous pas interroger directement les tables du gateway ?

Parce que le schéma n'est pas un contrat — ce sont l'API HTTP et les webhooks qui le sont.

Le moteur du gateway possède ses propres schémas Postgres (cw_core et cw_api). Votre produit ne devrait ni les lire ni y écrire, même lorsque les deux systèmes partagent la même instance Postgres. La coexistence de schémas est une forme de déploiement prise en charge, mais la frontière est le schéma, pas la base de données : ces schémas du moteur sont internes et peuvent changer sans préavis, alors que les plans HTTP et le firehose sont stables. Si vous franchissez cette frontière, une simple mise à niveau du gateway peut silencieusement casser votre produit.

Si vous avez besoin de données que l'API n'expose pas, voyez-y une lacune de l'API à signaler — et non une autorisation de faire des jointures entre schémas.

Comment construire vos propres écrans à partir des événements du gateway ?

Tout produit a besoin de ses propres vues : records envoyés, historique client, soldes, échecs de publication, chronologies de dossiers, lots de pièces, tableaux de bord d'audit. Ne les construisez pas en interrogeant chaque ligne ni en faisant des jointures avec les internes du gateway.

Enregistrez plutôt des webhooks et projetez les événements dans vos propres tables. Le gateway expose un firehose d'opérateur — chaque événement de cycle de vie sur l'instance — ainsi que des abonnements à des webhooks à portée de compte pour des flux plus ciblés. Une vue « messages envoyés » en est l'exemple canonique : consommez les événements de statut de publication, projetez-les dans votre propre table, et affichez à partir de là.

La livraison se fait au moins une fois, alors rendez votre projection idempotente. Un modèle de lecture pragmatique peut s'appuyer sur :

l'identifiant de l'événement ou l'identifiant de livraison (pour qu'une relivraison soit sans effet) ;
l'identifiant de record du gateway ;
l'empreinte de transaction finale ;
votre propre identifiant d'utilisateur ;
votre propre identifiant d'objet métier ;
le statut et les horodatages.

Votre interface affiche alors à partir de vos propres tables, tandis que le gateway demeure l'autorité pour les dépenses, le cycle de vie de la publication et les faits de la chaîne. Chaque livraison est signée ; vérifiez la signature et appliquez une fenêtre de tolérance d'horodatage avant de faire confiance à un événement.

Comment l'argent devrait-il circuler entre votre facturation et le gateway ?

Gardez le modèle simple : le solde du gateway est le solde dépensable, et votre système de facturation n'est qu'un moyen parmi d'autres d'y faire arriver l'argent.

Votre rail de facturation peut encaisser des cartes, des factures, des paiements en cryptomonnaie, des crédits entreprise manuels ou des dotations. Le gateway n'a besoin de rien savoir de tout cela. Le schéma propre est le suivant :

Votre système de facturation confirme un paiement.
Votre backend applique un ajustement de grand livre idempotent au compte gateway, indexé sur l'identifiant du paiement.
Le solde du gateway augmente.
Les futures opérations de publication et de téléversement débitent ce solde.
Si une publication échoue définitivement, le gateway annule lui-même le débit.

Deux conséquences en découlent. D'abord, l'idempotence compte parce que les pipelines de facturation livrent au moins une fois : passez l'identifiant propre du paiement comme référence d'ajustement, et cinq livraisons d'un même paiement créditent le solde une seule fois. Ensuite, ne reproduisez pas le grand livre du gateway dans votre propre table en traitant ce miroir comme la vérité pour vos décisions de dépense — mettez-le en cache pour l'affichage si nécessaire, mais lisez le gateway dès que la décision déplace réellement de l'argent. Comme le gateway émet ses propres remboursements, vous ne devriez pas non plus construire un chemin de remboursement côté fournisseur pour les échecs de publication ; cela rembourserait deux fois.

Où chaque type de clé devrait-il résider ?

Un gateway ne devrait jamais avoir besoin de la graine d'identité d'un utilisateur. Le client ou le SDK peut hacher le contenu, chiffrer les contenus scellés et signer les records localement ; le gateway ne fait que publier les octets du record finalisé et soumettre la transaction Cardano. (Pour comprendre pourquoi cette frontière compte de bout en bout, voyez pourquoi les clés ne quittent jamais l'appareil.)

Une intégration complète comporte plusieurs classes de clés distinctes, et l'erreur à éviter est de les aplatir en un seul « secret d'API ». Leurs rayons d'impact sont très différents :

les graines d'identité des utilisateurs et les clés privées des destinataires — l'identité cryptographique de l'utilisateur, qui a sa place à la périphérie ;
les clés de signature des records dérivées de cette identité ;
les clés API de compte et les tokens de compte de courte durée — qui ont leur place dans le contexte produit ou client qui en a besoin ;
les tokens d'opérateur et le secret racine — qui n'ont leur place que sur des backends de confiance ;
les propres clés de signature Cardano et de stockage du gateway, ainsi que ses secrets de signature de webhooks — qui ont leur place dans le trousseau de clés du gateway.

Associez chaque classe au plus petit endroit capable de la contenir, et une fuite isolée reste circonscrite.

Quand devriez-vous héberger vous-même le gateway plutôt que d'en utiliser un hébergé ?

Hébergez-le vous-même lorsque l'indépendance opérationnelle compte plus que la commodité.

Un gateway hébergé est la voie la plus simple pour la plupart des intégrations : vous publiez via un service prêt à l'emploi sur des surfaces d'API standard, et vous n'exécutez jamais vous-même d'opérations de chaîne ou de stockage. L'auto-hébergement échange cette simplicité contre du contrôle — votre propre financement de portefeuille Cardano, votre propre financement de stockage, vos propres politiques d'opérateur, votre propre disponibilité et vos propres dépendances réseau, vos propres marges, votre propre périmètre de conformité, et aucune dépendance à un tiers pour publier.

Mais le contrôle, c'est aussi de la responsabilité. L'auto-hébergement signifie que vous financez l'ADA et les crédits de stockage, que vous protégez le trousseau de clés, que vous exploitez Postgres, que vous surveillez les fournisseurs de chaîne, que vous gérez les sauvegardes, que vous faites tourner les identifiants, que vous gérez les webhooks et que vous répondez aux incidents. Cela supprime une dépendance à un fournisseur ; cela ne supprime pas le travail opérationnel. Exploiter votre propre gateway détaille ce que cela implique concrètement.

Que devraient voir vos utilisateurs dans une preuve ?

La plupart des utilisateurs devraient voir d'abord vos concepts produit. Ce qui les intéresse, c'est « publier des pièces », « sceller ce fichier », « prouver cet instantané de jeu de données » ou « ancrer cette version ». Ils ne devraient pas avoir à lire une spécification de métadonnées pour utiliser le produit.

Cela dit, toute vue de preuve devrait exposer les faits qui rendent l'affirmation vérifiable de façon indépendante :

l'empreinte de transaction ;
l'heure du bloc et le statut de confirmation ;
l'algorithme de hachage et le condensé ;
la clé publique du signataire, lorsque le record est signé ;
les URI de stockage, lorsqu'il y en a ;
le statut du destinataire scellé, lorsque c'est pertinent ;
la racine de Merkle et la preuve de feuille, lorsque le record regroupe plusieurs fichiers ;
le verdict de vérification lui-même.

C'est ainsi que le produit reste agréable à utiliser sans pour autant masquer l'affirmation cryptographique qui le sous-tend.

Comment éviter d'enchaîner votre produit à un seul gateway ?

Le gateway vous aide à publier ; il ne devrait jamais devenir la preuve.

Le record sur la chaîne est constitué de métadonnées Label 309, et la vérification est conçue pour fonctionner à partir de trois entrées seulement : les métadonnées de la transaction, éventuellement les octets du contenu, et un explorateur Cardano public — auxquels s'ajoutent les clés du destinataire uniquement pour déchiffrer les records scellés. Aucun serveur d'émetteur ne se trouve sur ce chemin de confiance. Si votre gateway disparaissait demain, un record valide devrait toujours se vérifier avec des outils indépendants. Il vaut aussi la peine de rappeler ce qu'une telle preuve affirme et n'affirme pas : elle montre que ces octets exacts existaient avant une date publique, pas qu'une quelconque affirmation à leur sujet soit vraie, légitimement détenue ou autorisée.

Construisez votre produit autour de cette promesse :

conservez durablement les empreintes de transaction ;
laissez les utilisateurs exporter des rapports de vérification et télécharger des lots de pièces ;
conservez les listes de feuilles Merkle et leurs preuves ;
documentez comment vérifier un record en dehors de votre interface ;
évitez les champs privés que seul votre backend peut interpréter.

C'est toute la différence entre « nous avons une ligne en base de données » et « nous avons produit une preuve que tout le monde peut vérifier ».

Pour aller plus loin

Qu'est-ce qu'un gateway Label 309 ? et exploiter votre propre gateway — le gateway du point de vue de l'opérateur.
Bâtir sur l'API CardanoWall et utiliser la CLI dans l'automatisation — les surfaces destinées aux développeurs, plus en détail.
Pourquoi la publication a un prix — ce que le solde prépayé paie réellement.
Label 309 est open source — le standard et son code de référence.
Le standard open source vit sur label309.org ; le gateway, les SDK et la CLI sont sur github.com/cardanowall. Label 309 a été soumis au processus CIP de Cardano et est en cours d'examen par les éditeurs CIP en tant que proposition de catégorie Metadata.