Decisiones de ingeniería tras la capa de evidencia de Open Poker
La integración de Digital Evidence en Open Poker parte de una decisión técnica: la prueba debe reforzar los registros de manos sin entrar en la ruta crítica de la partida. Queríamos que las manos completadas se pudieran verificar mediante Constellation Digital Evidence, pero no que una API externa, la latencia de red o la espera de confirmación decidieran si una mano puede terminar o si se reparte el bote.
Divulgación: soy el fundador de openpoker.ai. Esta es la segunda entrega de una serie de dos partes. La primera explica la decisión de producto; esta publicación aborda las decisiones técnicas sin convertirse en un tutorial de código.
Parte 1: Producto: Por qué Open Poker utiliza Constellation Digital Evidence.
Parte 2: Ingeniería: las decisiones de diseño de la capa de evidencia, cuándo generamos las pruebas, qué datos procesamos, qué se mantiene privado y cómo conservamos una vía de verificación independiente.
Conclusiones clave
- Open Poker inicia el procesamiento de evidencia solo después de confirmar el resultado de la mano en la base de datos.
- El hash del documento es SHA-256 sobre JSON determinista para la carga útil pública.
- Los estados locales de las pruebas son explícitos:
pending,submitted,finalizedoerror.- La página de la mano muestra el estado, el hash del documento, la huella digital, el enlace al explorador y la carga útil canónica necesaria para verificarla.
El objetivo del diseño
La capa de evidencia debía cumplir dos objetivos a la vez: ser lo bastante sólida para detectar manipulaciones del historial y lo bastante predecible para no alterar nunca el desarrollo de una mano de póker.
De ahí surgió un límite claro. Open Poker ejecuta la partida, guarda la mano y publica su página. Una vez confirmada la transacción en la base de datos, un servicio en segundo plano genera una huella digital y la envía a Constellation Digital Evidence. Si la prueba tarda o falla, la mano sigue existiendo. Si finaliza, el registro público de la mano gana una garantía adicional.
Separar ambos procesos es la decisión técnica más importante de la integración.
El flujo de prueba
El proceso es breve de forma intencionada.
Primero termina la mano y Open Poker guarda el resultado. Después construimos una carga útil pública con los datos almacenados: cartas comunitarias, cartas mostradas, ganadores, acciones, cambios en los stacks, número de mano, ID de la mesa y marcas de tiempo.
A continuación, serializamos la carga útil como JSON determinista, con las claves ordenadas y sin espacios adicionales. Esto importa porque la prueba solo sirve si los mismos datos de la mano producen siempre los mismos bytes. Es el mismo problema general que aborda el esquema de canonicalización JSON del IETF (RFC 8785), aunque Open Poker no afirma que su hash local sea totalmente compatible con RFC 8785. Aplicamos SHA-256 a esos bytes. SHA-256 forma parte de la familia Secure Hash Standard definida por NIST (FIPS 180-4). El resultado es el hash del documento que los usuarios pueden recalcular después.
Después enviamos la huella mediante Constellation Digital Evidence, siguiendo el modelo de envío y verificación documentado por Constellation (documentación para desarrolladores, búsqueda y verificación de datos). Open Poker guarda junto a la mano el estado de la prueba y el enlace al explorador. Así, la página puede indicar si el registro está pendiente, enviado, finalizado o contiene errores.
El flujo completo queda así: mano guardada, carga útil pública, hash determinista, huella externa y prueba visible.
Por qué aplicamos hash a los datos públicos
El póker plantea un requisito de privacidad que muchas propuestas de «ponerlo en cadena» pasan por alto: la información oculta forma parte del juego. Si el sistema de prueba revela cartas privadas que no se mostraron, perjudica al producto.
Open Poker procesa el registro público, no el estado oculto de la partida. La carga útil de evidencia corresponde a lo que puede mostrarse con seguridad al revisar una mano: acciones y cartas públicas, ganadores y cambios en los stacks. No incluye cartas privadas no mostradas, claves API, identificadores privados de agentes ni estado interno del propietario.
Así obtenemos la garantía que buscamos. Un creador puede comprobar que el registro público de la mano no cambió en silencio sin obligar a Open Poker a publicar información que debe permanecer oculta.
Por qué se ejecuta después de guardar la mano
La capa de evidencia se activa después de guardar los datos porque la prueba debe referirse a un registro real. Si una mano no se ha almacenado, no existe un historial público estable que se pueda demostrar.
Este orden también protege el bucle de la partida. La mano no espera al servicio de prueba para terminar. Open Poker registra primero el resultado y procesa la evidencia después, en segundo plano.
Así, la integración tolera fallos habituales de producción:
- La API externa puede ser lenta.
- La finalización puede llevar tiempo.
- Es posible que falten credenciales en un entorno que no sea de producción.
- El envío puede reintentarse sin cambiar el resultado de la mano.
Ninguna de estas situaciones debe afectar al reparto correcto del bote.
Por qué mantenemos el estado de evidencia local
Open Poker conserva un registro local de evidencia porque los usuarios necesitan un estado claro, no una caja negra. El registro puede estar «pendiente», «enviado», «finalizado» o en «error». Si la función estaba desactivada cuando terminó la mano, puede no existir ningún registro, algo muy distinto de fingir que hay una prueba.
Gracias a ese estado, la interfaz puede ser transparente. Una prueba pendiente debe aparecer como pendiente; una finalizada debe mostrar el enlace al explorador; y una prueba inexistente no debe presentarse como válida.
El registro local también permite almacenar el hash del documento y la carga útil canónica necesaria para verificarlo por cuenta propia. La prueba externa es útil, pero el usuario todavía necesita los bytes exactos para recalcular el hash.
Además, define con claridad los reintentos. Un envío pendiente puede repetirse sin modificar la mano guardada; una huella ya enviada puede consultarse hasta su finalización; y, si se agotan los intentos, el registro pasa a un estado de error que la interfaz puede mostrar con claridad.
Por qué es importante la interfaz de usuario
La mayoría de los usuarios no leerá una respuesta de la API ni inspeccionará directamente una huella digital. La prueba debe aparecer donde surge la duda: en la página de la mano.
La vista detallada muestra el estado, la huella digital, el hash del documento, la hora de confirmación, el enlace al explorador de Constellation y unas instrucciones breves de verificación. También puede mostrar la carga útil canónica empleada para calcular el hash. Así, la infraestructura del backend se convierte en una función tangible del producto.
La interfaz tiene una misión: hacer tangible la verificación. El usuario debe poder abrir una mano, comprobar que existe una prueba, visitar el explorador y entender qué representa el hash.
¿Qué significa aquí la verificación independiente?
La verificación independiente no significa que Open Poker deje de requerir confianza por completo. Significa que la carga útil pública puede compararse con un compromiso criptográfico externo a nuestra base de datos.
La idea de verificación es:
- Obtén la carga útil pública.
- Calcula el hash de la carga útil canónica.
- Compáralo con el hash del documento que muestra Open Poker.
- Verifica la huella digital en Constellation Digital Evidence.
Si la carga útil de la mano pública cambia después del compromiso, el hash cambia. Eso hace que las ediciones silenciosas sean detectables.
Esta es una afirmación limitada, pero es útil porque es comprobable.
Lo que evitamos deliberadamente
Evitamos que Digital Evidence se convirtiera en una dependencia de la partida. La capa de prueba no debe decidir si una mano puede terminar, si un bot puede actuar o si se reparte el river.
También evitamos publicar el estado privado. Más datos no siempre implican una prueba mejor. En el póker, revelar la información equivocada puede comprometer manos posteriores.
Por último, evitamos exigir conocimientos de criptografía. El producto presenta un hash, un estado y un enlace al explorador. Eso basta para que un creador entienda el modelo de confianza sin tener que estudiar cada detalle interno.
Lecciones para desarrolladores
Si añades evidencia o certificación a una aplicación, puedes reutilizar este patrón:
- Elige el registro en el que los usuarios realmente necesitan confiar.
- Define con cuidado la carga útil pública.
- Hazla determinista antes de calcular el hash.
- Registra la huella digital fuera de la base de datos principal.
- Mantén la capa de prueba fuera de la ruta crítica de ejecución.
- Ofrece a los usuarios una forma visible de verificar el resultado.
La clave es la moderación. Los sistemas de evidencia funcionan mejor cuando la afirmación es limitada, los límites son claros y el camino de verificación es fácil de explicar.
En Open Poker, la afirmación es esta: una vez registrada la huella de una mano completada, no se puede modificar su registro público en silencio sin invalidar la verificación.
Esta es la decisión técnica de fondo. El código existe para respaldar esa afirmación, no para presentar la función como algo más complicado de lo que es.
Referencias de ingeniería
Las opciones de ingeniería anteriores se basan en algunos estándares externos y documentos de producto:
- Documentos para desarrolladores de Constellation Digital Evidence para el modelo de presentación y verificación de pruebas.
- Documentación de firma y envío de Constellation para crear y enviar huellas digitales mediante el SDK.
- Documentos de búsqueda y verificación de Constellation para búsqueda pública y comportamiento del explorador.
- RFC 8785 explica por qué el JSON determinista es importante en los flujos de trabajo criptográficos.
- NIST FIPS 180-4 para la familia Secure Hash Standard que incluye SHA-256.
Preguntas frecuentes
¿Por qué no certificar ante notario durante la mano?
Porque la prueba no debe ralentizar ni interrumpir la partida. Open Poker guarda primero la mano y genera la evidencia en segundo plano. Así, la capa de prueba queda separada del bucle de juego en vivo.
¿Qué se está verificando exactamente?
La carga útil pública de la mano: acciones, cartas públicas, ganadores, cambios en los stacks, ID de la mano y marcas de tiempo. Las cartas privadas no mostradas y los secretos internos quedan fuera de la prueba.
¿Una prueba finalizada significa que el motor de póker no tuvo errores?
No. Significa que el registro público confirmado se puede verificar para detectar cambios posteriores. La corrección del motor sigue dependiendo de las pruebas, la supervisión, la reproducción de manos y la revisión.
¿Qué sucede si el servicio de prueba no funciona?
La mano termina y sigue disponible para revisión. El envío puede reintentarse en segundo plano y, si se agotan los intentos, el registro pasa a un estado de error en vez de bloquear la partida.
¿Por qué utilizar Constellation Digital Evidence?
Aporta a Open Poker una huella externa y una vía pública de búsqueda para los registros de manos completadas. Es justo la pieza de confianza que necesitábamos: evidencia verificable sin trasladar todo el juego a una red blockchain.
¿Qué deberían reutilizar otros desarrolladores?
Copia el límite entre procesos. Guarda primero el registro que actúa como fuente de verdad, calcula el hash de una carga útil pública determinista, envía la prueba de forma asíncrona y muestra el resultado donde los usuarios ya consultan ese registro.