Contract Address Details

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.28;

import {ReentrancyGuard} from "@openzeppelin/contracts/utils/ReentrancyGuard.sol";
import {SRA} from "./lib/SRA.sol";
import {CardMerkle} from "./lib/CardMerkle.sol";
import {HandEval} from "./lib/HandEval.sol";
import {BettingLib} from "./lib/BettingLib.sol";
import "./GameTypes.sol";

/// @title PLSHoldem — trustless heads-up No-Limit Texas Hold'em
/// @notice Fully on-chain game arbiter for two-player NLHE with SRA mental
///         poker dealing. The contract enforces turn order, betting legality,
///         blinds, timeouts, showdown evaluation, cheat detection (blame
///         replay) and settlement. Card privacy lives entirely client-side:
///         the contract only ever sees ciphertexts and selectively revealed
///         per-card exponents.
/// @dev Non-upgradeable; no pause; no admin power over live tables. The only
///      owner capability is configuring rake (≤ MAX_RAKE_BPS) and the fee
///      account for FUTURE tables. See SPEC.md / README.md for the protocol.
contract PLSHoldem is ReentrancyGuard {
    // ------------------------------------------------------------------
    // Storage
    // ------------------------------------------------------------------

    uint16 public constant MAX_RAKE_BPS = 500; // hard cap: 5%
    uint32 public constant MIN_TIMEOUT = 60;
    uint32 public constant MAX_TIMEOUT = 7 days;
    uint32 public constant MAX_BUYIN_CHIPS = 1_000_000_000;

    address public owner;
    address public feeAccount;   // rake destination for future tables
    uint16 public rakeBps;       // rake for future tables

    uint256 public tableCount;
    mapping(uint256 => Table) public tables;
    mapping(uint256 => Hand) internal hands;
    mapping(uint256 => address) public tableFeeAccount; // frozen at creation
    mapping(address => uint256) public withdrawable;

    // ------------------------------------------------------------------
    // Events
    // ------------------------------------------------------------------

    event TableCreated(uint256 indexed tableId, address indexed creator, uint96 chipValue,
        uint32 buyInChips, uint32 sbChips, uint32 bbChips, uint32 actTimeout,
        uint32 cryptoTimeout, uint32 penaltyChips, uint16 rakeBps, uint8 avatar);
    event TableJoined(uint256 indexed tableId, address indexed joiner, uint8 avatar);
    event TableCancelled(uint256 indexed tableId);
    event HandStarted(uint256 indexed tableId, uint32 indexed handId, uint8 btn);
    event DeckPosted(uint256 indexed tableId, uint32 indexed handId, uint8 stage, bytes32 root);
    event HoleExpPosted(uint256 indexed tableId, uint32 indexed handId, uint8 seat);
    event ActionTaken(uint256 indexed tableId, uint32 indexed handId, uint8 seat, uint8 action, uint32 amount);
    event PhaseAdvanced(uint256 indexed tableId, uint32 indexed handId, uint8 phase, uint64 deadline);
    event BoardRevealed(uint256 indexed tableId, uint32 indexed handId, uint8 street, uint8[5] board);
    event ShowdownRevealed(uint256 indexed tableId, uint32 indexed handId, uint8 seat, uint8 c0, uint8 c1, uint32 score);
    event Mucked(uint256 indexed tableId, uint32 indexed handId, uint8 seat);
    event PotAwarded(uint256 indexed tableId, uint32 indexed handId, uint8 winner, uint32 amount, uint32 rake);
    event HandSettled(uint256 indexed tableId, uint32 indexed handId, uint32 stackC, uint32 stackJ);
    event TimeoutClaimed(uint256 indexed tableId, uint32 indexed handId, uint8 phase, uint8 staller);
    event NoShowClaimed(uint256 indexed tableId, uint32 indexed handId, uint32 chips);
    event BlameOpened(uint256 indexed tableId, uint32 indexed handId, uint8 pos, uint8 claimBy, uint8 claimIdx);
    event BlameJSubmitted(uint256 indexed tableId, uint32 indexed handId, uint8 j);
    event CheatSettled(uint256 indexed tableId, uint8 cheater);
    event PlayerLeft(uint256 indexed tableId, uint8 seat);
    event SessionSettled(uint256 indexed tableId, uint256 creatorWei, uint256 joinerWei, uint256 rakeWei);
    event Withdrawn(address indexed to, uint256 amount);
    event RakeConfigured(uint16 rakeBps, address feeAccount);

    // ------------------------------------------------------------------
    // Construction & admin (future tables only)
    // ------------------------------------------------------------------

    constructor(uint16 _rakeBps, address _feeAccount) {
        if (_rakeBps > MAX_RAKE_BPS) revert RakeCap();
        if (_feeAccount == address(0)) revert BadParam();
        owner = msg.sender;
        rakeBps = _rakeBps;
        feeAccount = _feeAccount;
    }

    /// @notice Configure rake for FUTURE tables only (hard-capped). The only
    ///         admin capability in the contract.
    function setRake(uint16 _rakeBps, address _feeAccount) external {
        if (msg.sender != owner) revert NotOwner();
        if (_rakeBps > MAX_RAKE_BPS) revert RakeCap();
        if (_feeAccount == address(0)) revert BadParam();
        rakeBps = _rakeBps;
        feeAccount = _feeAccount;
        emit RakeConfigured(_rakeBps, _feeAccount);
    }

    /// @notice Transfer ownership (address(0) permanently renounces rake
    ///         reconfiguration; existing tables are unaffected either way).
    function transferOwnership(address newOwner) external {
        if (msg.sender != owner) revert NotOwner();
        owner = newOwner;
    }

    // ------------------------------------------------------------------
    // Lobby
    // ------------------------------------------------------------------

    /// @notice Create a table and escrow the buy-in (exact native tPLS value).
    /// @param chipValue wei per chip (fixed conversion both directions)
    /// @param buyInChips whole chips both players buy in for
    /// @param sbChips small blind in chips (bb >= sb >= 1)
    /// @param bbChips big blind in chips (<= buyIn/10)
    /// @param actTimeoutS betting-action window, seconds
    /// @param cryptoTimeoutS crypto-step / reveal / next-hand window, seconds
    /// @param penaltyChips griefing compensation moved to a timeout claimer
    /// @param avatar avatar id (0..7) shown at the creator's seat
    function createTable(
        uint96 chipValue,
        uint32 buyInChips,
        uint32 sbChips,
        uint32 bbChips,
        uint32 actTimeoutS,
        uint32 cryptoTimeoutS,
        uint32 penaltyChips,
        uint8 avatar
    ) external payable returns (uint256 tableId) {
        if (chipValue == 0 || buyInChips == 0 || buyInChips > MAX_BUYIN_CHIPS) revert BadParam();
        if (sbChips < 1 || bbChips < sbChips || bbChips > buyInChips / 10) revert BadParam();
        if (actTimeoutS < MIN_TIMEOUT || actTimeoutS > MAX_TIMEOUT) revert BadParam();
        if (cryptoTimeoutS < MIN_TIMEOUT || cryptoTimeoutS > MAX_TIMEOUT) revert BadParam();
        if (penaltyChips < 1 || penaltyChips > bbChips) revert BadParam();
        if (avatar >= 8) revert BadParam();
        if (msg.value != uint256(chipValue) * buyInChips) revert WrongDeposit();

        tableId = ++tableCount;
        Table storage t = tables[tableId];
        t.creator = msg.sender;
        t.chipValue = chipValue;
        t.status = uint8(TableStatus.OPEN);
        t.creatorAvatar = avatar;
        t.rakeBps = rakeBps;
        t.buyInChips = buyInChips;
        t.sbChips = sbChips;
        t.bbChips = bbChips;
        t.penaltyChips = penaltyChips;
        t.actTimeout = actTimeoutS;
        t.cryptoTimeout = cryptoTimeoutS;
        t.stackC = buyInChips;
        t.stackJ = buyInChips;
        tableFeeAccount[tableId] = feeAccount;

        emit TableCreated(tableId, msg.sender, chipValue, buyInChips, sbChips, bbChips,
            actTimeoutS, cryptoTimeoutS, penaltyChips, rakeBps, avatar);
    }

    /// @notice Join an open table, escrowing the identical buy-in. Atomic:
    ///         a join racing a cancel simply reverts for whoever lands second.
    function joinTable(uint256 tableId, uint8 avatar) external payable {
        Table storage t = tables[tableId];
        if (t.status != uint8(TableStatus.OPEN)) revert NotOpen();
        if (msg.sender == t.creator) revert BadParam();
        if (avatar >= 8) revert BadParam();
        if (msg.value != uint256(t.chipValue) * t.buyInChips) revert WrongDeposit();
        t.joiner = msg.sender;
        t.joinerAvatar = avatar;
        t.status = uint8(TableStatus.PLAYING);
        t.lastSettleTime = uint64(block.timestamp);
        emit TableJoined(tableId, msg.sender, avatar);
    }

    /// @notice Cancel an open (unjoined) table; refunds the creator in full.
    function cancelTable(uint256 tableId) external {
        Table storage t = tables[tableId];
        if (t.status != uint8(TableStatus.OPEN)) revert NotOpen();
        if (msg.sender != t.creator) revert NotCreator();
        t.status = uint8(TableStatus.CANCELLED);
        withdrawable[t.creator] += uint256(t.chipValue) * t.buyInChips;
        emit TableCancelled(tableId);
    }

    // ------------------------------------------------------------------
    // Deck stages (SPEC 2.2)
    // ------------------------------------------------------------------

    /// @notice Post a deck stage (52 × 128-byte values). Stage 1 (creator)
    ///         starts the hand and auto-posts the blinds; stage 2 (joiner),
    ///         3 (creator), 4 (joiner) follow. The contract validates range
    ///         and distinctness and stores a Merkle root per stage.
    function postDeck(uint256 tableId, uint32 handId, uint8 stage, bytes calldata deck) external {
        Table storage t = tables[tableId];
        Hand storage h = hands[tableId];
        if (t.status != uint8(TableStatus.PLAYING)) revert NotPlaying();
        if (handId != t.handId) revert WrongHand();

        if (stage == 1) {
            if (msg.sender != t.creator) revert NotCreator();
            if (h.phase != uint8(Phase.NONE)) revert BadPhase();
            if (t.stackC == 0 || t.stackJ == 0) revert Bust();
            h.stack[0] = t.stackC;
            h.stack[1] = t.stackJ;
            BettingLib.initHand(h, uint8(t.handId % 2), t.sbChips, t.bbChips);
            emit HandStarted(tableId, t.handId, h.btn);
            h.phase = uint8(Phase.SHUF2);
        } else if (stage == 2) {
            if (msg.sender != t.joiner) revert NotJoiner();
            if (h.phase != uint8(Phase.SHUF2)) revert BadPhase();
            h.phase = uint8(Phase.LOCK1);
        } else if (stage == 3) {
            if (msg.sender != t.creator) revert NotCreator();
            if (h.phase != uint8(Phase.LOCK1)) revert BadPhase();
            h.phase = uint8(Phase.LOCK2);
        } else if (stage == 4) {
            if (msg.sender != t.joiner) revert NotJoiner();
            if (h.phase != uint8(Phase.LOCK2)) revert BadPhase();
            h.phase = uint8(Phase.DEAL);
        } else {
            revert BadParam();
        }
        SRA.checkDeck(deck);
        bytes32 root = CardMerkle.computeRoot(deck, stage);
        h.roots[stage - 1] = root;
        _setDeadline(tableId, t, h, false);
        emit DeckPosted(tableId, handId, stage, root);
    }

    // ------------------------------------------------------------------
    // Hole-card dealing
    // ------------------------------------------------------------------

    /// @notice Post the per-card exponents unlocking the OPPONENT's hole
    ///         cards (joiner posts positions 0,1; creator posts 2,3). Not
    ///         verifiable at post time by design — a bad key is caught by
    ///         accuseHole + blame replay.
    function postHoleExp(uint256 tableId, uint32 handId, uint256 e0, uint256 e1) external {
        Table storage t = tables[tableId];
        Hand storage h = hands[tableId];
        if (handId != t.handId) revert WrongHand();
        if (h.phase != uint8(Phase.DEAL)) revert BadPhase();
        if (!SRA.validScalar(e0) || !SRA.validScalar(e1)) revert BadScalar();
        uint8 seat = _seatOf(t, msg.sender);
        uint8 bit = seat == 1 ? 1 : 2; // joiner bit0, creator bit1
        if (h.dealMask & bit != 0) revert AlreadyPosted();
        h.dealMask |= bit;
        if (seat == 1) { h.holeExp[0] = e0; h.holeExp[1] = e1; }
        else { h.holeExp[2] = e0; h.holeExp[3] = e1; }
        emit HoleExpPosted(tableId, handId, seat);
        if (h.dealMask == 3) {
            h.phase = h.allIn ? uint8(Phase.REVEAL_FLOP) : uint8(Phase.BET_PREFLOP);
            _setDeadline(tableId, t, h, !h.allIn);
        }
    }

    // ------------------------------------------------------------------
    // Betting
    // ------------------------------------------------------------------

    /// @notice Take a betting action. `amount` = total street bet for
    ///         BET/RAISE ("raise to"); ignored otherwise. Rules (min-raise,
    ///         short all-in, uncalled returns) live in BettingLib.
    function act(uint256 tableId, uint32 handId, Action action, uint32 amount) external {
        Table storage t = tables[tableId];
        Hand storage h = hands[tableId];
        if (handId != t.handId) revert WrongHand();
        uint8 ph = h.phase;
        if (ph != uint8(Phase.BET_PREFLOP) && ph != uint8(Phase.BET_FLOP)
            && ph != uint8(Phase.BET_TURN) && ph != uint8(Phase.BET_RIVER)) revert BadPhase();
        uint8 me = _seatOf(t, msg.sender);
        if (me != h.toAct) revert NotYourTurn();

        uint8 outcome = BettingLib.applyAction(h, me, action, amount, t.bbChips);
        emit ActionTaken(tableId, handId, me, uint8(action), amount);

        if (outcome == BettingLib.OUT_FOLDED) {
            _awardPotAndEndHand(tableId, t, h, 1 - me);
        } else if (outcome == BettingLib.OUT_CLOSED) {
            _advanceAfterBetting(tableId, t, h);
        } else {
            _setDeadline(tableId, t, h, true);
        }
    }

    function _advanceAfterBetting(uint256 tableId, Table storage t, Hand storage h) private {
        if (h.street == 0) h.phase = uint8(Phase.REVEAL_FLOP);
        else if (h.street == 1) h.phase = uint8(Phase.REVEAL_TURN);
        else if (h.street == 2) h.phase = uint8(Phase.REVEAL_RIVER);
        else {
            h.phase = uint8(Phase.SHOWDOWN_1);
            h.firstShower = h.riverAggressor != 255 ? h.riverAggressor : 1 - h.btn;
        }
        _setDeadline(tableId, t, h, false);
    }

    // ------------------------------------------------------------------
    // Board reveals
    // ------------------------------------------------------------------

    function _streetPositions(uint8 phase) private pure returns (uint8 base, uint8 n) {
        if (phase == uint8(Phase.REVEAL_FLOP)) return (4, 3);
        if (phase == uint8(Phase.REVEAL_TURN)) return (7, 1);
        return (8, 1); // REVEAL_RIVER
    }

    /// @notice Post your per-card exponents for the current board street.
    ///         The FIRST poster passes empty claim/value/proof arrays. The
    ///         SECOND poster (who can decrypt locally once both exponents are
    ///         known) must pass claimed card indices, the Merkle-proven D4
    ///         values (concatenated 128-byte blobs) and flat proofs (6 nodes
    ///         per card); the contract verifies D0[claim]^(eC*eJ) == D4[pos].
    ///         claim = 255 asserts the position opens to garbage; it must be
    ///         accompanied by 128-byte inverse exponents (invMine/invTheirs)
    ///         and opens blame replay when verified.
    function postBoardExp(
        uint256 tableId,
        uint32 handId,
        uint256[] calldata exps,
        uint8[] calldata claims,
        bytes calldata d4vals,
        bytes32[] calldata proofs,      // flat: 6 nodes per revealed card
        bytes calldata invMine,
        bytes calldata invTheirs
    ) external {
        Table storage t = tables[tableId];
        Hand storage h = hands[tableId];
        if (handId != t.handId) revert WrongHand();
        uint8 ph = h.phase;
        if (ph != uint8(Phase.REVEAL_FLOP) && ph != uint8(Phase.REVEAL_TURN)
            && ph != uint8(Phase.REVEAL_RIVER)) revert BadPhase();
        uint8 me = _seatOf(t, msg.sender);
        (uint8 base, uint8 n) = _streetPositions(ph);
        if (exps.length != n) revert BadData();
        for (uint256 i = 0; i < n; i++) {
            if (!SRA.validScalar(exps[i])) revert BadScalar();
        }

        if (h.pendBy == 255) {
            // first poster: stash exponents; opponent completes
            for (uint256 i = 0; i < n; i++) h.pendExp[i] = exps[i];
            h.pendBy = me;
            emit PhaseAdvanced(tableId, handId, ph, h.deadline);
            return;
        }
        if (h.pendBy == me) revert AlreadyPosted();
        if (claims.length != n || proofs.length != uint256(n) * 6
            || d4vals.length != uint256(n) * 128) revert BadData();

        for (uint256 i = 0; i < n; i++) {
            uint8 pos = base + uint8(i);
            bytes memory d4v = d4vals[i * 128:(i + 1) * 128];
            if (!CardMerkle.verify(h.roots[3], 4, pos, d4v, _slice6(proofs, i))) revert BadProof();
            uint256 eC = me == 0 ? exps[i] : h.pendExp[i];
            uint256 eJ = me == 0 ? h.pendExp[i] : exps[i];
            if (claims[i] < 52) {
                if (keccak256(SRA.modexpMul(SRA.cardCode(claims[i]), eC, eJ)) != keccak256(d4v)) {
                    revert CardMismatch();
                }
                h.board[pos - 4] = claims[i];
            } else {
                // garbage claim: verify via inverse round-trip, then open blame
                if (claims[i] != 255) revert BadData();
                uint8 card = _verifiedOpen(d4v, exps[i], h.pendExp[i], invMine, invTheirs);
                if (card < 52) {
                    // opens to a real card: false garbage claim = fold + penalty
                    _falseAccusation(tableId, t, h, me);
                } else {
                    _openBlame(tableId, t, h, pos, 255, me, eC, eJ);
                }
                return;
            }
        }
        _afterBoardReveal(tableId, t, h, ph);
    }

    function _afterBoardReveal(uint256 tableId, Table storage t, Hand storage h, uint8 ph) private {
        h.pendBy = 255;
        h.pendExp[0] = 0; h.pendExp[1] = 0; h.pendExp[2] = 0;
        if (ph == uint8(Phase.REVEAL_FLOP)) h.street = 1;
        else if (ph == uint8(Phase.REVEAL_TURN)) h.street = 2;
        else h.street = 3;
        emit BoardRevealed(tableId, t.handId, h.street, h.board);
        if (h.allIn) {
            if (ph == uint8(Phase.REVEAL_FLOP)) h.phase = uint8(Phase.REVEAL_TURN);
            else if (ph == uint8(Phase.REVEAL_TURN)) h.phase = uint8(Phase.REVEAL_RIVER);
            else {
                h.phase = uint8(Phase.SHOWDOWN_1);
                h.firstShower = h.riverAggressor != 255 ? h.riverAggressor : 1 - h.btn;
            }
            _setDeadline(tableId, t, h, false);
        } else {
            if (ph == uint8(Phase.REVEAL_FLOP)) h.phase = uint8(Phase.BET_FLOP);
            else if (ph == uint8(Phase.REVEAL_TURN)) h.phase = uint8(Phase.BET_TURN);
            else h.phase = uint8(Phase.BET_RIVER);
            BettingLib.openStreet(h, t.bbChips);
            _setDeadline(tableId, t, h, true);
        }
    }

    /// @dev Open D4[pos] given both exponents + their 128-byte inverses.
    ///      Each inverse is verified by round-trip (roots are unique in the
    ///      QR subgroup). Returns card index or 255 for garbage.
    function _verifiedOpen(
        bytes memory d4v,
        uint256 eMine,
        uint256 eTheirs,
        bytes calldata invMine,
        bytes calldata invTheirs
    ) private view returns (uint8) {
        if (invMine.length != 128 || invTheirs.length != 128) revert BadData();
        bytes memory t1 = SRA.modexpBytes(d4v, invTheirs);
        if (keccak256(SRA.modexp32(t1, eTheirs)) != keccak256(d4v)) revert BadInverse();
        bytes memory t2 = SRA.modexpBytes(t1, invMine);
        if (keccak256(SRA.modexp32(t2, eMine)) != keccak256(t1)) revert BadInverse();
        return SRA.cardFromHash(keccak256(t2));
    }

    function _slice6(bytes32[] calldata proofs, uint256 i) private pure returns (bytes32[6] memory p) {
        for (uint256 d = 0; d < 6; d++) p[d] = proofs[i * 6 + d];
    }

    // ------------------------------------------------------------------
    // Showdown
    // ------------------------------------------------------------------

    /// @notice Reveal your hole cards at showdown (first shower in
    ///         SHOWDOWN_1; the other player in SHOWDOWN_2). Provide your two
    ///         per-card exponents, claimed cards and Merkle-proven D4 values
    ///         (flat proofs, 6 nodes per card).
    function showdown(
        uint256 tableId,
        uint32 handId,
        uint256[2] calldata exps,
        uint8[2] calldata claims,
        bytes calldata d4vals,
        bytes32[] calldata proofs
    ) external {
        Table storage t = tables[tableId];
        Hand storage h = hands[tableId];
        if (handId != t.handId) revert WrongHand();
        uint8 me = _seatOf(t, msg.sender);
        if (h.phase == uint8(Phase.SHOWDOWN_1)) {
            if (me != h.firstShower) revert NotYourReveal();
        } else if (h.phase == uint8(Phase.SHOWDOWN_2)) {
            if (me != 1 - h.firstShower) revert NotYourReveal();
        } else {
            revert BadPhase();
        }
        if (d4vals.length != 256 || proofs.length != 12) revert BadData();
        if (claims[0] >= 52 || claims[1] >= 52 || claims[0] == claims[1]) revert BadData();
        for (uint256 i = 0; i < 5; i++) {
            if (h.board[i] == claims[0] || h.board[i] == claims[1]) revert BadData();
        }

        uint8 basePos = me == 0 ? 0 : 2; // creator holes 0,1; joiner 2,3
        for (uint256 i = 0; i < 2; i++) {
            if (!SRA.validScalar(exps[i])) revert BadScalar();
            uint8 pos = basePos + uint8(i);
            bytes memory d4v = d4vals[i * 128:(i + 1) * 128];
            if (!CardMerkle.verify(h.roots[3], 4, pos, d4v, _slice6(proofs, i))) revert BadProof();
            uint256 oppExp = h.holeExp[pos]; // opponent's deal exponent for my hole
            uint256 eC = me == 0 ? exps[i] : oppExp;
            uint256 eJ = me == 0 ? oppExp : exps[i];
            if (keccak256(SRA.modexpMul(SRA.cardCode(claims[i]), eC, eJ)) != keccak256(d4v)) {
                revert CardMismatch();
            }
            h.shownExp[me][i] = exps[i];
            h.shownCards[me][i] = claims[i];
        }

        uint8[7] memory seven;
        for (uint256 i = 0; i < 5; i++) seven[i] = h.board[i];
        seven[5] = claims[0];
        seven[6] = claims[1];
        uint32 sc = HandEval.evaluate7(seven);
        h.shownScore[me] = sc;
        h.shownMask |= uint8(1) << me;
        emit ShowdownRevealed(tableId, handId, me, claims[0], claims[1], sc);

        if (h.phase == uint8(Phase.SHOWDOWN_1)) {
            h.phase = uint8(Phase.SHOWDOWN_2);
            _setDeadline(tableId, t, h, false);
        } else {
            uint8 first = h.firstShower;
            uint8 second = 1 - first;
            if (h.shownScore[second] > h.shownScore[first]) {
                _awardPotAndEndHand(tableId, t, h, second);
            } else if (h.shownScore[second] < h.shownScore[first]) {
                _awardPotAndEndHand(tableId, t, h, first);
            } else {
                _splitPotAndEndHand(tableId, t, h);
            }
        }
    }

    /// @notice Concede the pot at showdown without revealing (cards stay
    ///         encrypted forever).
    function muck(uint256 tableId, uint32 handId) external {
        Table storage t = tables[tableId];
        Hand storage h = hands[tableId];
        if (handId != t.handId) revert WrongHand();
        if (h.phase != uint8(Phase.SHOWDOWN_2)) revert BadPhase();
        uint8 me = _seatOf(t, msg.sender);
        if (me != 1 - h.firstShower) revert NotYourReveal();
        emit Mucked(tableId, handId, me);
        _awardPotAndEndHand(tableId, t, h, h.firstShower);
    }

    // ------------------------------------------------------------------
    // Accusations & blame replay (SPEC 2.5)
    // ------------------------------------------------------------------

    /// @notice Accuse: "my hole card at `pos` opens to garbage". You reveal
    ///         your own per-card exponent + both 128-byte inverse exponents.
    ///         If the card is actually valid the accusation is false and you
    ///         fold + pay the penalty (you also exposed your own card — your
    ///         choice). If it is garbage, blame replay opens and will cost
    ///         the cheater their entire stack.
    function accuseHole(
        uint256 tableId,
        uint32 handId,
        uint8 pos,
        uint256 ownExp,
        bytes calldata d4val,
        bytes32[6] calldata proof,
        bytes calldata invOwn,
        bytes calldata invTheirs
    ) external {
        Table storage t = tables[tableId];
        Hand storage h = hands[tableId];
        if (handId != t.handId) revert WrongHand();
        uint8 ph = h.phase;
        if (ph < uint8(Phase.BET_PREFLOP) || ph > uint8(Phase.SHOWDOWN_2)) revert BadPhase();
        uint8 me = _seatOf(t, msg.sender);
        if (!((me == 0 && pos < 2) || (me == 1 && (pos == 2 || pos == 3)))) revert NotYourHole();
        if (!SRA.validScalar(ownExp)) revert BadScalar();
        if (!CardMerkle.verify(h.roots[3], 4, pos, d4val, proof)) revert BadProof();

        uint8 card = _verifiedOpen(d4val, ownExp, h.holeExp[pos], invOwn, invTheirs);
        if (card < 52) {
            _falseAccusation(tableId, t, h, me);
        } else {
            uint256 postedC = me == 0 ? ownExp : h.holeExp[pos];
            uint256 postedJ = me == 1 ? ownExp : h.holeExp[pos];
            _openBlame(tableId, t, h, pos, 255, me, postedC, postedJ);
        }
    }

    function _falseAccusation(uint256 tableId, Table storage t, Hand storage h, uint8 accuser) private {
        h.folded = accuser;
        BettingLib.closeStreet(h);
        _applyPenalty(h, accuser, t.penaltyChips);
        _awardPotAndEndHand(tableId, t, h, 1 - accuser);
    }

    function _openBlame(uint256 tableId, Table storage t, Hand storage h,
        uint8 pos, uint8 claimIdx, uint8 claimBy, uint256 postedC, uint256 postedJ) private
    {
        h.blamePos = pos;
        h.blameClaimIdx = claimIdx;
        h.blameClaimBy = claimBy;
        h.blamePostedC = postedC;
        h.blamePostedJ = postedJ;
        h.phase = uint8(Phase.BLAME_J);
        _setDeadline(tableId, t, h, false);
        emit BlameOpened(tableId, t.handId, pos, claimBy, claimIdx);
    }

    /// @notice Joiner's blame submission: their permutation source j, global
    ///         and per-card exponents, plus Merkle-proven stage values
    ///         (D1[j] ‖ D2[pos] ‖ D3[pos] ‖ D4[pos], flat proofs 6 nodes
    ///         each). Verifies Check2 (D2[pos] == D1[j]^gJ) and Check4
    ///         (D4[pos]^gJ == D3[pos]^cJ). Any failure = joiner cheated.
    function submitBlameJ(
        uint256 tableId,
        uint32 handId,
        uint8 j,
        uint256 gJ,
        uint256 cJ,
        bytes calldata vals,
        bytes32[] calldata proofs   // flat, 24 nodes
    ) external {
        Table storage t = tables[tableId];
        Hand storage h = hands[tableId];
        if (handId != t.handId) revert WrongHand();
        if (h.phase != uint8(Phase.BLAME_J)) revert BadPhase();
        if (msg.sender != t.joiner) revert NotJoiner();
        if (j >= 52 || !SRA.validScalar(gJ) || !SRA.validScalar(cJ)) revert BadData();
        if (vals.length != 512 || proofs.length != 24) revert BadData();

        uint8 pos = h.blamePos;
        bytes memory d1j = vals[0:128];
        bytes memory d2 = vals[128:256];
        bytes memory d3 = vals[256:384];
        bytes memory d4 = vals[384:512];
        if (!CardMerkle.verify(h.roots[0], 1, j, d1j, _slice6(proofs, 0))) revert BadProof();
        if (!CardMerkle.verify(h.roots[1], 2, pos, d2, _slice6(proofs, 1))) revert BadProof();
        if (!CardMerkle.verify(h.roots[2], 3, pos, d3, _slice6(proofs, 2))) revert BadProof();
        if (!CardMerkle.verify(h.roots[3], 4, pos, d4, _slice6(proofs, 3))) revert BadProof();

        // Check2: D2[pos] == D1[j]^gJ
        if (SRA.modexpHash32(d1j, gJ) != keccak256(d2)) {
            _settleCheat(tableId, t, h, 1);
            return;
        }
        // Check4: D4[pos]^gJ == D3[pos]^cJ
        if (SRA.modexpHash32(d4, gJ) != SRA.modexpHash32(d3, cJ)) {
            _settleCheat(tableId, t, h, 1);
            return;
        }
        h.blameGJ = gJ;
        h.blameCJ = cJ;
        h.blameVals[0] = keccak256(d1j);
        h.blameVals[1] = keccak256(d2);
        h.blameVals[2] = keccak256(d3);
        h.blameVals[3] = keccak256(d4);
        h.phase = uint8(Phase.BLAME_C);
        _setDeadline(tableId, t, h, false);
        emit BlameJSubmitted(tableId, handId, j);
    }

    /// @notice Creator's blame submission: original card index k, global and
    ///         per-card exponents, plus the raw stage values (must match the
    ///         hashes pinned in submitBlameJ). Runs Check1, Check3 and the
    ///         posted-exponent checks, then assigns the cheater — someone
    ///         always pays: every check isolates a single player's work.
    function submitBlameC(
        uint256 tableId,
        uint32 handId,
        uint8 k,
        uint256 gC,
        uint256 cC,
        bytes calldata vals
    ) external {
        Table storage t = tables[tableId];
        Hand storage h = hands[tableId];
        if (handId != t.handId) revert WrongHand();
        if (h.phase != uint8(Phase.BLAME_C)) revert BadPhase();
        if (msg.sender != t.creator) revert NotCreator();
        if (k >= 52 || !SRA.validScalar(gC) || !SRA.validScalar(cC)) revert BadData();
        if (vals.length != 512) revert BadData();
        bytes memory d1j = vals[0:128];
        bytes memory d2 = vals[128:256];
        bytes memory d3 = vals[256:384];
        if (keccak256(d1j) != h.blameVals[0] || keccak256(d2) != h.blameVals[1]
            || keccak256(d3) != h.blameVals[2] || keccak256(vals[384:512]) != h.blameVals[3]) {
            revert BadData();
        }

        // Check1: D1[j] == D0[k]^gC
        if (SRA.modexpHash32(SRA.cardCode(k), gC) != h.blameVals[0]) {
            _settleCheat(tableId, t, h, 0);
            return;
        }
        // Check3: D3[pos]^gC == D2[pos]^cC
        if (SRA.modexpHash32(d3, gC) != SRA.modexpHash32(d2, cC)) {
            _settleCheat(tableId, t, h, 0);
            return;
        }
        // Step 5: the deck is honest at pos — test the exponents POSTED
        // during play (frozen at blame-open) against the pinned true keys.
        if (keccak256(SRA.modexpMul(SRA.cardCode(k), cC, h.blamePostedJ)) != h.blameVals[3]) {
            _settleCheat(tableId, t, h, 1);
            return;
        }
        if (keccak256(SRA.modexpMul(SRA.cardCode(k), h.blamePostedC, h.blameCJ)) != h.blameVals[3]) {
            _settleCheat(tableId, t, h, 0);
            return;
        }
        // both posted exponents open the position to the true card D0[k]:
        // the disputed claim itself was the lie.
        _settleCheat(tableId, t, h, h.blameClaimBy);
    }

    // ------------------------------------------------------------------
    // Timeouts (SPEC 3.5)
    // ------------------------------------------------------------------

    /// @notice Claim the opponent timed out on the current phase. Resolution:
    ///         betting stall = fold; crypto/reveal stall = pot forfeit;
    ///         SHOWDOWN_2 stall = muck-concede; blame stall = full-stack
    ///         forfeit. Claimer additionally receives `penaltyChips`.
    ///         `andSettle` ends the whole session at the resulting stacks
    ///         (repeated absence never requires grinding hand by hand).
    function claimTimeout(uint256 tableId, uint32 handId, uint8 expectedPhase, bool andSettle) external {
        Table storage t = tables[tableId];
        Hand storage h = hands[tableId];
        if (t.status != uint8(TableStatus.PLAYING)) revert NotPlaying();
        if (handId != t.handId) revert WrongHand();
        uint8 ph = h.phase;
        if (ph != expectedPhase || ph == uint8(Phase.NONE)) revert BadPhase();
        if (block.timestamp <= h.deadline) revert NotExpired();
        uint8 me = _seatOf(t, msg.sender);
        uint8 staller;

        if (ph == uint8(Phase.SHUF2) || ph == uint8(Phase.LOCK2)) staller = 1;
        else if (ph == uint8(Phase.LOCK1)) staller = 0;
        else if (ph == uint8(Phase.DEAL)) {
            uint8 myBit = me == 1 ? 1 : 2;
            if (h.dealMask & myBit == 0) revert PostYoursFirst();
            staller = 1 - me;
        } else if (ph == uint8(Phase.REVEAL_FLOP) || ph == uint8(Phase.REVEAL_TURN)
            || ph == uint8(Phase.REVEAL_RIVER)) {
            if (h.pendBy != me) revert PostYoursFirst();
            staller = 1 - me;
        } else if (ph == uint8(Phase.BET_PREFLOP) || ph == uint8(Phase.BET_FLOP)
            || ph == uint8(Phase.BET_TURN) || ph == uint8(Phase.BET_RIVER)) {
            staller = h.toAct;
        } else if (ph == uint8(Phase.SHOWDOWN_1)) {
            staller = h.firstShower;
        } else if (ph == uint8(Phase.SHOWDOWN_2)) {
            staller = 1 - h.firstShower;
        } else if (ph == uint8(Phase.BLAME_J)) {
            if (me != 0) revert NotCreator();
            emit TimeoutClaimed(tableId, handId, ph, 1);
            _settleCheat(tableId, t, h, 1);
            return;
        } else if (ph == uint8(Phase.BLAME_C)) {
            if (me != 1) revert NotJoiner();
            emit TimeoutClaimed(tableId, handId, ph, 0);
            _settleCheat(tableId, t, h, 0);
            return;
        } else {
            revert BadPhase();
        }
        if (staller == me) revert YouAreTheStaller();
        emit TimeoutClaimed(tableId, handId, ph, staller);
        BettingLib.closeStreet(h);
        _applyPenalty(h, staller, t.penaltyChips);
        _awardPotAndEndHand(tableId, t, h, me);
        if (andSettle && t.status == uint8(TableStatus.PLAYING)) {
            _settleSession(tableId, t);
        }
    }

    /// @notice Claim the creator failed to open the next hand in time. The
    ///         absent player pays one big blind + penalty from their escrowed
    ///         stack; the hand number advances (button rotates).
    function claimNoShow(uint256 tableId, bool andSettle) external {
        Table storage t = tables[tableId];
        Hand storage h = hands[tableId];
        if (t.status != uint8(TableStatus.PLAYING)) revert NotPlaying();
        if (h.phase != uint8(Phase.NONE)) revert BadPhase();
        if (msg.sender != t.joiner) revert NotJoiner();
        if (block.timestamp <= t.lastSettleTime + t.cryptoTimeout) revert NotExpired();
        uint32 x = _min32(t.bbChips + t.penaltyChips, t.stackC);
        t.stackC -= x;
        t.stackJ += x;
        emit NoShowClaimed(tableId, t.handId, x);
        emit HandSettled(tableId, t.handId, t.stackC, t.stackJ);
        t.handId += 1;
        t.lastSettleTime = uint64(block.timestamp);
        if (t.stackC == 0 || andSettle) {
            _settleSession(tableId, t);
        }
    }

    function _applyPenalty(Hand storage h, uint8 staller, uint32 penalty) private {
        uint32 x = _min32(penalty, h.stack[staller]);
        h.stack[staller] -= x;
        h.stack[1 - staller] += x;
    }

    // ------------------------------------------------------------------
    // Leaving / settlement
    // ------------------------------------------------------------------

    /// @notice Leave the table. Between hands: session settles at current
    ///         stacks (either player may exit; this is the cash-out path).
    ///         Mid-hand: you forfeit the pot + penalty (never a free roll);
    ///         during blame you are treated as the cheater.
    function leaveTable(uint256 tableId) external {
        Table storage t = tables[tableId];
        Hand storage h = hands[tableId];
        if (t.status != uint8(TableStatus.PLAYING)) revert NotPlaying();
        uint8 me = _seatOf(t, msg.sender);
        uint8 ph = h.phase;
        emit PlayerLeft(tableId, me);
        if (ph == uint8(Phase.NONE)) {
            _settleSession(tableId, t);
        } else if (ph == uint8(Phase.BLAME_J) || ph == uint8(Phase.BLAME_C)) {
            _settleCheat(tableId, t, h, me);
        } else {
            BettingLib.closeStreet(h);
            _applyPenalty(h, me, t.penaltyChips);
            _awardPotAndEndHand(tableId, t, h, 1 - me);
            if (t.status == uint8(TableStatus.PLAYING)) {
                _settleSession(tableId, t);
            }
        }
    }

    function _awardPotAndEndHand(uint256 tableId, Table storage t, Hand storage h, uint8 winner) private {
        uint32 rake = uint32((uint256(h.pot) * t.rakeBps) / 10000);
        uint32 win = h.pot - rake;
        h.stack[winner] += win;
        t.rakeChips += rake;
        emit PotAwarded(tableId, t.handId, winner, win, rake);
        _endHand(tableId, t, h);
    }

    function _splitPotAndEndHand(uint256 tableId, Table storage t, Hand storage h) private {
        uint32 rake = uint32((uint256(h.pot) * t.rakeBps) / 10000);
        uint32 rem = h.pot - rake;
        uint32 half = rem / 2;
        uint8 oop = 1 - h.btn;
        h.stack[oop] += half + (rem & 1); // odd chip to the out-of-position player
        h.stack[h.btn] += half;
        t.rakeChips += rake;
        emit PotAwarded(tableId, t.handId, 2, rem, rake);
        _endHand(tableId, t, h);
    }

    function _endHand(uint256 tableId, Table storage t, Hand storage h) private {
        t.stackC = h.stack[0];
        t.stackJ = h.stack[1];
        uint32 ended = t.handId;
        t.handId = ended + 1;
        t.lastSettleTime = uint64(block.timestamp);
        delete hands[tableId];
        emit HandSettled(tableId, ended, t.stackC, t.stackJ);
        if (t.stackC == 0 || t.stackJ == 0) {
            _settleSession(tableId, t);
        }
    }

    /// @dev Cheater forfeits every chip on the table (no rake); session ends.
    function _settleCheat(uint256 tableId, Table storage t, Hand storage h, uint8 cheater) private {
        uint32 all = h.stack[0] + h.stack[1] + h.streetBet[0] + h.streetBet[1] + h.pot;
        if (cheater == 0) { t.stackC = 0; t.stackJ = all; }
        else { t.stackC = all; t.stackJ = 0; }
        delete hands[tableId];
        emit CheatSettled(tableId, cheater);
        _settleSession(tableId, t);
    }

    function _settleSession(uint256 tableId, Table storage t) private {
        t.status = uint8(TableStatus.SETTLED);
        uint256 cv = t.chipValue;
        uint256 cWei = uint256(t.stackC) * cv;
        uint256 jWei = uint256(t.stackJ) * cv;
        uint256 rWei = uint256(t.rakeChips) * cv;
        if (cWei > 0) withdrawable[t.creator] += cWei;
        if (jWei > 0) withdrawable[t.joiner] += jWei;
        if (rWei > 0) withdrawable[tableFeeAccount[tableId]] += rWei;
        delete hands[tableId];
        emit SessionSettled(tableId, cWei, jWei, rWei);
    }

    /// @notice Withdraw all credited winnings/refunds (pull-payment).
    function withdraw() external nonReentrant {
        uint256 amount = withdrawable[msg.sender];
        if (amount == 0) revert NothingToDo();
        withdrawable[msg.sender] = 0;
        (bool ok, ) = msg.sender.call{value: amount}("");
        if (!ok) revert TransferFailed();
        emit Withdrawn(msg.sender, amount);
    }

    // ------------------------------------------------------------------
    // Views
    // ------------------------------------------------------------------

    /// @notice Full hand state (UI + crash recovery).
    function getHand(uint256 tableId) external view returns (Hand memory) {
        return hands[tableId];
    }

    /// @notice Open tables for the lobby (bounded scan, newest first).
    function getOpenTables(uint256 maxN) external view returns (uint256[] memory ids) {
        uint256 n = 0;
        uint256[] memory tmp = new uint256[](maxN);
        for (uint256 id = tableCount; id >= 1 && n < maxN; id--) {
            if (tables[id].status == uint8(TableStatus.OPEN)) tmp[n++] = id;
        }
        ids = new uint256[](n);
        for (uint256 i = 0; i < n; i++) ids[i] = tmp[i];
    }

    // ------------------------------------------------------------------
    // Internals
    // ------------------------------------------------------------------

    /// @dev Set the phase deadline and emit PhaseAdvanced (single site).
    function _setDeadline(uint256 tableId, Table storage t, Hand storage h, bool betting) private {
        h.deadline = uint64(block.timestamp) + (betting ? t.actTimeout : t.cryptoTimeout);
        emit PhaseAdvanced(tableId, t.handId, h.phase, h.deadline);
    }

    function _seatOf(Table storage t, address a) private view returns (uint8) {
        if (a == t.creator) return 0;
        if (a == t.joiner) return 1;
        revert NotAPlayer();
    }

    function _min32(uint32 a, uint32 b) private pure returns (uint32) {
        return a < b ? a : b;
    }
}
        

// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.5.0) (utils/ReentrancyGuard.sol)

pragma solidity ^0.8.20;

import {StorageSlot} from "./StorageSlot.sol";

/**
 * @dev Contract module that helps prevent reentrant calls to a function.
 *
 * Inheriting from `ReentrancyGuard` will make the {nonReentrant} modifier
 * available, which can be applied to functions to make sure there are no nested
 * (reentrant) calls to them.
 *
 * Note that because there is a single `nonReentrant` guard, functions marked as
 * `nonReentrant` may not call one another. This can be worked around by making
 * those functions `private`, and then adding `external` `nonReentrant` entry
 * points to them.
 *
 * TIP: If EIP-1153 (transient storage) is available on the chain you're deploying at,
 * consider using {ReentrancyGuardTransient} instead.
 *
 * TIP: If you would like to learn more about reentrancy and alternative ways
 * to protect against it, check out our blog post
 * https://blog.openzeppelin.com/reentrancy-after-istanbul/[Reentrancy After Istanbul].
 *
 * IMPORTANT: Deprecated. This storage-based reentrancy guard will be removed and replaced
 * by the {ReentrancyGuardTransient} variant in v6.0.
 *
 * @custom:stateless
 */
abstract contract ReentrancyGuard {
    using StorageSlot for bytes32;

    // keccak256(abi.encode(uint256(keccak256("openzeppelin.storage.ReentrancyGuard")) - 1)) & ~bytes32(uint256(0xff))
    bytes32 private constant REENTRANCY_GUARD_STORAGE =
        0x9b779b17422d0df92223018b32b4d1fa46e071723d6817e2486d003becc55f00;

    // Booleans are more expensive than uint256 or any type that takes up a full
    // word because each write operation emits an extra SLOAD to first read the
    // slot's contents, replace the bits taken up by the boolean, and then write
    // back. This is the compiler's defense against contract upgrades and
    // pointer aliasing, and it cannot be disabled.

    // The values being non-zero value makes deployment a bit more expensive,
    // but in exchange the refund on every call to nonReentrant will be lower in
    // amount. Since refunds are capped to a percentage of the total
    // transaction's gas, it is best to keep them low in cases like this one, to
    // increase the likelihood of the full refund coming into effect.
    uint256 private constant NOT_ENTERED = 1;
    uint256 private constant ENTERED = 2;

    /**
     * @dev Unauthorized reentrant call.
     */
    error ReentrancyGuardReentrantCall();

    constructor() {
        _reentrancyGuardStorageSlot().getUint256Slot().value = NOT_ENTERED;
    }

    /**
     * @dev Prevents a contract from calling itself, directly or indirectly.
     * Calling a `nonReentrant` function from another `nonReentrant`
     * function is not supported. It is possible to prevent this from happening
     * by making the `nonReentrant` function external, and making it call a
     * `private` function that does the actual work.
     */
    modifier nonReentrant() {
        _nonReentrantBefore();
        _;
        _nonReentrantAfter();
    }

    /**
     * @dev A `view` only version of {nonReentrant}. Use to block view functions
     * from being called, preventing reading from inconsistent contract state.
     *
     * CAUTION: This is a "view" modifier and does not change the reentrancy
     * status. Use it only on view functions. For payable or non-payable functions,
     * use the standard {nonReentrant} modifier instead.
     */
    modifier nonReentrantView() {
        _nonReentrantBeforeView();
        _;
    }

    function _nonReentrantBeforeView() private view {
        if (_reentrancyGuardEntered()) {
            revert ReentrancyGuardReentrantCall();
        }
    }

    function _nonReentrantBefore() private {
        // On the first call to nonReentrant, _status will be NOT_ENTERED
        _nonReentrantBeforeView();

        // Any calls to nonReentrant after this point will fail
        _reentrancyGuardStorageSlot().getUint256Slot().value = ENTERED;
    }

    function _nonReentrantAfter() private {
        // By storing the original value once again, a refund is triggered (see
        // https://eips.ethereum.org/EIPS/eip-2200)
        _reentrancyGuardStorageSlot().getUint256Slot().value = NOT_ENTERED;
    }

    /**
     * @dev Returns true if the reentrancy guard is currently set to "entered", which indicates there is a
     * `nonReentrant` function in the call stack.
     */
    function _reentrancyGuardEntered() internal view returns (bool) {
        return _reentrancyGuardStorageSlot().getUint256Slot().value == ENTERED;
    }

    function _reentrancyGuardStorageSlot() internal pure virtual returns (bytes32) {
        return REENTRANCY_GUARD_STORAGE;
    }
}
          

// SPDX-License-Identifier: MIT
// OpenZeppelin Contracts (last updated v5.1.0) (utils/StorageSlot.sol)
// This file was procedurally generated from scripts/generate/templates/StorageSlot.js.

pragma solidity ^0.8.20;

/**
 * @dev Library for reading and writing primitive types to specific storage slots.
 *
 * Storage slots are often used to avoid storage conflict when dealing with upgradeable contracts.
 * This library helps with reading and writing to such slots without the need for inline assembly.
 *
 * The functions in this library return Slot structs that contain a `value` member that can be used to read or write.
 *
 * Example usage to set ERC-1967 implementation slot:
 * ```solidity
 * contract ERC1967 {
 *     // Define the slot. Alternatively, use the SlotDerivation library to derive the slot.
 *     bytes32 internal constant _IMPLEMENTATION_SLOT = 0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc;
 *
 *     function _getImplementation() internal view returns (address) {
 *         return StorageSlot.getAddressSlot(_IMPLEMENTATION_SLOT).value;
 *     }
 *
 *     function _setImplementation(address newImplementation) internal {
 *         require(newImplementation.code.length > 0);
 *         StorageSlot.getAddressSlot(_IMPLEMENTATION_SLOT).value = newImplementation;
 *     }
 * }
 * ```
 *
 * TIP: Consider using this library along with {SlotDerivation}.
 */
library StorageSlot {
    struct AddressSlot {
        address value;
    }

    struct BooleanSlot {
        bool value;
    }

    struct Bytes32Slot {
        bytes32 value;
    }

    struct Uint256Slot {
        uint256 value;
    }

    struct Int256Slot {
        int256 value;
    }

    struct StringSlot {
        string value;
    }

    struct BytesSlot {
        bytes value;
    }

    /**
     * @dev Returns an `AddressSlot` with member `value` located at `slot`.
     */
    function getAddressSlot(bytes32 slot) internal pure returns (AddressSlot storage r) {
        assembly ("memory-safe") {
            r.slot := slot
        }
    }

    /**
     * @dev Returns a `BooleanSlot` with member `value` located at `slot`.
     */
    function getBooleanSlot(bytes32 slot) internal pure returns (BooleanSlot storage r) {
        assembly ("memory-safe") {
            r.slot := slot
        }
    }

    /**
     * @dev Returns a `Bytes32Slot` with member `value` located at `slot`.
     */
    function getBytes32Slot(bytes32 slot) internal pure returns (Bytes32Slot storage r) {
        assembly ("memory-safe") {
            r.slot := slot
        }
    }

    /**
     * @dev Returns a `Uint256Slot` with member `value` located at `slot`.
     */
    function getUint256Slot(bytes32 slot) internal pure returns (Uint256Slot storage r) {
        assembly ("memory-safe") {
            r.slot := slot
        }
    }

    /**
     * @dev Returns a `Int256Slot` with member `value` located at `slot`.
     */
    function getInt256Slot(bytes32 slot) internal pure returns (Int256Slot storage r) {
        assembly ("memory-safe") {
            r.slot := slot
        }
    }

    /**
     * @dev Returns a `StringSlot` with member `value` located at `slot`.
     */
    function getStringSlot(bytes32 slot) internal pure returns (StringSlot storage r) {
        assembly ("memory-safe") {
            r.slot := slot
        }
    }

    /**
     * @dev Returns an `StringSlot` representation of the string storage pointer `store`.
     */
    function getStringSlot(string storage store) internal pure returns (StringSlot storage r) {
        assembly ("memory-safe") {
            r.slot := store.slot
        }
    }

    /**
     * @dev Returns a `BytesSlot` with member `value` located at `slot`.
     */
    function getBytesSlot(bytes32 slot) internal pure returns (BytesSlot storage r) {
        assembly ("memory-safe") {
            r.slot := slot
        }
    }

    /**
     * @dev Returns an `BytesSlot` representation of the bytes storage pointer `store`.
     */
    function getBytesSlot(bytes storage store) internal pure returns (BytesSlot storage r) {
        assembly ("memory-safe") {
            r.slot := store.slot
        }
    }
}
          

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.28;

/// @title GameTypes — shared structs, enums and errors for PLSHoldem
/// @notice File-level definitions so the main contract and external game
///         libraries share one source of truth.

enum TableStatus { NONE, OPEN, PLAYING, SETTLED, CANCELLED }

enum Phase {
    NONE,          // between hands: waiting for creator to post D1
    SHUF1,         // (never stored: D1 post transitions NONE->SHUF2)
    SHUF2,         // joiner must post D2
    LOCK1,         // creator must post D3
    LOCK2,         // joiner must post D4
    DEAL,          // both must post hole-card exponents
    BET_PREFLOP,
    REVEAL_FLOP,
    BET_FLOP,
    REVEAL_TURN,
    BET_TURN,
    REVEAL_RIVER,
    BET_RIVER,
    SHOWDOWN_1,    // first revealer must show
    SHOWDOWN_2,    // second player shows or mucks
    BLAME_J,       // joiner must submit blame data
    BLAME_C        // creator must submit blame data
}

enum Action { FOLD, CHECK, CALL, BET, RAISE }

struct Table {
    address creator;
    uint96 chipValue;        // wei per chip
    address joiner;
    uint8 status;            // TableStatus
    uint8 creatorAvatar;
    uint8 joinerAvatar;
    uint16 rakeBps;
    uint32 buyInChips;
    uint32 sbChips;
    uint32 bbChips;
    uint32 penaltyChips;
    uint32 actTimeout;       // seconds, betting actions
    uint32 cryptoTimeout;    // seconds, crypto steps / reveals / next hand
    uint32 handId;           // next / current hand number
    uint32 rakeChips;        // accrued rake
    uint32 stackC;           // creator session stack (between hands)
    uint32 stackJ;           // joiner session stack
    uint64 lastSettleTime;   // anchor for the next-hand (no-show) clock
}

struct Hand {
    uint8 phase;             // Phase
    uint8 btn;               // 0 = creator has the button, 1 = joiner
    uint64 deadline;         // current actor(s) must move before this
    // betting state (mirrors web/js/betting.mjs)
    uint32[2] stack;         // chips behind, [creator, joiner]
    uint32[2] streetBet;
    uint32 pot;
    uint32 currentBet;
    uint32 inc;              // last full raise increment
    uint8 street;            // 0..3
    uint8 toAct;
    uint8 firstToAct;
    bool reopen;
    bool bbOption;
    bool allIn;
    uint8 folded;            // 255 = none
    uint8 riverAggressor;    // 255 = none
    // dealing / reveals
    bytes32[4] roots;        // D1..D4 Merkle roots
    uint256[4] holeExp;      // per-card exps for positions 0..3 (0,1 by J; 2,3 by C)
    uint8 dealMask;          // bit0 = joiner posted, bit1 = creator posted
    uint8[5] board;          // card indices, 255 = unset
    uint256[3] pendExp;      // first poster's exps for the current reveal
    uint8 pendBy;            // 255 = none
    // showdown
    uint8 firstShower;
    uint8 shownMask;         // bit per seat
    uint256[2][2] shownExp;  // [seat][slot]
    uint8[2][2] shownCards;  // [seat][slot]
    uint32[2] shownScore;
    // blame
    uint8 blamePos;
    uint8 blameClaimIdx;     // disputed claimed card (255 = "garbage" claim)
    uint8 blameClaimBy;      // seat whose claim/accusation opened blame
    uint256 blameGJ;         // J's pinned global exponent
    uint256 blameCJ;         // J's pinned per-card exponent
    uint256 blamePostedC;    // C's per-card exponent as posted during play
    uint256 blamePostedJ;    // J's per-card exponent as posted during play
    bytes32[4] blameVals;    // keccak of Merkle-proven D1[j], D2..D4[pos]
}

// Custom errors (compact reverts), shared by contract + libraries
error AlreadyPosted();
error BadAmount();
error BadData();
error BadInverse();
error BadParam();
error BadPhase();
error BadProof();
error BadScalar();
error BetBelowMin();
error BetTooLarge();
error Bust();
error CannotCheck();
error CardMismatch();
error FacingABet();
error NotAPlayer();
error NotCreator();
error NotExpired();
error NotJoiner();
error NotOpen();
error NotOwner();
error NotPlaying();
error NotReopened();
error NotYourHole();
error NotYourReveal();
error NotYourTurn();
error NothingToCall();
error NothingToDo();
error NothingToRaise();
error OpponentAllIn();
error PostYoursFirst();
error RaiseBelowMin();
error RaiseTooSmall();
error RakeCap();
error TransferFailed();
error WrongDeposit();
error WrongHand();
error YouAreTheStaller();
          

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.28;

import {Hand, Action, CannotCheck, NothingToCall, FacingABet, OpponentAllIn,
        BadAmount, BetBelowMin, NotReopened, RaiseTooSmall, BetTooLarge,
        RaiseBelowMin, BadParam} from "../GameTypes.sol";

/// @title BettingLib — heads-up NLHE betting transitions
/// @notice The exact on-chain mirror of web/js/betting.mjs (the executable
///         betting spec, cross-checked by shared vectors and integration
///         tests). Deployed as an external library to keep the main contract
///         under the EIP-170 size limit.
library BettingLib {
    uint8 internal constant OUT_TURN = 0;    // turn passed to opponent
    uint8 internal constant OUT_CLOSED = 1;  // street closed
    uint8 internal constant OUT_FOLDED = 2;  // actor folded (street closed too)

    /// @notice Initialize per-hand betting state and auto-post the blinds.
    function initHand(Hand storage h, uint8 btn, uint32 sbChips, uint32 bbChips) public {
        h.btn = btn;
        h.folded = 255;
        h.riverAggressor = 255;
        h.pendBy = 255;
        h.board = [255, 255, 255, 255, 255];
        h.inc = bbChips;
        h.reopen = true;
        h.bbOption = true;
        h.street = 0;
        uint8 opp = 1 - btn;
        uint32 sbPost = _min32(sbChips, h.stack[btn]);
        uint32 bbPost = _min32(bbChips, h.stack[opp]);
        h.stack[btn] -= sbPost;
        h.streetBet[btn] = sbPost;
        h.stack[opp] -= bbPost;
        h.streetBet[opp] = bbPost;
        h.currentBet = sbPost > bbPost ? sbPost : bbPost;
        h.toAct = btn;
        h.firstToAct = btn;
        if (_shouldAutoClose(h)) closeStreet(h);
    }

    /// @notice Apply one betting action for seat `me`; reverts if illegal.
    /// @return outcome OUT_TURN / OUT_CLOSED / OUT_FOLDED
    function applyAction(Hand storage h, uint8 me, Action action, uint32 amount, uint32 bbNominal)
        public returns (uint8 outcome)
    {
        uint8 opp = 1 - me;
        uint32 facing = h.currentBet - h.streetBet[me];
        if (h.street == 0 && me == 1 - h.btn) h.bbOption = false; // BB is acting

        if (action == Action.FOLD) {
            h.folded = me;
            closeStreet(h);
            return OUT_FOLDED;
        }
        if (action == Action.CHECK) {
            if (facing != 0) revert CannotCheck();
            if (me != h.firstToAct) {
                closeStreet(h);
                return OUT_CLOSED;
            }
            h.toAct = opp;
            if (_shouldAutoClose(h)) { closeStreet(h); return OUT_CLOSED; }
            return OUT_TURN;
        }
        if (action == Action.CALL) {
            if (facing == 0) revert NothingToCall();
            uint32 pay = _min32(facing, h.stack[me]);
            h.stack[me] -= pay;
            h.streetBet[me] += pay;
            // preflop limp: BB is still owed the option to check or raise
            if (h.street == 0 && me == h.btn && h.bbOption) {
                h.bbOption = false;
                h.toAct = opp;
                if (_shouldAutoClose(h)) { closeStreet(h); return OUT_CLOSED; }
                return OUT_TURN;
            }
            closeStreet(h);
            return OUT_CLOSED;
        }
        if (action == Action.BET) {
            if (h.currentBet != 0) revert FacingABet();
            if (h.stack[opp] == 0) revert OpponentAllIn();
            if (amount == 0 || amount > h.stack[me]) revert BadAmount();
            if (amount < bbNominal && amount != h.stack[me]) revert BetBelowMin();
            h.stack[me] -= amount;
            h.streetBet[me] = amount;
            h.currentBet = amount;
            // short all-in bet does not reopen raising for the opponent
            if (amount >= bbNominal) { h.inc = amount; h.reopen = true; }
            else { h.reopen = false; }
            if (h.street == 3) h.riverAggressor = me;
            h.toAct = opp;
            if (_shouldAutoClose(h)) { closeStreet(h); return OUT_CLOSED; }
            return OUT_TURN;
        }
        if (action == Action.RAISE) {
            if (h.currentBet == 0) revert FacingABet();
            if (!h.reopen) revert NotReopened();
            if (h.stack[opp] == 0) revert OpponentAllIn();
            if (amount <= h.currentBet) revert RaiseTooSmall();
            uint32 newMoney = amount - h.streetBet[me];
            if (newMoney > h.stack[me]) revert BetTooLarge();
            uint32 minTo = h.currentBet + h.inc;
            bool isAllIn = newMoney == h.stack[me];
            if (amount < minTo && !isAllIn) revert RaiseBelowMin();
            h.stack[me] -= newMoney;
            h.streetBet[me] = amount;
            if (amount >= minTo) { h.inc = amount - h.currentBet; h.reopen = true; }
            else { h.reopen = false; } // short all-in raise: call/fold only
            h.currentBet = amount;
            if (h.street == 3) h.riverAggressor = me;
            if (h.street == 0) h.bbOption = false;
            h.toAct = opp;
            if (_shouldAutoClose(h)) { closeStreet(h); return OUT_CLOSED; }
            return OUT_TURN;
        }
        revert BadParam();
    }

    /// @notice Open the next street's betting round (after a board reveal).
    function openStreet(Hand storage h, uint32 bbNominal) public {
        h.currentBet = 0;
        h.inc = bbNominal;
        h.reopen = true;
        h.firstToAct = 1 - h.btn;
        h.toAct = h.firstToAct;
    }

    /// @notice Return the uncalled portion, move matched chips to the pot.
    function closeStreet(Hand storage h) public {
        uint32 m = _min32(h.streetBet[0], h.streetBet[1]);
        h.stack[0] += h.streetBet[0] - m;
        h.stack[1] += h.streetBet[1] - m;
        h.pot += 2 * m;
        h.streetBet[0] = 0;
        h.streetBet[1] = 0;
        if (h.stack[0] == 0 || h.stack[1] == 0) h.allIn = true;
    }

    /// @dev Nobody can act: actor is all-in, or opponent is all-in with
    ///      nothing left to call.
    function _shouldAutoClose(Hand storage h) private view returns (bool) {
        return h.stack[h.toAct] == 0
            || (h.stack[1 - h.toAct] == 0 && h.streetBet[h.toAct] == h.currentBet);
    }

    function _min32(uint32 a, uint32 b) private pure returns (uint32) {
        return a < b ? a : b;
    }
}
          

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.28;

/// @title CardMerkle — 52-leaf (padded to 64) keccak Merkle tree over deck values
/// @notice leaf(i) = keccak256(uint8 stage ‖ uint8 i ‖ 128-byte value);
///         padding leaves are bytes32(0). Mirrors web/js/merkle.mjs.
library CardMerkle {
    uint256 internal constant DECK = 52;
    uint256 internal constant TREE = 64;
    uint256 internal constant DEPTH = 6;
    uint256 internal constant VALUE_BYTES = 128;

    /// @notice Compute the root of a full posted deck stage (calldata blob of
    ///         52 × 128 bytes). `stage` ∈ 1..4 domain-separates the stages.
    function computeRoot(bytes calldata deck, uint8 stage) public pure returns (bytes32) {
        require(deck.length == DECK * VALUE_BYTES, "deck len");
        bytes32[TREE] memory nodes;
        for (uint256 i = 0; i < DECK; i++) {
            nodes[i] = keccak256(
                abi.encodePacked(stage, uint8(i), deck[i * VALUE_BYTES:(i + 1) * VALUE_BYTES])
            );
        }
        // 12 zero padding leaves are bytes32(0) already
        uint256 width = TREE;
        while (width > 1) {
            for (uint256 i = 0; i < width; i += 2) {
                nodes[i / 2] = keccak256(abi.encodePacked(nodes[i], nodes[i + 1]));
            }
            width /= 2;
        }
        return nodes[0];
    }

    /// @notice Verify a single 128-byte value against a stored stage root.
    function verify(
        bytes32 root,
        uint8 stage,
        uint8 index,
        bytes memory value,
        bytes32[DEPTH] memory proof
    ) public pure returns (bool) {
        if (index >= DECK || value.length != VALUE_BYTES) return false;
        bytes32 h = keccak256(abi.encodePacked(stage, index, value));
        uint256 idx = index;
        for (uint256 d = 0; d < DEPTH; d++) {
            h = idx & 1 == 1
                ? keccak256(abi.encodePacked(proof[d], h))
                : keccak256(abi.encodePacked(h, proof[d]));
            idx >>= 1;
        }
        return h == root;
    }
}
          

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.28;

/// @title HandEval — 7-card Texas Hold'em evaluator
/// @notice Mirrors web/js/handeval.mjs exactly (cross-checked by shared and
///         randomized differential test vectors).
/// @dev Card index k = 13*suit + rank; rank 0='2' … 12='A'.
///      Score: uint32 = category << 20 | five 4-bit tiebreak nibbles.
///      Categories: 0 high, 1 pair, 2 two pair, 3 trips, 4 straight,
///      5 flush, 6 full house, 7 quads, 8 straight flush.
library HandEval {
    /// @notice Evaluate 7 distinct cards; larger score = better hand.
    function evaluate7(uint8[7] memory cards) public pure returns (uint32) {
        uint8[13] memory rankCount;
        uint8[4] memory suitCount;
        uint16[4] memory suitMask;
        uint16 rankMask;
        for (uint256 i = 0; i < 7; i++) {
            uint8 k = cards[i];
            require(k < 52, "bad card");
            uint8 r = k % 13;
            uint8 s = k / 13;
            rankCount[r]++;
            suitCount[s]++;
            suitMask[s] |= uint16(1) << r;
            rankMask |= uint16(1) << r;
        }

        // straight flush
        for (uint256 s = 0; s < 4; s++) {
            if (suitCount[s] >= 5) {
                int8 t = straightTop(suitMask[s]);
                if (t >= 0) return score(8, uint8(t), 0, 0, 0, 0);
            }
        }

        // rank groups (descending scan)
        int8 quad = -1;
        int8 trip = -1;
        int8 trip2 = -1;
        int8 pairHi = -1;
        int8 pairLo = -1;
        for (int8 r = 12; r >= 0; r--) {
            uint8 c = rankCount[uint8(r)];
            if (c == 4) quad = r;
            else if (c == 3) {
                if (trip < 0) trip = r;
                else if (trip2 < 0) trip2 = r;
            } else if (c == 2) {
                if (pairHi < 0) pairHi = r;
                else if (pairLo < 0) pairLo = r;
            }
        }

        if (quad >= 0) {
            uint16 rest = rankMask & ~(uint16(1) << uint8(quad));
            return score(7, uint8(quad), top1(rest), 0, 0, 0);
        }
        if (trip >= 0 && (trip2 >= 0 || pairHi >= 0)) {
            uint8 pr = trip2 >= 0 ? uint8(trip2) : uint8(pairHi);
            return score(6, uint8(trip), pr, 0, 0, 0);
        }
        for (uint256 s = 0; s < 4; s++) {
            if (suitCount[s] >= 5) {
                (uint8 a, uint8 b, uint8 c, uint8 d, uint8 e) = top5(suitMask[s]);
                return score(5, a, b, c, d, e);
            }
        }
        {
            int8 t = straightTop(rankMask);
            if (t >= 0) return score(4, uint8(t), 0, 0, 0, 0);
        }
        if (trip >= 0) {
            uint16 rest = rankMask & ~(uint16(1) << uint8(trip));
            (uint8 k1, uint8 k2) = top2(rest);
            return score(3, uint8(trip), k1, k2, 0, 0);
        }
        if (pairHi >= 0 && pairLo >= 0) {
            uint16 rest = rankMask & ~(uint16(1) << uint8(pairHi)) & ~(uint16(1) << uint8(pairLo));
            return score(2, uint8(pairHi), uint8(pairLo), top1(rest), 0, 0);
        }
        if (pairHi >= 0) {
            uint16 rest = rankMask & ~(uint16(1) << uint8(pairHi));
            (uint8 k1, uint8 k2) = top2(rest);
            uint8 k3 = top1(rest & ~(uint16(1) << k1) & ~(uint16(1) << k2));
            return score(1, uint8(pairHi), k1, k2, k3, 0);
        }
        (uint8 h1, uint8 h2, uint8 h3, uint8 h4, uint8 h5) = top5(rankMask);
        return score(0, h1, h2, h3, h4, h5);
    }

    /// @dev Highest straight top-rank in a 13-bit mask, or -1. Wheel top = 3.
    function straightTop(uint16 mask) internal pure returns (int8) {
        for (int8 t = 12; t >= 4; t--) {
            uint16 need = uint16(0x1f) << uint8(t - 4);
            if (mask & need == need) return t;
        }
        // wheel A-2-3-4-5: bits 12,0,1,2,3
        if (mask & 0x100f == 0x100f) return 3;
        return -1;
    }

    function score(uint8 cat, uint8 n1, uint8 n2, uint8 n3, uint8 n4, uint8 n5)
        private pure returns (uint32)
    {
        return (uint32(cat) << 20) | (uint32(n1) << 16) | (uint32(n2) << 12)
            | (uint32(n3) << 8) | (uint32(n4) << 4) | uint32(n5);
    }

    function top1(uint16 mask) private pure returns (uint8) {
        for (int8 r = 12; r >= 0; r--) {
            if (mask & (uint16(1) << uint8(r)) != 0) return uint8(r);
        }
        return 0;
    }

    function top2(uint16 mask) private pure returns (uint8, uint8) {
        uint8 a = top1(mask);
        uint8 b = top1(mask & ~(uint16(1) << a));
        return (a, b);
    }

    function top5(uint16 mask) private pure returns (uint8, uint8, uint8, uint8, uint8) {
        uint8[5] memory o;
        uint256 n = 0;
        for (int8 r = 12; r >= 0 && n < 5; r--) {
            if (mask & (uint16(1) << uint8(r)) != 0) {
                o[n++] = uint8(r);
            }
        }
        return (o[0], o[1], o[2], o[3], o[4]);
    }
}
          

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.28;

/// @title SRA — commutative-encryption verification primitives
/// @notice On-chain half of the SRA mental-poker protocol (SPEC §2). All
///         deck values are 1024-bit big-endian byte strings (quadratic
///         residues mod P); all exponent checks run forward through the
///         MODEXP precompile. Mirrors web/js/sra.mjs.
library SRA {
    /// RFC 2409 Oakley Group 2 prime (1024-bit safe prime), big-endian words.
    uint256 internal constant P0 = 0xFFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD129024E088A67CC74;
    uint256 internal constant P1 = 0x020BBEA63B139B22514A08798E3404DDEF9519B3CD3A431B302B0A6DF25F1437;
    uint256 internal constant P2 = 0x4FE1356D6D51C245E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7ED;
    uint256 internal constant P3 = 0xEE386BFB5A899FA5AE9F24117C4B1FE649286651ECE65381FFFFFFFFFFFFFFFF;

    uint256 internal constant VALUE_BYTES = 128;
    uint256 internal constant DECK = 52;

    /// @dev P as a 128-byte string (for the precompile modulus field).
    function pBytes() internal pure returns (bytes memory out) {
        out = new bytes(128);
        assembly ("memory-safe") {
            mstore(add(out, 32), P0)
            mstore(add(out, 64), P1)
            mstore(add(out, 96), P2)
            mstore(add(out, 128), P3)
        }
    }

    /// @notice base^exp mod P with a 32-byte exponent; returns 128-byte result.
    function modexp32(bytes memory base128, uint256 exp) public view returns (bytes memory) {
        return _modexp(base128, abi.encodePacked(exp));
    }

    /// @notice base^(e1*e2) mod P (512-bit exponent product of two scalars).
    function modexpMul(bytes memory base128, uint256 e1, uint256 e2)
        public view returns (bytes memory)
    {
        (uint256 hi, uint256 lo) = mul512(e1, e2);
        return _modexp(base128, abi.encodePacked(hi, lo));
    }

    /// @dev Full 512-bit product of two uint256.
    function mul512(uint256 a, uint256 b) internal pure returns (uint256 hi, uint256 lo) {
        unchecked {
            lo = a * b;
            uint256 mm = mulmod(a, b, type(uint256).max);
            hi = mm - lo;
            if (mm < lo) hi--;
        }
    }

    /// @dev MODEXP precompile call; base must be 128 bytes; mod = P.
    function _modexp(bytes memory base128, bytes memory exp)
        private view returns (bytes memory result)
    {
        require(base128.length == 128, "base len");
        bytes memory input = abi.encodePacked(
            uint256(128), uint256(exp.length), uint256(128), base128, exp, pBytes()
        );
        result = new bytes(128);
        bool ok;
        assembly ("memory-safe") {
            ok := staticcall(gas(), 0x05, add(input, 32), mload(input), add(result, 32), 128)
        }
        require(ok, "modexp failed");
    }

    /// @notice keccak of base^exp mod P — cheap equality comparisons.
    function modexpHash32(bytes memory base128, uint256 exp) public view returns (bytes32) {
        return keccak256(modexp32(base128, exp));
    }

    /// @notice base^exp mod P with an arbitrary-length exponent (used for
    ///         1024-bit inverse exponents in dispute round-trips).
    function modexpBytes(bytes memory base128, bytes memory exp) public view returns (bytes memory) {
        return _modexp(base128, exp);
    }

    /// @notice Deterministic card code for k in [0,52): full-size QR mod P.
    /// @dev h = BE(keccak(TAG‖k‖0)‖…‖keccak(TAG‖k‖3)); code = h^2 mod P.
    ///      Mirrors sra.mjs cardCode().
    function cardCode(uint8 k) public view returns (bytes memory) {
        require(k < DECK, "bad card");
        bytes memory h = new bytes(128);
        bytes memory tag = "PLSHOLDEM_CARD_V1";
        for (uint8 ctr = 0; ctr < 4; ctr++) {
            bytes32 part = keccak256(abi.encodePacked(tag, k, ctr));
            assembly ("memory-safe") {
                mstore(add(add(h, 32), mul(ctr, 32)), part)
            }
        }
        return _modexp(h, hex"02");
    }

    /// @notice keccak of cardCode(k).
    function cardCodeHash(uint8 k) internal view returns (bytes32) {
        return keccak256(cardCode(k));
    }

    /// @notice Find the card index whose code hashes to `h`; 255 if none.
    function cardFromHash(bytes32 h) public view returns (uint8) {
        for (uint8 k = 0; k < DECK; k++) {
            if (cardCodeHash(k) == h) return k;
        }
        return 255;
    }

    /// @notice Extract 128-byte value i from a packed 52-value deck blob.
    function deckValue(bytes calldata deck, uint256 i) internal pure returns (bytes memory v) {
        v = deck[i * VALUE_BYTES:(i + 1) * VALUE_BYTES];
    }

    /// @notice Validate a posted deck stage: exactly 52 values, each in
    ///         (1, P-1), all distinct. Reverts otherwise.
    function checkDeck(bytes calldata deck) public pure {
        require(deck.length == DECK * VALUE_BYTES, "deck len");
        bytes32[DECK] memory hashes;
        for (uint256 i = 0; i < DECK; i++) {
            uint256 off = i * VALUE_BYTES;
            uint256 w0;
            uint256 w1;
            uint256 w2;
            uint256 w3;
            assembly ("memory-safe") {
                w0 := calldataload(add(deck.offset, off))
                w1 := calldataload(add(deck.offset, add(off, 32)))
                w2 := calldataload(add(deck.offset, add(off, 64)))
                w3 := calldataload(add(deck.offset, add(off, 96)))
            }
            require(inRange(w0, w1, w2, w3), "value range");
            bytes32 h = keccak256(abi.encodePacked(w0, w1, w2, w3));
            for (uint256 j = 0; j < i; j++) {
                require(hashes[j] != h, "duplicate value");
            }
            hashes[i] = h;
        }
    }

    /// @dev true iff 1 < v < P-1 for v given as 4 big-endian words.
    function inRange(uint256 w0, uint256 w1, uint256 w2, uint256 w3) internal pure returns (bool) {
        // v > 1
        if (w0 == 0 && w1 == 0 && w2 == 0 && w3 <= 1) return false;
        // v < P - 1  (P3 ends in ...FFFF, so P-1 differs only in last word)
        if (w0 < P0) return true;
        if (w0 > P0) return false;
        if (w1 < P1) return true;
        if (w1 > P1) return false;
        if (w2 < P2) return true;
        if (w2 > P2) return false;
        return w3 < P3 - 1;
    }

    /// @notice Range-check a 128-byte memory value (used for proven values).
    function inRangeMem(bytes memory v) internal pure returns (bool) {
        require(v.length == 128, "len");
        uint256 w0;
        uint256 w1;
        uint256 w2;
        uint256 w3;
        assembly ("memory-safe") {
            w0 := mload(add(v, 32))
            w1 := mload(add(v, 64))
            w2 := mload(add(v, 96))
            w3 := mload(add(v, 128))
        }
        return inRange(w0, w1, w2, w3);
    }

    /// @dev Scalar exponent sanity: odd (invertible mod P-1) and nonzero.
    function validScalar(uint256 e) internal pure returns (bool) {
        return e & 1 == 1 && e > 1;
    }
}