Open Pokerのエビデンスレイヤーを支える設計判断
Open Pokerのデジタル エビデンスの統合は、エンジニアリング上の 1 つのアイデアに基づいて構築されています。つまり、証明処理をポーカーのクリティカルパスへ含めずに、ハンドの記録を強化する必要があります。私たちは、完成したハンドを Constellation Digital Evidence を通じて検証できるようにしたいと考えていましたが、ハンドが終了できるか、ポットが授与されるかどうかを決定するために、証明API、ネットワーク遅延、またはファイナライズ待機を必要としませんでした。
開示: 私は openpoker.ai の創設者です。これは 2 部構成シリーズの第 2 部です。 パート 1 では製品の理由を説明します;この投稿では、コードの逐語的な解説ではなく、エンジニアリング上の選択について説明します。
パート 1: 製品 - Open Pokerが Constellation デジタル証拠を使用する理由。
パート 2: エンジニアリング - 証拠レイヤーの背後にある設計の選択: 証拠を作成するとき、何をハッシュするか、何を非公開にしておくか、検証をどのように独立させるか。
重要なポイント
- Open Pokerは、ハンドの結果がデータベースにコミットされた後にのみ証拠作業を開始します。
- ドキュメント ハッシュは、公開ハンドペイロードの正規化したJSON 上の SHA-256 です。
- ローカル証拠の状態は明示的です: 保留中、提出済み、完了済み、またはエラー。
- ハンド ページは、ステータス、ドキュメント ハッシュ、フィンガープリント、エクスプローラー リンク、検証に必要な正規ペイロードを公開します。
設計目標
証拠レイヤーは 2 つのニーズを同時に満たさなければなりません。1 つはハンド履歴の改ざんを可視化できるほど強力であること、もう 1 つはポーカー ハンドのプレイ方法が決して変わらないほど平凡で予測可能に動くことです。
これにより、単純な境界が得られました。 Open Poker はゲームを実行し、ハンドを保存し、パブリック ハンド ページを公開します。データベースのコミット後、バックグラウンド証拠サービスがフィンガープリントを作成し、それを Constellation Digital Evidence に送信します。証明が遅れてもハンドはまだ存在します。証明が失敗してもハンドはまだ存在します。証明が完了すると、ハンドはより強力な公開記録を取得します。
この境界は、統合における最も重要なエンジニアリング上の決定です。
証明パイプライン
パイプラインは意図的に短くしています。
まず、ハンドが完了し、Open Poker が結果を保存します。次に、保存されたデータ (ボード カード、公開されたカード、勝者、アクション、スタックの動き、ハンド番号、テーブル ID、タイムスタンプ) から公開ハンドペイロードを構築します。
次に、そのペイロードは、ソートされたキーと余分な空白を含まない確定的な JSON に変換されます。同じハンドデータが常に同じバイトを生成する場合にのみ証明が役立つため、決定論が重要です。これは IETF の JSON 正規化スキーム (RFC 8785) で対処されている一般的な問題と同じですが、Open Poker のローカル ドキュメント ハッシュは RFC 8785 との完全な互換性を主張していません。これらのバイトは、NIST (FIPS 180-4) によって定義された Secure Hash Standard ファミリのメンバーである SHA-256 でハッシュされ、ユーザーが後で再計算できるドキュメント ハッシュが生成されます。
次に、Constellation の文書化された送信および検証モデル (開発者ドキュメント、ドキュメントの検索と検証) に従って、フィンガープリントが Constellation Digital Evidence を通じて送信されます。 Open Poker はプルーフ ステータスとエクスプローラー リンクをハンドの横に保存するため、ハンド ページにはレコードが保留中、送信済み、確定済み、またはエラーのいずれであるかを表示できます。
処理の全体像は以上です。保存されたハンド、公開ペイロード、決定論的ハッシュ、外部指紋、目に見える証拠です。
公開ハンドデータをハッシュする理由
ポーカーにはプライバシーの問題があり、多くの「オンチェーンに置く」という考えが無視しています。隠された情報はゲームの一部です。プルーフシステムからフォールドしたプレイヤーのホールカードが漏れると、製品の品質が悪化します。
Open Pokerは、非公開のゲーム状態ではなく、公開記録をハッシュします。証拠ペイロードは、ハンド レビューで安全に表示できるもの (公開アクション、パブリック カード、勝者、スタックの変更) と一致することを目的としています。これには、フォールドしたプレイヤーのホールカード、API キー、プライベート エージェント ID、内部所有者の状態は含まれません。
これにより、実際に必要なプロパティが得られます。ビルダーは、Open Poker に隠蔽すべき情報の公開を強制することなく、公開ハンド記録が密かに変更されていないことを検証できます。
ハンドが保存された後に実行される理由
証明は実際の記録を参照する必要があるため、証拠レイヤーは永続化の後に開始されます。ハンドがセーブに失敗した場合、証明できる安定した公開ハンド履歴はありません。
この順序により、ゲーム ループも保護されます。ハンドは終了する前に証明サービスを待ちません。Open Pokerは最初に結果を記録し、その後証拠作業がバックグラウンドで行われます。
これにより、通常の本番環境の障害モードでも統合が復元可能になります。
- 外部 API は低速になる可能性があります。
- 完成には時間がかかる場合があります。
- 非実稼働環境では認証情報が欠落している可能性があります。
- ハンドの結果を変更せずに再試行することができます。
これらのいずれも、ポットが正しく授与されるかどうかには影響しません。
証拠をローカルにも保存する理由
ユーザーはブラックボックスではなく明確なステータスを必要とするため、Open Pokerはローカルの証拠記録を保持します。レコードは、pending、submitted、finalized、または error です。ハンドが完了したときに証拠が無効になっていた場合、証拠記録がまったく存在しない可能性がありますが、これは証拠が存在するふりをすることとは異なります。
この状態により、UI が正直になります。保留中の証拠には「保留中」と表示されます。確定済みの証明にはエクスプローラーのリンクが表示されるはずです。欠けている証拠が存在するふりをするべきではありません。
ローカル レコードは、自己検証に必要なドキュメント ハッシュと正規ペイロードを保存する場所も Open Poker に提供します。外部証明は便利ですが、ユーザーはハッシュを再計算するために正確なペイロード バイトを必要とします。
また、再試行動作を明示的にします。保留中の送信は保存されたハンドを変更せずに再試行でき、送信されたフィンガープリントは完了するまでポーリングでき、再試行が完了すると、UI に正直に表示できるエラー状態になる可能性があります。
UI が重要な理由
ほとんどのユーザーは、API 応答を読んだり、フィンガープリントを直接検査したりしません。証明は、質問が表示される場所、つまりハンドページに表示される必要があります。
ハンド詳細画面には、ステータス、フィンガープリント、ドキュメント ハッシュ、確認時間、Constellation Explorer リンク、および短い「確認方法」フローが表示されます。また、ドキュメント ハッシュに使用される正規ペイロードを公開することもできます。これにより、証拠レイヤーがバックエンド内部の処理から実際の製品機能に変わります。
UI には 1 つの役割があります。それは、検証を具体的にすることです。ハンドを見て、証拠が存在することを確認し、エクスプローラーを開いて、ハッシュが何を表しているのかを理解できるはずです。
ここでの独立した検証の意味
独立した検証は、Open Poker が完全にトラストレスになることを意味するものではありません。これは、公開ハンドのペイロードをデータベース外の暗号学的コミットメントと照合できることを意味します。
検証のアイデアは次のとおりです。
- 公開ハンドペイロードを取得します。
- 正規ペイロードをハッシュします。
- Open Poker によって表示されるドキュメント ハッシュと比較します。
- Constellation Digital Evidence でフィンガープリントを確認します。
コミット後に公開ハンドペイロードが変更されると、ハッシュも変更されます。これにより、静かな編集が検出可能になります。
これは狭い主張ですが、テスト可能であるため便利です。
私たちが意図的に避けたこと
私たちはデジタル証拠をゲームプレイの依存関係に変えることを避けました。証明レイヤーは、ハンドを終了できるかどうか、ボットがアクションできるかどうか、またはリバー カードが配られるかどうかを決定すべきではありません。
また、プライベートなゲーム状態の公開も避けました。データが多ければ多いほど、必ずしもより良い証拠になるとは限りません。ポーカーでは、間違ったデータは将来のハンドの完全性を損なう可能性があります。
また、この機能に暗号通貨の知識が必要になることは避けました。ユーザーに見える要素は、ハッシュ、ステータス、およびエクスプローラー リンクです。ビルダーが内部実装の詳細をすべて気にしなくても、信頼モデルを理解するにはこれで十分です。
ビルダー向けのレッスン
アプリケーションに証拠または公証を追加する場合、パターンは再利用可能です。
- ユーザーが実際に信頼する必要があるレコードを選択してください。
- パブリック ペイロードは慎重に定義してください。
- ハッシュする前にペイロードを決定的にしてください。
- フィンガープリントをプライマリ データベースの外部にコミットします。
- 証明レイヤーを重要な実行時パスから遠ざけてください。
- ユーザーに結果を確認するための視覚的な方法を提供します。
鍵となるのは抑制です。証拠システムは、主張が狭く、境界が明確で、検証経路が説明しやすい場合に最も効果を発揮します。
Open Pokerの主張は次のとおりです。完成したハンドのフィンガープリントが記録されると、検証を中断することなく公開ハンドの記録を静かに変更することはできません。
それがエンジニアリングの話です。このコードはその主張を裏付けるために存在しており、機能を必要以上に複雑に見せるためではありません。
エンジニアリングの参考資料
上記のエンジニアリング上の選択は、いくつかの外部規格と製品ドキュメントに基づいています。
- 証拠の提出と検証モデルについては、Constellation Digital Evidence 開発者ドキュメント を参照してください。
- SDK ベースのフィンガープリントの作成と送信用の Constellation 署名および送信ドキュメント。
- パブリック ルックアップとエクスプローラーの動作については、Constellation find-and-verify docs を参照してください。
- RFC 8785 暗号化ワークフローで決定論的な JSON が重要な理由。
- SHA-256 を含む Secure Hash Standard ファミリ用の NIST FIPS 180-4。
よくある質問
なぜハンド進行中に証明を作成しないのですか
なぜなら、証明によってゲームプレイが遅くなったり中断されたりしてはいけないからです。Open Pokerでは、まずハンドを保存し、次にバックグラウンドで証拠を作成します。これにより、証明レイヤーがライブ ゲーム ループから分離されます。
いったい何が検証されているのでしょうか？
公開ハンドペイロード: アクション、パブリック カード、勝者、スタックの動き、ハンド ID、およびタイムスタンプ。フォールドしたプレイヤーの非公開カードや内部機密は証拠の一部ではありません。
証明が完了したということは、ポーカー エンジンにバグがなかったことを意味するのでしょうか
いいえ。これは、コミットされた公開ハンド記録が後で改ざんされていないかチェックできることを意味します。エンジンの正確性は依然としてテスト、モニタリング、再生、レビューに依存します。
証明サービスが停止した場合はどうなりますか
ハンドはまだ完了しており、レビュー可能な状態のままです。証拠の提出はバックグラウンドで再試行でき、再試行が完了した場合、証拠レコードはゲームプレイをブロックするのではなくエラー状態に移行する可能性があります。
Constellation Digital Evidence を使用する理由
これにより、Open Poker に外部フィンガープリントと、完了したハンド記録の公開検索経路が提供されます。それはまさに私たちが必要としていた信頼を支える基盤、つまりゲーム全体をチェーンに移すことなく検証可能な証拠です。
他のビルダーは何をコピーすべきでしょうか
境界をコピーします。まず信頼の基点となる記録を保存し、決定論的なパブリック ペイロードをハッシュし、証拠を非同期で送信し、ユーザーが既にレコードをレビューしている場所で検証結果を表示できるようにします。