[FEATURE] Implement Interactive Provably Fair Hand Verification Interface – PlayBlind Reference

Moved from block52/poker-vm#2643 (filed by @Dzeezbtc on 2026-10-07). The design discussion stays on the original issue, which is private. Outcome: phase 1 is commit-reveal dealing with a trusted validator dealer (pokerchain#426 for the chain, poker-vm#2695 for the engine), and this panel is built against the checks those expose.

Priority: High
Platform: Block52 Poker
Type: Feature / UI / Blockchain Verification
Reference: PlayBlind – https://playblind.com/

Overview

Implement a comprehensive, user-friendly, provably fair hand verification interface within Block52.

The proposed feature should closely follow the visual presentation, navigation, and verification workflow demonstrated in the attached PlayBlind screenshots.

The objective is to allow players to inspect the cryptographic integrity of any poker hand, understand how the cards were generated, and independently verify that the deal was fair.

The verification interface must be accessible at any time, including during an active hand.

Important: Verification results must reflect whether the hand is still running or has been completed.

1. Accessing the Verification Interface

Introduce a clearly visible “Provably Fair” button or indicator near the poker table information.

The indicator should display the current commitment status, similar to PlayBlind's “Deck committed” indicator.

Clicking this button should open a compact information panel displaying:

• Explanation of how Block52's provably fair dealing works.
• Current hand number and cryptographic commitment.
• Relevant blockchain information.
• Upcoming hand commitment, where applicable.
• Player seed information, if supported by Block52's protocol.
• “Verify this hand” button.

The panel should be accessible without leaving the poker table.

2. Verification Workflow – Hand Still Running

Players must be able to click “Verify this hand” while a hand is in progress.

When selected, a larger verification window should open over the poker table.

Expected Display

Hand #XXXXX – Table Name

Status: Hand still running – verification pending.

Display an explanation such as:

“Hand still running – the server seed is revealed when it ends.”

The verification window should display the four verification categories:

1. Seed matches the commitment.
2. Public randomness matches the randomness beacon.
3. Commitment was anchored on-chain before the public randomness became available.
4. Recomputed deck reproduces every card.

Each category should display a pending or unavailable status rather than a green verification checkmark.

Where appropriate, explain why verification cannot yet be completed.

Important Requirements

• Verification must not reveal unreleased cards or secret seeds.
• Verification should not interfere with gameplay.
• The interface should remain accessible while players are making decisions.
• Players should be able to close the verification window and continue playing normally.
• Verification should become available once the required hand data has been published.

3. Verification Workflow – Completed Hand

Once a hand is completed and the necessary cryptographic data is available, the verification interface should display the full results.

Verification Summary

A prominent green success banner should appear when all checks pass:

“Verified – this hand was dealt exactly as committed.”

Below this, display four independently verified categories.

Check 1 – Seed Matches the Commitment

Verify that the revealed seed and associated inputs reproduce the commitment published before the hand.

Display the relevant cryptographic method and verification result.

Check 2 – Public Randomness Verification

Display the randomness source used by Block52.

Where applicable, show:

• Randomness round or identifier.
• Published randomness value.
• Verification result.
• Link to the independent randomness source.

Check 3 – Blockchain Commitment Verification

Demonstrate that the commitment was recorded before the relevant randomness became available.

Display:

• Commitment hash.
• Blockchain transaction reference.
• Block number or height.
• Relevant timestamps.
• Verification status.

Provide clickable links to the relevant blockchain explorer where available.

Check 4 – Recomputed Deck Verification

Verify that the cryptographic inputs reproduce the original shuffled deck and dealt cards.

Display whether the recomputed deck matches the recorded hand.

All four checks must pass before the hand receives the final green verified status.

4. Cards as Dealt

Include a visual breakdown of the cards dealt during the hand.

For Texas Hold'em, display:

• Each player's seat number.
• Player name or identifier.
• Two hole cards per player, where disclosure is permitted.
• Five community cards.

Use recognisable playing-card graphics rather than displaying cards as plain text.

Security requirement: Never expose private or unrevealed cards while a hand is active. After completion, the cards displayed must follow Block52's authorised disclosure and verification model.

5. Verification Inputs – Detailed Technical Information

Below the verification summary, include a scrollable section titled “Inputs.”

This section should contain the information required to independently reproduce the verification checks.

Depending on Block52's underlying protocol, this may include:

• Hand ID.
• Table ID.
• Cryptographic commitment.
• Revealed seed or equivalent randomness inputs.
• Commitment preimage.
• Randomness round.
• Public randomness value.
• Player seed contributions, if applicable.
• Blockchain anchor transaction.
• Block height and timestamp.
• Protocol version.

All applicable cryptographic values should be displayed in full.

Include copy-to-clipboard functionality for hashes, addresses, seeds and transaction references.

Provide external links for independently verifiable blockchain and randomness records.

The exact input fields and algorithms must correspond to Block52's actual implementation rather than assuming its architecture is identical to PlayBlind.

6. Downloadable Verification Record

Include a “Download Record” button.

The downloaded record should contain the relevant hand information and cryptographic verification inputs.

The objective is to allow users or external auditors to reproduce the verification independently.

Consider providing a standalone verification utility or documented verification procedure.

7. User Interface and Visual Design

The interface should closely replicate the usability and presentation demonstrated in the attached PlayBlind screenshots while maintaining Block52 branding.

Design Requirements

• Dark, semi-transparent overlay.
• Clearly defined verification panel.
• Green success indicators for verified checks.
• Neutral or amber indicators for pending checks.
• Red indicators for failed verification.
• Scrollable content within the panel.
• Clear section headings and explanatory text.
• Readable cryptographic values with appropriate text wrapping.
• Playing-card graphics for the reconstructed deal.
• Clickable blockchain references.
• Copy buttons for technical information.
• Downloadable verification record.
• Close button returning directly to the poker table.

The poker table should remain visible behind the verification panel.

The design should work across desktop, tablet and mobile interfaces.

8. Verification Status Handling

The interface must distinguish between the following states:

Pending

• Hand is still running.
• Required cryptographic inputs are not yet available.
• Verification cannot be completed.

Verified

• All required cryptographic checks have passed.
• The reconstructed deal matches the committed result.

Failed

• One or more verification checks have failed.
• Display which check failed and the reason, where available.
• Never display a successful verification banner.

Unavailable / Error

• Verification data cannot be retrieved.
• Blockchain or randomness service is unavailable.
• Verification is incomplete due to a technical issue.

An unavailable verification must never be incorrectly displayed as successful.

9. Hand History Integration

Players should be able to access verification information for previously completed hands.

Include a “Verify Hand” option within the existing Block52 hand history interface.

Selecting a historical hand should open the same verification panel, populated with that hand's data.

Where possible, include a replay link or integration with the existing hand replay functionality.

10. Acceptance Criteria

• Provably Fair indicator accessible from the poker table.
• Verification window accessible during active hands.
• Active hands display pending verification status.
• No unreleased cards or confidential seeds are exposed.
• Completed hands can display independently calculated verification results.
• Four verification categories are displayed with individual statuses.
• A green verified banner appears only when every required check passes.
• Cards-as-dealt visualisation is included.
• Cryptographic verification inputs are accessible.
• Blockchain and randomness references are linked where supported.
• Copy-to-clipboard functionality is available.
• Verification records can be downloaded.
• Historical hands can be verified.
• Interface works on desktop and mobile.
• Verification does not interrupt gameplay.
• All verification logic is compatible with Block52's actual cryptographic architecture.

Reference Screenshots

Attach the supplied PlayBlind screenshots to this GitHub issue.

They demonstrate:

1. Standard poker table with Provably Fair indicator.
2. Initial Provably Fair information panel.
3. “Verify this hand” button.
4. Verification window during an active hand.
5. Completed hand verification with four successful checks.
6. Cards-as-dealt visualisation.
7. Detailed cryptographic verification inputs.
8. Scrollable verification panel and download functionality.
9. Side-by-side comparison of Block52 and PlayBlind interfaces.

Development Objective

Deliver a verification experience comparable to the PlayBlind reference, enabling users to inspect and independently verify the integrity of poker hands through a clear, intuitive and visually polished interface.

The verification must be cryptographically genuine, not simply a visual representation of fairness.