Faites tourner votre propre passerelle

Vérifier un enregistrement Label 309 ne demande rien à personne — pas de compte, pas de serveur, pas de clé. La publication est l’autre moitié : elle inscrit une transaction sur Cardano, et cela a un coût. La passerelle est la pièce qui le règle. Elle détient le portefeuille Cardano approvisionné qui ancre l’enregistrement (et un portefeuille Arweave pour les fichiers scellés), construit et soumet la transaction, la suit jusqu’à sa confirmation, puis restitue les enregistrements pour une vérification autonome.

La plupart du temps, vous dirigez votre SDK ou votre CLI vers la passerelle de quelqu’un d’autre. Mais tout le backend est open source — label-309-gateway, un seul binaire Rust plus Postgres — vous pouvez donc faire tourner la vôtre. Faites-en tourner une en privé pour vos propres applications, ou exploitez-en une comme service payant pour d’autres : elle est multi-tenant par conception, avec de nombreux comptes et clés d’API sous une seule instance. Ce guide vous mène de zéro à un premier devis tarifé à l’aide du Docker Compose de référence.

Avant de commencer

Il vous faut Docker et Docker Compose, ainsi qu’un hôte disposant de quelques gigaoctets d’espace disque libre. Tout ce qui suit vise le réseau preprod de Cardano — l’approche prudente pour mettre en route un déploiement. Le passage au mainnet est un choix délibéré que vous faites plus tard, une fois le déploiement approvisionné et vérifié.

Récupérer le code et rédiger la configuration

Clonez le dépôt et placez-vous dans deploy/, où se trouve le docker-compose.yml de référence. Copiez la configuration d’exemple et adaptez-la à votre déploiement — réseau, fourchette de frais, stockage et tarification :

git clone https://github.com/cardanowall/label-309-gateway
cd label-309-gateway/deploy
cp ../gateway.example.toml gateway.toml

L’exemple est annoté et vise déjà preprod, si bien qu’il démarre tel quel pour un premier essai.

Créer le trousseau de clés

Chaque clé de signature qu’utilise la passerelle réside dans un unique fichier de trousseau chiffré avec age. Créez-le, puis ajoutez une clé Cardano (preprod), une clé Arweave et une clé de chiffrement des webhooks. Ces étapes keyring exécutent directement le binaire gateway — le trousseau est censé être créé sur une machine de confiance, et seul son fichier chiffré est copié dans le conteneur ; récupérez donc un binaire précompilé depuis le dépôt pour cette seule étape.

mkdir -p secrets
printf '%s' 'a-strong-passphrase' > secrets/gateway-keyring-passphrase
export GATEWAY_KEYRING_PASSPHRASE="$(cat secrets/gateway-keyring-passphrase)"

gateway keyring init             --path secrets/gateway-keyring.age
gateway keyring add-cardano      --path secrets/gateway-keyring.age --network preprod
gateway keyring add-arweave      --path secrets/gateway-keyring.age
gateway keyring add-webhook-wrap --path secrets/gateway-keyring.age
chmod 600 secrets/*

Chaque étape add- affiche l’adresse qu’elle vient de créer. Approvisionnez les deux adresses affichées : l’adresse Cardano paie les frais d’ancrage, et l’adresse Arweave finance les crédits de stockage pour les fichiers scellés. Définissez ensuite le mot de passe de base de données que lit le compose :

echo 'POSTGRES_PASSWORD=a-strong-db-password' > .env

Démarrer l’ensemble

Provisionnez d’abord l’opérateur. Cette étape applique les migrations et affiche le secret racine une seule fois — conservez-le en lieu sûr, c’est l’identifiant maître du plan de contrôle :

docker compose run --rm gateway operator bootstrap --label acme

Démarrez ensuite Postgres et la passerelle :

docker compose up -d

Enregistrer un portefeuille, un compte et une clé

Le compose n’expose volontairement aucun port sur l’hôte : le plan de données et le plan de contrôle partagent un même socket, si bien que l’exposer exposerait aussi le plan de contrôle. Pilotez le plan de contrôle depuis l’intérieur du conteneur. Ouvrez un shell :

docker compose exec gateway sh

Dirigez-le vers le plan de contrôle local à l’aide du secret racine affiché par bootstrap, puis enregistrez le portefeuille Cardano approvisionné (l’adresse affichée par keyring add-cardano), créez un compte, créditez-le et générez une clé d’API du plan de données dont la portée couvre la publication :

export GATEWAY_CONTROL_URL=http://127.0.0.1:8080/control/v1
export GATEWAY_CONTROL_TOKEN='ctl_…the root secret from bootstrap…'

gateway admin wallet register primary addr_test1… preprod
gateway admin account create
gateway admin account fund <account_id> 10000000 "starter credit"   # $10
gateway admin key create <account_id> poe:create,poe:read,account:read

key create affiche la clé d’API qui pilote le plan de données. Cela, plus l’URL de base, est tout ce dont une application a besoin.

Obtenir votre premier devis

Pour atteindre le plan de données depuis l’hôte pendant la configuration, décommentez le mappage ports en loopback (127.0.0.1:8080:8080) dans docker-compose.yml et relancez docker compose up -d — en loopback uniquement, jamais 0.0.0.0. Fixez ensuite un prix avec la clé d’API que vous venez de générer :

curl -sS -X POST http://127.0.0.1:8080/api/v1/poe/quote \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"record_bytes":256,"recipient_count":0,"file_bytes_total":0}'

La réponse contient un quote_id valable 15 minutes ainsi qu’un détail des coûts. Un appel de publication consomme ce quote_id de façon atomique en même temps que le débit du solde — la même structure en deux étapes, fixer un prix, puis soumettre, que celle des guides du SDK. Votre passerelle est opérationnelle.

Pour aller plus loin

Le binaire en cours d’exécution sert sa propre référence d’API interactive — le plan de données sur /api/v1/docs et le plan de contrôle sur /control/v1/docs, chacune rendue entièrement hors ligne. Deux documents du dépôt vont plus loin : le manuel de l’opérateur couvre l’approvisionnement, les identifiants, la sémantique monétaire et les opérations du quotidien, et le guide de l’intégrateur explique comment bâtir un produit par-dessus.

Le plan de données de votre passerelle est exactement ce que les guides du SDK et de la CLI appellent une URL de base. Remplacez https://your-gateway.example par l’adresse que vous contrôlez désormais, distribuez des clés d’API et publiez votre première PoE via un backend entièrement à vous.