Battle Engine

type Layout = {
  // 9 slots, indexed 0–8 matching the 3×3 grid:
  //  [0] [1] [2]   ← Wave 1 (left, center, right)
  //  [3] [4] [5]   ← Wave 2
  //  [6] [7] [8]   ← Wave 3
  units: Array<'W' | 'A' | 'S'>; // length 9, exactly 3 of each
};

// Deterministic nonce — derived from a wallet signature so the player
// never has to remember it. Re-derivable from the wallet alone.
const nonce: Hex = keccak256(walletSignature("BasePixel.Layout.v1"));

const layoutHash: Hex = keccak256(
  abi.encode(units, nonce, pixelId)
);

function commitLayout(uint256 pixelId, bytes32 layoutHash) external;

GET /api/layouts/:tokenId/plaintext?signature=...&deadline=...

const AttackIntent = {
  domain: {
    name: 'BasePixel',
    version: '1',
    chainId: 8453,
    verifyingContract: BATTLE_FACET_ADDRESS,
  },
  types: {
    AttackIntent: [
      { name: 'attackerPixelId', type: 'uint256' },
      { name: 'defenderPixelId', type: 'uint256' },
      { name: 'attackerLayoutHash', type: 'bytes32' },
      { name: 'attackFee', type: 'uint256' }, // 0.0005 ETH in wei
      { name: 'nonce', type: 'uint256' },     // anti-replay; per-attacker counter
      { name: 'deadline', type: 'uint256' },  // unix seconds; intent expires after this
    ],
  },
  message: { attackerPixelId, defenderPixelId, attackerLayoutHash, attackFee, nonce, deadline },
};

const signature = await wallet.signTypedData(AttackIntent);

POST /v1/intents
Content-Type: application/json

{
  "intent": { ...AttackIntent.message },
  "signature": "0x...",
  "layoutPlaintext": { "units": ["S","W","A","A","S","W","W","A","S"], "nonce": "0x..." }
}

function lockBattle(
  uint256 attackerPixelId,
  uint256 defenderPixelId,
  bytes32 attackerLayoutHash,
  bytes calldata engineSignature
) external payable returns (uint256 battleId);

function simulate(input: SimulationInput): ReplayLog {
  // Verify both hashes
  assert(keccak256(input.attackerLayout, input.attackerNonce, input.attackerPixelId) === input.attackerLayoutHash);
  assert(keccak256(input.defenderLayout, input.defenderNonce, input.defenderPixelId) === input.defenderLayoutHash);

  // Random seed: bound to the lock event's block hash so the seed is verifiable
  // without trusting the Engine, but unknown to either player at intent-signing time.
  const seed = keccak256(input.lockBlockHash, input.battleId);
  const rng = makeDeterministicRng(seed);

  // Combat is Hearthstone-style mutual damage: every strike is simultaneous,
  // so the target always swings back for `target.atk` damage — even ranged
  // attackers (Archers) eat the counter, and even targets that just hit 0 HP
  // still get their last lick in. Both attacker and target can die in the
  // same step. See /play/battle for the full unit/damage table.

  // ... runs the rules from /play/battle
  return replayLog;
}

type ReplayLog = {
  battleId: bigint;
  attackerPixelId: bigint;
  defenderPixelId: bigint;
  attackerLayout: Layout;
  defenderLayout: Layout;
  lockBlockHash: Hex;
  seed: Hex;

  rounds: Array<{
    roundNumber: number;
    activeWave: { red: 1 | 2 | 3 | 4; blue: 1 | 2 | 3 | 4 };
    steps: Array<ReplayStep>;
  }>;

  outcome: {
    type: 'annihilation' | 'timeout' | 'draw' | 'forfeit';
    winner: 'attacker' | 'defender';
    finalHpRed: number;   // sum of surviving HP
    finalHpBlue: number;
  };
};

type ReplayStep = {
  step: number;
  side: 'red' | 'blue';
  attackerSlot: 0..8;       // which of the 9 slots is acting
  attackerUnit: 'W' | 'A' | 'S';
  attackerHpBefore: number;
  targetSlot: 0..8;
  targetUnit: 'W' | 'A' | 'S';
  targetHpBefore: number;
  damageDealt: number;      // attacker → target
  damageTaken: number;      // target → attacker (always == target.atk under the mutual-damage rule)
  attackerHpAfter: number;
  targetHpAfter: number;
  killed: Array<0..8>;      // slots that hit 0 HP this step
};

const replayHash: Hex = keccak256(canonicalize(replayLog));

function resolveBattle(
  uint256 battleId,
  bytes32 replayHash,
  uint8 outcome,                 // 0=attackerWin, 1=defenderWin, 2=draw, 3=forfeit
  string calldata replayUri,     // ipfs://... or https://...
  bytes calldata engineSignature
) external onlyEngine;

type EngineError =
  | { code: 'INVALID_SIGNATURE' }
  | { code: 'LAYOUT_HASH_MISMATCH'; expected: Hex; got: Hex }
  | { code: 'PIXEL_NOT_OWNED' }
  | { code: 'PIXEL_NOT_IN_ACTION' }
  | { code: 'PIXEL_LOCKED_IN_BATTLE' }
  | { code: 'INTENT_EXPIRED' }
  | { code: 'INTENT_REPLAY' }
  | { code: 'INSUFFICIENT_FEE' }
  | { code: 'DEFENDER_FORFEIT_TIMEOUT' }
  | { code: 'ENGINE_INTERNAL'; requestId: string };