Unigen Genesis

The user opens the public Uniswap app (we don't deploy our own router) and swaps ETH for $UGEN against the V4 pool that's wired with our hook. Any amount is accepted by the pool itself; the NFT mint only triggers if the trade clears the minBuyEth threshold.

Frontend default input

0.001 ETH

Mint threshold — Sepolia

0.01 ETH

Mint threshold — Mainnet

0.1 ETH

Buys above threshold

Mint 1 NFT to buyer

Buys below threshold

Get UGEN only, no NFT

UGEN sells

Never mint an NFT (one-way)

Uniswap V4 calls our hook's afterSwap() callback. Inside, the hook:

1. Reads the swap direction — confirms it's ETH→UGEN (a buy)
2. Reads amountIn(ETH) from the V4 BalanceDelta
3. If below minBuyEth → returns silently. No mint, no revert.
4. If UgenNFT.totalSupply() ≥ MAX_SUPPLY → returns silently. Collection is closed.
5. Otherwise → proceeds to the mint logic below

In Uniswap V4, the msg.sender inside afterSwap is the router, not the actual buyer. To know who gets the NFT, the buyer address must travel through hookData — an arbitrary bytes payload that the router appends to the swap call.

// Inside the public Uniswap router (or our SwapTest harness):
poolManager.swap(
    poolKey,
    swapParams,
    abi.encode(buyer)  // <-- hookData
);

// Inside UnigenHook._afterSwap:
address buyer = abi.decode(hookData, (address));

The public Uniswap app encodes the connected wallet here automatically when interacting with a hooked pool. If a router forgets to pass hookData, the hook silently no-ops (no NFT minted) — never reverts the swap.

The hook calls UgenNFT.mintNext(buyer, seed). The NFT contract uses a deterministic seeded RNG to pick a rarity tier. The seed comes from block.prevrandao + buyer address + an internal counter — same inputs always produce the same outputs (auditable, non-grindable post-tx).

Wallet-age boost: if the buyer has called registerAge() with a valid Merkle proof, their assigned tier (S/A/B/C) subtracts basis points from the rolled rng before tier matching. Lower rng = rarer tier.

Tier S — boost

−4000 bps (−40 percentage points)

Tier A — boost

−2000 bps

Tier B — boost

−800 bps

Tier C — boost

−200 bps

Not registered

0 bps (raw rng)

Example: rolled rng = 1200 (raw). Buyer is registered tier-S. Adjusted rng = 1200 − 4000 = −2800, clamped to 0 → falls into the Mythic bucket. A non-registered buyer with the same roll lands in Epic.

If the rolled tier is exhausted (all 2 Mythics already minted, say), the contract walks down to the next available tier: Mythic → Legendary → Epic → Rare → Uncommon → Common.

Important: the walk is always downward, never upward. A tier-S buyer can't accidentally mint a Common because Mythic is empty — they get a Legendary instead. Only if every tier above Common is empty would they roll Common.

200 unigens total. Bumped from the original 100 to 200 on 2026-05-08 (Raph's commit 2124281) with proportional tier rebalancing.

The 200 unigens are split across 6 rarity tiers using a linear ranking strategy ("Option A" per PR #8):

tokenId 1 = Mythic, tokenId 200 = Common. The numbering is inverted to match the rarity ranking: lower IDs are rarer. This was committed in 882ee01 (2026-05-11).

1 – 2

Mythic (Ascended, Origin)

3 – 10

Legendary

11 – 30

Epic

31 – 70

Rare

71 – 130

Uncommon

131 – 200

Common

Each tokenId has a fixed JSON metadata file pinned on IPFS (via Pinata). The metadata declares the unigen's name, concept, trait breakdown, and IPFS image URL.

{
  "name": "Unigen Genesis #1 — Ascended",
  "description": "The first soul. Mythic tier.",
  "image": "ipfs://IMAGE_CID/1.png",
  "attributes": [
    { "trait_type": "Rarity", "value": "Mythic" },
    { "trait_type": "Power",  "value": 950 },
    { "trait_type": "Concept", "value": "Ascended" }
  ]
}

The UgenNFT.baseURI is set to ipfs://METADATA_CID/ once at deploy. tokenURI(id) returns ipfs://METADATA_CID/{id}.json. The base URI can be frozen via freezeBaseURI() (owner-only, one-way) to make the metadata immutable post-mint.

We compute a Merkle tree from the historical Ethereum genesis wallet snapshot (contracts/ethereum_genesis_wallets.csv). The current root is:

0x87110017b88c3c9be357f4bdc66689035edbee95c87d7110ab18919a7efc7336

The full proof JSON is generated locally with script/snapshot/build-merkle.js and served on-demand. The on-chain contract only stores the root.

The snapshot maps each eligible address to one of four tiers:

S — Genesis allocation wallet

Touched ETH in the first 12 months

A

Active before block 4M (mid 2017)

B

Active before block 8M (early 2019)

C

Active before block 12M (mid 2021)

Not eligible

Outside snapshot; 0 boost

1. User connects wallet
2. Frontend fetches the user's proof from a public JSON endpoint (or static asset)
3. If found, frontend shows a "Register Genesis boost" CTA
4. User signs UgenNFT.registerAge(tier, proof[]) — costs gas only
5. On-chain stores ageTierOf[wallet] = tier permanently
6. All future mints from this wallet get the corresponding bps reduction

The rng → tier table (assumes already age-adjusted):

rng < 100

Mythic (1%)

rng < 500

Legendary (4%)

rng < 1500

Epic (10%)

rng < 3500

Rare (20%)

rng < 6500

Uncommon (30%)

rng ≥ 6500

Common (35%)

Out of 10,000 cumulative bps. A tier-S buyer drops their rng by 4,000 before this table is consulted — pushing their effective odds way up the curve.

The owner of an NFT must first approve(arena, tokenId) or setApprovalForAll(arena, true). Then call:

GenesisArena.enterCombat(tokenId)

This locks the NFT as the wallet's active fighter. Each wallet can have at most one active fighter at a time.

A challenger picks one of their owned NFTs and calls:

GenesisArena.challenge(myTokenId, defenderAddress)

The defender must have an active fighter. The combat resolves instantly in the same transaction.

Combat is a probability roll weighted by each fighter's effective power:

effectivePower(token) = baseRarityPower(token) * ageMultiplierBps(owner) / 10_000

attackerOdds = effectivePower(attackerToken) / (effectivePower(attackerToken) + effectivePower(defenderToken))

rng = uint256(keccak256(blockhash, attackerToken, defenderToken)) % 10_000
attackerWins = rng < (attackerOdds * 10_000)

Outcome is emitted via the CombatResolved event.

The wallet-age boost doesn't just bias mints — it also boosts your combat power.

S-tier owner

× 1.40 (14000 bps)

A-tier owner

× 1.20

B-tier owner

× 1.10

C-tier owner

× 1.05

No registration

× 1.00 (raw power)

The multiplier follows the current owner of the token, not the minter. Transfer an NFT to a tier-S wallet, it gets the boost immediately.

After any combat (win or lose), both NFTs enter a 6-hour cooldown. They can't fight again until cooldownUntil(tokenId) ≤ block.timestamp. Cooldown is per-token, not per-wallet — you can fight your other unigens while one is cooling down.

When a combat resolves, the loser's NFT is transferFrom(loser, winner, loserTokenId). Permanent. No undo, no escrow grace period.

Sepolia

0xae327FAefD77535dF15035da7a0bFdBe6cde7EF2

Type

Fixed-supply ERC-20

Total supply

1,000,000,000 UGEN

Decimals

18

Sepolia

0xcD78d11c83d1BB7A7c1D98EEABDFF9Ef0CCD2D8f

MAX_SUPPLY

200

Mint authority

UnigenHook only

Base URI

ipfs://METADATA_CID/

Key read functions:

totalSupply() → uint256
balanceOf(address) → uint256
ownerOf(uint256 tokenId) → address
tokenOfOwnerByIndex(address, uint256) → uint256
tokenURI(uint256) → string
rarityOf(uint256) → uint8 (0..5)
powerOf(uint256) → uint16
mintedAtOf(uint256) → uint40
remainingPerTier(uint8) → uint16
ageTierOf(address) → uint8
ageRegistered(address) → bool

Key writes (user-facing):

registerAge(uint8 tier, bytes32[] proof)

Sepolia

0x83087fF09622c9081959241293976112c32690c0

Permissions

afterInitialize, beforeSwap, afterSwap

minBuyEth

Immutable, set at deploy

LP fee defaults

DEFAULT_LP_FEE = 10000 bps (1%)

Tier-S fee override

TIER_S_FEE = 100 bps (0.01%)

The hook is constructed with the minBuyEth param. Passing 0 defaults to 0.1 ether. Sepolia was deployed with 0.01 ether for cheaper testing.

Sepolia

0x2B67013Fe769E2FFAe3107a6b53377c93E9774D7

Cooldown

6 hours

Active fighter limit

1 per wallet

enterCombat(uint256 tokenId)
challenge(uint256 myTokenId, address defender)
activeTokenOf(address) → uint256
cooldownUntil(uint256) → uint40
ageMultiplierBps(address) → uint16

Sepolia

0xD2E9D13f04D70D2Fab34afc58332B94ea3AbdC88

Reward token

UGEN

Default duration

30 days per season

currentSeasonId() → uint256
seasons(uint256 id) → Season struct
claimedTokenInSeason(uint256 seasonId, uint256 tokenId) → bool
claimRewards(uint256 seasonId, uint256[] tokenIds)

Owner-only: startSeason, endSeason.