EscalationGame Architecture

Module Split

The first question in this stack is always ownership: which file is allowed to mutate which part of the game. The state-owning modules form one inheritance ladder over EscalationGameStorage. The deposit delegate uses the same layout and may mutate it only while the game invokes it with delegatecall. The proof verifier stays outside both mutation paths because it should never write live game state.

This order matters. New modules should join the inheritance ladder only when they truly need the full state surface. If a helper can compute a value without touching storage, it belongs in the proof verifier, a free function, or a test helper instead of widening the mutable stack.

For the carry-proof data structure itself, including leaf fields, peak bagging, the 64-peak bound, and nullifier replay protection, see Merkle Mountain Range carry proofs.

Accounting Invariants

Security assumptions: A01 risk-adjusted incentives, A10 timely outcome evidence, A03 independent participants, A04 early alarm capital, A16 timely inclusion, A21 genesis REP behavior, A06 lifecycle executors, A20 proof-data availability, and A27 cryptographic security.

Safe refactors keep the local REP and unresolved-deposit counters in sync. Before aggregate export, every active vault lock appears in both its vault-local counter and the corresponding global total. Aggregate export is optional cleanup: it clears those counters and the parent vault's escrow, while the individual deposit rows remain only as canonical proof material and no longer represent parent logical authorization or physical escrow.

Child initialization copies the authenticated carry totals and funds the child game once at the applicable aggregate rate: one child REP per effective source REP for an unrelated fork, or the already-haircut aggregate backing for the escalation's own fork. It does not allocate that backing among vaults. After the child resolves, only proofs for winning deposits may settle. Any caller may relay a proof through the pool, while the authenticated depositor always receives the normal winning payout from the aggregate game balance. Inherited losing principal becomes terminal without a per-leaf transaction; local losing deposits still follow the ordinary local settlement rules.

The stable parent deposit identifier has two domains. In ordinary games it stays equal to the local depositIndex. In fork-continuation games it becomes uint256(keccak256(abi.encode(address(this), outcomeIndex, depositIndex))), so a child-local deposit and a grandchild-local deposit can never reuse the same carry/nullifier key just because both were appended at local index zero. That same identifier is stored in carry leaves, emitted by LocalDepositAppended, CarryDepositConsumed, and ClaimDeposit, returned by exportUnresolvedDeposit(uint256,...), and consumed through consumedParentDepositIndexes.

The highest-risk paths already have regression coverage. Scenario tests exercise consumed local carry leaves, constant-size unresolved-vault export, and lazy child materialization, while escalationGameInterfaceRegression.test.ts snapshots the inherited storage layout so refactors do not silently move live slots.

Interface Drift

Public-surface changes need an explicit review trail because a split architecture makes accidental ABI drift easy to miss. The ABI snapshot and bytecode snapshot are there to prove that a surface change was intentional rather than an unnoticed side effect of refactoring one of the modules.

Review the snapshot diff together with the Solidity diff. If the change was not deliberate, fix the contract rather than normalizing the drift by updating the fixture.

Deployment and Bytecode

Security assumptions: A02 viable operating costs, A23 verified deployment, and A26 executable Ethereum gas bounds.

The proof verifier and deposit delegate splits also exist because bytecode headroom is tight. Keeping proof math and the cohesive deposit mutation path outside the deployed game bytecode keeps the contract under the current bytecode budgets and leaves only limited headroom for small execution changes without collapsing the public game contract into an unreviewable blob.

Any Solidity change can also move deterministic deployment addresses, because address derivation uses init code. After contract changes, regenerate and review every network deployment manifest with the normal artifact workflow. Follow the Operator Reference launch release checklist when those addresses intentionally change.

For gas-sensitive work, measure instead of assuming. Scenario tests are the first line of defense, and bun run gas-costs is the follow-up when deployment or settlement costs are part of the change.

Future Extraction Criteria

A module should be extracted only when the ownership boundary becomes clearer after the split. File count by itself is not a reason. The question is whether the new boundary would reduce review risk by making state mutation, proof math, or settlement authority easier to see.