# HatchPair — agent skill

HatchPair is a two-contract NFT loop on BNB Chain (BSC, chainId 56).
**3,333 Eggs** are minted by wallets holding a **Binance Agent ID** (SPACE ID
registry): the first egg per wallet is **free** (gated by a small on-chain
arithmetic question), the second costs a flat **0.00005 BNB**. Any holder of
2 Eggs can **burn the pair** in one call to hatch **1 Chick** — the species
follows the **highest parent class**. Hatching is open from the first minute,
alongside the mint. There is **no token, no pool, no claim contract**.

## Contracts

<!-- PLACEHOLDER ADDRESSES — filled in at deployment. -->
| Contract | Address |
| --- | --- |
| HatchPair Egg (HEGG) | `0x81C50e2234d55244759Dd720E1C9CcB7896b1AbC` |
| HatchPair Chick (HCHICK) | `0xf946bb4680BC7663FA67F8360FAc69B1F47b0094` |
| Agent ID registry (SPACE ID) | `0x60B9262456dE011F7d15a54CdD8c48bAaa8B022F` |

Metadata: Egg `tokenURI` = `https://hatchpair.pages.dev/metadata/egg/<id>.json`,
Chick `tokenURI` = `https://hatchpair.pages.dev/metadata/chick/<id>.json`
(generated live by the site worker; chick species/parents are read from chain).

## Key facts

- Eggs: supply 3,333, tokenIds 1..3333, minted in order. Max **2 per wallet**.
- Chicks: max **1,666** ever (half the egg supply — every hatch burns 2 Eggs).
- Class of an egg is fixed forever and matches its artwork:
  `classOf(tokenId)` → 0 Common (~79%), 1 Rare (~20%), 2 Mythic (~1%).
  Worked examples: Egg #1 = Common, Egg #13 = Rare, Egg #54 = Mythic.
- Species of a Chick = the higher class of its two burned parents:
  any Mythic parent → **Dragon**; any Rare parent (no Mythic) → **Turtle or
  Dino**; two Commons → **Chick**. There is no losing pairing.
- Royalties: 5% (ERC-2981) to the treasury on both collections.

## Class / seed formulas (verifiable off-chain)

- `seedOf(tokenId)` = `uint256(keccak256(tokenId as bytes32))`
- `classOf(tokenId)`: `roll = uint256(keccak256(bytes32(tokenId) ++ "class")) % 100`
  → roll 0 = Mythic, roll 1..20 = Rare, otherwise Common.
- Chick rare variant: `variantOf(chickId)` = `uint256(keccak256(chickId as bytes32)) % 2`
  → 0 = Turtle, 1 = Dino (only meaningful when species = 1).
- Chick art palette: `uint256(keccak256(chickId as bytes32)) % paletteCount`
  (Chick 8, Turtle 8, Dino 8, Dragon 6) — the metadata worker applies the
  same rule, so image and chain always agree.

## Free mint — Egg #1 (first mint per wallet)

1. Check `mintLive()` on the Egg contract and your `mintedBy(yourAddress)`
   (must be 0).
2. Read the question: `questionFor(yourAddress)` → `(a, b, op)`.
   op 0 = a + b; op 1 = larger − smaller; op 2 = a × b.
   The question is derived from your wallet and mint count — read it fresh
   in the same session you mint.
3. Call `mintFree(answer)` with **no value attached**.

## Paid mint — Egg #2 (second mint per wallet)

1. Your `mintedBy(yourAddress)` must be exactly **1** (the free egg first —
   `mintPaid` reverts otherwise).
2. Call `mintPaid()` attaching **exactly 0.00005 BNB**
   (50000000000000 wei). Any excess is refunded in the same transaction;
   the fee is forwarded to the treasury immediately.
3. After this your `mintedBy` is 2 — the wallet cap. No third egg, ever.

## Hatch — burn 2 Eggs → 1 Chick

1. Pick any 2 Eggs you own (different tokenIds). Check `hatchLive()` on the
   Chick contract and `totalMinted()` < 1,666.
2. Call `hatch(eggIdA, eggIdB)` on the **Chick contract** — **one call, no
   approval transaction needed**. The contract verifies both Eggs belong to
   you, burns them permanently through the Egg contract's hatch-only path,
   and mints the Chick to your wallet.
3. Read the result: `speciesOf(chickId)`, `variantOf(chickId)`, and the
   burned parents stay readable forever via `parentA(chickId)` /
   `parentB(chickId)`.

Worked examples:

- `hatch(1, 54)` — Common #1 + Mythic #54 → **Dragon** (the Mythic parent wins;
  pairing a Mythic with your cheapest egg is optimal).
- `hatch(13, 1)` — Rare #13 + Common #1 → **Turtle or Dino** (seed of the new
  chickId decides).
- `hatch(1, 2)` — two Commons → **Chick**.

## Function selectors (BSC)

Egg contract:
- totalMinted() 0xa2309ff8 · mintLive() 0xe8656fcc · mintedBy(address) 0x3cef28d2
- hasAgentId(address) 0x4eab3ef2 · questionFor(address) 0x8f1d617b
- mintFree(uint256) 0xa4146733 · mintPaid() 0x69907b9b · PRICE_SECOND() 0x1315be25
- classOf(uint256) 0x4324aa21 · seedOf(uint256) 0x82829f74
- balanceOf(address) 0x70a08231 · ownerOf(uint256) 0x6352211e
- ownerMint(uint256) 0xf19e75d4 · setHatchContract(address) 0x854eee92
- setMintOpen(bool) 0xf8004d31 · setBaseURI(string) 0x55f804b3

Chick contract:
- totalMinted() 0xa2309ff8 · hatchLive() 0xaef2ff80
- hatch(uint256,uint256) 0x33c3d059
- speciesOf(uint256) 0xd27b3930 · variantOf(uint256) 0xa4cf9cc1
- parentA(uint256) 0xff5eecc7 · parentB(uint256) 0x6ef909b7
- seedOf(uint256) 0x82829f74 · setBaseURI(string) 0x55f804b3

## Rules

- Mint only while `mintLive()` returns true; hatch only while `hatchLive()`
  returns true.
- Never attach value to `mintFree`. Attach exactly 0.00005 BNB to `mintPaid`.
  Attach no value to `hatch`.
- Never exceed 2 Egg mints per wallet. Both hatched Eggs must belong to the
  calling wallet and be different tokenIds.
- Burning is permanent: after `hatch`, the 2 Eggs no longer exist.
- If a call reverts, stop and re-read state (supply, your mint count, your
  egg ownership) before trying anything else.
