Decisões de engenharia por trás da camada de evidências do Open Poker
A integração do Digital Evidence ao Open Poker parte de uma decisão de engenharia: a prova deve fortalecer os registros das mãos sem entrar no caminho crítico do jogo. Queríamos que as mãos concluídas pudessem ser verificadas pelo Constellation Digital Evidence, mas uma API de prova, a latência da rede ou a espera pela finalização jamais poderiam determinar se a mão termina ou se o pote é concedido.
Divulgação: sou o fundador do openpoker.ai. Esta é a Parte 2 de uma série de duas partes. Parte 1 explica o motivo do produto; esta postagem explica as opções de engenharia sem se transformar em um passo a passo do código.
Parte 1: Produto - Por que Open Poker usa evidências digitais da Constellation.
Parte 2: Engenharia - as escolhas de design por trás da camada de evidências: quando criamos provas, o que fazemos hash, o que permanece privado e como a verificação permanece independente.
Principais conclusões
- Open Poker inicia o trabalho de evidência somente após o resultado da mão ser confirmado no banco de dados.
- O hash do documento é SHA-256 sobre JSON determinístico para a carga útil pública.
- Os estados das evidências locais são explícitos: pendente, enviado, finalizado ou erro.
- A página da mão exibe o status, o hash do documento, a impressão digital, o link do explorador e a carga canônica necessária para a verificação.
O objetivo do projeto
A camada de evidências precisava atender a duas exigências ao mesmo tempo: ser forte o bastante para revelar alterações no histórico e discreta o bastante para nunca mudar a forma como as mãos são jogadas.
Isso definiu um limite simples. Open Poker executa o jogo, salva a mão e publica sua página. Depois da confirmação no banco de dados, um serviço de evidências em segundo plano cria uma impressão digital e a envia ao Constellation Digital Evidence. Se a prova demorar ou falhar, a mão continua existindo. Quando a prova é finalizada, o registro público da mão ganha uma garantia adicional.
Esse limite é a decisão de engenharia mais importante na integração.
O pipeline de provas
O pipeline é intencionalmente curto.
Primeiro, uma mão termina e o Open Poker salva o resultado. Depois, montamos uma carga pública com os dados persistidos: cartas do board, cartas reveladas, vencedores, ações, variações nos stacks, número da mão, ID da mesa e timestamps.
Em seguida, essa carga é convertida em JSON determinístico, com chaves ordenadas e sem espaços em branco extras. O determinismo importa porque a prova só é útil se os mesmos dados da mão sempre produzirem os mesmos bytes. Esse é o problema geral tratado pelo esquema de canonicalização de JSON da IETF (RFC 8785), embora o hash local de documentos do Open Poker não alegue compatibilidade total com a RFC 8785. Aplicamos SHA-256 a esses bytes, um algoritmo da família Secure Hash Standard definida pelo NIST (FIPS 180-4), e produzimos o hash de documento que os usuários podem recalcular depois.
Depois, a impressão digital é enviada pelo Constellation Digital Evidence conforme o fluxo documentado de envio e verificação (documentação para desenvolvedores, localizar e verificar documentos). Open Poker armazena o status da prova e o link do explorador junto à mão, permitindo que a página informe se o registro está pendente, enviado, finalizado ou com erro.
Essa é a forma completa: mão salva, carga pública, hash determinístico, impressão digital externa, prova visível.
Por que fazemos hash de dados públicos
O pôquer traz uma questão de privacidade ignorada por muitas propostas de “colocar tudo na blockchain”: informações ocultas fazem parte do jogo. Um sistema de prova que exponha as hole cards de quem foldou prejudica o produto.
Open Poker gera o hash do registro público, não do estado oculto do jogo. A carga de evidências corresponde ao que uma análise de mão pode mostrar com segurança: ações públicas, cartas públicas, vencedores e variações nos stacks. Ela não inclui hole cards de quem foldou, chaves de API, IDs privados de agentes ou o estado interno do proprietário do bot.
Isso nos dá a propriedade que realmente desejamos. Um construtor pode verificar se o registro público não mudou silenciosamente, sem forçar Open Poker a publicar informações que deveriam permanecer ocultas.
Por que funciona depois que a mão é salva
A camada de evidências começa depois da persistência porque a prova precisa se referir a um registro real. Se a mão não for salva, não existe um histórico público estável a comprovar.
Essa ordem também protege o loop do jogo. A mão não espera por um serviço de prova antes de terminar. Open Poker registra o resultado primeiro e, em seguida, o trabalho de evidência acontece em segundo plano.
Isso torna a integração resiliente em modos normais de falha de produção:
- A API externa pode ser lenta.
- A finalização pode levar algum tempo.
- As credenciais podem estar faltando em um ambiente que não seja de produção.
- Uma nova tentativa pode acontecer sem alterar o resultado da mão.
Nada disso deve afetar se um pote é concedido corretamente.
Por que mantemos o estado das evidências locais
Open Poker mantém um registro local de evidências porque os usuários precisam de um status claro, não de uma caixa preta. O registro pode estar em pending, submitted, finalized ou error. Se o recurso estava desativado quando a mão terminou, pode não existir registro algum, o que é diferente de fingir que há uma prova.
Esse estado permite que a interface seja transparente. Uma prova pendente deve aparecer como pendente. Uma prova finalizada deve mostrar o link do explorador. Se não houver prova, a interface não deve sugerir o contrário.
O registro local também fornece ao Open Poker um local para armazenar o hash do documento e a carga canônica necessária para a autoverificação. A prova externa é útil, mas o usuário ainda precisa dos bytes de carga exatos para recalcular o hash.
Também torna explícito o comportamento de nova tentativa. Os envios pendentes podem ser repetidos sem alterar a mão salva, as impressões digitais enviadas podem ser pesquisadas até a finalização e as tentativas esgotadas podem se tornar um estado de erro que a IU pode mostrar honestamente.
Por que a IU é importante
A maioria dos usuários não lerá uma resposta da API nem inspecionará uma impressão digital diretamente. A prova tem que aparecer onde aparece a pergunta: na página de mão.
A página de detalhes da mão mostra status, impressão digital, hash do documento, horário da confirmação, link do Constellation Explorer e um breve roteiro de verificação. Ela também pode exibir a carga canônica usada para gerar o hash. Assim, a infraestrutura de back-end se transforma em um recurso visível do produto.
A IU tem uma função: fazer com que a verificação pareça concreta. Você deve ser capaz de olhar para uma mão, ver que existe uma prova, abrir o explorador e entender o que o hash representa.
O que significa verificação independente aqui
A verificação independente não significa que Open Poker se torne totalmente confiável. Isso significa que a carga útil pública pode ser verificada em relação a um compromisso criptográfico fora do nosso banco de dados.
A ideia de verificação é:
- Obtenha a carga pública.
- Calcule o hash da carga canônica.
- Compare o resultado com o hash do documento exibido pelo Open Poker.
- Verifique a impressão digital no Constellation Digital Evidence.
Se a carga pública mudar depois da confirmação, o hash também muda. Assim, alterações silenciosas se tornam detectáveis.
Esta é uma afirmação restrita, mas é útil porque é testável.
O que evitamos deliberadamente
Evitamos transformar a Evidência Digital em uma dependência de jogabilidade. A camada de prova não deve decidir se uma mão pode terminar, se um bot pode agir ou se uma carta no river é distribuída.
Também evitamos publicar o estado privado do jogo. Mais dados nem sempre são melhores provas. No pôquer, dados errados podem prejudicar a integridade de mãos futuras.
Também evitamos exigir conhecimentos de criptografia. O usuário vê um hash, um status e um link para o explorador. Isso basta para entender o modelo de confiança sem conhecer todos os detalhes internos da implementação.
Lições para construtores
Se você estiver adicionando evidências ou certificação digital a um aplicativo, este padrão pode ser reutilizado:
- Escolha o registro em que os usuários realmente precisam confiar.
- Defina a carga pública com cuidado.
- Torne a carga útil determinística antes do hash.
- Registre a impressão digital fora do banco de dados principal.
- Mantenha a camada de prova fora do caminho crítico do tempo de execução.
- Dê aos usuários uma maneira visível de verificar o resultado.
O segredo é manter o escopo contido. Sistemas de evidências funcionam melhor quando a afirmação é específica, os limites são claros e o processo de verificação é fácil de explicar.
No Open Poker, a afirmação é esta: depois que uma mão concluída recebe sua impressão digital, o registro público não pode ser alterado silenciosamente sem invalidar a verificação.
Essa é a história da engenharia. O código existe para apoiar essa afirmação, não para fazer o recurso parecer mais complicado do que realmente é.
Referências de engenharia
As opções de engenharia acima são baseadas em alguns padrões externos e documentos de produto:
- Documentos do desenvolvedor do Constellation Digital Evidence para o modelo de envio e verificação de evidências.
- Documentos de assinatura e envio do Constellation para criação e envio de impressões digitais baseadas em SDK.
- Documentos de localização e verificação do Constellation para pesquisa pública e comportamento do explorador.
- RFC 8785 para saber por que o JSON determinístico é importante em fluxos de trabalho criptográficos.
- NIST FIPS 180-4 para a família Secure Hash Standard que inclui SHA-256.
Perguntas frequentes
Por que não autenticar durante a mão
Porque a prova não deve retardar ou interromper o jogo. Open Poker salva a mão primeiro e depois cria evidências em segundo plano. Isso mantém a camada de prova separada do loop do jogo ao vivo.
O que exatamente está sendo verificado
A carga da mão pública: ações, cartas públicas, vencedores, variações nos stacks, IDs das mãos e timestamps. As cartas privadas de quem foldou e os segredos internos não fazem parte da prova.
Uma prova finalizada significa que o motor de pôquer não teve nenhum bug
Não. Significa apenas que é possível detectar alterações posteriores no registro público confirmado. A correção do motor ainda depende de testes, monitoramento, reprodução e revisão.
O que acontece se o serviço de prova estiver inativo
A mão ainda é concluída e permanece revisável. O envio de evidências pode ser repetido em segundo plano e, se as novas tentativas se esgotarem, o registro de evidências poderá passar para um estado de erro em vez de bloquear o jogo.
Por que usar a Evidência Digital Constellation
Ele oferece ao Open Poker uma impressão digital externa e um caminho de consulta pública para registros de mãos concluídas. Era exatamente a garantia básica de que precisávamos: evidências verificáveis sem mover todo o jogo para uma blockchain.
O que outros construtores deveriam copiar
Copie a separação de responsabilidades. Primeiro salve o registro que serve como fonte de verdade, depois gere o hash de uma carga pública determinística, envie a prova de forma assíncrona e mostre o resultado da verificação onde os usuários já consultam o registro.