Game Guide

What is Spirit Cards

Spirit Cards is an on-chain world of elemental creatures. A card is not an abstract token but a spirit-character with an element, battle stats and a 'personality' — all derived deterministically from its on-chain seed. You don't buy a picture; you mine a creature.

Each card is rendered from layered art derived from its seed, so the same token always looks identical in the app, in its metadata and in the explorer.

• ▸16 species in Season 1 — 8 universal (Emberback · Ripplefin · Mossroot · Cloudwhisk · Flashbound · Frostpuff · Quicksilver · Moonglimmer) and 8 dragons (Cindermaw · Tidecoil · Rootwaker · Zephyrcrest · Voltrush · Frostmane · Silvervein · Starwisp).
• ▸6 rarity tiers: Common, Rare, Super Rare, Ultra Rare, Secret Rare and Prism (1-of-1). Rarity is read from the top bits of the seed and scales base HP / ATK / DEF.
• ▸4 elements forming a rock–paper–scissors cycle: Ember › Stone › Gale › Tide › Ember.
• ▸A finite supply — at most 8888 cards (maxSupply). Minting and burns only ever reduce what is left.

⚠ A fight's outcome is not guaranteed by stats alone — element, skill and per-battle variance all matter. See Battle.

The Loop

The whole game is a five-node cycle you repeat hundreds of times. There are no hundred-page rule trees: the home screen is one big MINE button, and everything else is a clear section.

挖 MINE  →  熔 MERGE  →  ⚔ BATTLE  →  押 STAKE  →  榜 POINTS  →  repeat

The nodes feed each other: weak cards become merge fuel, stronger cards fight better, winning cards are worth staking, and the pool share encourages another round. Every action also earns points.

Mining (PoW)

You can't buy a card in a shop — you mine it. Mining here is real proof-of-work: your device searches nonces until a hash clears the difficulty threshold. The grind happens off-chain and is free; you only pay gas at the moment of mint.

work = keccak256(chainId ‖ contract ‖ miner ‖ nonce)
valid ⟺ leadingZeroBits(work) ≥ requiredBits()

leadingZeroBits is the count of leading zero bits in the hash. The SpiritCards contract enforces this rule, and the on-chain Mined event carries exactly the same work a CLI miner computes.

Difficulty is fixed for the season and rises only alongside price eras — there is no 'difficulty ratchet', the fast-up / slow-down regulator that killed many earlier projects. Pace is set by the protocol (emission gate + price), not by a hashpower race, so a phone and a farm earn the same reward per card.

With eraSize 1111 and maxSupply 8888 there are ≈8 price eras: the price walks from the first era up to a few dollars in the last one — a soft step, not a doubling.

Chip (ERC-1155): a full-price mint grants one chip; using a chip takes −30% off your next mint and the chip is burned. A discounted mint only spends the chip and grants no new one.

⚠ All of these are Config knobs — the owner can retune difficulty, rate limits and prices without redeploying.

Merge

Merge is the reroll: two weak cards fuse into one stronger card. The world's supply shrinks (deflation), and junk that nobody would buy at mint price becomes a chance at rarity.

• ▸Pick two of your cards (neither may be staked).
• ▸Pay a small merge fee.
• ▸Both cards burn; one new card a tier higher is born (evolution).

The child's seed is decided after inclusion, so you cannot pre-compute a winning pair before the transaction. base = max(rankA, rankB); the child is a weighted pick that can stay the same or, rarely, drop.

⚠ If a merge comes up empty (dud), both cards burn and no new card appears — this is anti-arbitrage protection (it closes the '2×N is always worth less than N+1' loop). Set mergeFailBps = 0 to disable it. Invariants: you can't merge a card with itself, nor a card you don't own or that is staked; the operation is atomic.

Staking (6 tiers)

Staking is the card bank. You lock a card in the StakeVault for a chosen term and receive a share of the pool — a portion of the real fees the game actually collects. Longer locks carry more weight and therefore a bigger share.

t0 is flexible (withdraw any time); t1–t5 are hard locks — the card can't be withdrawn before the term ends. Weight sets what fraction of the pool a card receives relative to every other staked card.

The pool is filled by project fees (a share of mint, merge and pack revenue) and external revenue (duel rake), then distributed proportional to weight inside the StakeVault (accRewardPerWeight). If no cards are staked, inflows accrue and go to the first staker. You can claim at any time without unstaking, and stakeBatch / claimBatch / unstakeBatch move many cards in one transaction.

A staked card can still fight: it never leaves the vault — it is only locked for the duel (lockForBattle), dividends keep accruing, and no NFT approval is needed. If it loses its last life in battle, the vault itself burns it and settles any unclaimed rewards to the staker.

⚠ Honest warning: the pool is tied to real activity. No mints or turnover → no inflows → payouts fall, down to zero. This is a revenue-share of what the project actually earned, not 'interest on a deposit' and not a promise of return. No APY, no percentage returns and no payback dates are published or guaranteed.

Battle

Battle v2 is a staked duel-escrow. Two players each commit one card and an equal stake in ETH; the winner takes the pot minus a rake, and the loser loses one of the card's three lives. Fights are resolved deterministically on-chain, but the outcome is gambling — not simply 'the stronger card always wins'.

Format: you create an open duel with a card + stake; an opponent accepts with their card + the same stake and the fight resolves in that same transaction; you can cancel your own open duel (card and stake return). You cannot accept your own duel. The pot is stake × 2.

Elements

Cycle: Ember › Stone › Gale › Tide › Ember. The winning element deals +20% damage; the losing one deals −20% (typeAdvBps = 2000).

Skills

A card's skill is derived from its seed (skill = (seed >> 208) % 6); the player doesn't control it.

Every attack is multiplied by a random factor in ±40% (atkVarianceBps = 4000). Add ±20% from element plus the skill effects, and the result is genuine variance: roughly equal cards are close to a coin flip, and a card about 25% stronger wins ≈72% of fights — the underdog still wins ≈28%. A clearly stronger card wins almost always.

Honest detail: the exact outcome also depends on the executing block's prevrandao, which the accepter does not know at signing time — so nobody can pick a guaranteed-winning moment. Because the fight is deterministic on-chain, anyone can replay the result off-chain from the card seeds, the stake and prevrandao.

Lives: each card has 3 lives. The loser loses one life; the winner takes the pot minus rake and gains +1 on its win counter. A card with 0 lives burns (a real supply sink), and every card keeps a win/loss history as its provenance.

The rake is 10% of the pot (pvpRakeBps = 1000). It is external revenue (not from mints), so duels feed the dividend pool. A duel is a zero-sum game between players plus the rake — not a pyramid.

⚠ Battle is a zero-sum gambling mechanic (plus rake): you can lose both money and cards. No income is guaranteed.

Packs

Packs are buying a bundle of cards at a discount. The Packs contract mints N real cards to the buyer — normal token ids, normal rarity, normal rights. Buying a pack bypasses PoW, the epoch cap and the cooldown, because that is the product.

Pack price = size × (currentPrice() × 2) − volume discount (packPriceBps = 20000): a pack skips proof-of-work, so each card costs ×2 the mint price minus the size discount. Revenue flows through the same shared split as every other fee (pool 60 / referral 10 / treasury 30 / reserve 0). Each card comes out of the 8888 max supply with rarity derived from its seed.

The contract keeps a pity counter for the buyer, and the public pull rates for rarities are disclosed on the dashboard.

⚠ A pack does not guarantee a specific card or a payback; a card's value is set by the market (secondary sales), not by the project. No income is guaranteed.

Points

Points are on-chain activity points plus a leaderboard. The game rewards activity — mining, merging, staking and PvP wins — and that competition is the retention engine.

Points are credited by authorised modules (SpiritCards, StakeVault, Battle) through the Points contract and stored on-chain as points[address]; the leaderboard reads the same contract. Seasons are off-chain (by snapshot). The contract emits PointsAdded(user, amount, reason), so activity is verifiable.

⚠ Points have no monetary value and are not exchangeable for money — they are a gameplay metric. Season rewards are skins or unique items, not money. A new season resets only the leaderboard; your collection never rotates out of the game.

Economy & Referral

Spirit Cards is a game; its money layer is built on the real fees the project actually collects. There is no guaranteed yield and no 'deposit at interest'. Everything distributed is a share of collected fees.

Every project fee is split by these fixed shares (they can be retuned via setSplit, but must always sum to 100%). Royalties (5%, ERC-2981) go to the treasury, not the pool, and come from secondary sales on OpenSea.

Referral: an invite is a percentage of the invitee's activity, not of their deposit. A player sets a referrer once, and the referrer must have mined at least once. From the 10% referral fund, 3% of the gross payment goes to the master referrer (a fixed top-level referrer for every payer) and 7% goes to the payer's own referrer. If a payer has no referrer, that 7% stays in the undistributed fund. Amounts credited to referrers are protected and cannot be withdrawn by the owner as 'leftover'.

The pool is filled by: 60% of mint fees, 60% of merge fees, 60% of pack revenue, 30% of the duel rake, and (planned) external sponsorship. Royalties do not go to the pool. A permissionless pumpPool() moves the accumulated pool into the StakeVault as dividends — anyone can call it, and the funds always go to the vault, never to the caller.

⚠ Honest math: the pool share is tied to activity — no fees means no inflows and payouts fall to zero. There are no APY figures, no percentage returns and no payback dates. There is no 'interest on a deposit' — referral is paid on activity only, and there is no manual floor-push or wash volume.

Chain & Contracts

Spirit Cards deploys on Robinhood Chain, an Arbitrum Orbit L2, with gas paid in ETH. chainId 4663.

The core contracts are Config, SpiritCards, ChipToken (ERC-1155 chip), StakeVault, Battle, Points and Packs. Ownership moves to a multi-signature Safe (and later a timelock); every economic parameter is a Config knob, changeable without redeployment.

Trading happens on OpenSea, the marketplace native to the chain. There is no ERC-20 token and no LP — the project does not use Uniswap.

⚠ Contract addresses are maintained in the project's ops/ADDRESSES.md and are updated whenever the stack is redeployed. Treat that file as the single source of truth; we deliberately do not hard-code addresses in this guide, since they change.