EscalationGame

Escrows outcome REP, raises the running resolution cost, detects non-decision, and settles local or carried deposits. EscalationGame source contract

Read surface

Base getters are securityPool, repToken, activationTime, nonDecisionThresholdAttoRep, startBondAttoRep, nonDecisionTimestamp, nonDecisionState, forkContinuation, forkElapsedAtStart, forkResumedAt, fixedQuestionOutcome, nodes, disputeStakedRepByVaultAttoRep, totalDisputeStakedAttoRep, truthAuctionRepBeforeAttoRep, and truthAuctionRepRemainingAttoRep. The claim delegate fallback exposes rootClaimSourceGame, getInheritedClaimAllocation, and getUnresolvedClaimInterval. The allocation read returns source principal, retained principal, reward-interval length, and the cumulative reward endpoint after per-generation auction rounding. The reward interval is the deposit’s range within its outcome’s cumulative deposits: its start is the returned endpoint minus the returned length. It determines which portion enters the reward calculation; the length is not a payable reward. Exported principal intervals compact consumed prefixes, while reward positions remain unshifted by prior claims. Allocations within a game stay fixed in every claim order. disputeStakedRepByVaultAttoRep is locally attributed current-game escrow used for health; inherited carry remains aggregate commitment state until proof settlement. Use previewDepositOnOutcome, computeIterativeAttritionCostAttoRep, computeTimeSinceStartFromAttritionCostAttoRep, totalCostAttoRep, getEscalationGameEndDate, getQuestionResolution, getFinalQuestionResolution, hasReachedNonDecision, canTriggerOwnFork, getBindingCapitalAttoRep, getOutcomeBalancesAttoRep, getDepositsByOutcome, getDepositsByOutcomeLength, forkCarrySnapshotInitialized, getOutcomeState, getForkCarrySnapshot, getForkCarryRoots, isForkCarryFundingComplete, getCarryLeafPageByOutcome, getProofConsumedCarriedDepositIndexesByOutcome, getLocalUnresolvedPrincipalByVaultAndOutcome, and getForkedEscrowByVaultAndOutcome for calculations, lifecycle authorization, pages, carry state, and escrow. Vault-funded deposits and all withdrawals route through SecurityPool; after an ordinary game starts, wallet-funded deposits use depositRepOnOutcome and mint no pool backing units.

State-changing interactions

Transaction	Caller	Main prerequisites	State or asset effect	Primary signals
`start(startBondAttoRep, nonDecisionThresholdAttoRep)`	`EscalationGameFactory` contract during atomic deployment	Game not already started; threshold exceeds the positive start bond. Positive attoREP values are valid.	Initializes a local game and sets activation three days after deployment. For ordinary pool games, the factory lowers an oversized configured bond to `nonDecisionThresholdAttoRep - 1` before this call.	`GameStarted`
`startFromFork(startBondAttoRep, nonDecisionThresholdAttoRep, elapsedAtFork, fixedQuestionOutcome, winnerHaircutPaidByFork, forkCarryInitialBackingAttoRep)`	Immutable owner (`EscalationGameFactory`) during atomic continuation deployment	Game not started; threshold exceeds the positive start bond; inherited elapsed time is no greater than seven weeks. Positive attoREP values are valid.	Initializes a paused continuation with inherited elapsed time, an optional fixed matching child outcome, and immutable fork-time haircut/backing accounting. It does not start the remaining clock until `resumeFromFork`.	`GameContinuedFromFork`
`resumeFromFork()`	Owning `SecurityPool` only	Fork-continuation mode; not previously resumed; immutable carry snapshot installed; aggregate REP funding complete. An unrelated fork requires one-to-one backing of effective unresolved principal. For an own-fork continuation, recorded initial backing must be at least `sourcePrincipalAtForkAttoRep - ⌊sourcePrincipalAtForkAttoRep / 5⌋`, where `sourcePrincipalAtForkAttoRep` is the aggregate raw unresolved principal installed by the snapshot before effective direct-claim deductions. The live balance must cover that initial backing minus child REP already exported by valid direct pre-resume claims.	Records the resume timestamp once the immutable carry commitment is installed and funded. The new deadline is `max(rebasedCurveEnd, forkResumedAt + 3 days)`, so even an exhausted inherited clock receives a fresh response period. After that deadline, `getFinalQuestionResolution` returns the fixed outcome when the continuation has one.	`ForkContinuationResumed`
`applyTruthAuctionHaircut(repToRemoveAttoRep)`	The child pool's `SecurityPoolForker` only	Paused fork continuation; no prior auction haircut; the requested amount is below the game's live REP balance.	Transfers sold REP to the pool, proportionally reduces escrow and outcome balances, and rebases curve time. If an unfixed continuation inherited two threshold-full outcome balances and the haircut leaves them below the current game threshold, ordinary pool-mediated deposit checks apply after the pool resumes the game. Fixed outcomes and local non-decisions retain their state. The game stays paused until the pool resumes it.	`TruthAuctionHaircutApplied` and REP `Transfer`; `InheritedThresholdTieReopened` when an unfixed inherited tie reopens
`depositRepOnOutcome(outcome, maximumDepositAttoRep)`	Any REP holder	Current game is the pool's ordinary unresolved game; pool operational; universe unforked; outcome non-`None`; caller allowance to this game covers the accepted REP; preview accepts a positive amount within the remaining threshold room.	Transfers the accepted REP directly from the caller into dispute escrow, appends a local deposit, and records its carry leaf without minting pool backing units.	`LocalDepositAppended`, `DepositOnOutcome`, REP `Transfer`, optionally `NonDecisionReached`
`recordDepositFromSecurityPool(...)`	Owning `SecurityPool` only	Explicit non-decision state is `None`; game unresolved; valid outcome; preview and accepted cumulative amount match; room remains below threshold.	Appends an accepted local deposit, updates outcome and vault escrow, and records its carry leaf.	`LocalDepositAppended`, `DepositOnOutcome`, optionally `NonDecisionReached`
`withdrawDeposit(uint256 depositIndex, outcome)`	Owning `SecurityPool` only	Explicit non-decision state is `None`; non-`None` supplied outcome; game final; game and pool final outcomes match; valid unsettled local deposit index.	Consumes one local deposit after resolution. A winner pays the deposit's immutable depositor after its haircut; a loser only retires its escrow accounting.	`CarryDepositConsumed` and `VaultEscrowUpdated`; for a winner, `ClaimDeposit`, positive REP payout `Transfer`, and haircut burn signals when nonzero
`initializeForkCarrySnapshotWithResolutionBalances(...)`	Owning `SecurityPool` only	Fork-continuation mode; no prior snapshot; each leaf count fits the MMR; supplied nonzero snapshot ID equals the hash of the normalized data.	Installs the immutable inherited peaks, leaf counts, carry totals, resolution balances, and normalized nullifier roots; zero snapshot ID selects the computed ID. Two or more threshold-full inherited balances set `nonDecisionState` to `InheritedThresholdTie` without creating a local timestamp.	`ForkCarryCheckpoint`; additionally `InheritedThresholdTie` when the installed balances meet the non-decision threshold
`claimDepositForWinning(depositIndex, outcome)`	Owning `SecurityPool` or its `SecurityPoolForker`	Non-`None` supplied outcome and valid unsettled local deposit with sufficient escrow. This entrypoint itself does not check final resolution or that the supplied outcome won; its trusted caller selects that path.	Consumes a selected local deposit as a winner, consumes its vault escrow, burns the computed haircut when nonzero, and transfers the remaining positive REP payout to the deposit's immutable depositor.	`CarryDepositConsumed`, `VaultEscrowUpdated`, `ClaimDeposit` with `transferredRep = true`; REP payout `Transfer` and haircut burn signals only when their amounts are positive
`claimDepositForWinningWithoutTransfer(depositIndex, outcome)`	Owning `SecurityPool` or its `SecurityPoolForker`	Valid in-range supplied outcome and unsettled local deposit with sufficient escrow. Unlike the transferring form, it has no explicit non-`None` guard; neither form checks final resolution or that the outcome won.	Consumes a selected local deposit and its vault escrow. The depositor's raw escrow backing decreases by the inverse-retention claim units corresponding to the deposit's original principal: the principal itself with no local auction checkpoint, or `⌈originalPrincipal × truthAuctionRepBeforeAttoRep / truthAuctionRepRemainingAttoRep⌉` after a local haircut. Other unconsumed deposits by the same depositor remain backed. The game returns the computed winner amount to the trusted caller but deliberately neither transfers REP nor burns the computed haircut.	`CarryDepositConsumed`, `VaultEscrowUpdated`, and `ClaimDeposit` with `transferredRep = false`; no REP transfer or haircut burn
`exportUnresolvedDeposit(depositIndex, outcome)`	Owning `SecurityPool` or its `SecurityPoolForker`	Non-`None` outcome and a valid unsettled local deposit. Final resolution is not required.	Returns deposit identity and amount to the trusted caller while consuming the local deposit from unresolved/escrow accounting without transferring REP.	`CarryDepositConsumed` and `VaultEscrowUpdated`; no `ClaimDeposit` or REP transfer
`withdrawDeposit(CarriedDepositProof proof, outcome)`	Owning `SecurityPool` or its `SecurityPoolForker`	Non-`None` supplied outcome; game final and matching the pool final outcome; supplied outcome is the winner; parent deposit was not directly claimed; valid unconsumed Merkle/nullifier proof.	Consumes an inherited proof, transfers any positive winning payout, and burns the positive haircut unless the fork already paid it.	`CarryDepositConsumed` and `ClaimDeposit` with `transferredRep = true`; REP payout `Transfer` and haircut burn signals only when positive
`exportVaultUnresolvedTotals(vault, repReceiver)`	Owning `SecurityPool` or its `SecurityPoolForker`	`vault` is nonzero and has not exported before. There is no explicit nonzero-receiver guard: a zero receiver succeeds when the total is zero but the token rejects it when a positive transfer is attempted.	Marks the vault's local unresolved totals exported exactly once, clears each outcome amount, consumes aggregate unresolved and escrow accounting when positive, and transfers the positive total to `repReceiver`.	Always `VaultUnresolvedTotalsExported`, including when every amount is zero; `VaultEscrowUpdated` and REP `Transfer` only for a positive total
`exportVaultUnresolvedTotalsWithoutTransfer(vault)`	Owning `SecurityPool` or its `SecurityPoolForker`	`vault` is nonzero and has not exported before.	Marks the vault's local unresolved totals exported exactly once, clears each outcome amount, and consumes aggregate unresolved and escrow accounting when positive, but leaves token movement to its caller.	Always `VaultUnresolvedTotalsExported` with `transferredRep = false`, including when every amount is zero; `VaultEscrowUpdated` only for a positive total; no REP transfer
`drainAllRep(receiver)`	Owning `SecurityPool` only	`receiver` is nonzero; no positive-balance requirement. The protocol reaches this call from the owning pool after `activateForkMode` enters `PoolForked`.	Transfers the game's full REP balance to `receiver`. A zero balance returns zero without a transfer or event.	REP `Transfer` for a positive balance; no event at zero balance
`recordForkedEscrowForOutcome(depositor, outcome, sourcePrincipalAttoRep, childRepAmountAttoRep)`	Owning `SecurityPool` or its `SecurityPoolForker`	Outcome is not `None`; depositor is nonzero. Source principal and child REP may independently be zero; when both are zero, the call is a no-op.	Accumulates source principal and child REP escrow for the depositor and outcome. The depositor remains the immutable payout owner; inherited claims remain in the carry commitment and are not copied into child-local ownership state. When both amounts are zero, returns without changing state or emitting an event.	`ForkedEscrowRecorded` for a nonzero record; no event when both amounts are zero
`exportForkedEscrowByOutcome(vault, repReceiver)`	Owning `SecurityPool` or its `SecurityPoolForker`	`vault` and `repReceiver` are nonzero.	Marks every remaining per-outcome escrow amount exported and transfers its positive child REP. When all outcomes were already empty or exported, returns zero arrays without state change, token transfer, or event.	`ForkedEscrowExported` when any source principal or child REP remains; REP `Transfer` when positive child REP is transferred; no event for an already-empty export
`exportForkedEscrowByOutcomeWithoutTransfer(vault)`	Owning `SecurityPool` or its `SecurityPoolForker`	`vault` is nonzero.	Marks every remaining per-outcome escrow amount exported without transferring child REP. When all outcomes were already empty or exported, returns zero arrays without state change or event.	`ForkedEscrowExported` with `transferredRep = false` when any source principal or child REP remains; no REP transfer; no event for an already-empty export
`sweepResidualRepToSecurityPool()`	Anyone	Final outcome; no unresolved principal; no vault escrow; positive residual balance.	Returns ordinary-game residual REP to the owning pool. Burns fork-continuation residual so pre-child capital cannot accrue to late or nonexistent child owners.	`ResidualRepSweptToSecurityPool` for an ordinary game; `ForkContinuationResidualRepBurned` for a fork continuation

Accounting examples

Required support threshold

The contract waits activationDelay (3 days) after start() before the escalation clock begins. From day 3 the cumulative binding-capital requirement rises from the configured start bond S to the non-decision threshold T over the 49-day ESCALATION_TIME_LENGTH, reaching T on day 52. The contract evaluates a fixed-point curve; this expression is its readable idealization.

\begin{matrix} A (d) & = & 0 & for 0 \leq d < 3 \\ = & S & for d = 3 \\ = & S \times \exp (\ln (\frac{T}{S}) \times \frac{d - 3}{49}) & for 3 < d < 52 \\ = & T & for d \geq 52 \end{matrix}

Winning-deposit payout

Binding capital is the median outcome balance at settlement; no outcome balance can exceed the non-decision threshold. The reward-eligible cap is binding capital plus binding capital divided by EXCESS_REWARD_WINDOW_DIVISOR (2), so only the portion of winning deposits up to 1.5 × binding capital participates in the bonus. Of the binding capital, 3 / 5 funds the reward pool and 2 / 5 funds the haircut pool; both are shared pro rata across the reward-eligible principal, which is the smaller of the winning outcome balance and that cap.

Let binding capital be 10 REP, so the reward-eligible cap is 15 REP, the reward pool is 6 REP, and the haircut pool is 4 REP. If the winning outcome holds 15 REP and one deposit contributed 5 REP inside the eligible range:

Principal returned: 5 REP.
Bonus: 5 × 6 / 15 = 2 REP.
Winning payout: 5 + 2 = 7 REP.
Haircut burned: 5 × 4 / 15 = 1.333333333333333333 REP at attoREP precision.

A winning deposit position above 15 REP returns its principal without a bonus. When Zoltar's fork threshold at settlement is below the game's non-decision threshold, the whole withdrawal is scaled by their ratio. If this game's non-decision threshold were 20 REP and the fork threshold 16 REP, the 7 REP payout becomes 7 × 16 / 20 = 5.6 REP, rounded down to attoREP. Fork scaling can therefore reduce the final transfer below principal.