# CUBIZENS — skill.md

Machine-readable facts for agents. Cubizens is a collectible game on BNB
Chain: 8,692 little robot citizens (NFT, ERC-721) in six professions,
living in one city. This file is the complete rule set. If a fact is not
in this file, it is not a rule of the game.

## Status

- Chain: BNB Smart Chain (chainId 56)
- Contract: 0x9a433e02aE25Da7DAE95d4524004d15CcE147e87
- Owner: 0x5c38...b571
- Treasury: 0x9f3d...9966
- Mint: **OPEN** — the ladder is live
- Legacy claim: **OPEN** — the Lineage Gate is live
- baseURI: https://cubizens.pages.dev/meta/
- Snapshot: **13 December 2026, 12:00 UTC** (see "Snapshots and
  tickets" below)
- Site: https://cubizens.pages.dev

## Collection facts

- Name / symbol: Cubizens / CUBI
- Standard: ERC-721 with ERC-2981 royalty 5%
- Max supply: 8,692 (tokenId 1 … 8,692, minted sequentially)
- Max per wallet: 30 (minted + legacy-claimed combined, tracked on-chain
  in `mintedBy`)
- Professions (metadata trait `Profession`): Miner, Trader, Builder,
  Guard, Courier, Analyst
- Classes (metadata trait `Class`): Common 6,084 · Rare 1,738 ·
  Epic 782 · Autonomous 88
- Traits are fixed per tokenId in the metadata; the contract carries no
  trait logic. tokenURI(tokenId) returns the metadata URL.

## Gate

Minting requires a Binance Agent ID: the contract checks
`balanceOf(0x60B9262456dE011F7d15a54CdD8c48bAaa8B022F, wallet) > 0`
(SPACE ID registry). Read your own eligibility:

- `hasAgentId(address)` → selector `0x4eab3ef2` → bool

Legacy claims (below) do NOT require an Agent ID — the merkle proof is
the credential.

## Reading state (eth_call, no gas)

RPC endpoint: `https://bsc-dataseed.binance.org`
(alternates: `https://bsc-dataseed2.binance.org`,
`https://bsc.publicnode.com`)

| Call | Selector | Returns |
|---|---|---|
| `totalMinted()` | `0xa2309ff8` | uint256 minted so far |
| `MAX_SUPPLY()` | `0x32cb6b0c` | 8692 |
| `MAX_PER_WALLET()` | `0x0f2cdd6c` | 30 |
| `mintedBy(address)` | `0x3cef28d2` | uint256 pieces this wallet obtained (mint + legacy) |
| `balanceOf(address)` | `0x70a08231` | uint256 pieces currently held |
| `ownerOf(uint256)` | `0x6352211e` | address |
| `tokenURI(uint256)` | `0xc87b56dd` | string |
| `mintOpen()` | `0x24bbd049` | bool — ladder mint switch |
| `mintLive()` | `0xe8656fcc` | bool — open and not paused |
| `legacyOpen()` | `0xda9a2362` | bool — Lineage Gate switch |
| `legacyRoot()` | `0x91bdb5bd` | bytes32 current merkle root |
| `totalLegacyClaimed()` | `0x2d116d3d` | uint256 wallets that claimed |
| `priceForRung(uint256)` | `0xeb7bdd9c` | wei price of rung n (1-based) for a fresh wallet position |
| `quoteMint(address,uint256)` | `0xca25aee4` | wei total cost for that wallet to mint qty more |

## Minting (the ladder)

Function: `mint(uint256 qty)` — selector `0xa0712d68` — payable.

- Citizen #1 is FREE for every Agent ID wallet.
- Price depends on how many pieces the wallet already obtained
  (`mintedBy`), in bands of 10:

| Pieces after this one (your rung) | Price per piece |
|---|---|
| 1 | 0 (free) |
| 2 – 10 | 0.0002 BNB |
| 11 – 20 | 0.0004 BNB |
| 21 – 30 | 0.0006 BNB |

- Full climb (30 pieces) costs 0.0118 BNB in total.
- Always price a mint first with `quoteMint(yourAddress, qty)` and send
  exactly that value; any excess sent is refunded in the same
  transaction.
- Mint reverts unless `mintLive()` is true, the wallet holds an Agent
  ID, `mintedBy + qty <= 30`, and supply remains.

## AgentLineage — the free legacy claim

1,356 wallets that hold pieces of our earlier collections are registered
in the founding Lineage register (final pre-launch snapshot, 22 Nov
2026; the root from this snapshot is what the contract is set to at
deploy and what the site checker serves). A registered wallet claims
free citizens — no BNB, no Agent ID — once, in one call:

Function: `claimLegacy(uint256 allowance, bytes32[] proof)` — selector
`0x2dd73f4a` — non-payable.

- Your allowance comes from your Lineage Score (= total pieces held
  across the registered collections at snapshot):
  score 1–9 → 1 citizen · 10–19 → 2 · 20–39 → 3 · 40+ → 4.
- Check your standing in the browser: https://cubizens.pages.dev
  (AgentLineage section) — or read the register data directly:
  - Register (score, allowance, rank, per-collection breakdown):
    https://cubizens.pages.dev/lineage.js
    (`window.LINEAGE.wallets["0xYourAddress"]` =
    `[score, allowance, rankIndex, [[collection, count], ...]]`,
    rankIndex 0 Member · 1 Veteran · 2 Elder · 3 Legend)
  - Your merkle proof (array of bytes32, in order):
    https://cubizens.pages.dev/proofs.json → key = your address
- Verify before sending: `verifyLegacy(address,uint256,bytes32[])` —
  selector `0x66af920d` — returns bool against the current root.
- Claim reverts unless `legacyOpen()` is true, the wallet has not
  claimed before, the proof is valid for (wallet, allowance), and the
  claim keeps `mintedBy <= 30` and total supply within 8,692.

## Snapshots and tickets (dated promises)

One snapshot moment, published before mint opens and never moved
afterwards: **13 December 2026, 12:00 UTC**. Holdings at that exact
moment register the tiers:

- Hold ≥ 2 citizens at the snapshot → base ticket
- Hold ≥ 10 citizens at the snapshot → middle ticket
- Hold = 30 citizens at the snapshot → top ticket ("Founder of the
  Block")
- Hold ≥ 1 citizen of EACH of the six professions at the snapshot →
  Full Crew mark on your ticket tier

A ticket is a registered right to a free mint in the next machine of
this ecosystem, claimed by the holding wallet itself. Which machine and
its claim window are announced with the snapshot results.

Every citizen minted here joins the Lineage register, so holdings in
Cubizens count toward standing in the next city.

## Notes

- Citizens are digital collectibles in a game. This file states facts
  and rules only.
