Claim Lifecycle State Machine¶

stateDiagram-v2
    [*] --> NotClaimable
    NotClaimable --> RunningClaimable: fresh safe observation and trigger armed
    RunningClaimable --> PendingClaim: initiatePendingClaim
    PendingClaim --> Finalizable: readyAt elapsed
    PendingClaim --> Cancelled: risk, receipt, reserve, exit, or explicit cancel
    Finalizable --> Paid: finalizePendingClaim + vault transferETH
    Paid --> RunningClaimable
    RunningClaimable --> Limited: reserve-backed or dust-limited mode
    Limited --> RunningClaimable: repaired/healthy
    RunningClaimable --> Disabled: stop-loss, stale, quarantine, exit, settlement
    Limited --> Disabled
    Disabled --> RunningClaimable: evidence restored
    Cancelled --> NotClaimable

Claim Inputs¶

Claim state depends on seat initialization, settlement phase, exit flags, risk observation, freshness, trigger armed, reserve coverage, dust state, reserve health, network phase, and uncovered deficit.

Allowed Callers¶

Beneficiary or authorized executor can initiate/finalize through controller paths.
Controller is the only caller of gatekeeper pending-claim mutations.
Owner can change executor grants, pause executors, and alter reserve/risk inputs.

Failure/Hold States¶

Pending claims should be cancelled or fail when risk or reserve assumptions change. Executor authorization fails if paused, expired, missing scope, over daily cap, or over beneficiary period cap.

Contract References¶

CenturionEconomicController.initiateClaim
finalizeClaim
cancelClaim
claimSettlementRewards
CenturionClaimGatekeeper.initiatePendingClaim
finalizePendingClaim
cancelPendingClaim
clearPendingClaimIfAny

Expanded State Model¶

State List¶

Unavailable.
Available.
Pending.
Ready.
Paid.
Cancelled.
Blocked.

Transition Table¶

From	To	Transition trigger	Actor or data source	Fail-closed behavior
`Unavailable`	`Available`	Source event/function evidence	Operator or controller data source	Fail closed if evidence missing
`Available`	`Pending`	Source event/function evidence	Operator or controller data source	Fail closed if evidence missing
`Pending`	`Ready`	Source event/function evidence	Operator or controller data source	Fail closed if evidence missing
`Ready`	`Paid`	Source event/function evidence	Operator or controller data source	Fail closed if evidence missing
`Pending`	`Cancelled`	Source event/function evidence	Operator or controller data source	Fail closed if evidence missing
`Any state`	`Blocked`	Source event/function evidence	Operator or controller data source	Fail closed if evidence missing

Contract And Function References¶

Use the generated Solidity inventory to reconcile each transition with the current contract functions and events before relying on the state machine for production. For claim transitions, source-grounded references must include the relevant controller, deposit, governor, gatekeeper, factory, or vault function named by the page.

Operational Impact¶

Every transition changes what an operator is allowed to do next. A transition into a blocked, cancelled, slashed, unsafe, or final state must stop routine automation until an independent reviewer confirms the next runbook.

Incident Implications¶

Unexpected transitions are incident evidence. Archive block number, transaction hash, decoded events, current state reads, and offchain source data. If the transition cannot be traced to a known runbook or approved automation, escalate before retrying dependent actions.