Betreiben Sie Ihr eigenes Gateway

Einen Label-309-Datensatz zu verifizieren verlangt von niemandem etwas: kein Konto, keinen Server, keinen Schlüssel. Das Veröffentlichen ist die andere Hälfte: Dabei wird eine Transaktion auf Cardano geschrieben, und das kostet eine Gebühr. Das Gateway ist der Baustein, der sie zahlt. Es hält die finanzierte Cardano-Wallet, die den Datensatz verankert (und eine Arweave-Wallet für versiegelte Dateien), erstellt und übermittelt die Transaktion, verfolgt sie bis zur Bestätigung und liefert die Datensätze zur eigenständigen Verifizierung wieder aus.

Meistens richten Sie Ihr SDK oder Ihre CLI auf das Gateway eines anderen. Das gesamte Backend ist jedoch quelloffen, label-309-gateway, ein einzelnes Rust-Binary plus Postgres, sodass Sie auch Ihr eigenes betreiben können. Betreiben Sie eines privat für Ihre eigenen Anwendungen oder als bezahlten Dienst für andere: Es ist von Grund auf mandantenfähig, mit vielen Konten und API-Schlüsseln unter einer einzigen Instanz. Diese Anleitung bringt Sie mit der mitgelieferten Docker-Compose-Konfiguration von null bis zu einem ersten bepreisten Angebot.

Bevor Sie beginnen

Sie brauchen Docker und Docker Compose sowie einen Host mit ein paar Gigabyte freiem Speicherplatz. Alles Folgende zielt auf Cardano preprod, die sichere Ausgangslage, um ein Deployment in Betrieb zu nehmen. Der Wechsel auf Mainnet ist eine bewusste Umstellung, die Sie später vornehmen, sobald das Deployment finanziert und verifiziert ist.

Den Code holen und die Konfiguration schreiben

Klonen Sie das Repository und arbeiten Sie aus deploy/ heraus, wo die mitgelieferte docker-compose.yml liegt. Kopieren Sie die Beispielkonfiguration und passen Sie sie an Ihr Deployment an, also Netzwerk, Gebührenband, Speicher und Preisgestaltung:

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

Die Beispieldatei ist kommentiert und zielt bereits auf preprod, sodass sie für einen ersten Durchlauf unverändert startet.

Den Schlüsselbund anlegen

Jeder Signaturschlüssel, den das Gateway verwendet, liegt in einer einzigen, mit age verschlüsselten Schlüsselbund-Datei. Legen Sie sie an und fügen Sie dann einen Cardano-Schlüssel (preprod), einen Arweave-Schlüssel und einen Webhook-Wrap-Schlüssel hinzu. Diese keyring-Schritte führen das gateway-Binary direkt aus: Der Schlüsselbund soll auf einer vertrauenswürdigen Maschine erstellt und nur seine verschlüsselte Datei in den Container kopiert werden. Holen Sie sich für diesen einen Schritt daher einen Release-Build aus dem Repository.

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/*

Jeder add--Schritt gibt die Adresse aus, die er gerade erstellt hat. Statten Sie die beiden ausgegebenen Adressen mit Guthaben aus: Die Cardano-Adresse zahlt die Verankerungsgebühren, und die Arweave-Adresse finanziert das Speicherguthaben für versiegelte Dateien. Setzen Sie anschließend das Datenbankpasswort, das Compose ausliest:

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

In Betrieb nehmen

Richten Sie zuerst den Betreiber ein. Das spielt die Migrationen ein und gibt das Root-Secret genau einmal aus. Bewahren Sie es an einem sicheren Ort auf, denn es ist die oberste Zugangsberechtigung für die Steuerungsebene:

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

Starten Sie dann Postgres und das Gateway:

docker compose up -d

Wallet, Konto und Schlüssel registrieren

Compose gibt bewusst keinen Host-Port frei: Datenebene und Steuerungsebene teilen sich einen Socket, sodass eine Freigabe auch die Steuerungsebene nach außen offenlegen würde. Bedienen Sie die Steuerungsebene daher aus dem Container heraus. Öffnen Sie eine Shell:

docker compose exec gateway sh

Richten Sie sie auf die lokale Steuerungsebene, mit dem Root-Secret, das bootstrap ausgegeben hat, und registrieren Sie dann die finanzierte Cardano-Wallet (die Adresse, die keyring add-cardano ausgegeben hat), legen Sie ein Konto an, schreiben Sie ihm Guthaben gut und erzeugen Sie einen API-Schlüssel für die Datenebene mit einem Scope zum Veröffentlichen:

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 gibt den API-Schlüssel aus, der die Datenebene bedient. Dieser und die Basis-URL sind alles, was eine Anwendung braucht.

Ihr erstes Angebot einholen

Um die Datenebene während der Einrichtung vom Host aus zu erreichen, entfernen Sie in docker-compose.yml die Kommentarzeichen vor dem ports-Mapping auf das Loopback-Interface (127.0.0.1:8080:8080) und führen Sie docker compose up -d erneut aus, ausschließlich auf dem Loopback, niemals auf 0.0.0.0. Schreiben Sie dann mit dem gerade erzeugten API-Schlüssel einen Preis fest:

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}'

Die Antwort enthält eine quote_id, die 15 Minuten gültig ist, samt einer Kostenaufschlüsselung. Ein Veröffentlichungsaufruf verbraucht diese quote_id atomar zusammen mit der Belastung des Guthabens, derselbe zweistufige Ablauf, erst den Preis festschreiben, dann einreichen, den auch die SDK-Anleitungen nutzen. Ihr Gateway läuft.

Wie es weitergeht

Das laufende Binary stellt seine eigene interaktive API-Referenz bereit, die Datenebene unter /api/v1/docs und die Steuerungsebene unter /control/v1/docs, jeweils vollständig offline gerendert. Zwei Dokumente im Repository gehen tiefer: Das Betreiber-Runbook behandelt Finanzierung, Zugangsdaten, Geldsemantik und den laufenden Betrieb, und der Integrationsleitfaden behandelt, wie Sie darauf ein Produkt aufbauen.

Die Datenebene Ihres Gateways ist genau das, was die SDK- und CLI-Anleitungen mit einer Basis-URL meinen. Ersetzen Sie https://your-gateway.example durch die Adresse, die Sie jetzt kontrollieren, geben Sie API-Schlüssel aus und veröffentlichen Sie Ihren ersten PoE über ein Backend, das ganz Ihnen gehört.