Whitepaper

Thirteen contracts, six libraries, no proxies. The dependency graph is a strict DAG: lower-level contracts know nothing about higher-level callers. Every contract is deployed at a deterministic address derived from the deployer's nonce, except BitCardsHook which is mined via CREATE2 to satisfy Uniswap v4's permission-bit address constraint (0x0EC0).

CardsToken (ERC-20)
  ↓
BitCards (ERC-721) ← CardArt (lib) ← Palette (lib) ← SVGFont (lib)
  ↓
CardPacks ← Abilities (lib)
  ↓
Expedition ← Combat (lib)
  ↓
Tournament ← BitCardsCore
  ↓
BitCardsHook (Uniswap v4) ← HookMiner (lib)
  ↓
Treasury

Every byte of color in the entire system goes through one of Palette's 32 named indices. Every glyph in the bitmap-font name plate goes through SVGFont. Every card stat-table lookup goes through CardPacks._archetypeStats. The system has no escape hatches.

Combat.resolveMatch(deck1, deck2) is a pure function. Given two 8-card decks, it deterministically returns the winner address, the turn count, and a finalState bytes blob (the per-slot HP at end of match).

1. Sort each deck ascending by cost (initiative).
2. While any unit alive on both sides AND turn < MAX_TURNS:
     for slot in 0..7:
       if attacker[slot] alive AND defender[slot] alive:
         apply pre-attack abilities (QUICK, HEAVY)
         damage = attacker.atk × multiplier
         apply defender abilities (SHIELD reduces, MIRROR reflects)
         defender[slot].hp -= damage
         apply post-hit abilities (DRAIN heals attacker, BURN sets dot)
         if defender[slot].hp ≤ 0:
           apply death abilities (SACRIFICE, GENESIS revive)
     swap roles, increment turn
3. Survivor count determines winner; tie → defender.

Same inputs always give the same outputs. The test suite runs 100 matchups twice and asserts identical winners every time. See test/Combat.t.sol.

BitCardsHook implements IHooks directly (no BaseHook inheritance). It registers permission bits 0x0EC0:

uint160 PERMISSIONS =
    BEFORE_ADD_LIQUIDITY_FLAG  // 0x0800
  | AFTER_ADD_LIQUIDITY_FLAG   // 0x0400
  | BEFORE_REMOVE_LIQUIDITY_FLAG // 0x0200
  | BEFORE_SWAP_FLAG           // 0x0080
  | AFTER_SWAP_FLAG;           // 0x0040
                              // = 0x0EC0

The hook address must have these bits in its low 14 bits. We mine a CREATE2 salt using HookMiner.find until the resulting address satisfies the constraint. The salt is computed at deploy time and is verifiable from the address.

On every afterSwap, the hook compares the current $CARDS/ETH price tick against a running 24h average. The delta determines a 5-state mood: BULL_RUN / ACCUMULATION / SIDEWAYS / DIP / CAPITULATION. The mood is written to BitCardsCore.mood, which gates expedition rewards and pack rare-rates.

CardsToken is a standard ERC-20 with ERC20Permit. The constructor mints exactly 21,000,000 tokens to the deployer. There is no mint() function. CardsToken.totalSupply() is constant.

Pack costs are denominated in $CARDS:

• Genesis pack: 100 $CARDS · 5 cards · weighted Common-heavy
• Halving pack: 500 $CARDS · 5 cards · 1 guaranteed Rare+
• Whale pack: 2,500 $CARDS · 5 cards · 1 guaranteed Epic+, 5% Mythic chance

Pack revenue routes through Treasury with a 50/25/15/10 split: LP rewards / tournament prize pool / week-1 airdrop / Genesis Card holders.

Bitcoin halves block rewards every 210,000 blocks. We do too.

function rewardForEpoch(uint256 epoch) pure returns (uint256) {
    if (epoch >= 64) return 0;          // saturates after 64 halvings
    return INITIAL_BASE_REWARD >> epoch;
}

At ~12s per Ethereum block, 210k blocks ≈ 29 days. After epoch 64 (~5.1 years), the right shift saturates and the base reward becomes zero. By that point, treasury reserves built up from pack sales fund tournament prize pools indefinitely.

What the protocol defends against:

• Pack roll manipulation: block.prevrandao is the only randomness. A miner can withhold blocks but cannot rewrite past blocks. Worst case: a miner sees their roll outcome and decides not to publish, forfeiting the block reward (~$700) for a single pack.
• Combat outcome lying: impossible. Combat.resolveMatch is pure; any client computes the same answer from the same decks.
• Hook front-running: the mood update happens in the same swap transaction as the trade. There's no MEV opportunity to predict the mood before it's set.
• Tournament bracket manipulation: bracket positions are deterministically derived from keccak256(tour_id, entrant_addresses_sorted). Any change to the entrant set re-shuffles the bracket.

Etherscan addresses (post-deploy):

Source code is published verbatim to Etherscan. Bytecode hashes match contracts/out/*.json in the repo.