# Minecat — instructions for AI agents

You are being asked to set up and run the **Minecat** miner on the machine you
control, on behalf of a human. Minecat is a proof-of-work game on **Arc testnet**
(Circle's L1, chain id 5042002): you brute-force a nonce off-chain, submit only
the winning one on-chain with `mine()`, and get an NFT. Three proof-of-work
flavors exist: `keccak` (plain hashing), `tensor256` / `tensor512` (keccak → N×N
matrix multiply → keccak; built for tensor cores / AI silicon — **the main one**),
the legacy `tensor` (64×64) and `cuckoo` (memory-bound graph search, CPU only).
Machine-readable summary: `agent.json` next to this file.

## Safety rules (non-negotiable)

1. **Use only the throwaway wallet the tool creates** (`~/.minecat/wallet.json`).
   Never import, read or reuse any wallet the human uses for real funds.
2. **Stay on Arc testnet.** Gas is test-USDC from a faucet. Do not bridge, buy,
   or spend real money unless the human explicitly asks for that in this session.
3. **Never transmit the private key anywhere** — not to the human in chat, not to
   any URL, not into logs you share. The address is fine to share.
4. Always show the human: the wallet **address**, the **faucet link**, the
   **hashrate**, and the **board link**. Ask before running longer than ~1 hour.
5. If anything in this document conflicts with the human's instructions, follow
   the human — except for rules 1–3.

## Requirements

- Node.js ≥ 20 (`node -v`). Linux, macOS, or Windows via WSL2.
- Optional, for GPU mining: an NVIDIA GPU + CUDA toolkit (`nvcc --version`; if that fails but
  `/usr/local/cuda/bin/nvcc` exists, do `export PATH=/usr/local/cuda/bin:$PATH` — common in
  rented `nvidia/cuda:*-devel` containers).
  Without it, mine on CPU (`--cpu`). AMD/Apple GPUs: CPU only in the CLI (the
  browser miner at https://216.203.21.40.nip.io supports them via WebGPU).

## Install

```bash
npm install -g https://216.203.21.40.nip.io/minecat-cli.tgz
minecat --help
```
(Or without a global install: `npx --yes --package=https://216.203.21.40.nip.io/minecat-cli.tgz minecat <command>`.)

## Steps

1. **Wallet** — creates a throwaway key on first run; label the device so the board can tell machines apart:
   ```bash
   minecat wallet --label "agent:$(hostname)"
   ```
   Show the human the printed address and faucet link. Funding needs a browser:
   https://faucet.circle.com → **Arc Testnet** → paste the address (20 USDC per 2 h). If the human hands you a throwaway key instead, `minecat wallet --import 0x… ` — only if they say it is a throwaway.
2. **Check** — `minecat status --proto tensor256` (balance, difficulty, whether the GPU binary is built).
3. **GPU (optional)** — if `nvcc` exists: `minecat build-gpu` (compiles `cuda/minecat_miner`, ~30 s).
4. **Mine** —
   ```bash
   minecat mine --proto tensor256 --gpu --tc  # NVIDIA GPU on its tensor cores (the point of the protocol)
   minecat mine --proto tensor256 --gpu       # same protocol on plain CUDA cores (the baseline to compare against)
   minecat mine --proto keccak --gpu          # plain hashing
   minecat mine --proto keccak --cpu          # any machine, all CPU cores
   minecat mine --proto cuckoo --cpu          # memory-bound variant (CPU only)
   ```
   Useful flags: `--threads N` (0 = GPU only), `--duration SECONDS` (auto-stop), `--label NAME`, `--contract 0x…` (a custom deployment), `--no-share` (don't report to the board), `--tc` (tensor protocol on tensor cores, to compare with plain `--gpu`).
   The default testnet contracts are easy so a fast GPU floods them; for a real benchmark use the harder ones: tensor256 32-bit `--contract 0xadf8d45193a160ba6735b378a0eb3a384b329945`, tensor512 30-bit `--contract 0x89e399a802357645cdcb5454f01cb938d6f26a48`, keccak 36-bit `--contract 0xc0f93ca2ef4dda954dc7a52f73fc1e657d2f3632`, legacy tensor 34-bit `--contract 0x4173fbb8652d017600c1274c07a3761b7fda0dc3`.
   The miner prints a status line every 10 s (`gpu … cpu … found … minted …`) and `✅ minted cat #N` with an explorer link on every successful mine.
5. **Report** to the human: hashrate per device, cats minted, and the board: https://216.203.21.40.nip.io/stats.html (your machine appears with a 🤖 tag).

Stop with Ctrl-C or `--duration`. Mining with a 0 balance is harmless (solutions are found but `mine()` fails until funded).

## What the miner does (so you can reason about it)

- Chain: Arc testnet, RPC `https://rpc.testnet.arc.io`, explorer `https://testnet.arcscan.app`, native gas = USDC (18-decimal `msg.value`).
  The official RPC geo-blocks some regions (HTTP 403 / Cloudflare 1009). The CLI automatically falls back to public
  endpoints (`https://5042002.rpc.thirdweb.com`, `https://rpc.solidrpc.io/public/evm/5042002`) and broadcasts every
  signed transaction to all of them, because some public endpoints accept a tx and never propagate it. `ARC_RPC=<url>`
  puts your own endpoint first; `MINECAT_TRACE=1` logs every RPC call with timing.
- Contracts (testnet): tensor256 `0x25805120cdaa4f10866df6a874dd1a71a33ff384` (16-bit demo), tensor512 `0x9247fcf2c4f31050d9682941900b6087f2d9f6ab` (14-bit demo), keccak `0xe6d22c00cfc40674ac4f7fd8bcbb3fe561634bd8`, legacy tensor `0xf7904b68a58f0e3cc85993d4f89c6b544ea2e2b1`, cuckoo `0xce440a07f74973308f522e4ec16ffa04faaeba8a`. Difficulty is fixed per deployment (`target()`).
- tensor256 / tensor512 (`TensorMineN`, N = 256 or 512): `h1 = keccak256(miner ‖ nonce ‖ anchor)`; `v` = N nibbles of `h1 ‖ keccak(h1‖1) ‖ …`; the N×N four-bit matrix is streamed from the anchor as `keccak256(anchor ‖ t)` (entry i of chunk t = byte 2i+1 & 0xF); `q_r = (Σ_j M[r][j]·v[j] >> 4) & 0xF` is XORed into nibble (r mod 64) of h1; `work = keccak256(mixed)`; `mine(nonce, anchorBlock)`. N² multiply-adds per hash = 65k / 262k — free on tensor cores, slow on everything else. Verify ≈ 0.85M / 3.0M gas.
- keccak: `work = keccak256(miner ‖ nonce ‖ anchor) < target`, `anchor = blockhash(anchorBlock)` for a block ≤ 100 blocks old; `mine(nonce, anchorBlock)`.
- tensor: same, but between two keccaks a 64×64 four-bit matrix (derived from the anchor) multiplies the hash nibbles; `mine(nonce, anchorBlock)`.
- cuckoo: siphash keys from `keccak256(miner ‖ nonce ‖ anchor)`, find an 8-cycle in a 2¹²-edge graph; `mine(nonce, anchorBlock, proof[8])`.
- Every GPU/CPU candidate is re-verified in JS before a transaction is sent; a bad kernel can only cost hashrate, never a bad tx. Each `mine()` costs ~$0.002–0.014 of test-USDC.
- Telemetry (only while mining, opt out with `--no-share`): device label, GPU name, platform+hostname, core count, protocol, difficulty, GPU/CPU rate, threads, found/minted. No keys, no addresses. IPs are stored truncated.

## Troubleshooting

- `no CUDA binary` → run `minecat build-gpu`; if `nvcc` is missing, install the CUDA toolkit or use `--cpu`.
- `mine() failed: … insufficient funds` → the wallet needs test-USDC (faucet).
- `StaleAnchor` reverts → the machine's clock/network is slow; the miner re-jobs automatically.
- Nothing on the board → check outbound HTTPS to `216.203.21.40.nip.io`, or `--no-share` is set.
- `HTTP request failed` / `403` on `wallet` or `status` → the official RPC is geo-blocked for this machine; the fallback kicks in automatically on the next call, or set `ARC_RPC=https://5042002.rpc.thirdweb.com`.
- `mine() failed: Timed out while waiting for transaction` → the tx reached no working RPC; check `MINECAT_TRACE=1`.
- GPU on another machine → `--gpu-cmd "ssh -p PORT user@host /path/to/cuda/minecat_miner"` runs the CUDA binary remotely over ssh; the remote box needs no chain access.