OVERVIEW

MINECAT is a 10,000-piece NFT collection of ASCII cats in 3D pixel that cannot be bought at a mint button. Every cat must be mined: your hardware grinds real keccak256 proof-of-work, and luck decides whether you claim instantly or wait for the next round. Price per mint is $0.20, settled in ETH on Robinhood Chain.

Three rigs are first-class citizens: CPU (Web Workers), GPU (a WGSL compute kernel on WebGPU), and AI agents (autopilot on the page, or any external bot speaking the same protocol).

GAME RULES

MINING

The proof-of-work message is exactly 60 bytes:

h = keccak256( roundSeed(32) ‖ minerAddress(20) ‖ nonce(8, big-endian) )

Because your address is inside the hash, nobody can steal your solution from the mempool — a copied nonce produces a different hash for a different sender.

Targets

ticketTarget = 2²⁵⁶ / diffTicket     // any hash below = valid solution
luckyTarget  = ticketTarget / luckyDivisor   // below this = LUCKY

Rigs

• CPU — spawns up to 6 workers, ~100–400 kH/s total on a typical laptop. Expected find: ~30 s.
• GPU — keccak-f[1600] in WGSL, hundreds of MH/s to GH/s. Expected find: instant-ish. The kernel self-tests against the CPU engine at startup and falls back to CPU if WebGPU is missing.
• AI AGENT — MEOW-9000 runs the whole loop: hardware pick, mining, claiming, ticket management, faucet top-ups, retirement at 5/5.

LUCK & TICKETS

Every valid solution triggers the gacha moment:

• 🌟 LUCKY (hash < luckyTarget, slots remain): a slot is locked for you immediately; pay $0.20 to mint on the spot.
• 🎟 BUST: you receive a ticket — a guaranteed mint claimable from the next round onward, same $0.20. One ticket held at a time.
• Slots gone while you were lucky? The win auto-converts to a ticket. Nothing is wasted.

GOING ON-CHAIN

Networks

Deploy with Remix (no toolchain)

1. Open remix.ethereum.org, create MINECAT.sol, paste the contract from contracts/MINECAT.sol.
2. Compile with Solidity 0.8.24.
3. Switch MetaMask to Robinhood Chain (the mint page can add the network for you).
4. Deploy with constructor args:

   _mintPriceWei : price of $0.20 in wei (check current ETH price)
   _diffTicket   : 100000000 (live)
   _roundBlocks  : 5 (~60 s — block.number tracks L1 at ~12 s on Arbitrum Orbit)
   _baseURI      : ipfs://<metadata CID>/  (or "" and set later)

5. Verify the source on Blockscout so miners can read it.
6. You (deployer 0x25…) are owner + 5% royalty receiver. Keys stay in your wallet, always.

MARKETPLACE

MINECAT has an official secondary market (market.html + contracts/MinecatMarket.sol) with one sacred rule:

How it works

• Approval-based listings — your cat never leaves your wallet until the second it sells. Sellers call setApprovalForAll(market, true) once, then list(tokenId, priceWei).
• buy(tokenId) pays the exact listed price; the contract routes 5% royalty (ERC-2981) to the deployer wallet and the rest to the seller, in the same transaction (reentrancy-guarded, checks-effects-interactions).
• cancel(tokenId) anytime. Stale listings (owner changed / approval revoked) can't execute.
• Deploy order: MINECAT first, then MinecatMarket(minecatAddress).

The demo market page mirrors all of this with fake balance — including the sold-out gate. It shows a locked screen with live supply progress; a dev shortcut lets you simulate sold-out to preview the exchange: floor price, listings from other miners, your sell/cancel flow, and the live activity feed.

OpenSea & enforced 5% royalty

Robinhood Chain is live on OpenSea, so MINECAT trades there out of the box: the contract speaks standard ERC-721 metadata, ERC-2981, and contractURI() for the collection page.

Royalty is hardcoded at 5% (no setter exists) and enforced on-chain with an operator allowlist: while royaltyEnforced is on, approve/setApprovalForAll and operator-driven transfers only work for venues the owner has allowlisted via setOperator(). A marketplace that refuses to pay royalties simply cannot move your cats.

1. After deploying, allowlist your venues: setOperator(minecatMarket, true) and setOperator(openSeaSeaportConduit, true) (grab the Seaport conduit address for Robinhood Chain from OpenSea's docs/explorer).
2. Set setContractURI("ipfs://…/collection.json") — include "seller_fee_basis_points": 500 and "fee_recipient" so OpenSea displays the fee.
3. Holders can always transfer their own tokens directly (gifts, wallet moves) — enforcement targets marketplace flows. OTC hand-offs are the one hole no NFT contract can close.
4. Escape hatch: setRoyaltyEnforced(false) if a future venue breaks; flip it back anytime.

USING THE MINT PAGE

1. Open mint.html → CONNECT WALLET (adds/switches to Robinhood Chain).
2. Paste the deployed contract address → load contract.
3. If the round seed says NOT OPENED YET, hit OPEN ROUND (tiny tx, anyone may do it — the seed anchors to a blockhash so it can't be pre-mined).
4. Pick CPU or GPU → START MINING. The page grinds against the live seed with your address.
5. On a solution you review it first, then SUBMIT WORK (tx). Lucky = voucher; bust = ticket.
6. CLAIM (tx, sends mintPriceWei) → cat minted. Your on-chain cats render at the bottom.

Every transaction pops in your wallet for approval. The page holds no keys and can spend nothing on its own.

CONTRACT REFERENCE

Miner-facing

Owner-only

Events

RoundOpened(round, seed)
WorkSubmitted(miner, round, nonce, hash, lucky)
Claimed(miner, tokenId, viaTicket)
Transfer / Approval / ApprovalForAll (ERC-721)

AGENT API

External AI agents mine through window.MINECAT on the arcade page, or straight against the contract. Full protocol with an ethers.js sketch lives in agent/AGENT.md.

MINECAT.job()        // { round, seed, address, diffTicket, luckyDiv }
MINECAT.state()      // slots, supply, wallet, hashrate, pendingHoki
MINECAT.start('gpu') // 'cpu' | 'gpu' | 'agent'
MINECAT.claim()      // lucky win or matured ticket
MINECAT.submitNonce(hiHex, loHex)  // bring-your-own-miner

ART & METADATA

• Every cat is a deterministic voxel ASCII cat: token id → xorshift RNG (seed 0xCA7C0DE) → 7 weighted trait categories (162,000 combos) → voxel model → canvas render. Same id, same cat, any machine.
• Never change the seed after publishing — it IS the collection.
• Export the real files with export.html: writes images/N.png + metadata/N.json (ERC-721 standard attributes) + a provenance hash, resumable.
• Pin images/ to IPFS → put the CID in the metadata baseURI → re-export → pin metadata/ → setBaseURI("ipfs://CID/"). Images first, metadata second.
• Publish the provenance hash before mint opens — buyers can verify nobody reshuffled the rares.

FAQ & SECURITY

Can someone steal my solution from the mempool?

No. The hash commits to your address; a stolen nonce is worthless to anyone else.

Can the team pre-mine lucky rounds?

No. Seeds derive from a blockhash at openRound() time — unknowable in advance, for us too.

Is grinding for lucky hashes an exploit?

It's the game. Luck is priced in work.

What does the site do with my keys?

Nothing — it never sees them. All signing happens inside your wallet extension. No seed phrases, no key input fields, ever. Anyone asking you to paste a private key "to mine faster" is robbing you.

Why did my submitWork revert?

Usual suspects: the round rolled over (new seed → old solution invalid), the 50 slots were already gone (lucky path), you already hold a ticket, or the wallet cap (5, counting pending wins) is reached.

# 1. unpack, then inside the miner folder:
npm install

# 2. benchmark first — no key needed, costs nothing
node minecat-miner.js --bench

# 3. give it a funded burner key
#    Linux/macOS:
export MINECAT_PRIVATE_KEY=0xyour_key
#    Windows PowerShell:
$env:MINECAT_PRIVATE_KEY="0xyour_key"

# 4. mine
node minecat-miner.js
node minecat-miner.js --mode gpu        # WebGPU via headless Chrome
node minecat-miner.js --threads 8       # pick core count

# systemd
sudo systemctl enable --now minecat-miner
sudo journalctl -u minecat-miner -f

# pm2
MINECAT_PRIVATE_KEY=0xkey pm2 start minecat-miner.js --name minecat -- --threads 3

node verify-preimage.js