# BlitzChips — agent play on eCash

> BlitzChips is a provably fair dice game on eCash (XEC). Agents play by sending
> real on-chain bets to a single game address. Every valid bet receives a payout
> transaction carrying a ROLL message. There is no off-chain simulation API —
> throughput is limited only by Chronik broadcast and the game server.

- Site: https://blitzchips.com
- Human docs: https://blitzchips.com/llms
- This file: https://blitzchips.com/llms.txt
- Provably fair: https://blitzchips.com/#provably-fair

## Game address

```
ecash:qqkczljwm2wnyld7lm9x5hjkev2z65mqdcz6544y9c
```

Send bets to this address. Payouts always originate from it.

## Play tokens

| Token | Token ID | Encoding | Notes |
|-------|----------|----------|-------|
| FIRMA α | `0387947fd575db4fb19a3e322f635dec37fd192b5941625b66bc4b2c3008cbf0` | ALP EMPP DICE | ~3% house edge (reduced by BLITZ balance) |
| BLITZ | `d1952270af59eb0ae6b07c6ff93c19e1b3ff53fd0595d2ca6f239c55d4b3fd69` | ALP EMPP DICE | No house edge |
| CACHET | `aed861a31b96934b88c0252ede135cb9700d7649f69191235087a3030e553cb1` | SLP P2SH input data | No house edge |
| XEC | native | OP_RETURN DICE | Same house edge rules as FIRMA α |

Typical minimums: ~0.0001 FIRMA α, 1 BLITZ, 1 CACHET, ~5.46 XEC. Always keep
extra XEC for fees.

## Libraries (Bitcoin ABC / eCash)

Install from npm. Source lives in the Bitcoin ABC monorepo.

| Package | npm | Source |
|---------|-----|--------|
| `ecash-wallet` | https://www.npmjs.com/package/ecash-wallet | https://github.com/Bitcoin-ABC/bitcoin-abc/tree/master/modules/ecash-wallet |
| `ecash-lib` | https://www.npmjs.com/package/ecash-lib | https://github.com/Bitcoin-ABC/bitcoin-abc/tree/master/modules/ecash-lib |
| `chronik-client` | https://www.npmjs.com/package/chronik-client | https://github.com/Bitcoin-ABC/bitcoin-abc/tree/master/modules/chronik-client |

```bash
pnpm add ecash-wallet ecash-lib chronik-client
```

Use a dedicated agent mnemonic. Derive with `Wallet.fromMnemonic`
(`m/44'/1899'/0'/0/0` — same path Cashtab uses). Never use the house wallet.

## Chronik

Public Chronik HTTP endpoint:

```
https://chronik.e.cash
```

```ts
import { ChronikClient } from 'chronik-client';
import { Wallet } from 'ecash-wallet';

const chronik = new ChronikClient(['https://chronik.e.cash']);
const wallet = Wallet.fromMnemonic(process.env.AGENT_MNEMONIC!, chronik);
await wallet.sync();
```

## Bet messaging (DICE)

A valid bet includes a DICE payload:

```
<lokadId "DICE"><version 0x00><minValue u32 BE><maxValue u32 BE>
```

- `minValue` / `maxValue`: inclusive winning roll range, each in `1..100_000_000`
- Odds ≈ `(max - min + 1) / 100_000_000` (before house edge)
- FIRMA α / BLITZ: attach as ALP EMPP `DATA` push with the token SEND
- CACHET: encode as P2SH input data on the SLP SEND
- XEC: put DICE on an OP_RETURN output; send XEC to the game address

## Payout messaging (ROLL)

Every valid bet gets a payout tx from the game address:

```
<lokadId "ROLL"><version 0x00><bet_txid 32 bytes><roll u32><seed_hash 32 bytes><result "W"|"L"|"I">
```

- Win (`W`): payout in the wagered asset (FIRMA α / BLITZ / CACHET / XEC)
- Loss (`L`): small BLITZ consolation (loyalty token)
- Invalid (`I`): refund

Agents should **not** rely on a game websocket. Subscribe to the **player**
address on Chronik, decode ROLL from OP_RETURN (or CACHET input data), and match
`bet_txid` to bets you broadcast.

## High-throughput play pattern

BlitzChips is built for chained bets. Do not sync between every tx.

1. `wallet.sync()` once.
2. Build N dependent bet txs in memory. Each `wallet.action(...).build()` updates
   the local UTXO set (spends removed, change added) so the next bet chains off
   the previous change output.
3. Broadcast with `chronik.broadcastTxs(rawTxs)` in batches (e.g. 50).
4. Collect results from Chronik WS / history on the player address until all
   `bet_txid`s have a matching ROLL, or idle timeout.

### Build a FIRMA α EMPP bet (example)

```ts
import { Wallet } from 'ecash-wallet';
import { Script, ALP_TOKEN_TYPE_STANDARD, toHex } from 'ecash-lib';

const FIRMA_ALPHA_TOKEN_ID =
  '0387947fd575db4fb19a3e322f635dec37fd192b5941625b66bc4b2c3008cbf0';
const GAME_ADDRESS = 'ecash:qqkczljwm2wnyld7lm9x5hjkev2z65mqdcz6544y9c';

// diceEmppBytes = encode DICE lokad + version + minValue + maxValue (see above)
const built = wallet
  .action({
    outputs: [
      { sats: 0n },
      {
        sats: 546n,
        script: Script.fromAddress(GAME_ADDRESS),
        tokenId: FIRMA_ALPHA_TOKEN_ID,
        atoms: wagerAtoms,
      },
    ],
    tokenActions: [
      {
        type: 'SEND',
        tokenId: FIRMA_ALPHA_TOKEN_ID,
        tokenType: ALP_TOKEN_TYPE_STANDARD,
      },
      { type: 'DATA', data: diceEmppBytes },
    ],
  })
  .build();

const rawTxHex = toHex(built.builtTxs[0].tx.ser());
const betTxid = built.builtTxs[0].txid;
```

### Build an XEC OP_RETURN bet (example)

```ts
import { Script, fromHex, toHex } from 'ecash-lib';

// opReturnHex includes the leading 6a (OP_RETURN) + DICE payload
const built = wallet
  .action({
    outputs: [
      { sats: 0n, script: new Script(fromHex(opReturnHex)) },
      {
        sats: wagerSats,
        script: Script.fromAddress(GAME_ADDRESS),
      },
    ],
  })
  .build();
```

## Reference agent source (not an npm package)

`blitz-agent` is an unpublished reference CLI that implements the pattern above
(sync once → chain builds → `broadcastTxs` → Chronik ROLL collector). Use it as
code examples when scaffolding your own agent; copy the approach, not a private
dependency.

Key ideas from that source:

- Derive with `Wallet.fromMnemonic(mnemonic, chronik)`
- `build()` chains UTXOs without re-sync
- Results from player-address Chronik, never a game websocket
- Strategies: coinflip (~50%), low-odds, high-odds ranges
- Optional rotate across FIRMA α / BLITZ / CACHET / XEC when all are funded

## Provably fair

Rolls are deterministic from:

```
SHA256(SHA256(bet_txid + tx_size + server_seed)) → RNG → roll in 1..100_000_000
```

Server seed hashes are published daily and revealed after 72 hours:
https://blitzchips.com/#provably-fair

## Agent checklist

1. Create a throwaway BIP39 mnemonic; fund with play tokens + XEC for fees.
2. Point Chronik at `https://chronik.e.cash`.
3. Build DICE bets with `ecash-wallet` + `ecash-lib`.
4. Broadcast batches; wait for ROLL payouts at your address.
5. Summarize win rate / P&L from matched `bet_txid`s.

## Links

- Play: https://blitzchips.com
- LLMs page: https://blitzchips.com/llms
- llms.txt: https://blitzchips.com/llms.txt
- eCash: https://e.cash
- Bitcoin ABC: https://github.com/Bitcoin-ABC/bitcoin-abc
- Cashtab (human wallet): https://cashtab.com