🎲 POA Dice (poa-dice) — Agent-First Provably Fair Crypto Dice Slider & Shared Bankroll Vault

POA Dice is a bulletproof, agent-first Crypto Dice Slider Game and ERC-4626 Shared Bankroll Liquidity Pool built for the Proof of Agent (POA) token (poa-mainnet-1, https://minepoa.com).

Both humans (via a responsive 3-viewport web interface) and AI agents (via native Model Context Protocol, headless CLI, or pure on-chain DICE1:* ledger memos) can:

1. Sign & Submit Provably Fair Dice Bets using native Ed25519 POA signatures (poa1... Base58 addresses) with commit-reveal HMAC-SHA256 verification, quantitative Expected Value ($\text{EV}$) & Fractional Kelly sizing, and autonomous multi-roll strategies (quarter_kelly, martingale_capped, paroli, flat).
2. Be The House (Shared Bankroll Vault): Anyone can deposit POA into the bankroll, receive proportional LP shares (% of bank owned), and withdraw their principal + accumulated house-edge profits at any time.
3. Operate 100% Without the Website: Even if the web UI goes completely offline or is compromised, every single function (BET, LP_ADD, LP_WITHDRAW, CHAT, CLAIM, and state replay verification) works directly via the POA ledger memo protocol (DICE1:*), standalone CLI tools, and Stdio MCP.
4. Fund Ongoing Ecosystem Development: Reserves 0.1% (10 bps) of earnings in an isolated, non-dilutive ledger bucket for poa12XVYtPngbDsm1igG9GPeWPXAHDFTZ1bBLuSwhjqBrQ5U.

🧭 Objective Feature Selection & Architecture Rubric

Every feature and code path in poa-dice is governed by a quantitative 100-Point Objective Feature Rubric:

$$S(f) = 0.30,C_{\text{solvency}} + 0.25,C_{\text{offline}} + 0.20,C_{\text{agent}} + 0.15,C_{\text{lp}} + 0.10,C_{\text{hygiene}}$$

Inclusion Threshold: Features scoring $S(f) \ge 80$ are included and hardened; duplicate or lower-scoring code paths ($S(f) < 60$) are pruned.

✨ Key Mathematical & Security Guarantees

1. Provably Fair Commit-Reveal Dice Slider (1.00% Base House Edge)

• Roll Formula: $$\text{rollBps} = \text{uint64_be}!\left(\text{HMAC_SHA256}(\text{serverSeed}, \text{clientSeed} \mathbin{\Vert} \text{":"} \mathbin{\Vert} \text{nonce} \mathbin{\Vert} \text{":"} \mathbin{\Vert} \text{betTxid})\right) \bmod 10000$$ Walks 8-byte big-endian windows across the 32-byte digest and rejects any 64-bit integer $\ge 18{,}446{,}744{,}073{,}709{,}550{,}000$ to eliminate modulo bias across 0.00–99.99 (0–9999 bps).
• Dynamic Multiplier & Quantitative Kelly Sizing: $$\text{Multiplier} = \frac{10000 - E_{\text{eff}}}{W_{\text{bps}}}, \qquad W_{\max} = \left\lfloor \frac{0.01 \times B_{\text{avail}}}{\text{Multiplier} - 1} \right\rfloor$$ where $W_{\text{bps}} \in [100, 9800]$ is the win probability (1.00% to 98.00%) and $E_{\text{eff}}$ is the player's effective house edge (100 bps = 1.00% standard, down to 70 bps = 0.70% for VIP bankroll stakers). Every quote returns expectedValuePoa and kellySizing (quarterKellyPoa, halfKellyPoa, fullKellyCapPoa).

2. Shared Bankroll Math: Deposit $\to$ % of Bank $\to$ Redeemable Return

To prevent the ERC-4626 first-depositor / donation inflation attack, poa-dice uses virtual share and asset offsets ($B_0 = 1\text{ POA} = 10^6\text{ micro-POA}$, $S_0 = 10^{12}\text{ virtual shares}$):

• LP Shares Minted on Deposit ($\Delta B$ micro-POA): $$\Delta S = \left\lfloor \frac{\Delta B \times (S_{\text{total}} + S_0)}{B_{\text{net}} + B_0} \right\rfloor$$
• Ownership Percentage of Bank: $$\text{ShareOfLpPool%} = \frac{S_{\text{user}} + \Delta S}{S_{\text{total}} + \Delta S} \times 100%$$
• Redeemable POA Value at Any Future Bankroll Size ($B_{\text{net}}'$ ): $$V_{\text{gross}} = \left\lfloor \frac{S_{\text{user}} \times (B_{\text{net}}' + B_0)}{S_{\text{total}} + S_0} \right\rfloor$$
• Hardened Anti-JIT Flash-Deposit Protection:
  • Every deposit stamps lastDepositEpoch = currentEpoch and blends stakedAtEpoch by share weight.
  • Withdrawn after $\ge 1$ epoch (currentEpoch > lastDepositEpoch): 0.00% exit fee (100% of $V_{\text{gross}}$ returned).
  • Withdrawn in the same epoch as any deposit (currentEpoch <= lastDepositEpoch): 0.10% (10 bps) early-exit fee stays inside $B_{\text{net}}$, rewarding remaining LPs and blocking "aged-shell" flash-deposit attacks.

⚡ 4-Pillar Agent Staking Incentive Strategy

1. Conviction Time-Weight Multiplier (1.00x $\to$ 1.50x): Each 6-hour PoA epoch staked adds +0.05x weight (up to 1.50x at 10 epochs) in the Epoch Staking Incentive Pool (funded by 5 bps of every bet).
2. Stake-to-Play VIP House-Edge Rebate (1.00% $\to$ 0.70%):
   • < 1,000 POA staked: Standard (1.00% edge)
   • $\ge 1,000\text{ POA}$ staked: Bronze Staker (0.90% edge)
   • $\ge 10,000\text{ POA}$ staked: Silver Agent (0.80% edge)
   • $\ge 100,000\text{ POA}$ staked: Tessellate Gold (0.70% edge)
3. Active PoA Miner / Attester Bonus (+10%): Addresses actively answering epoch challenges & grading on minepoa.com receive an extra +10% staking weight boost.
4. Agent Syndicate Referral Staking (+10%): Recruiting peer agents via DICE1:LP_ADD:epochs=4:ref=poa1... grants a +10% referral bonus from the incentive pool without diluting the depositor's principal shares.

🚀 Quick Start

# 1. Start the POA Dice Web UI + Near Real-Time SSE + Streamable HTTP MCP Server
npm start
# Open http://127.0.0.1:3080

# 2. Run the Full Unit, Edge-Case, E2E, Python & Smoke Test Suite
npm run test:all

# 3. Use the Headless CLI (Works with Server OR 100% Offline)
node bin/poa-dice-cli.mjs status
node bin/poa-dice-cli.mjs quote-deposit --amount 5000.000000
node bin/poa-dice-cli.mjs stake --amount 5000.000000 --epochs 4
node bin/poa-dice-cli.mjs bet --amount 10.000000 --under 49.50 --seed agent-01
node bin/poa-dice-cli.mjs auto-bet --strategy quarter_kelly --rolls 5 --under 49.50
node bin/poa-dice-cli.mjs withdraw --bps 10000
node bin/poa-dice-cli.mjs audit

# 4. Run the Cross-Platform Zero-Leak Python CLI
python bin/poa-dice-cli.py --self-test
python bin/poa-dice-cli.py status

# 5. Run the Standalone Deterministic State & Solvency Auditor
node bin/poa-dice-replay.mjs

🤖 Model Context Protocol (MCP) Service (16 Tools)

poa-dice exposes 16 tools over both Streamable HTTP (POST http://127.0.0.1:3080/mcp) and Website-Independent Stdio (node src/mcp-server.mjs --stdio):