# Stones & Bones NYSA escrow

Current model: human scorekeeper reports final **NYSA amounts**, not dice scores.
Scorekeeper: `0x435c6647f8f32e8464786c6ba87293a2338e42d8`.

## Contracts

- `NysaEscrowDeployment`: deploys and binds the other two atomically. Caller must be the designated scorekeeper. No NYSA transfers occur at deployment.
- `NysaGameEscrow`: immutable token and engine; exactly 5,000 atomic units (5 NYSA) per player; 3–4 funded players to start. All players must mark ready; any roster change resets readiness. Each game has independent remaining funds. An address may be in multiple games, but may join each once while present and exit it once after start.
- `NysaScorekeeperEngine`: immutable scorekeeper; escrow-only start/exit entry points. Scorekeeper reports each player's final amount once. Reserves prevent multiple unclaimed reports over-allocating the pot. The last pending report must allocate all remaining value.

Players can leave a funding lobby at any time before start, moving 5 NYSA into their claim. Anyone may cancel an expired, unstarted lobby; each funded player receives a claim. The UI creates one-hour lobbies; the contract permits deadlines up to seven days. Once started, there is no unilateral stake refund. The scorekeeper must provide exit reports; if unavailable, funds may remain locked. Post-start recovery is an unresolved product rule and is not silently entrusted to an admin.

After a report, the player calls `exit(gameId)` to allocate their payout, then `withdraw()` to receive it. Zero payout is a valid exit. The scorekeeper cannot withdraw another player's claim. There is no owner sweep, upgrade hook, engine replacement, or host-set payout method on the escrow. A scorekeeper still has material control over game outcomes, so this version requires player trust in the named wallet. No automatic dice, VRF, or proof of honest play exists.

Amounts use integer Copper: `1 = 0.001 NYSA`. The actual Sonic NYSA token is `0xd0c53e7078b195fa5f410ad7ab27a3cd7ef57ca0`. USD reference prices are irrelevant to contract balances. The escrow requires exact transfer-in amounts; rebasing and fee-on-transfer tokens are not supported.

## Deployment and sharing

The app currently has **no preconfigured live deployment**. At https://coin.nysa.quest/#escrow:

1. Connect the scorekeeper wallet and switch to Sonic (chain 146).
2. Review the source and press **Deploy contracts with MetaMask**. The wallet owner reviews and submits the creation transaction. This spends S gas and creates the deployment, engine and escrow atomically.
3. After confirmation, the app reads and verifies deployed runtime code against the build, excluding compiler-declared immutable regions, then checks actual token, stake, engine binding and scorekeeper values. It generates a share link containing the deployment address.
4. Other players use that link, or enter the deployment address and load/verify it. No server-side configuration is required for shared links. `assets/escrow-deployment.json` can later be updated with a verified deployment for a site-wide default.
5. Create a game, share its ID, approve exactly 5 NYSA and join. Each player marks ready. A funded participant starts the table. Scorekeeper enters final NYSA cash-outs; players claim and withdraw.

**No mainnet transaction has been executed by the coding agent.** Local tests do not constitute an independent audit. The one-time reporter and token configuration cannot be changed after deployment; verify them before staking.

## Reproduce

Private build tools: `WEB-INF/nysacoin-build` (blocked from HTTP by Tomcat). Use a supported Node version >=20.19.

```text
npm ci
npm run compile
npm run build
npm test
```

Pinned Solidity 0.8.30, OpenZeppelin 5.4.0, optimizer 200 runs, EVM Paris. Artifacts include ABI, creation/runtime bytecode, immutable references and compiler settings. Test fixtures mint fake NYSA on an in-process Ganache chain; test engines must never be used for real funds.

Checks cover exact balances, readiness, participant limits, duplicate stake/exit/withdraw, staggered 2/8/0/10 exits, 15-NYSA winner-takes-all, pregame withdrawal/expiry, token tax rejection, unauthorized score reporting, report replay, reserved-payout oversubscription, and final conservation.

## Confirmed Sonic deployment
Verified existing on-chain deployment on 2026-10-30: deployment 0x16cb8bcb565204e01283a97d799a175fc2942132; escrow 0x135f9089878020f3861d4e6e7e851e1dc33a06b1. All three contract runtimes matched the compiled artifacts and immutable getter values were checked. This is now the dashboard default. The user performed deployment; the coding agent only read and configured it.