Auf der CardanoWall-API aufbauen

Du kannst eine Existenznachweis-Funktion in dein eigenes Produkt einbauen, ohne deine Nutzer über die CardanoWall-Website zu schicken. CardanoWall ist eine Benutzeroberfläche auf einem gehosteten Gateway, und dieses Gateway stellt eine schlichte HTTP-API bereit: einen Nachweis kalkulieren, Inhalte hochladen, wenn Speicher gebraucht wird, einen Label-309-Eintrag veröffentlichen, seinen Status verfolgen, öffentliche Einträge lesen, Guthaben prüfen und Webhooks empfangen. Was auf Cardano landet, sind standardkonforme Label-309-Metadaten, kein privates, nur CardanoWall-eigenes Format – damit kann es später jeder mit jedem beliebigen Werkzeug verifizieren.

Genau darauf kommt es an. Das Produkterlebnis kann vollständig deins sein. Der Nachweis bleibt unabhängig verifizierbar. Es ist dieselbe API, auf der die Web-App und der Worker von CardanoWall laufen – es gibt keine private Tür und keinen schnelleren internen Weg.

Was kannst du darauf aufbauen?

Überall dort, wo ein Existenznachweis in einen Workflow gehört, passt die API:

ein SaaS-Produkt, das Kundendokumente mit einem Zeitstempel versieht;
eine CI/CD-Pipeline, die Release-Manifeste verankert (siehe Nachweise in CI/CD);
eine KI-Plattform, die Provenienz-Einträge im großen Maßstab veröffentlicht;
ein Compliance-Archiv, das tägliche Nachweis-Bündel festschreibt;
ein juristisches Werkzeug, das Beweismittel für bestimmte Empfänger versiegelt;
ein internes Audit-System, das Kontroll-Snapshots signiert;
ein öffentlicher Explorer oder eine Profilseite, die die Einträge eines Veröffentlichenden auflistet.

Die API ist nicht bloß eine bequeme Hülle um die Website. Sie ist die Automatisierungsschicht – das, wonach du greifst, wenn kein Mensch im Spiel ist.

Wie sieht der Haupt-Publish-Ablauf aus?

Ein Publish hat drei Stufen: Kostenvoranschlag, Upload (nur wenn Bytes gespeichert werden müssen), dann Veröffentlichen. Auf der Data Plane des Gateways (/api/v1/*) bildet sich das so ab:

POST /api/v1/poe/quote – den Preis für ein kurzes Fenster festschreiben.
POST /api/v1/poe/uploads – Inhalte speichern und inhaltsadressierte URIs zurückgeben.
POST /api/v1/poe/uploads/sessions und die zugehörigen Chunk-Routen – der fortsetzbare Pfad für große Dateien.
POST /api/v1/poe/publish – den fertiggestellten Eintrag einreichen.
POST /api/v1/poe/publish-batch – viele Einträge in einem Aufruf einreichen.
GET /api/v1/poe/events/{poe_id} – Status-Updates über Server-Sent Events streamen.

Die genauen Request- und Response-Bodies stehen im OpenAPI-Dokument des Gateways, das jedes Deployment ausliefert – binde dich daran, nicht an einen Blog-Schnipsel. Stabil bleibt das mentale Modell: Schreib zuerst den Preis fest, speichere etwaige Inhalte, reiche dann die fertiggestellten kanonischen CBOR-Eintrags-Bytes zusammen mit der Kostenvoranschlags-ID ein.

Warum kommt der Kostenvoranschlag zuerst?

Weil Veröffentlichen ein kostenpflichtiger Vorgang ist und der Preis sich nicht im Voraus kennen lässt.

Ein Gateway trägt für dich echte Kosten: Cardano-Transaktionsgebühren, Arweave-Speicher, wenn Inhalte angehängt sind, das Wechselkursrisiko zwischen USD und diesen Netzwerken sowie die Marge des Betreibers. Ein Kostenvoranschlag macht diese Kosten explizit, bevor der Publish-Aufruf etwas ausgibt. (Zu den Gründen für kostenpflichtiges Veröffentlichen siehe warum Veröffentlichen einen Preis hat.)

Eine Kostenvoranschlags-Antwort trägt eine quote_id, eine bepreiste Aufschlüsselung (Netzwerk-, Speicher- und Service-Anteile), die angewandte Marge, die Aktualität des Wechselkurs-Snapshots und einen Ablaufzeitstempel. Der Preis ist nur für ein begrenztes Fenster festgeschrieben – etwa fünfzehn Minuten –, danach forderst du einen frischen Kostenvoranschlag an.

So kann deine Anwendung entscheiden:

ob das Konto sich das Veröffentlichen leisten kann;
ob der Wechselkurs-Snapshot für deine Richtlinie aktuell genug ist;
ob der Vorgang eine Nutzerbestätigung braucht;
ob ein großes Bündel aufgeteilt werden soll;
ob mit einem neuen Kostenvoranschlag erneut versucht werden soll, wenn der alte abläuft.

Zeig kein „kostenlos“-Label, bevor das Gateway bestätigt, dass der Vorgang nichts kostet. Ein reiner Hash-Eintrag ohne Speicher kann günstig sein, aber die Autorität über den Preis ist das Gateway, nicht deine UI.

Was macht der Upload-Schritt?

Der Upload kümmert sich um Bytes, die irgendwo leben müssen.

Ein reiner Hash-Nachweis lädt nichts hoch – du hältst den Digest bereits. Ein Eintrag mit angehängten Inhalten, ein versiegelter Chiffretext oder Wiederherstellungsmaterial braucht inhaltsadressierten Speicher, und die Upload-Endpunkte speichern diese Bytes und geben eine URI wie ar://... zurück. Die API unterstützt Multipart-Uploads, Ergebnisse pro Datei, Deduplizierung über den Content-Hash innerhalb eines Kontos und fortsetzbare Sessions für Dateien, die zu groß sind, um sie in einem Request zu senden. CardanoWall erzwingt keine feste maximale Upload-Größe – Inhalte werden pro Byte abgerechnet, und Uploads im Gigabyte-Bereich sind zu erwarten.

Behandle den Upload als eigenen kleinen Lebenszyklus:

Lade die Bytes hoch.
Empfange die inhaltsadressierte URI.
Baue oder finalisiere den Label-309-Eintrag mit dieser URI.
Veröffentliche den Eintrag.

Wenn ein Upload eine laufende Attempt-ID zurückgibt, frag den Status-Endpunkt dieses Versuchs ab, statt blind erneut hochzuladen – eine mehrere Gigabyte große Datei erneut zu senden, weil du eine Antwort verpasst hast, ist genau der Fehler, den die Attempt-ID verhindern soll.

Was macht Veröffentlichen, und warum ist es asynchron?

Veröffentlichen reicht den Eintrag ein und startet die Chain-Pipeline.

Der Publish-Aufruf nimmt die fertiggestellten kanonischen CBOR-Eintrags-Bytes plus die quote_id entgegen. Das Gateway verankert den Eintrag auf Cardano unter dem Metadaten-Label 309, bucht den kalkulierten Betrag ab und gibt eine Gateway-Eintrags-ID (einen poe_...-Wert) zurück, während die Transaktion noch durch Einreichung und Bestätigung läuft.

Diese Asynchronität ist wichtig für dein Design. Wenn der Aufruf zurückkehrt, existiert der On-Chain-Transaktions-Hash unter Umständen noch nicht. Zeig einen ausstehenden Zustand und höre auf Updates. Der Status, den die API meldet, durchläuft diese Werte:

submitting – die Transaktion wird gebaut und gesendet;
confirming – sie ist auf der Chain, aber unter der Bestätigungsschwelle;
confirmed – sie hat diese Schwelle überschritten und ist abgeschlossen;
failed – das Veröffentlichen ist endgültig fehlgeschlagen und wird nicht landen.

Der Status-Stream unter GET /api/v1/poe/events/{poe_id} existiert genau dafür. Bei einem endgültigen Fehlschlag macht das Gateway die Abbuchung selbst rückgängig – so kann dein Produkt den Nutzern ehrlich sagen „du wirst nur für das belastet, was on-chain landet“, ohne eine eigene Abstimmung zu fahren. Bau keinen anbieterseitigen Erstattungspfad für Publish-Fehler; das würde doppelt erstatten.

Was sollte dein API-Client speichern?

Speichere gerade genug, um den Workflow wieder anzuknüpfen – und nicht mehr. Mindestens:

deine eigene Nutzer- oder Konto-ID;
die Gateway-poe_id;
die für das Veröffentlichen verwendete Kostenvoranschlags-ID;
den Digest des Eintrags oder einen Hash der Eintrags-Bytes;
den finalen Cardano-Transaktions-Hash, sobald er existiert;
Status und Zeitstempel;
etwaige Upload-Attempt-IDs;
etwaige inhaltsadressierte URIs;
jegliches lokale Material, das du später zum Verifizieren brauchst.

Behandle deine Datenbank nicht als den Nachweis. Behandle sie als ein Produkt-Read-Model. Der Nachweis ist der On-Chain-Label-309-Eintrag plus die Inhalte oder Schlüssel, die zu seiner Verifizierung nötig sind – und diese Kombination steht für sich allein, unabhängig von deinen Servern.

Wie liest und verifizierst du Einträge?

Die Einträge-Schicht ist für öffentliche, anonyme Lesezugriffe gebaut:

GET /api/v1/records – der On-Chain-Eintrags-Feed, mit Filtern und Pagination.
GET /api/v1/records/count – eine Zählung für diesen Feed.
GET /api/v1/records/{tx_hash} – ein einzelner Eintrag per Transaktions-Hash.
POST /api/v1/records/{tx_hash}/verify – ein serverseitiger Verifizierungsbericht.

Die List- und Get-Routen bedienen anonyme Aufrufer – öffentliche Verifizierungsseiten und Explorer brauchen keinen Berechtigungsnachweis. Ein Bearer-Token kann dort, wo es relevant ist, Konto-Kontext hinzufügen, aber die öffentliche Eintrags-Verifizierung sollte nie von einer privaten CardanoWall-Session abhängen.

Nutze diese Endpunkte für den Produktkomfort. Für hochsichere Prüfungen führe zusätzlich einen eigenständigen Verifizierer aus, der Chain-Daten über eine Cardano-Infrastruktur abruft, die er selbst wählt, und einen unabhängigen Bericht erzeugt. Das ist die gesunde Aufteilung: Die API erleichtert das Bauen von Apps, aber der Nachweis muss weiterhin außerhalb der API bestehen. Die Open-Source-SDKs und die CLI liefern genau diesen Verifizierer – siehe einen Label-309-Eintrag verifizieren dazu, wie das von Anfang bis Ende funktioniert.

Wie sollte die Authentifizierung funktionieren?

Halte Berechtigungsnachweise eng, und halte Betreiber-Credentials auf deinem Backend.

Das Gateway trennt zwei Ebenen. Deine Nutzer agieren über die Data Plane (/api/v1/*) mit einem kurzlebigen Account-Token oder API-Schlüssel, den dein Backend pro Session ausstellt. Allein dein Backend hält das Operator-Credential für die Control Plane (/control/v1/*) – Konten bereitstellen, Guthaben gutschreiben, wenn deine Abrechnung Geld einzieht, Margen setzen und ebenjene Account-Tokens ausstellen.

Der Zugriff auf die Data Plane ist auf Scopes beschränkt. Die Scopes, die du nutzen wirst:

poe:create – Kostenvoranschlag, Upload, Veröffentlichen und Batch-Publish;
poe:read – Eintrags-Lesezugriffe, die Verify-Route und der Status-Stream, wenn er mit einem Bearer aufgerufen wird;
account:read – Guthaben- und Ledger-Lesezugriffe;
webhooks:read und webhooks:write – kontobezogene Webhook-Verwaltung;
billing:read – reserviert für anbieterseitige Abrechnungsschichten.

Eine Publish-Seite braucht poe:create; ein Guthaben-Widget braucht account:read; keines braucht mehr. Operator-Credentials dürfen niemals in ein Browser-Bundle, eine mobile App, das Skript eines Partners oder einen CI-Job gelangen, der nur Nachweise veröffentlichen muss – die stellen stattdessen ihr eigenes, eng gefasstes Account-Token aus. Ein geleaktes Account-Token sollte ein Ein-Stunden-Problem sein, kein Vorfall.

Wie sollten Retries und Idempotenz funktionieren?

Plane Retries vor dem Produktivbetrieb, denn Publish-Systeme scheitern auf langweilige Weise: Netzwerk-Aussetzer, abgelaufene Kostenvoranschläge, unzureichendes Guthaben, Rate Limits, ein noch laufender Upload oder ein abgerissener Status-Stream.

Eine solide Integration sollte:

Idempotenz nutzen, wo die API sie unterstützt, geschlüsselt auf einer stabilen Ursprungs-ID;
das Ablaufen eines Kostenvoranschlags als normal behandeln – einen neuen Kostenvoranschlag holen und fortfahren;
nach einem unsicheren Fehlschlag den maßgeblichen Attempt- oder Eintrags-Endpunkt abfragen, statt blind erneut einzureichen;
das doppelte Hochladen großer Dateien vermeiden;
das doppelte Gutschreiben von Guthaben vermeiden (jede Gutschrift auf die ID der Zahlung selbst schlüsseln);
Request-IDs und Gateway-IDs für den Support protokollieren;
in deinen Berichten einen fehlgeschlagenen Publish von einem nicht verifizierbaren Eintrag unterscheiden.

Veröffentlichen dedupliziert über die Eintrags-Bytes, und Upload-Batches unterstützen idempotentes Replay. Stütz dich auf diese Semantik statt auf eine „nochmal probieren und hoffen“-Schleife.

Was sollten Webhooks tun?

Webhooks sind der Weg, auf dem du Read-Models baust – nicht durch sekündliches Pollen und schon gar nicht durch das Lesen der Datenbanktabellen des Gateways, die engine-intern sind und sich ohne Vorwarnung ändern.

Registriere ein Webhook-Abonnement, und das Gateway pusht Lifecycle-Events: poe_status_changed, balance_changed, Erstattungsabsichten, Upload-Fehler. Betreiber können den vollen instanzweiten Firehose abonnieren; kontobezogene Webhook-Routen gibt es auch auf der Data Plane. Eine „Sent“-Ansicht – jeder Nutzer sieht die Einträge, die er veröffentlicht hat, mit Live-Status – ist der kanonische Anwendungsfall: Konsumiere poe_status_changed, projiziere es in deine eigene Tabelle und rendere von dort.

Dein Empfänger sollte die Signatur jeder Zustellung verifizieren, mindestens einmalige Zustellung akzeptieren, Projektionen auf der Event- oder Zustell-ID schlüsseln und eine erneute Zustellung als No-op behandeln. Das Read-Model gehört deiner App. Der kanonische Ausgaben- und Veröffentlichungszustand gehört dem Gateway – cache ihn fürs Rendern, wenn du musst, aber lies das Gateway für jede Entscheidung, die eine Ausgabe freigibt.

Was sollte den Client niemals verlassen?

Privates Identitätsmaterial. Deine Anwendung ruft die API auf, um Einträge zu veröffentlichen; sie sollte niemals den Identity Seed des Nutzers, einen privaten Signaturschlüssel oder einen privaten Empfängerschlüssel an das Gateway übergeben.

Für signierte Einträge signiere lokal oder nutze Off-Host-Signing – die SDKs bieten einen Ablauf, bei dem der private Schlüssel in einem KMS, einem HSM oder einer Air-Gapped-Maschine liegt und nur der öffentliche Schlüssel und die Signatur über die Leitung gehen.
Für versiegelte Einträge verschlüssele lokal vor dem Upload, wenn der Anwendungsfall Ende-zu-Ende-Vertraulichkeit braucht.
Für die Empfänger-Verifizierung entschlüssele lokal.

Die API ist für Veröffentlichungs- und Lifecycle-Vorgänge da. Sie ist nicht die Vertrauenswurzel, und sie ist so konzipiert, dass sie es nie sein muss. Zum weiterreichenden Prinzip siehe warum Schlüssel das Gerät nie verlassen.

Wo anfangen

Der schnellste Weg sind die Open-Source-SDKs und die CLI unter github.com/cardanowall: ein TypeScript-SDK (@cardanowall/sdk-ts), ein Python-SDK (cardanowall-sdk), ein Rust-SDK (cardanowall) und die cardanowall-CLI. Alle sind gateway-unabhängig – du lieferst die Basis-URL und einen opaken API-Schlüssel – und alle liefern denselben eigenständigen Verifizierer. Wenn du die API lieber zunächst von Hand bedienen willst, führt dich deinen ersten Nachweis veröffentlichen durch einen Eintrag von Anfang bis Ende, und die CLI in der Automatisierung nutzen deckt den Skript-Pfad ab. Wenn du das Backend lieber selbst betreiben willst, statt das gehostete zu nutzen, ist auch das Gateway Open Source – siehe dein eigenes Gateway betreiben.

Weiterführendes

Label 309, der offene Standard, auf dem das aufbaut: label309.org
Die Open-Source-SDKs, die CLI und das Gateway: github.com/cardanowall
Der Cardano-CIP-Vorschlag für das Metadaten-Label, beim Cardano-CIP-Prozess eingereicht und von den CIP-Editoren in Prüfung: github.com/cardano-foundation/CIPs/pull/1205
Deinen ersten Nachweis veröffentlichen
Einen Label-309-Eintrag verifizieren
Die CLI in der Automatisierung nutzen
Was ist ein Label-309-Gateway?