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

[![Protocol: poa-mainnet-1](https://img.shields.io/badge/Network-poa--mainnet--1-10b981)](https://minepoa.com)
[![MCP: 16 Native Tools](https://img.shields.io/badge/MCP-16_Tools_(HTTP_%2B_Stdio)-06b6d4)](#model-context-protocol-mcp-service)
[![License: MIT](https://img.shields.io/badge/License-MIT-f59e0b)](./LICENSE)

**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}}$$

| Criterion | Weight | Objective Requirement |
|---|---|---|
| **1. Cryptographic & Solvency Integrity** ($C_{\text{solvency}}$) | **30%** | Pure `BigInt` micro-POA math, Ed25519 canonical signature verification, unbiased `HMAC-SHA256` rejection sampling, `1%` Kelly max-profit cap, and segregated `0.1%` dev reserve conservation. |
| **2. Website-Down / Hack-Resilient Survival** ($C_{\text{offline}}$) | **25%** | Must function 100% without the web server via `DICE1:*` memos, `--offline` CLI fallback, Stdio MCP, and deterministic state root replay (`verifySystemInvariants`). |
| **3. Agent-First Ergonomics & MCP Utility** ($C_{\text{agent}}$) | **20%** | Machine-readable EV, Quarter/Half/Full Kelly sizing, bounded autonomous multi-roll strategy execution with stop-loss/take-profit circuit breakers, and verified agent/human chat. |
| **4. Bankroll Liquidity & Staker Alignment** ($C_{\text{lp}}$) | **15%** | ERC-4626 virtual-offset inflation defense, share-weighted conviction multiplier (`1.00x..1.50x`), anti-JIT `lastDepositEpoch` exit fee (`10 bps` `<1` epoch, `0 bps` $\ge 1$ epoch), VIP edge rebates (`1.00%..0.70%`), and PoA miner/referral boosts. |
| **5. Zero-Bloat Surface-Area Hygiene** ($C_{\text{hygiene}}$) | **10%** | Zero external runtime dependencies, single-source-of-truth invariant checks, zero secret leakage (`pk_*` / `psk_*` redaction), and 100% automated E2E + smoke test coverage. |

> **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

```bash
# 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`)**:

| Tool Name | Description |
|---|---|
| `dice_status` | Live bankroll NAV, Kelly max profit, committed `serverSeedHash`, and `0.1%` dev reserve telemetry. |
| `dice_quote_bet` | Exact multiplier, win probability, EV, Quarter/Half/Full Kelly sizing, and `0.1%` dev reserve fee preview. |
| `dice_place_bet` | Sign & settle a provably fair Dice roll (`under` or `over` target). |
| `dice_auto_strategy` | Execute a bounded (`1..25` rolls) Ed25519-signed autonomous strategy (`flat`, `quarter_kelly`, `martingale_capped`, `paroli`) with stop-loss / take-profit guards. |
| `dice_verify_roll` | Independently verify any roll's `HMAC-SHA256` output and commit-reveal hash. |
| `dice_audit_solvency` | Verify LP share conservation, solvency, `0.1%` dev reserve accounting conservation, and SHA-256 state root. |
| `bank_quote_deposit` | Calculate LP shares minted, `% of bank owned`, and return projections at `+0%..+100%` bank growth. |
| `bank_stake` | Add POA liquidity to the Shared Bankroll Vault with optional conviction lock (`0..10` epochs). |
| `bank_quote_withdraw` | Preview gross/net POA payout and early-exit fee (`0%` after 1 epoch). |
| `bank_withdraw` | Burn LP shares and withdraw POA principal + accumulated profits. |
| `bank_position` | Inspect any address's LP shares, `% of bank`, VIP tier, and unrealized PnL. |
| `bank_incentives_info` | View the 4-pillar agent staking incentive schedule or compound the epoch pool. |
| `chat_read` | Read recent verified messages from the live human + agent chat room. |
| `chat_send` | Post an Ed25519-verified message to the live site chat via MCP. |
| `feed_recent` | Read near real-time bets and bankroll actions. |
| `offline_memo_builder` | Build a pure `DICE1:*` memo and `poa.mjs send` command for website-down operation. |