Die technischen Entscheidungen hinter der Nachweisebene von Open Poker
Die Integration von Digital Evidence in Open Poker folgt einem technischen Grundsatz: Nachweise sollen Handdatensätze belastbarer machen, ohne Teil des kritischen Spielpfads zu werden. Abgeschlossene Hände sollten über Constellation Digital Evidence überprüfbar sein. Eine Nachweis-API, Netzwerklatenz oder Wartezeit bis zur Finalisierung sollte jedoch niemals darüber entscheiden, ob eine Hand beendet oder ein Pot ausgezahlt werden kann.
Offenlegung: Ich bin der Gründer von openpoker.ai. Dies ist Teil 2 einer zweiteiligen Reihe. Teil 1 erläutert die Produktentscheidung. Dieser Beitrag beschreibt die technischen Entscheidungen, ohne zu einer schrittweisen Code-Anleitung zu werden.
Teil 1: Produkt - Warum Open Poker Constellation Digital Evidence nutzt.
Teil 2: Technik - die Architektur der Nachweisebene: wann wir den Nachweis erzeugen, was wir hashen, was privat bleibt und wie die unabhängige Verifizierung funktioniert.
Das Wichtigste in Kürze
- Open Poker beginnt erst mit der Nachweiserstellung, nachdem das Handausgangsergebnis in der Datenbank festgeschrieben wurde.
- Der Dokument-Hash ist ein SHA-256-Hash über deterministisches JSON der öffentlichen Hand-Nutzlast.
- Die lokalen Nachweiszustände sind eindeutig: pending, submitted, finalized oder error.
- Die Handseite zeigt Status, Dokument-Hash, Fingerabdruck, Explorer-Link und die für die Verifizierung erforderliche kanonische Nutzlast.
Das Architekturziel
Die Nachweisebene musste zwei Anforderungen gleichzeitig erfüllen: Sie sollte Manipulationen an Handhistorien sichtbar machen und zugleich so unauffällig arbeiten, dass sie niemals den Ablauf einer Pokerhand verändert.
Daraus entstand eine klare Grenze. Open Poker führt das Spiel aus, speichert die Hand und stellt die öffentliche Handseite bereit. Erst nach dem Datenbank-Commit erzeugt ein Hintergrunddienst einen Fingerabdruck und übermittelt ihn an Constellation Digital Evidence. Verzögert sich der Nachweis, bleibt die Hand bestehen. Schlägt der Nachweis fehl, bleibt die Hand ebenfalls bestehen. Nach der Finalisierung verfügt die Hand über einen belastbareren öffentlichen Datensatz.
Diese Trennung ist die wichtigste technische Entscheidung der gesamten Integration.
Die Nachweis-Pipeline
Die Pipeline ist bewusst kurz gehalten.
Zuerst wird eine Hand beendet und Open Poker speichert das Ergebnis. Aus den gespeicherten Daten erstellen wir anschließend eine öffentliche Hand-Nutzlast: Boardkarten, öffentlich aufgedeckte Karten, Gewinner, Aktionen, Stackbewegungen, Handnummer, Tisch-ID und Zeitstempel.
Danach wird diese Nutzlast in deterministisches JSON mit sortierten Schlüsseln und ohne überflüssige Leerzeichen umgewandelt. Determinismus ist entscheidend, weil ein Nachweis nur dann nützlich ist, wenn dieselben Handdaten immer dieselbe Bytefolge ergeben. Das ist dasselbe Grundproblem, das das JSON Canonicalization Scheme der IETF behandelt (RFC 8785). Der lokale Dokument-Hash von Open Poker beansprucht jedoch keine vollständige Kompatibilität mit RFC 8785. Die Bytefolge wird mit SHA-256 gehasht. Dieser Algorithmus gehört zur von NIST definierten Secure Hash Standard-Familie (FIPS 180-4). Das Ergebnis ist der Dokument-Hash, den Nutzer später selbst neu berechnen können.
Anschließend wird der Fingerabdruck entsprechend dem dokumentierten Einreichungs- und Verifizierungsmodell über Constellation Digital Evidence eingereicht (Entwicklerdokumentation, Dokumentation zum Suchen und Verifizieren). Open Poker speichert den Nachweisstatus und den Explorer-Link bei der Hand. So kann die Handseite anzeigen, ob der Datensatz aussteht, eingereicht, finalisiert oder fehlerhaft ist.
Der vollständige Ablauf lautet damit: gespeicherte Hand, öffentliche Nutzlast, deterministischer Hash, externer Fingerabdruck, sichtbarer Nachweis.
Warum wir öffentliche Handdaten hashen
Poker stellt eine Datenschutzanforderung, die viele Ideen nach dem Muster "einfach on-chain speichern" übersehen: Verborgene Informationen sind Teil des Spiels. Legt ein Nachweissystem die verdeckten Karten gefoldeter Spieler offen, verschlechtert es das Produkt.
Open Poker hasht den öffentlichen Datensatz und nicht den verborgenen Spielzustand. Die Nachweis-Nutzlast entspricht den Informationen, die eine Handanalyse gefahrlos zeigen kann: öffentliche Aktionen, öffentliche Karten, Gewinner und Stackänderungen. Verdeckte Karten nach einem Fold, API-Schlüssel, private Agenten-IDs und interner Eigentümerstatus sind nicht enthalten.
Dadurch erhalten wir genau die gewünschte Eigenschaft. Entwickler können prüfen, ob der öffentliche Handdatensatz unbemerkt verändert wurde, ohne dass Open Poker schützenswerte Informationen veröffentlichen muss.
Warum der Prozess erst nach dem Speichern beginnt
Die Nachweisebene startet erst nach der dauerhaften Speicherung, weil sich ein Nachweis auf einen realen Datensatz beziehen muss. Kann eine Hand nicht gespeichert werden, existiert keine stabile öffentliche Handhistorie, die belegt werden könnte.
Diese Reihenfolge schützt auch die Spielschleife. Eine Hand wartet für ihren Abschluss nicht auf einen Nachweisdienst. Open Poker speichert zuerst das Ergebnis, danach läuft die Nachweiserstellung im Hintergrund.
So bleibt die Integration gegenüber typischen Produktionsfehlern robust:
- Die externe API kann langsam reagieren.
- Die Finalisierung kann Zeit benötigen.
- In einer Umgebung außerhalb der Produktion können Zugangsdaten fehlen.
- Ein erneuter Versuch kann stattfinden, ohne das Handausgangsergebnis zu verändern.
Keiner dieser Fälle darf beeinflussen, ob ein Pot korrekt ausgezahlt wird.
Warum wir den Nachweisstatus lokal speichern
Open Poker führt einen lokalen Nachweisdatensatz, weil Nutzer einen klaren Status brauchen und keine Blackbox. Ein Datensatz kann pending, submitted, finalized oder error sein. War die Nachweisfunktion beim Abschluss der Hand deaktiviert, gibt es möglicherweise überhaupt keinen Nachweisdatensatz. Das ist etwas anderes, als einen nicht vorhandenen Nachweis vorzutäuschen.
Dank dieses Zustands kann die Benutzeroberfläche ehrlich bleiben. Ein ausstehender Nachweis wird als ausstehend angezeigt. Ein finalisierter Nachweis zeigt den Explorer-Link. Fehlt der Nachweis, behauptet die Oberfläche nicht das Gegenteil.
Der lokale Datensatz bietet Open Poker außerdem einen Speicherort für den Dokument-Hash und die kanonische Nutzlast, die zur eigenständigen Verifizierung benötigt werden. Der externe Nachweis ist wichtig, doch Nutzer brauchen zusätzlich die exakte Bytefolge der Nutzlast, um den Hash neu zu berechnen.
Auch das Verhalten bei Wiederholungsversuchen wird dadurch eindeutig. Ausstehende Einreichungen können erneut versucht werden, ohne die gespeicherte Hand zu verändern. Eingereichte Fingerabdrücke lassen sich bis zur Finalisierung abfragen. Sind alle Versuche ausgeschöpft, kann der Datensatz in den Fehlerzustand wechseln, den die Oberfläche offen anzeigt.
Warum die Benutzeroberfläche wichtig ist
Die meisten Nutzer werden weder eine API-Antwort lesen noch einen Fingerabdruck direkt untersuchen. Der Nachweis muss dort erscheinen, wo die Frage entsteht: auf der Handseite.
Die Detailansicht der Hand zeigt Status, Fingerabdruck, Dokument-Hash, Bestätigungszeit, Constellation-Explorer-Link und einen kurzen Ablauf zur Verifizierung. Sie kann außerdem die kanonische Nutzlast bereitstellen, aus der der Dokument-Hash erzeugt wurde. Dadurch wird aus einer reinen Backend-Funktion ein sichtbares Produktmerkmal.
Die Benutzeroberfläche hat eine Aufgabe: Sie soll die Verifizierung greifbar machen. Nutzer sollen eine Hand öffnen, den vorhandenen Nachweis sehen, den Explorer aufrufen und verstehen können, wofür der Hash steht.
Was unabhängige Verifizierung hier bedeutet
Unabhängige Verifizierung bedeutet nicht, dass Open Poker vollständig vertrauensfrei wird. Sie bedeutet, dass sich die öffentliche Hand-Nutzlast mit einer kryptografischen Festschreibung außerhalb unserer Datenbank vergleichen lässt.
Die Verifizierung funktioniert so:
- Rufen Sie die öffentliche Hand-Nutzlast ab.
- Hashen Sie die kanonische Nutzlast.
- Vergleichen Sie das Ergebnis mit dem von Open Poker angezeigten Dokument-Hash.
- Prüfen Sie den Fingerabdruck bei Constellation Digital Evidence.
Wird die öffentliche Hand-Nutzlast nach der Festschreibung geändert, ändert sich der Hash. Heimliche Änderungen werden dadurch erkennbar.
Diese Aussage ist eng begrenzt, aber wertvoll, weil sie überprüfbar ist.
Was wir bewusst vermieden haben
Wir haben Digital Evidence bewusst nicht zu einer Abhängigkeit des Spielablaufs gemacht. Die Nachweisebene darf weder entscheiden, ob eine Hand enden kann, noch ob ein Bot handeln darf oder eine Riverkarte ausgeteilt wird.
Ebenso haben wir darauf verzichtet, private Spielzustände zu veröffentlichen. Mehr Daten ergeben nicht automatisch einen besseren Nachweis. Beim Poker können die falschen Daten die Integrität späterer Hände beeinträchtigen.
Außerdem sollte die Funktion keine Krypto-Kenntnisse voraussetzen. Sichtbar sind ein Hash, ein Status und ein Explorer-Link. Das reicht aus, damit Entwickler das Vertrauensmodell verstehen können, ohne jedes interne Implementierungsdetail kennen zu müssen.
Erkenntnisse für Entwickler
Wenn Sie eine Anwendung um Nachweise oder Notarisierung erweitern, können Sie dieses Muster übernehmen:
- Wählen Sie den Datensatz aus, dem Nutzer tatsächlich vertrauen müssen.
- Definieren Sie die öffentliche Nutzlast sorgfältig.
- Bringen Sie die Nutzlast vor dem Hashen in eine deterministische Form.
- Schreiben Sie den Fingerabdruck außerhalb Ihrer primären Datenbank fest.
- Halten Sie die Nachweisebene vom kritischen Laufzeitpfad fern.
- Geben Sie Nutzern einen sichtbaren Weg zur Verifizierung des Ergebnisses.
Der Schlüssel liegt in der Beschränkung. Nachweissysteme funktionieren am besten, wenn die Aussage eng gefasst, die Grenze eindeutig und der Verifizierungsweg leicht zu erklären ist.
Für Open Poker lautet diese Aussage: Sobald eine abgeschlossene Hand mit einem Fingerabdruck versehen wurde, kann der öffentliche Handdatensatz nicht unbemerkt verändert werden, ohne dass die Verifizierung fehlschlägt.
Das ist die technische Kernaussage. Der Code unterstützt diesen Anspruch, statt die Funktion komplizierter erscheinen zu lassen, als sie ist.
Technische Quellen
Die beschriebenen Architekturentscheidungen stützen sich auf externe Standards und Produktdokumentationen:
- Die Entwicklerdokumentation zu Constellation Digital Evidence beschreibt das Modell für Einreichung und Verifizierung.
- Die Constellation-Dokumentation zum Signieren und Einreichen erläutert die SDK-basierte Erstellung und Übermittlung von Fingerabdrücken.
- Die Constellation-Dokumentation zum Suchen und Verifizieren beschreibt öffentliche Suche und Explorer-Verhalten.
- RFC 8785 erklärt, warum deterministisches JSON in kryptografischen Abläufen wichtig ist.
- NIST FIPS 180-4 definiert die Secure Hash Standard-Familie, zu der SHA-256 gehört.
FAQ
Warum wird eine Hand nicht schon während des Spiels notarisiert?
Weil der Nachweis das Spiel weder verlangsamen noch unterbrechen darf. Open Poker speichert zuerst die Hand und erzeugt den Nachweis anschließend im Hintergrund. So bleibt die Nachweisebene von der laufenden Spielschleife getrennt.
Was genau wird verifiziert?
Die öffentliche Hand-Nutzlast: Aktionen, öffentliche Karten, Gewinner, Stackbewegungen, Hand-IDs und Zeitstempel. Verdeckte Karten gefoldeter Spieler und interne Geheimnisse sind nicht Teil des Nachweises.
Bedeutet ein finalisierter Nachweis, dass die Poker-Engine fehlerfrei war?
Nein. Er bedeutet, dass der festgeschriebene öffentliche Handdatensatz auf spätere Manipulationen geprüft werden kann. Die korrekte Funktion der Engine hängt weiterhin von Tests, Überwachung, Replays und Reviews ab.
Was geschieht, wenn der Nachweisdienst ausfällt?
Die Hand wird trotzdem abgeschlossen und bleibt analysierbar. Die Einreichung des Nachweises kann im Hintergrund erneut versucht werden. Sind alle Versuche ausgeschöpft, wechselt der Nachweisdatensatz in den Fehlerzustand, statt den Spielablauf zu blockieren.
Warum verwendet Open Poker Constellation Digital Evidence?
Constellation Digital Evidence bietet einen externen Fingerabdruck und einen öffentlichen Suchpfad für abgeschlossene Handdatensätze. Genau diese Vertrauensgrundlage haben wir benötigt: überprüfbare Nachweise, ohne das gesamte Spiel auf eine Chain zu verlagern.
Was sollten andere Entwickler übernehmen?
Übernehmen Sie die klare Systemgrenze. Speichern Sie zuerst den maßgeblichen Datensatz, hashen Sie eine deterministische öffentliche Nutzlast, reichen Sie den Nachweis asynchron ein und zeigen Sie das Verifizierungsergebnis dort an, wo Nutzer den Datensatz ohnehin prüfen.