Introduction

KICKAIFM is a fully on-chain competitive football manager where every player in your squad is powered by an AI brain. You build a team of 11 AI agents, train them, set tactics, upgrade your club's infrastructure, and compete in real $KICK-staked matches against other managers.

Unlike traditional football games, no outcomes are scripted. Matches are simulated deterministically server-side using each player's real trained stats, your tactical configuration, and a cryptographic seed — and the result is settled on-chain by the KICKAIFM oracle. Everything from player growth to prize distributions is governed by transparent smart contracts on BASE.

Key Numbers

Live on BASE

• •Network: BASE
• •Smart contracts: Solidity
• •Token standard: ERC-20
• •Wallet: any EVM wallet (MetaMask, Coinbase Wallet, WalletConnect…)

Architecture

KICKAIFM is split into three repositories that communicate through a strict trust boundary: the BASE smart contracts are the source of truth for all economic and match settlement; the backend runs the AI Agents engines that produce the match simulation and submits results via the oracle; the frontend is a read-mostly interface that never touches raw private keys except through the user's wallet adapter.

Request Flow

User Wallet
  │
  ├─▶ Next.js
  │     └─▶ REST API (Express)          — JWT auth via wallet signature
  │           ├─▶ Prisma DB             — read/write player/team state
  │           ├─▶ Training Engine       — XP calc, move unlocks, injury check
  │           └─▶ Oracle Service        — signs & submits contract transactions
  │
  └─▶ Solidity Contracts
        ├─ trainCollective()           — transfer $KICK + ETH, record stats
        ├─ resolveInjuryCheck()       — oracle-only, sets injuryUntil
        ├─ createMatchChallenge()     — escrow half prize pool
        ├─ acceptMatchChallenge()     — escrow opponent half, commit formation
        ├─ settleMatch()              — oracle-only, distribute winnings
        └─ claimRewards()             — distribute $KICK from emission share

Data Layers

Player Brain

Every one of your 11 players is an autonomous AI agent parameterised by a set of persistent on-chain stats. These stats directly influence every decision the match simulation engine makes on behalf of that player — from triggering a shot to winning a tackle. There is no hidden RNG bonus: better stats = higher probability of success.

Skill Attributes

Player Roles

Each player has a PlayerRole that describes their behavioural archetype. Roles influence how stats are weighted during match decisions — a Poacher prioritises Shooting while a Playmaker leans on Passing and Decision.

Positions

Players are placed on the pitch according to their Position enum, mapped to normalised (x, z) coordinates defined per formation. Their initial coordinates are determined by formation and they drift toward goal or back into shape depending on possession and tactical settings.

XP & Diminishing Returns

Every training session grants XP. Raw XP is converted into skill points using a diminishing- returns formula: the more total XP a player has accumulated, the smaller the increment from each new session. This prevents pay-to-win scenarios where short-term grinding becomes exponentially effective — elite players require sustained investment.

The on-chain training instruction applies a diminishing-returns multiplier to raw XP: the multiplier starts at 1.0 for a fresh player and gradually floors at 10% as total accumulated XP grows. This ensures early gains are fast but elite players require sustained long-term investment — exact thresholds are not published.

Move Library (64-bit Bitmask)

Each player has a move_library: u64 — a 64-position bitmask where each bit represents an unlockable special move. Moves are unlocked automatically by the training engine when a player meets the required skill threshold and session count. Unlocked moves are factored into match simulation to trigger special animations and grant small probability bonuses.

Fatigue & Morale

fatigue accumulates with each training session — intensity × 10 points. Fatigue over a threshold blocks further training. It recovers passively at 5 + (facilities_tier × 3) points per hour. Higher Facilities tier dramatically accelerates recovery.

morale (0–100) is initialised at 80 and influenced by match outcomes and training consistency. High morale results in a slight up-tick to decision-making quality during matches.

Team Brain

Beyond individual skill, a football squad is more than the sum of its parts. KICKAIFM models collective intelligence via the chemistry stat (0–100) and a set of unlockable team behaviours called collective drills. Chemistry is the team's shared neural glue — it amplifies every player's effective stats during match simulation.

Chemistry (0–100)

Chemistry is stored per team on-chain. It is:

In match simulation, chemistry acts as a shared team modifier. It is mixed with each defender's defense stat when calculating defensive strength against shots:

During shot resolution, the engine combines the defender's defense stat with the team's chemistry score to produce a composite defensive strength value. Higher chemistry meaningfully raises the bar for attackers to score.

Collective Drills

Running a collective training session costs $KICK plus a small ETH fee, requires the on-chain cooldown window, and currently uses Fitness, Technical, or Chemistry drills. These sessions update selected players or team chemistry and feed the collective move unlock system in the move library bitmask.

Formation Commitment (Commit-Reveal)

When you create or accept a match challenge, you submit a hash of your formation using the match contract address, chain id, match id, wallet address, side flag, formation code, and a 32-byte salt. The actual formation is only revealed after both sides have committed, preventing opponents from counter-picking. The smart contract verifies the hash on-chain when you call revealFormation(matchId, formation, salt).

bytes32 computed = keccak256(
  abi.encode(
    address(this),
    block.chainid,
    matchId,
    msg.sender,
    isChallenger,
    formation,
    salt
  )
);
require(computed == expectedHash, "Invalid formation reveal");

Training System

Training is the primary way to grow your squad. Players improve through individual sessions targeting a specific skill, collective squad sessions that raise stats or chemistry, and tactical scenario training that teaches decision patterns. Training spends $KICK and may include a small ETH fee depending on the on-chain action; upgrade payments are the main $KICK burn path.

Individual Training

You choose a SkillTarget (one of the 7 skills) and an intensity level. The training engine calculates:

// 1. Base XP = session weight × facilities multiplier
const base_xp = BASE_SESSION_XP * session_intensity + (facilities_tier * FACILITIES_XP_BONUS);

// 2. Apply diminishing returns
const xp_gain = calculate_xp_gain(base_xp, player.total_xp);

// 3. Convert XP to skill points (capped at MAX_SKILL = 99)
const xp8 = Math.min(Math.floor(xp / 100), 255);
player[skillTarget] = Math.min(99, player[skillTarget] + xp8);

// 4. Accumulate total XP
player.total_xp += xp_gain;

// 5. Raise fatigue
player.fatigue = Math.min(MAX_FATIGUE, player.fatigue + intensity * 10);

Facilities Bonus

Upgrading your Facilities asset tier gives a multiplicative XP bonus per training session. Higher facilities also reduce injury risk and accelerate fatigue recovery. This makes Facilities the most direct multiplier on player development speed.

Collective Training

Any owner can run a collective training session once per cooldown window. All 11 players participate; the session raises team.chemistry and contributes toward unlocking team moves in every player's move library.

Tactical Scenario Training

Tactical scenarios are built in the Tactics view by placing players and the ball, adding action steps, then training the saved scenario. Scenario training transfers $KICK directly to treasury and can be amplified in one transaction.

Injury System

After every individual training session, a pending injury check is flagged on the player account (pending_injury_check = true). The oracle resolves this server-side using a deterministic hash of a server-generated entropy value and the player ID.

Injury probability scales with the player's current fatigue and the session intensity; higher Facilities tier significantly reduces the chance. When an injury triggers, severity is classified as Minor (days), Moderate (up to ~10 days), or Severe (up to ~30 days) — determined deterministically by the oracle. Exact thresholds are internal to the oracle service.

An injured player (injury_until > block.timestamp) cannot be selected for training. They can still appear in match squads but with heavily reduced effective stats in the simulation engine.

Move Unlock Triggers

After every training session the backend runs checkMoveUnlocks() against the updated player snapshot. Any move whose skill threshold and session-count requirements are now met is automatically added to the player's move_library bitmask and persisted to the DB. Move unlocks are shown as real-time notifications in the UI.

Tactics & Player Decisions

The match simulation engine is a deterministic, seed-driven agent loop. Every tick (1 simulated second) each player acts according to their stats and the team's tactical configuration. There is no human intervention mid-match; formations are committed on-chain before the game, while trained tactical scenarios inform the backend AI engine.

Tactical Configuration

Formations

Formation positions are mapped as normalised (x, z) coordinate pairs. The engine places all 11 players at their formation positions at kickoff and half-time, then each player drifts toward attack or defence based on possession and tick-level logic.

Tick-Level Decision Loop

Each of the 5,400 ticks runs the following decision pipeline: possession is tracked per-player, defenders close down the ball carrier, tackle and shot checks are resolved using each player's stats combined with the team's tactical configuration, and stamina decays gradually throughout the match. The exact coefficients and thresholds are internal to the simulation engine and not published to prevent exploitation.

How Stats Influence Decisions

Individual vs Team Intelligence

Individual stats determine micro-level outcomes: will this shoulder-barge succeed? Will this shot beat the keeper? Team chemistry and collective drills determine the macro shape: Does the midfield press as a unit? Do wingers time their overlapping runs? A squad of individually mediocre players with 100 chemistry can outperform disjointed superstars.

Match System

Matches are peer-to-peer challenges backed by on-chain $KICK escrow. The full lifecycle — challenge creation, acceptance, simulation, oracle settlement, and prize distribution — is governed by the smart contracts. No third party can alter the outcome.

Full Match Lifecycle

1. CHALLENGE CREATED
   Challenger calls createMatchChallenge(prizePool, formationHash)
   Minimum full prize pool: 10 $KICK (5 $KICK per side)
    └─ Half prize pool locked in contract escrow
    └─ formationHash = keccak256(abi.encode(matchContract, chainId, matchId, owner, side, formation, salt))

2. CHALLENGE ACCEPTED
    Opponent calls acceptMatchChallenge(matchId, formationHash)
   └─ Other half locked in escrow
   └─ Match status → InProgress
   └─ Backend detects event, queues simulation

3. FORMATIONS REVEALED
    Both managers call revealFormation(matchId, formation, salt)
   └─ On-chain hash verification
   └─ Formation stored in match state

4. SIMULATION (off-chain, backend)
   MatchEngine.simulate(homeTeam, awayTeam, seed)
   └─ seed derived from both team addresses and a recent block hash
   └─ 5,400 ticks computed deterministically by the backend engine
   └─ resultHash = cryptographic commitment to (seed, scores, events)

5. SETTLEMENT (oracle → on-chain)
   Oracle calls settleMatch(homeScore, awayScore, resultHash)
   └─ Match status → Settled
   └─ Winner gets prizePool − 5% fee
   └─ Draw → each team gets half back
   └─ W/D/L records updated on both teams
   └─ 5% fee → protocol treasury

Prize Distribution

Live Match Streaming

While the simulation runs server-side, every tick is streamed to connected clients via WebSocket. The frontend's Three.js renderer consumes these ticks in real time, smoothly interpolating 22 player positions and the ball on the 3D pitch. Clients can also request a replay of any past match using the REPLAY_REQUEST message type.

Match Events

Finance & $KICK Token

$KICK is the native utility token of KICKAIFM. It is both the currency for all in-game actions and the source of protocol emissions for active teams. The current finance panel tracks wallet balance, live pending rewards, daily emissions, emission score, protocol share, and upgrade ROI.

$KICK Flows

Emission Score

Rewards accrue from the protocol emission rate according to your team's emission score. The frontend reads on-chain economy data and shows your score, total protocol score, protocol share, estimated daily emissions, and a smooth live pending counter between chain refreshes.

protocolShare = myEmissionScore / totalEmissionScore
dailyEmission = emissionRateWeiPerSecond * protocolShare * 86400

// The UI snaps to on-chain pendingRewards every 2 seconds and interpolates
// between refreshes using the computed per-team emission rate.

Infrastructure Upgrades

Stadium, Merch Store, Ad Boards, and Facilities each have four paid tiers after the starting tier. Upgrading burns the listed $KICK amount, sends the listed ETH fee with the transaction, starts an on-chain cooldown, and then requires a separatecompleteUpgrade call once the timer is ready.

Claiming Revenue

You claim accrued $KICK by calling claimRewards. Claims require at least1 $KICK pending on-chain. Before signing, the frontend requests a backend quote containing the pending $KICK and ETH fee. If the claim oracle is not configured, the claim button is disabled and rewards continue to accrue.

Protocol Revenue Sources

Emission Score (Upgrade Points)

Upgrade tiers generate upgrade_points that contribute to your team's global emission score. The Finance panel also displays statPoints, so managers can see how much of their score comes from infrastructure versus squad development.

Max upgrade points = 4 assets × 8 points = 32 points. Combined with training stat points (max 16), total emission score ceiling is 48 per team.

Smart Contracts

The KICKAIFM Solidity contracts (KickToken, KickProtocol, KickMatch, and KickOracle) are the authoritative layer for economic decisions. They enforce access control, handle token transfers, manage match escrow, and store the canonical state of every team, player, economy account, and match on-chain.

Contract Functions

Contract Storage

Token Operations

All token operations use the ERC-20 standard. The KickToken contract grants the KickProtocol contract minter privileges for distributing revenue. Match escrow is held directly by the KickMatch contract — no external key can unilaterally access it.

Oracle Service

The oracle is a privileged backend service. Its signing keypair is stored in a secrets manager and never exposed in code or environment files. It is the only authority permitted to call resolveInjuryCheck and settleMatch on-chain. After the simulation completes, the oracle submits a signed settlement transaction containing the scores and a cryptographic result commitment, then triggers the live match-end event stream to all connected clients.

Custom Error Codes

Security

Security is a first-class concern at every layer of KICKAIFM. The economic model and match system are designed to be fair, transparent, and manipulation-resistant.

Match Integrity

Economic Security

Backend & API Security

Verifiability

Settled matches are cryptographically auditable. The on-chain KickMatchcontract stores the result commitment (scores + cryptographic hash of the full event log) signed by the oracle. An independent auditor with access to the simulation engine can reproduce the result from the on-chain seed and team snapshots and confirm it matches the stored commitment — no trust in the oracle is required beyond the key rotation process.