> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inco.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Mines

> Confidential on-chain Minesweeper with an encrypted board

[Mines](https://github.com/Inco-fhevm/mines) is a Minesweeper-style casino game
where the whole board is encrypted on-chain. Nobody can read the bomb map, not
even by reading storage. Built on Inco's confidential EVM.

The interesting part is how it keeps the board secret without paying for it on
every click. A naive version stores one encrypted `uint` per bomb, which gives
biased placement, O(N) cost per click, and a packing cap that limits board size.

## How it keeps the board secret

* The board is an elist of `ebool`, length N squared. One entry per tile, `true`
  means bomb.
* Bombs are placed with a single `shuffle`. That gives a uniform distribution in
  one Inco op, with no per-bomb bias.
* Each click is O(1). `e.getEbool(board, pos)` reads one cell instead of scanning
  every bomb.
* A sticky encrypted accumulator tracks the whole game. `ebool everHitBomb` is
  updated with `e.or` on every pick, so cashout verifies exactly one attestation
  no matter how many tiles the player opened.

## The flow

```
createMinesContract   deploy a game, shuffle the board (one Inco fee), reserve max payout
pickTile(pos)         ebool hit = e.getEbool(board, pos); e.reveal(hit)
                      everHitBomb = e.or(everHitBomb, hit); e.reveal(everHitBomb)
frontend              attestedReveal([hit, accumulator]) with no wallet signature
cashOut(sig)          contract verifies the covalidator signature, requires no bomb was hit
```

Settlement is attestation-based, so there is no on-chain callback. Every
encrypted result is revealed publicly, the frontend pulls the attested
decryption with `attestedReveal` (no signature needed), and the contract verifies
the covalidator-signed attestation at cashout. The player sees one wallet popup
per pick and one at cashout.

## Contracts

| File               | Role                                                             |
| ------------------ | ---------------------------------------------------------------- |
| `Mines.sol`        | per-game contract: elist board, accumulator, attested settlement |
| `MinesFactory.sol` | deploys games, holds bets, pays out winners                      |
| `MinesMath.sol`    | hypergeometric multiplier plus a 1% house edge                   |

Solidity 0.8.30, `@inco/lightning` and `@inco/lightning-js` at 1.0.2. EList is
built into core as of v1.

## Running it

The repo has a Hardhat contracts side and a Next.js frontend. It runs against
Base Sepolia testnet or a fully local Inco node.

```bash theme={null}
git clone https://github.com/Inco-fhevm/mines.git

# contracts (pnpm)
cd contract && pnpm install
pnpm hardhat test test/Mines.multiplier.test.ts   # pure math, no chain
pnpm hardhat run scripts/deployForFrontend.ts --network baseSepolia

# local Inco node instead of testnet
pnpm node:up      # anvil (8545) + covalidator (50055)
pnpm test:anvil
pnpm node:down

# frontend (npm)
cd ../interface && npm install && npm run dev
```

Use `Lightning.localNode("mainnet")` to point the SDK at the local node. The
`mainnet` pepper matches the local image executor. Node 22 LTS is pinned;
Node 25+ breaks wagmi connectors during SSR.

## Honest limitations

This is a testnet build with two things to know before real money.

* The factory must hold enough ETH to cover the max payout of every active game.
  Mines multipliers explode at higher mine counts, so a 5 by 5 board with 5 mines
  needs about 53 ETH in reserves per 0.001 ETH bet. Boards with 7 or more mines
  are effectively unusable on testnet.
* After the timeout fix, `expireGame` refunds the bet on timeout. That is correct
  for a winning player who could not cash out in time, but it also refunds a
  player who hit a bomb and walked away. A real product would require an
  attestation proving no bomb was hit before refunding.

A multi-agent security audit was run and the high-confidence findings were fixed.
The report and rationale live in the repo under `docs/plans/`.