Wie du ein Produkt auf einem Label-309-Gateway baust

Um eine Existenznachweis-Funktion zu bauen, ohne selbst eine Blockchain zu betreiben, baust du auf einem Gateway. Ein Label 309-Gateway ist die Veröffentlichungs-Engine hinter einem Existenznachweis-Produkt: Es erledigt die schwere Betriebsarbeit – Kostenvoranschläge, Uploads, Cardano-Transaktions-Submission, Bestätigung, Reorg-Handling, Eintragsindexierung, Kontoguthaben, Speicherfinanzierung, API-Schlüssel und Webhooks – und stellt all das über schlichtes HTTP bereit. Dein Produkt ruft diese Endpunkte auf und besitzt alles, was deine Nutzer tatsächlich sehen: die Oberfläche, die Abrechnungsbeziehung, den Domänen-Workflow und die Marke.

Der Gateway-Kern ist Open Source, und CardanoWall ist das Referenzprodukt, das darauf aufbaut. Das Nützliche für Entwickler: Es gibt keine private Hintertür. CardanoWall erreicht das Gateway über dieselben öffentlichen Endpunkte wie du – jedes Muster, das für das Referenzprodukt funktioniert, funktioniert also auch für dich.

Wer sollte auf einem Gateway bauen?

Bau auf einem Gateway, wenn du Existenznachweise innerhalb eines Produkts willst und nicht als manuelle Aktion, die ein Nutzer auf einer Website ausführt.

Gut geeignet sind unter anderem:

Produkte zur Dokumentennotarisierung;
Compliance-Beweisarchive;
Plattformen für KI-Provenienz und Datensatz-Governance;
Beweissysteme für Continuous Integration;
Werkzeuge für juristische Beweismittel;
verschlüsselte Offenlegungsportale;
Dienste zur Medienauthentizität;
interne Audit-Werkzeuge für Unternehmen;
Nachweisseiten von Herausgebern.

In all diesen Fällen wollen die Nutzer nicht über Cardano-Transaktionskonstruktion, UTxO-Finanzierung, Speicher-Credits oder Chain-Bestätigungen nachdenken. Sie wollen einen Workflow, der dauerhafte, verifizierbare Nachweise erzeugt. Das Gateway macht diesen Workflow möglich, ohne dass dein Team zum Cardano-Infrastrukturbetreiber wird.

Was besitzt das Gateway, und was besitzt dein Produkt?

Die Aufteilung ist der ganze Sinn der Sache, daher lohnt es sich, sie klar zu benennen. Das Gateway besitzt die Base Plane – die Veröffentlichungs-Pipeline und den gesamten Geld-, Chain- und Speicherzustand dahinter:

Kostenvoranschlag, Upload und Veröffentlichung;
Cardano-Transaktion bauen, einreichen, bestätigen, Reorg-Handling und Erstattungen bei dauerhaftem Fehlschlag;
Uploads von Inhalt und Chiffretext in den Speicher, samt der Speicherfinanzierung dahinter;
ein gemeinsamer On-Chain-Index der Einträge, der jeden Label-309-Eintrag im Netzwerk abdeckt;
Kontoguthaben und die Ledger-Einträge, die sie bewegen;
Devisenkurs-Preisbildung und Margen;
API-Zugangsdaten und Webhook-Zustellung.

Das ist Infrastrukturarbeit. Sie muss präzise, beobachtbar und im Produktivbetrieb langweilig sein. Deine Anwendung sollte sie nicht neu implementieren, es sei denn, der Betrieb eines Gateways ist tatsächlich dein Job – und wenn das so ist, sieh dir betreibe dein eigenes Gateway an.

Dein Produkt besitzt die Vendor Plane – alles, was anbieterseitig ist:

Nutzerkonten und Sessions;
Onboarding und Abrechnung;
Produktberechtigungen;
deine Oberfläche und deine E-Mails;
die Preise, die du Kunden präsentierst;
Domänenkonzepte wie „Fall“, „Release“, „Datensatz“ oder „Beweispaket“;
Read Models, die aus Gateway-Ereignissen aufgebaut sind;
Support-Workflows.

Das Gateway muss nicht wissen, dass ein Nachweis zu einem Rechtsstreit, einem Modelltraining, einem vierteljährlichen Compliance-Paket oder einer Magazinausgabe gehört. Es muss nur korrekte Label-309-Einträge veröffentlichen und den operativen Zustand drumherum pflegen. Diese Trennung hält beide Systeme sauberer: Dein Produkt lässt sich neu bauen oder umbenennen, ohne den Chain- oder Geldzustand anzufassen, und das Gateway lässt sich aktualisieren, ohne dass es von der Existenz deines Produkts weiß.

Wie rufst du die Data Plane im Namen eines Nutzers auf?

Die Data Plane (/api/v1/*) ist die kontobezogene API. Nutze sie immer dann, wenn die Aktion im Namen eines Nutzers oder Kontos geschieht:

für eine Veröffentlichung einen Kostenvoranschlag anfordern;
Inhalt oder Chiffretext hochladen;
einen Eintrag veröffentlichen;
ein Guthaben oder das Konto-Ledger lesen;
öffentliche Einträge auflisten, abrufen oder verifizieren;
kontobezogene Webhooks registrieren.

In einem Wrapper-Produkt erzeugt dein Backend ein kurzlebiges Account-Token für das Gateway-Konto des Nutzers, und der Client ruft die Data Plane nur mit den Scopes auf, die er braucht. Die Scopes sind die Berechtigungsgrenze: Eine Veröffentlichungsansicht braucht poe:create, ein Guthaben-Widget braucht account:read, und die öffentlichen Eintrags-Endpunkte brauchen überhaupt keine Zugangsdaten – sie bedienen anonyme Aufrufer, und genau das macht den Index zu einem öffentlichen Gut statt zu einer kundenspezifischen Sicht.

Tokens sind bewusst kurzlebig (standardmäßig eine Stunde). Erzeuge eines pro Session und erneuere es bei Ablauf, damit ein durchgesickertes Token ein Ein-Stunden-Problem bleibt und kein Vorfall wird. Und sende niemals Operator-Zugangsdaten an den Browser – das ist die eine Regel, zu deren Schutz der nächste Abschnitt existiert.

Wie rufst du die Control Plane als Operator auf?

Die Control Plane (/control/v1/*) ist ausschließlich für vertrauenswürdige Backends und Operatoren da. Nutze sie, um:

Gateway-Konten anzulegen und zu aktivieren oder zu deaktivieren;
Ledger-Anpassungen anzuwenden, nachdem dein Abrechnungssystem Geld eingezogen hat;
kontospezifische Margen festzulegen;
Account-Tokens und API-Schlüssel zu erzeugen;
die Operator-Webhook-Firehose zu registrieren;
Wallets und Speicherfinanzierungsquellen zu registrieren und zu verwalten;
Audit- und Betriebszustand zu lesen.

Diese Plane lebt hinter deinem Backend. Behandle Operator-Zugangsdaten wie Produktivgeheimnisse mit Ausgabebefugnis – denn genau die haben sie. Ein kurzlebiges Operator-Token (standardmäßig 24 Stunden) erledigt die tägliche Administration; ein einzelnes Root-Geheimnis, in einem Secret Store aufbewahrt, ist den wenigen Operationen vorbehalten, die Wallets und Speicherquellen registrieren.

Über die Control Plane bleiben dein Abrechnungssystem und das vorausbezahlte Guthaben des Gateways verbunden. Eine Zahlung gelingt in deinem System, und danach wendet dein Backend eine idempotente Ledger-Anpassung auf das Gateway-Konto an. Das ist die gesamte Kredit-Schiene, und die nächsten beiden Abschnitte erklären, warum sie genau so gebaut ist.

Warum solltest du die Tabellen des Gateways nicht direkt abfragen?

Weil das Schema kein Vertrag ist – die HTTP-API und die Webhooks sind es.

Die Gateway-Engine besitzt ihre eigenen Postgres-Schemas (cw_core und cw_api). Dein Produkt sollte sie weder lesen noch beschreiben, selbst wenn sich beide Systeme dieselbe Postgres-Instanz teilen. Schema-Koexistenz ist eine unterstützte Deployment-Form, aber die Grenze ist das Schema, nicht die Datenbank: Diese Engine-Schemas sind intern und können sich ohne Vorankündigung ändern, während die HTTP-Planes und die Firehose stabil sind. Wenn du über diese Grenze greifst, kann ein routinemäßiges Gateway-Update dein Produkt stillschweigend zerschießen.

Wenn du Daten brauchst, welche die API nicht bereitstellt, behandle das als eine API-Lücke, die zu melden ist – nicht als Freibrief, über Schemas hinweg zu joinen.

Wie baust du deine eigenen Ansichten aus Gateway-Ereignissen?

Jedes Produkt braucht eigene Sichten: gesendete Einträge, Kundenhistorie, Guthaben, Veröffentlichungsfehler, Fall-Zeitachsen, Beweispakete, Audit-Dashboards. Bau diese nicht, indem du jede Zeile abpollst oder in Gateway-Interna hineinjoinst.

Registriere stattdessen Webhooks und projiziere die Ereignisse in deine eigenen Tabellen. Das Gateway stellt eine Operator-Firehose bereit – jedes Lifecycle-Ereignis auf der Instanz – plus kontobezogene Webhook-Abonnements für engere Workflows. Eine „Sent“-Sicht ist das kanonische Beispiel: Konsumiere die Veröffentlichungsstatus-Ereignisse, projiziere sie in deine eigene Tabelle und rendere von dort.

Die Zustellung erfolgt mindestens einmal, mach deine Projektion also idempotent. Ein praktisches Read Model kann anknüpfen an:

die Event-ID oder Delivery-ID (sodass eine erneute Zustellung wirkungslos bleibt);
die Eintrags-ID des Gateways;
den finalen Transaktions-Hash;
deine eigene Nutzer-ID;
die ID deines eigenen Domänenobjekts;
Status und Zeitstempel.

Deine Oberfläche rendert dann aus deinen eigenen Tabellen, während das Gateway die Autorität für Ausgaben, den Veröffentlichungs-Lifecycle und Chain-Fakten bleibt. Jede Zustellung ist signiert; verifiziere die Signatur und erzwinge ein Zeitstempel-Toleranzfenster, bevor du einem Ereignis vertraust.

Wie sollte Geld zwischen deiner Abrechnung und dem Gateway fließen?

Halte das Modell einfach: Das Gateway-Guthaben ist das ausgebbare Guthaben, und dein Abrechnungssystem ist nur ein Weg, auf dem Geld dorthin gelangt.

Deine Abrechnungsschiene kann Karten, Rechnungen, Krypto-Zahlungen, manuelle Unternehmens-Credits oder Grants einziehen. Das Gateway muss von all dem nichts wissen. Das saubere Muster ist:

Dein Abrechnungssystem bestätigt eine Zahlung.
Dein Backend wendet eine idempotente Ledger-Anpassung auf das Gateway-Konto an, verknüpft mit der ID der Zahlung.
Das Gateway-Guthaben steigt.
Künftige Veröffentlichungs- und Upload-Operationen belasten dieses Guthaben.
Schlägt eine Veröffentlichung dauerhaft fehl, kehrt das Gateway die Belastung selbst um.

Daraus folgen zwei Dinge. Erstens zählt Idempotenz, weil Abrechnungs-Pipelines mindestens einmal zustellen: Übergib die eigene ID der Zahlung als Anpassungsreferenz, und fünf Zustellungen einer Zahlung schreiben das Guthaben genau einmal gut. Zweitens: Spiegele das Gateway-Ledger nicht in deine eigene Tabelle und behandle den Spiegel nicht als Wahrheit für Ausgabeentscheidungen – cache ihn fürs Rendern, wenn es sein muss, aber lies das Gateway immer dann, wenn die Entscheidung tatsächlich Geld bewegt. Da das Gateway seine eigenen Erstattungen ausstellt, solltest du auch keinen anbieterseitigen Erstattungspfad für Veröffentlichungsfehler bauen; das würde doppelt erstatten.

Wo sollte jede Art von Schlüssel leben?

Ein Gateway sollte niemals den Identity Seed eines Nutzers brauchen. Der Client oder das SDK kann Inhalte hashen, versiegelte Payloads verschlüsseln und Einträge lokal signieren; das Gateway veröffentlicht nur die fertigen Eintrags-Bytes und reicht die Cardano-Transaktion ein. (Warum diese Grenze von Ende zu Ende wichtig ist, erfährst du unter warum Schlüssel das Gerät nie verlassen.)

Eine vollständige Integration hat mehrere unterschiedliche Schlüsselklassen, und der Fehler, den du vermeiden solltest, ist, sie alle zu einem einzigen „API-Geheimnis“ zu verflachen. Sie haben sehr unterschiedliche Schadensradien:

Identity Seeds und private Empfängerschlüssel der Nutzer – die kryptografische Identität des Nutzers, die an den Rand gehört;
Signaturschlüssel für Einträge, abgeleitet aus dieser Identität;
Account-API-Schlüssel und kurzlebige Account-Tokens – die in den Produkt- oder Client-Kontext gehören, der sie braucht;
Operator-Tokens und das Root-Geheimnis – die nur auf vertrauenswürdige Backends gehören;
die eigenen Cardano- und Speicher-Signaturschlüssel des Gateways sowie seine Webhook-Signaturgeheimnisse – die in den Gateway-Keyring gehören.

Ordne jede Klasse dem kleinsten Ort zu, der sie halten kann, und ein einzelnes Leck bleibt eingegrenzt.

Wann solltest du das Gateway selbst hosten, statt ein gehostetes zu nutzen?

Hoste selbst, wenn operative Unabhängigkeit wichtiger ist als Bequemlichkeit.

Ein gehostetes Gateway ist für die meisten Integrationen der einfachste Weg: Du veröffentlichst über einen fertigen Dienst auf Standard-API-Oberflächen und betreibst nie selbst Chain- oder Speicheroperationen. Selbst-Hosting tauscht diese Einfachheit gegen Kontrolle ein – deine eigene Cardano-Wallet-Finanzierung, deine eigene Speicherfinanzierung, deine eigenen Operator-Richtlinien, deine eigene Verfügbarkeit und Netzwerkabhängigkeiten, deine eigenen Margen, deine eigene Compliance-Grenze und keine Abhängigkeit von einem Dritten fürs Veröffentlichen.

Aber Kontrolle ist auch Verantwortung. Selbst-Hosting bedeutet, dass du ADA und Speicher-Credits finanzierst, den Keyring schützt, Postgres betreibst, Chain-Anbieter überwachst, Backups erstellst, Zugangsdaten rotierst, Webhooks verwaltest und auf Vorfälle reagierst. Es beseitigt eine Anbieterabhängigkeit; es beseitigt nicht die operative Arbeit. Betreibe dein eigenes Gateway erklärt, was das tatsächlich mit sich bringt.

Was sollten deine Nutzer in einem Nachweis sehen?

Die meisten Nutzer sollten zuerst deine Produktkonzepte sehen. Ihnen geht es um „Beweise veröffentlichen“, „diese Datei versiegeln“, „diesen Datensatz-Snapshot nachweisen“ oder „dieses Release verankern“. Sie sollten keine Metadaten-Spezifikation lesen müssen, um das Produkt zu nutzen.

Dennoch sollte jede Nachweissicht die Fakten offenlegen, welche die Behauptung unabhängig überprüfbar machen:

den Transaktions-Hash;
die Blockzeit und den Bestätigungsstatus;
den Hash-Algorithmus und den Digest;
den öffentlichen Schlüssel des Signierenden, wenn der Eintrag signiert ist;
Speicher-URIs, sofern vorhanden;
den Status des versiegelten Empfängers, sofern relevant;
die Merkle-Wurzel und den Blatt-Nachweis, wenn der Eintrag viele Dateien bündelt;
das Verifizierungsergebnis selbst.

So bleibt das Produkt angenehm in der Nutzung, ohne die kryptografische Behauptung darunter zu verstecken.

Wie vermeidest du, dein Produkt an ein einziges Gateway zu binden?

Das Gateway hilft dir beim Veröffentlichen; es sollte niemals zum Nachweis werden.

Der Eintrag auf der Chain besteht aus Label-309-Metadaten, und die Verifizierung ist so ausgelegt, dass sie mit nur drei Eingaben funktioniert: den Transaktions-Metadaten, optional den Inhalts-Bytes und einem öffentlichen Cardano-Explorer – wobei Empfängerschlüssel nur hinzukommen, um versiegelte Einträge zu entschlüsseln. Kein Herausgeberserver sitzt in diesem Vertrauenspfad. Wenn dein Gateway morgen verschwindet, sollte sich ein gültiger Eintrag dennoch mit unabhängigem Werkzeug verifizieren lassen. Erwähnenswert ist außerdem, was ein solcher Nachweis behauptet und was nicht: Er zeigt, dass genau diese Bytes vor einem öffentlichen Zeitpunkt existierten, nicht, dass irgendeine Behauptung über sie wahr ist, dass sie jemandem gehören oder autorisiert sind.

Bau dein Produkt um dieses Versprechen herum:

speichere Transaktions-Hashes dauerhaft;
lass Nutzer Verifizierungsberichte exportieren und Beweispakete herunterladen;
bewahre Merkle-Blattlisten und ihre Nachweise auf;
dokumentiere, wie man einen Eintrag außerhalb deiner Oberfläche verifiziert;
vermeide private Felder, die nur dein Backend interpretieren kann.

Das ist der Unterschied zwischen „wir haben eine Datenbankzeile“ und „wir haben einen Nachweis erzeugt, den jeder prüfen kann“.

Weiterführende Lektüre

Was ist ein Label-309-Gateway? und betreibe dein eigenes Gateway – das Gateway aus Sicht des Operators.
Bau auf der CardanoWall-API und nutze die CLI in der Automatisierung – die entwicklerseitigen Oberflächen im Detail.
Warum Veröffentlichen einen Preis hat – wofür das vorausbezahlte Guthaben tatsächlich aufkommt.
Label 309 ist Open Source – der Standard und sein Referenzcode.
Der Open-Source-Standard lebt unter label309.org; das Gateway, die SDKs und die CLI liegen unter github.com/cardanowall. Label 309 wurde in den Cardano-CIP-Prozess eingereicht und ist bei den CIP-Editoren in Prüfung als Vorschlag der Kategorie Metadata.