Docs — the OCCV2 reference manual

Chapter 01

What is OCCV2

OnChain Citizens V2 (OCCV2) is a 10,000-supply ERC-721 collection on Ethereum mainnet. Every Citizen is a flat-cartoon SVG portrait composed and stored fully on-chain. There is no IPFS link, no image host, no off-chain database — the artwork lives inside the contract itself and is rendered straight from it. As long as Ethereum exists, your Citizen's picture exists.

OCCV2 is the migration of the original OCC V1 collection. V1 holders can burn their V1 token to claim the matching V2 Citizen with the same ID; everyone else can free-mint a brand-new Citizen — only paying gas. The top 2,000 IDs ship via an external raffle on dropr.fun.

Supply: 10,000 Citizens
Network: Ethereum Mainnet
Mint price: Free · gas only

Contract: 0x55ad98c4D8ECE5E1f40C04e0E1D87c014584Dc76

Chapter 02

Three ways to get a Citizen

There are three paths into the collection. None of them has a mint price — you only ever pay Ethereum gas. They aren't a clean partition either: V1 holders and wallets that have already claimed are barred from the Free Mint route, but a raffle mint can land in any wallet without locking it out of anything else.

For V1 holders

Claim

Hold an OnChain Citizens V1 token in this wallet? Burn it to mint the matching V2 Citizen — same token ID, brand-new on-chain art. The contract checks that you currently own the V1, so you can claim every V1 in your wallet, one by one. A two-step move: approve the V2 contract on V1, then claim. Free — gas only.

Go to Claim

For everyone else

Free Mint

Fully claimed. The Free Mint allocation has sold out — no IDs remain in the mintable pool.

While it was live, this was the path for anyone without a V1 token and no prior claim. The mintable pool was every V2 ID in 1–8000 whose original V1 token is no longer live — the never-minted block in 4541–8000, plus the 24 V1 tokens that were burnt-in-place inside 1–4540. Cap was 2 per wallet.

See the wallet gate below for context on the “transaction might fail” warning.

For raffle entrants

Raffle

The top 2,000 IDs (8001–10000) are minted externally via raffles on dropr.fun — not from this dapp. Citizens minted there are first-class members of the collection: they appear in My Collection and behave identically.

Visit dropr.fun ↗

Reminder: there is no mint price on OCCV2. Anyone telling you otherwise is selling you something else.

Chapter 03

Why a Citizen is alive — the Reshuffle

All Citizens are built to be alive. Every time a Citizen is transferred, five of its trait slots are liable to be re-rolled into a new combination, producing a new look. We call this a reshuffle. However, all rare traits within these five trait categories are locked at mint and cannot be re-rolled during transfers. Holders can also freely re-roll new background colors for Citizens held.

The five reshufflable categories:

Eyes
Eyebrows
Mouth
Clothing
Accessory II

Five trait slots re-roll on every transfer. By performing self-transfers, holders can customize their Citizens' appearance — mood and clothing — at will.

A reference sheet showing every Eyes variant on its own — the kind of category that re-rolls every transfer. — **Eyes overview.** One of the five reshufflable categories — every variant shown on its own, no head silhouette in the way. On every wallet-to-wallet transfer (once reshuffles are active), the slot above re-rolls to a different one of these.

Chapter 04

Rare traits never reshuffle

The reshuffle has one big exception. Each trait variant has a weight — a number that controls how often it rolls at mint. The lower a trait's weight, the rarer it is.

If a Citizen mints with a trait whose weight is less than 16, that trait is locked forever. It never reshuffles.

This is how rare traits are defined. The lock is permanent against reshuffles on-transfer. The only way a locked rare trait ever leaves a Citizen is if its owner deliberately trades it on the Trait Market.

Additional Note

Internally, Eyes and Specials weights are stored ×2, so their on-chain comparison uses a threshold of 32. The user-facing rule is the same either way: the rare-trait list is exactly the variants whose metadata weight is below 16. See the metadata weight on every atlas card below.

Chapter 05 · 53 variants · 36 cards · 9 categories

The Rare Traits Atlas

Every rare variant in the collection. Paired entries (e.g. Crown — male / female) show both art renders inside one card; the eight extra-rare variants (weight ≤ 1) carry an Extra-Rare tag. Use the chips and search box to narrow the view.

Eyes4 rare

Animated
Extra-Rare
weight 0.5
Cross-Eyed
Rare
weight 15
Heart Eyes
Rare
weight 15
Starry
Rare
weight 15

Eyebrows1 rare

Unibrow
Rare
weight 15

Mouth3 rare

Cigarette
Rare
weight 15
Tongue Out
Rare
weight 15
Vape
Rare
weight 10

Clothing3 rare

Coat
Rare
weight 10· male / female
ETH T-Shirt
Extra-Rare
weight 1· male / female
Suit
Rare
weight 15· male / female

Accessory II9 rare

Bitcoin Maxi Cap
Rare
weight 2· male / female
Crown
Rare
weight 3· male / female
ETH Maxi Cap
Rare
weight 5· male / female
ETH Maxi Cap II
Rare
weight 4· male / female
ETH Maxi Cap III
Rare
weight 3· male / female
Halo
Rare
weight 5· male / female
Jazzman Hat
Rare
weight 5· male / female
Leather Hat
Rare
weight 3· male / female
Top Hat
Rare
weight 3· male / female

Accessory I9 rare

3D Glasses
Rare
weight 15· male / female
AR Goggles
Extra-Rare
weight 1· male / female
Band-Aid
Rare
weight 15
Clear Goggles
Extra-Rare
weight 1· male / female
Dark Goggles
Extra-Rare
weight 1· male / female
Eye Patch
Rare
weight 15· male-only
Laser
Rare
weight 5
Monocle
Rare
weight 15
Sunglasses
Rare
weight 15· male / female

Facial Hair2 rare

Mutton Chops
Rare
weight 15· male-only
Soul Patch
Rare
weight 15· male-only

Hair2 rare

Pigtails
Rare
weight 15· female-only
Mohawk
Rare
weight 15· male-only

Special3 rare

Chart Down
Extra-Rare
weight 0.5
Chart Up
Extra-Rare
weight 0.5
Glitch
Extra-Rare
weight 0.5

Chapter 06

The Core Personality Traits

These five attributes never reshuffle. Whatever your Citizen mints with stays with it forever — these attributes make each Citizen unique, no matter how many times other traits change with transfers.

17 variants · gendered

Hair

Sets the silhouette at a glance. Each Citizen carries one hair variant from mint, gendered.

Bangs
Female only
Bob
Female only
Bun
Female only
Long Straight
Female only
Long Wavy
Female only
Pigtails
Rare
Female only
Short
Female only
Wavy
Female only
Bald
Male only
Big
Male only
Bun
Male only
Buzzcut
Male only
Combover
Male only
Mohawk
Rare
Male only
Parted
Male only
Spiky
Male only
Wavy
Male only

9 palette colors

Hair Color

Applied as the fill on Hair and Facial Hair traits.

#090806
Black
#2C222B
Dark Brown
#71635A
Brown
#B7A69E
Light Brown
#8D4A43
Auburn
#DEBC99
Strawberry
#D6C4C2
Blonde
#ECDCB0
Platinum
#E6E6E6
Grey

9 variants · male only

Facial Hair

A male-only attribute. Female citizens don't carry a Facial Hair variant at all.

Clean Shaven
Male only
Full Beard
Male only
Goatee I
Male only
Goatee II
Male only
Handlebars
Male only
Mustache
Male only
Mutton Chops
Rare
Male only
Soul Patch
Rare
Male only
Stubble
Male only

7 palette colors

Skin Tone

The fill colour applied to head and body. Pinned at mint and never reshuffles.

#FFE0BD
Porcelain
#FFDBB4
Ivory
#F5D0A9
Beige
#EDB98A
Sand
#D08B5B
Caramel
#AE5D29
Toffee
#694D3A
Espresso

22 variants · 14 rare

Accessory I

The static face-affixed slot. Eight eyewear kinds — 3D Glasses, AR Goggles, Clear Glasses, Clear Goggles, Dark Goggles, Round Glasses, Sunglasses, Monocle — alongside four face marks (Band-Aid, Blush, Freckles, Scar), an Eye Patch, the full-canvas Laser overlay, and a “No Accessory” baseline. Most eyewear ships as a male/female pair; fourteen of the variants are rare and frozen at mint, the other eight are common.

3D Glasses
Rare
Male only
3D Glasses
Rare
Female only
AR Goggles
Rare
Male only
AR Goggles
Rare
Female only
Band-Aid
Rare
Blush
Clear Glasses
Male only
Clear Glasses
Female only
Clear Goggles
Rare
Male only
Clear Goggles
Rare
Female only
Dark Goggles
Rare
Male only
Dark Goggles
Rare
Female only
Eye Patch
Rare
Male only
Freckles
Laser
Rare
Monocle
Rare
No Accessory
Round Glasses
Male only
Round Glasses
Female only
Scar
Sunglasses
Rare
Male only
Sunglasses
Rare
Female only

Chapter 07

Shape your Citizen — owner actions

As the owner you have three on-chain levers. They're all available from the Citizen detail page in your collection.

Re-roll Background

Free — gas only. The contract picks a brand-new background color at random, on-chain. You can't choose or preview the result — it's a fresh roll every time.

Heads up: after the first re-roll, the background also becomes a reshuffling slot. Also, the first few re-rolls may land on the same color — this is normal. Keep trying until the reshuffle seed lands a new color.

Lock / Unlock Traits

Pauses reshuffles for an entire Citizen so the current look holds steady. Reversible — unlock whenever you like to let reshuffles resume on the next transfer. Locking and unlocking each cost 0.001 ETH.

Locking is separate from rare-trait freeze: rare freeze protects individual traits, locking pauses the whole Citizen.

Transfer

Send the Citizen to another wallet. Standard ERC-721 transferFrom.

On arrival, an unlocked Citizen's reshufflable traits re-roll for the new owner. Locked Citizens keep their look.

Chapter 08

Provenance & the Transfer Count

Every Citizen carries an on-chain transfer count — the number of times it's been moved around. The count increments on every transfer and is surfaced on the Citizen detail page as the “life story” line.

Because reshuffles fire on transfer, the transfer count is effectively the number of times each Citizen's outlook changed. It's the closest thing the collection has to a wear-and-tear indicator — except instead of degrading, the collection evolves.

Chapter 09 · Peer-to-peer rare trades

The Trait Market

Coming
Soon

The market is dormant.

The contract ships ready; the team will flip the public switch when it's time. The rules below are how trades will work once it's live.

The Trait Market is a peer-to-peer venue for trading frozen rare traits between Citizens. List one of yours, browse what others are offering, and strike a deal on-chain.

The trade rules

01
Traits trade only between Citizens of the same gender. A male crown can only move to another male Citizen; a female crown can only move to another female.
02
The receiving Citizen must have an empty slot in that same trait category. Buying a Crown for a Citizen that already wears Accessory II won't go through.
03
It's a one-way move. The seller's Citizen loses the trait and that slot goes back to reshuffling on transfer; the buyer's Citizen receives the trait frozen.
04
Only the five reshufflable categories can be traded — Eyes, Eyebrows, Mouth, Clothing, Accessory II. Static rare traits (e.g. Eye Patch, Mohawk, Mutton Chops) stay with the Citizen they minted on.

See the Trait Market page for the (currently dormant) UI preview.

Chapter 10

Anti-bot, the wallet warning, and the 0.015 ETH gate

The free-mint function has a small anti-bot rule: your wallet must hold at least 0.015 ETH. The contract checks this balance and never spends it — minting stays genuinely free.

A side effect of that check: wallet simulators sometimes flash a “this transaction might fail” warning. That's a benign false positive — the simulator is tracing a caught revert path inside the contract. As long as your wallet has a little ETH for gas, the mint goes through.

We recommend keeping a small headroom over the gate: 0.02 ETH or more. Some wallets reserve gas before running the transaction, which can briefly dip your balance under the line and cause a real failure. The Free Mint page's wallet pill tells you exactly which state you're in.

Minimum gate

0.015 ETH

Recommended

0.02 ETH

Recommended wallet

MetaMask

A note on wallet choice. MetaMask handles the free mint most reliably. Some other wallets (Rabby in particular) are stricter about pre-flight simulation and may refuse to broadcast even with sufficient balance — switch to MetaMask if you hit that, or top up further.

Chapter 11 · Shortcuts to every defined term

Glossary

Reshuffle: The on-chain act of re-rolling five trait categories — Eyes, Eyebrows, Mouth, Clothing and Accessory II — when a Citizen is transferred wallet-to-wallet. Reshuffles happen only after the owner-flipped activation switch is on.
Frozen trait: A trait whose upload weight is less than 16. The contract freezes any frozen trait a Citizen mints with — no reshuffle can ever re-roll it. The only way a frozen trait leaves is if its owner deliberately trades it on the Trait Market.
Locked traits: An owner-toggled state that pauses reshuffles for an entire Citizen. Locking and unlocking each cost 0.001 ETH. Reversible at any time — independent of, and additional to, the per-trait frozen-rare protection.
Permanent seed: The on-chain randomness fixed at mint that drives every static (non-reshufflable) trait — Hair, Hair Color, Skin Tone, Facial Hair, Accessory I, Head Shape, Body, Hair Back. These never change for a Citizen.
Reshuffle seed: The on-chain randomness that derives the reshufflable five (Eyes, Eyebrows, Mouth, Clothing, Accessory II) at mint and on every transfer thereafter once reshuffles are active.
Background re-roll: A free owner action that picks a brand-new background color at random, on-chain — the owner can't choose or preview the result. The first re-roll also makes the background a reshuffling slot, so future transfers will re-roll it too.
Trait Market: A peer-to-peer marketplace for trading frozen rare traits between Citizens — same gender only, the receiver needs an empty slot in that category, one-way (the seller's slot goes back to reshuffling), and only the five reshufflable categories can be traded.
Migration bucket: Token IDs 1–8000 — the slots reserved for V1 → V2 migration. A V1 holder claims by burning their V1 to mint the matching V2 ID. IDs whose original V1 token is no longer live are free-mintable.
Raffle bucket: Token IDs 8001–10000 — minted externally via raffles on dropr.fun, not from this dapp. Citizens minted there still appear in collections and behave identically.

Chapter 12

FAQ

What does "fully on-chain" actually mean?

Every Citizen's artwork is drawn as SVG and stored inside the Ethereum contract itself. There's no IPFS link, no image server, no off-chain database. As long as Ethereum exists, your Citizen's picture exists — rendered straight from the chain.

Why would my Citizen's face change when I transfer it?

That's the reshuffle. Reshuffles are switched on by a one-time activation — they may not be live until after the mint window. Once active, every time a Citizen moves to a new wallet, five trait categories (Eyes, Eyebrows, Mouth, Clothing and Accessory II) re-roll into a new combination. When they're on, a Citizen is alive: it changes hands, and it changes face.

If it reshuffles, can I lose a rare trait?

Not to a reshuffle or a transfer. If a Citizen mints with a rare trait, that trait is frozen — no reshuffle can ever re-roll it away, and it carries through every transfer untouched. The only way a rare trait moves is if you choose to move it: the Trait Market lets an owner deliberately trade a frozen trait to another Citizen. Reshuffles can't take it — only you can.

Can I stop my Citizen from changing?

Yes — and you can change your mind. As the owner you can lock all traits, which pauses reshuffles so the current look holds steady. It isn't permanent: unlock anytime to let reshuffles resume. Locking and unlocking each cost the same small fee of 0.001 ETH. You can also re-roll the background color separately.

What are the three ways to get a Citizen?

Claim — if you hold an OCC V1 token, burn it to receive the matching V2 Citizen with the same ID. Free Mint — if you don't hold a V1 and haven't claimed, mint a fresh Citizen (max 2 per wallet). Raffle — IDs 8001–10000 are minted externally on dropr.fun.

Is there a mint price?

No. There is no mint price for Claim or Free Mint — you only ever pay Ethereum gas. "Free to mint" means exactly that.

My wallet says "this transaction might fail" — is something wrong?

No, that's expected and harmless on the Free Mint. The contract has an anti-bot rule that checks your wallet holds at least 0.015 ETH (it's only checked, never spent). That check makes wallets show a cautious warning. As long as you hold a little ETH, the mint goes through.

How much ETH should I have before free-minting?

Hold comfortably more than the 0.015 ETH minimum — we recommend at least 0.02 ETH. Some wallets reserve gas before running the transaction, which can briefly dip your balance under the threshold and cause a real failure. A little headroom avoids that entirely.

Claim your V1 Free Mint Back to the home page