Les choix techniques de la couche de preuves d'Open Poker

L'intégration des preuves numériques d'Open Poker est construite autour d'une idée d'ingénierie : la preuve devrait renforcer les enregistrements de mains sans devenir une partie du chemin critique du poker. Nous voulions que les mains terminées soient vérifiables via Constellation Digital Evidence, mais nous ne voulions pas d'API de preuve, de retard réseau ou d'attente de finalisation pour décider si une main peut se terminer ou si un pot peut être attribué.

Divulgation : je suis le fondateur de openpoker.ai. Il s'agit de la deuxième partie d'une série en deux parties. La partie 1 explique la raison du produit ; cet article explique les choix d'ingénierie sans se transformer en une présentation du code.

Partie 1 : Produit : Pourquoi Open Poker utilise Constellation Digital Evidence.

Partie 2 : Ingénierie : les choix de conception de la couche de preuves, le moment où nous les créons, les données que nous hachons, ce qui reste privé et la façon dont la vérification demeure indépendante.

Points clés à retenir

• Open Poker ne commence le travail de preuve qu'une fois le résultat de la main enregistré dans la base de données.
• Le hachage du document est SHA-256 sur JSON déterministe pour la charge utile publique.
• Les états des preuves locales sont explicites : en attente, soumis, finalisé ou erreur.
• La page de main expose le statut, le hachage du document, l'empreinte digitale, le lien de l'explorateur et la charge utile canonique nécessaire à la vérification.

L'objectif de conception

La couche de preuves devait répondre à deux exigences : être assez robuste pour révéler toute falsification de l’historique des mains, et assez discrète pour ne jamais modifier le déroulement du jeu.

Cela a conduit à une frontière simple. Open Poker exécute le jeu, enregistre la main et expose la page de la main publique. Après la validation de la base de données, un service de preuve en arrière-plan crée une empreinte digitale et l'envoie à Constellation Digital Evidence. Si la preuve tarde, la main existe toujours. Si la preuve échoue, la main existe toujours. Si la preuve est finalisée, la main obtient un enregistrement public plus solide.

Cette limite est la décision technique la plus importante dans l’intégration.

Le pipeline de preuves

Le pipeline est volontairement court.

Tout d'abord, une main se termine et Open Poker enregistre le résultat. Ensuite, nous construisons une charge utile de main publique à partir des données enregistrées : cartes du tableau, cartes affichées publiquement, gagnants, actions, évolution des stacks, numéro de main, identifiant de table et horodatages.

Ensuite, cette charge utile est transformée en JSON déterministe avec des clés triées et sans espace supplémentaire. Le déterminisme est important car la preuve n'est utile que si les mêmes données de la main produisent toujours les mêmes octets. Il s'agit du même problème général résolu par le système de canonisation JSON de l'IETF (RFC 8785), mais le hachage de document local d'Open Poker ne revendique pas une compatibilité totale avec la RFC 8785. Ces octets sont hachés avec SHA-256, un membre de la famille Secure Hash Standard définie par le NIST (FIPS 180-4), produisant le hachage de document que les utilisateurs peuvent recalculer ultérieurement.

Ensuite, l'empreinte digitale est soumise via Constellation Digital Evidence, selon le modèle de soumission et de vérification documenté de Constellation (documents du développeur, trouver et vérifier les documents). Open Poker stocke le statut de la preuve et le lien de l'explorateur à côté de la main, afin que la page de la main puisse indiquer si l'enregistrement est en attente, soumis, finalisé ou erroné.

Le processus complet est donc le suivant : main enregistrée, charge utile publique, hachage déterministe, empreinte numérique externe, preuve visible.

Pourquoi nous hachons les données publiques

Le poker a un problème de confidentialité que de nombreuses idées de « inscription sur une blockchain » ignorent : les informations cachées font partie du jeu. Si un système de preuve fuit des cartes privatives des joueurs ayant foldé, cela a aggravé le produit.

Open Poker hache le dossier public, pas le jeu caché. La charge utile de preuves est censée correspondre à ce qu'un examen manuel peut montrer en toute sécurité : actions publiques, cartes publiques, gagnants et évolution des stacks. Il n'inclut pas les cartes privatives des joueurs ayant foldé, les clés API, les identifiants d'agent privés ou l'état du propriétaire interne.

Nous obtenons ainsi la garantie recherchée. Un développeur peut vérifier que l'historique public des mains n'a pas été modifié discrètement, sans obliger Open Poker à publier des informations qui devraient rester cachées.

Pourquoi le traitement s'exécute après l'enregistrement de la main

La couche de preuves commence après la persistance car une preuve doit faire référence à un enregistrement réel. Si une main ne parvient pas à sauvegarder, il n’y a pas d’historique public stable à prouver.

Cet ordre protège également la boucle de jeu. La main n’attend pas un service d’épreuve pour terminer. Open Poker enregistre d'abord le résultat, puis le travail de preuve se déroule en arrière-plan.

Cela rend l’intégration résiliente dans les modes normaux d’échec de production :

• L'API externe peut être lente.
• La finalisation peut prendre du temps.
• Les informations d'identification peuvent manquer dans un environnement hors production.
• Une nouvelle tentative peut avoir lieu sans changer le résultat de la main.

Aucun de ces éléments ne devrait affecter l'attribution correcte d'un pot.

Pourquoi nous conservons l'état des preuves locales

Open Poker conserve un dossier de preuves local car les utilisateurs ont besoin d'un statut clair, pas d'une boîte noire. Un enregistrement peut être « en attente », « soumis », « finalisé » ou « erreur ». Si la preuve a été désactivée une fois la main terminée, il se peut qu'il n'y ait aucune preuve du tout, ce qui est différent de prétendre que la preuve existe.

C’est cet état qui permet à l’interface utilisateur d’être honnête. Une preuve en attente devrait dire en attente. Une preuve finalisée doit montrer le lien de l'explorateur. Une preuve manquante ne doit pas prétendre exister.

L'enregistrement local donne également à Open Poker un endroit pour stocker le hachage du document et la charge utile canonique nécessaires à l'auto-vérification. La preuve externe est utile, mais l'utilisateur a toujours besoin des octets exacts de charge utile pour recalculer le hachage.

Cela rend également explicite le comportement de nouvelle tentative. Les soumissions en attente peuvent réessayer sans changer la main enregistrée, les empreintes digitales soumises peuvent être interrogées jusqu'à la finalisation, et les tentatives épuisées peuvent devenir un état d'erreur que l'interface utilisateur peut afficher honnêtement.

Pourquoi l'interface utilisateur est importante

La plupart des utilisateurs ne liront pas une réponse API et n’inspecteront pas directement une empreinte numérique. La preuve doit apparaître là où la question se pose : sur la page de la main.

La vue détaillée de la main affiche l'état, l'empreinte digitale, le hachage du document, l'heure de confirmation, le lien de l'explorateur Constellation et un bref flux « comment vérifier ». Il peut également exposer la charge utile canonique utilisée pour le hachage du document. Cela transforme la couche de preuves de la plomberie back-end en une véritable fonctionnalité de produit.

L’interface utilisateur n’a qu’une seule tâche : rendre la vérification concrète. Vous devriez pouvoir regarder une main, voir qu'une preuve existe, ouvrir l'explorateur et comprendre ce que représente le hachage.

Que signifie ici la vérification indépendante

Une vérification indépendante ne signifie pas qu'Open Poker devient totalement sans confiance. Cela signifie que la charge utile publique peut être vérifiée par rapport à un engagement cryptographique en dehors de notre base de données.

L'idée de vérification est la suivante :

1. Récupérez la charge utile publique.
2. Hachez la charge utile canonique.
3. Comparez ce résultat au hachage du document affiché par Open Poker.
4. Vérifiez l'empreinte digitale sur Constellation Digital Evidence.

Si la charge utile de la main publique change après l'engagement, le hachage change. Cela rend les modifications discrètes détectables.

Il s’agit d’une affirmation étroite, mais elle est utile car elle est testable.

Ce que nous avons délibérément évité

Nous avons évité de transformer les preuves numériques en une dépendance du gameplay. La couche de preuve ne doit pas décider si une main peut se terminer, si un bot peut agir ou si une carte river est distribuée.

Nous avons également évité de publier l'état du jeu privé. Plus de données ne constituent pas toujours une meilleure preuve. Au poker, des données erronées peuvent nuire à l’intégrité des mains futures.

Et nous avons évité que cette fonctionnalité nécessite des connaissances en cryptographie. L'interface du produit est un hachage, un statut et un lien explorateur. Cela suffit pour qu'un développeur comprenne le modèle de confiance sans se soucier de chaque détail de mise en œuvre interne.

Leçons pour les développeurs

Si vous ajoutez un système de preuve ou de notarisation à une application, ce modèle est réutilisable :

1. Choisissez les enregistrements auxquels les utilisateurs doivent réellement faire confiance.
2. Définissez soigneusement la charge utile publique.
3. Rendez la charge utile déterministe avant le hachage.
4. Validez l'empreinte digitale en dehors de votre base de données principale.
5. Gardez la couche de preuve hors du chemin d'exécution critique.
6. Donnez aux utilisateurs un moyen visible de vérifier le résultat.

La clé consiste à rester mesuré. Les systèmes de preuves fonctionnent mieux lorsque la garantie annoncée reste précise, que la limite est claire et que la procédure de vérification est facile à expliquer.

Pour Open Poker, l'affirmation est la suivante : une fois l'empreinte digitale d'une main terminée, le historique public de la main ne peut pas être modifié en silence sans interrompre la vérification.

C'est l'histoire de l'ingénierie. Le code existe pour soutenir cette affirmation, et non pour rendre la fonctionnalité plus compliquée qu'elle ne l'est.

Références d'ingénierie

Les choix d'ingénierie ci-dessus sont fondés sur quelques normes externes et documents de produits :

• Documents du développeur Constellation Digital Evidence pour le modèle de soumission et de vérification des preuves.
• Documents Constellation sign-and-submit pour la création et la soumission d'empreintes digitales basées sur le SDK.
• Documents Constellation Find-and-Verify pour la recherche publique et le comportement de l'explorateur.
• RFC 8785 expliquant pourquoi le JSON déterministe est important dans les flux de travail cryptographiques.
• NIST FIPS 180-4 pour la famille Secure Hash Standard qui inclut SHA-256.

FAQ

Pourquoi ne pas ancrer une preuve pendant la main ?

Parce que la preuve ne doit pas ralentir ou interrompre le gameplay. Open Poker enregistre d'abord la main, puis crée des preuves en arrière-plan. Cela maintient la couche de preuve séparée de la boucle du jeu en direct.

Qu'est-ce qui est vérifié exactement ?

La charge utile de la main publique : actions, cartes publiques, gagnants, évolution des stacks, identifiants de main et horodatages. Les cartes privatives des joueurs ayant foldé et les secrets internes ne font pas partie de la preuve.

Une preuve finalisée signifie-t-elle que le moteur de poker n'avait aucun bug ?

Non. Cela signifie que le dossier public engagé peut être vérifié pour une falsification ultérieure. L'exactitude du moteur dépend toujours des tests, de la surveillance, de la relecture et de la révision.

Que se passe-t-il si le service de preuve est en panne ?

La main se termine toujours et reste révisable. La soumission de preuves peut être réessayée en arrière-plan, et si les tentatives sont épuisées, l'enregistrement des preuves peut passer à un état d'erreur au lieu de bloquer le jeu.

Pourquoi utiliser Constellation Digital Evidence ?

Il donne à Open Poker une empreinte externe et un moyen public de la rechercher pour les enregistrements de mains complétés. C’est exactement la garantie élémentaire dont nous avions besoin : des preuves vérifiables sans inscrire l'ensemble du jeu sur une blockchain.

Que devraient copier les autres développeurs ?

Reprenez cette séparation des responsabilités. Enregistrez d'abord la donnée qui fait foi, hachez une charge utile publique déterministe, soumettez les preuves de manière asynchrone et affichez le résultat de la vérification là où les utilisateurs consultent déjà l'enregistrement.