NFT War Whitepaper

1. Overview and Vision

1.1 Project Positioning

NFT War is a fully on-chain NFT battle protocol deployed on Ethereum L2 (currently Base). Users deposit ERC721 or ERC1155 NFTs into the protocol and pay a small on-chain fee to enter the “battle pool.” Other users can then choose a specific opponent or have the system randomly match an opponent from the same pool to start a battle. Each battle’s outcome is determined by on-chain verifiable randomness: the winner receives the loser’s NFT and protocol token rewards, and the loser receives a proportional token consolation. The protocol does not rely on a centralized server to decide results; all state and asset changes are recorded on-chain for transparency and auditability.

1.2 Core Features

• Fully on-chain execution: Listing, matching, randomness requests, settlement, reward distribution, and jackpot draws are all performed inside smart contracts.

• Tier-isolated matching: Each NFT collection has a default Tier (1–5) in the protocol; matching occurs only within the same collection and same Tier pool, ensuring both sides fight at the same power level.

• Verifiable randomness: Outcomes use Pyth Entropy for off-chain randomness, written on-chain via contract callbacks; users and third parties can verify the source and consistency of results.

• Multiple earning streams: Beyond per-battle win/loss rewards, the protocol integrates referral commissions, periodic jackpot draws, and daily check-in chests (Token rewards by tier based on daily wins); holders of the official Void Knights NFT also receive battle reward bonuses and battle fee discounts.

1.3 Target Chain and Ecosystem

The protocol is deployed on Base to reduce gas costs and improve responsiveness. It supports protocol-owned assets (NFTWar Token, WarChip, Void Knights) and third-party NFT collections configured via governance/whitelist, enabling more partnerships and Tier configurations.

---

2. Mechanism Design

2.1 Listing

To make your NFT available as an opponent that others can challenge, you must list it first:

1. Eligibility: When the protocol enforces whitelist mode, the NFT’s collection must be configured in the contract (whitelist, default Tier, floor price, etc.). When not enforced, any compatible collection is allowed.

2. Action: The user approves the protocol to transfer their NFT (one ERC721 or a quantity of a given ERC1155 tokenId) and pays the listing fee (listingFee, set in the contract, e.g. 0.00001 ETH). Single or batch listing is supported (fees scale with quantity in batch).

3. Pooling: After the NFT is transferred to the contract, it is placed in the pool by “collection + Tier”; a user can have multiple listings to be chosen as an opponent or matched randomly.

Users can cancel a listing at any time to withdraw their NFT, unless that NFT is already locked in an ongoing battle (see below).

2.2 Battle

Battle flow:

1. Initiation: The user selects an NFT they own that is compatible with the target pool (same collection as the opponent), and either picks a “specific opponent” (a listing) or “random match.” The system resolves the opponent within the “same collection + same Tier” pool; for random match, it selects a non-self listing from that pool using a random seed.

2. Fees: The initiator pays:

   • Battle base fee (battleBaseFee);

   • Optionally, a battle fee as a percentage of the collection floor (battleFeePercent, may be 0);

   • Pyth Entropy fee (set by the randomness service);

   • Optionally, jackpot fee (jackpotFee) if jackpot is enabled and the user opts in.

   • Void Knights holders get a battle fee discount (stacked by holding count, capped); this applies only to battle-related fees, not Entropy or jackpot fees.

3. Escrow and randomness request: The initiator’s NFT is transferred to the contract; the contract requests one random number from Pyth Entropy and records the battle request (initiator, NFT, opponent listing ID).

4. Async settlement: When Pyth calls back, the contract uses the returned randomness to determine the winner (e.g. 50/50 or as configured). The winner receives: the opponent’s NFT + protocol token rewards; the loser receives consolation tokens. If either side has a bound referrer, the referrer gets a share of tokens. If a token transfer fails, rewards are recorded as “pending” for the user to claim later.

5. Timeout and exceptions: If the Pyth callback is not received within the set time (e.g. 24 hours), the initiator can request a timeout refund to recover their NFT; the opponent’s NFT is returned to the opponent. The contract may also allow an admin to rescue stuck assets in edge cases.

Thus, a single battle from “initiate → randomness callback → settle” is fully on-chain and does not depend on off-chain referees.

2.3 Rewards and Distribution

• Winner/loser base rewards: Configured in the contract as winnerRewardAmount and loserRewardAmount (e.g. 1500 / 750 NFTWar Token units) to the winner and loser.

• Void Knights bonus: Holders receive an extra percentage on battle token rewards (win/loss) based on holding count, with a cap (e.g. 20% per NFT, 200% total); this affects only protocol token rewards, not NFT ownership.

• Referrers: Users can bind to a referrer (by referrer ID or short link); after binding, each time the user battles, the referrer receives a proportion (e.g. 10%) of the battle rewards in tokens. The binding is typically immutable (see contract).

Any token rewards that cannot be transferred at settlement (e.g. token contract paused) go to “pending” balance; users can claim them later via the claim function.

2.4 Jackpot

The jackpot is implemented in a separate contract (e.g. NFTWarJackpot), decoupled from the main battle contract:

• Participation: Users can pay an extra jackpot fee (jackpotFee) when battling to enter the current jackpot period (one “ticket” or participation per fee, per contract).

• Period: The jackpot runs in time periods (e.g. 24 hours); each period ends with one draw.

• Draw: The main contract supplies a random seed (from Pyth Entropy, etc.); the jackpot contract uses it to randomly select winner(s) from that period’s participants. Example allocation: a large share (e.g. 60%) to one main winner, a share (e.g. 30%) to runners-up, and a small share (e.g. 1%) to protocol/ops; see deployed contract for exact split.

• Claim: Winning ETH is credited to the user’s “pending” balance in the jackpot contract; the user must call the jackpot contract’s withdraw function to receive it.

Jackpot is separate from battle settlement: win/loss and NFT ownership are unaffected by whether the user joined the jackpot; the jackpot only determines extra ETH payouts.

2.5 Daily Check-In

Daily check-in is implemented in a separate contract (e.g. DailyCheckIn), granting Token rewards by tier based on “daily win count”:

• Tiers and conditions: Check-in has multiple tiers (e.g. 0–5). Tier 0 may require no daily wins for a base reward; tiers 1–5 require 1, 5, 10, 20, 30 daily wins, etc. (per contract). Each tier can be claimed once per day.

• Reward formula: Each tier has a multiplier; final reward = base random range (minReward–maxReward) × tier multiplier; Void Knights holders get an extra percentage on top.

• Fee: Users pay a small ETH check-in fee (checkInFee) to cover contract and ops costs.

Check-in rewards are paid in the protocol token (NFTWar Token); if the contract has insufficient balance or transfer fails, behavior is as defined by the contract (e.g. partial send or pending).

---

3. Assets and Roles

3.1 NFTWar Token

The protocol’s general reward token for battle outcomes, referral payouts, daily check-in, etc. The token address is set at deployment and cannot be changed. If a reward transfer fails, it is recorded as “pending Token” in the protocol contract; users can claim via the dedicated method. Token supply, distribution, and secondary markets are announced separately by the project.

3.2 Void Knights (VK)

Official ERC721 NFT, max supply 10,000. Minted via whitelist or designated channels. Protocol benefits:

• Battle reward bonus: Holders get an extra percentage on battle token rewards (capped).

• Battle fee discount: Holders get a discount on battle-related fees (stacked by count, capped).

• Check-in bonus: In the daily check-in contract, holders get an extra percentage on check-in rewards.

Exact percentages and caps are set in the contracts and can be queried on-chain.

3.3 WarChip

Official ERC1155 asset; Token IDs 1–5 correspond to different Tiers with set mint prices (e.g. 0.0001 ETH to 1 ETH). Users pay ETH to mint the desired Tier; some versions support burn-and-redeem for ETH. WarChip can be listed and used in battles as one of the supported collections, allowing users without other NFTs to participate quickly.

3.4 User Types and Referrals

• Regular players: List NFTs, start battles, claim rewards, join jackpot and check-in.

• Referrers: Invite new users via referral link or ID; when invitees battle, the referrer earns a share of tokens (does not reduce invitee rewards).

• Protocol: Earns ETH from listing fees, battle fees, jackpot share, check-in fees, etc., for ops and development; token rewards are paid from pre-funded or topped-up contract balances.

---

4. Technical Notes

4.1 Randomness

Battle results and jackpot draws depend on unpredictable randomness. The protocol uses Pyth Entropy V2: the contract pays a fee and submits a user-side random factor; the off-chain service generates randomness and writes it on-chain via an authorized callback; the contract completes the battle settlement or supplies the jackpot seed in that callback. This design ensures no single party can control the outcome, and results are verifiable by anyone.

4.2 Security and Risk Control

• Contracts use ReentrancyGuard, Pausable, Ownable and similar patterns to reduce reentrancy and unauthorized access.

• If a battle does not receive a randomness callback in time, users can request a timeout refund to recover their NFT; the opponent’s NFT is returned to the opponent to avoid long-term locking.

• In extreme cases, an admin can rescue stuck battle requests and return NFTs to a designated address, per contract permissions and events.

4.3 Pool Isolation and Matching

Matching is strictly isolated by “collection + Tier”: only listings in the same collection and tier share a pool; random matching picks only from that pool and never matches the user to themselves. This keeps both sides at the same “level” and avoids cross-collection or cross-tier mismatches.

---

5. Economics and Parameters

5.1 $NFTWAR Token Supply and Allocation

$NFTWAR is the protocol’s general reward token. Total supply: 10 billion (10,000,000,000). Allocation:

Use	Share	Description
Airdrop	30%	Airdrop to NFT veterans and early users
Game reward pool	40%	In-game rewards: battles, referrals, check-in, etc.
Team, marketing, liquidity	30%	Team incentives, marketing, and liquidity

Release schedule and rules are subject to official announcements.

5.2 Fees and Reward Parameters

The following are parameter categories; exact values are set in the contracts and official announcements; this whitepaper only describes structure:

• Fees: listingFee, battleBaseFee, refreshFee, battleFeePercent, jackpotFee, checkInFee, and Pyth Entropy per-request fee.

• Rewards: Winner/loser base token amounts, referrer share, Void Knights battle bonus and discount per-NFT % and caps, check-in tier multipliers and VK check-in bonus.

• Jackpot: Draw interval (e.g. 24 hours), allocation (main/runners-up/protocol), max participants per period, etc.

All adjustable parameters are managed by the contract owner or governance; changes are disclosed via events and announcements. Token allocation and release follow Section 5.1 and official disclosures.

---

6. Risks and Disclaimer

• Smart contract risk: Despite design and audits, contracts may have bugs or unforeseen behavior leading to loss of assets. Participation is at your own risk.

• Randomness dependency: Results depend on third-party services such as Pyth; outages or delays may cause delayed settlement or reliance on timeout/rescue mechanisms.

• Market and liquidity: Protocol token and NFT prices and liquidity are market-driven; the protocol does not promise any return or guarantee.

• Compliance: Users must ensure that their participation complies with the laws of their jurisdiction; the protocol does not provide legal or investment advice.

By participating, you acknowledge that you have read and understood the above mechanics and risks and accept responsibility. Terms are as set out on the protocol’s official site and on-chain contracts.