BattleHook

The Uniswap V4 hook that owns every BattleMeme token’s LP, runs the per-token state machine, accounts ETH raised, splits fees between platform & creator, and enforces the trading freeze on QUEUE/WARMUP/ELIMINATED/LOST states.

Source: contracts/src/core/BattleHook.sol. Hook permissions: all 14 V4 callbacks enabled (0x3FFF).

Roles

Public views — read state

For an FE/integrator the most useful read paths:

Bootstrap & creator pre-buy

function bootstrapToken(address token, address creator)
  external payable
  returns (PoolId poolId);

Called once per token by TokenFactory.createToken:

1. Initialize the V4 pool at sqrtPriceX96 = sqrt(price@tick 173220) (top of the LP range).
2. Mint LP_MINT = 1.6B tokens to the hook.
3. poolManager.unlock(BootstrapAddLp) → deposit all 1.6B across 5 chained single-sided positions at salts bytes32(0..4).
4. If msg.value > 0: poolManager.unlock(CreatorPrebuy) → exact-input ETH→TOKEN swap of msg.value at the freshly initialised price. Output TOKEN goes to creator. The ETH leg credits totalETHRaised and counts toward the 5 ETH queue threshold.

Emits TokenBootstrapped(token, poolId).

Fee sweep — 1.0% / 0.3% split

function sweepLpFees(PoolId poolId)
  external
  returns (uint256 ethSwept, uint256 tokenSwept);

Permissionless. Walks all 5 positions with modifyLiquidity(delta=0) to harvest accrued fees, then routes the combined BalanceDelta:

• CREATOR_FEE_BPS / POOL_FEE = 3000/13000 ≈ 0.3% of trade → BattleMemeToken.creator
• Remainder = 10000/13000 ≈ 1.0% of trade → factory.feeRecipient()

The same split is applied automatically before any LP unwind (graduation, withdrawal) so the vault captures principal only.

Emits LpFeesSwept(poolId, ethToPlatform, ethToCreator, tokenToPlatform, tokenToCreator).

State-transition gates

All callable only by orchestrator:

Lifecycle support — orchestrator-only

Uniswap V4 callbacks

All 14 callbacks are enabled (mask 0x3FFF) but only a few are load-bearing:

Events

event TokenBootstrapped(address indexed token, PoolId indexed poolId);
event StateChanged(PoolId indexed poolId, State previous, State next);
event Trade(PoolId indexed poolId, address indexed trader, bool isBuy,
            int128 amount0, int128 amount1, uint256 ethRaisedInPool);
event QualifiedForQueue(PoolId indexed poolId);
event LpFeesSwept(PoolId indexed poolId,
                  uint256 ethToPlatform, uint256 ethToCreator,
                  uint256 tokenToPlatform, uint256 tokenToCreator);
event RoundScoreCommitted(PoolId indexed poolId, uint256 indexed round, uint256 score);

Indexers typically subscribe to:

• Trade — price chart + fill book
• StateChanged — drives UI banners
• TokenBootstrapped + QualifiedForQueue — token lifecycle
• LpFeesSwept — platform / creator revenue accounting

Errors

Common usage patterns

Reading current state from a frontend

import { useReadContract } from "wagmi";
import { BattleHookAbi } from "@/lib/abis";
import { ADDRESSES } from "@/lib/addresses";
 
const { data: state } = useReadContract({
  address: ADDRESSES.BattleHook,
  abi: BattleHookAbi,
  functionName: "getState",
  args: [poolId],
});
// state: 0=NONE 1=INIT 2=QUEUE 3=WARMUP 4=BATTLE 5=RESTING 6=ELIMINATED 7=GRADUATED 8=LOST

Live score during a battle

const { data: ethInPool } = useReadContract({
  address: ADDRESSES.BattleHook,
  abi: BattleHookAbi,
  functionName: "getEthReserves",
  args: [poolId],
  query: { refetchInterval: 3_000 }, // 3s polling is enough
});
// `ethInPool` is the live battle score, in wei.

Sweeping fees as a keeper

import { useWriteContract } from "wagmi";
 
const { writeContract } = useWriteContract();
writeContract({
  address: ADDRESSES.BattleHook,
  abi: BattleHookAbi,
  functionName: "sweepLpFees",
  args: [poolId],
});
// No payment needed; anyone can do it. The 1.0%/0.3% split happens automatically.

See also: BattleOrchestrator, State machine, Tokenomics.