ICircuitBreaker
Title: ICircuitBreaker
Interface for the CircuitBreaker module — a multi-key threshold-based pause that automatically trips when a tracked metric exceeds a threshold within a rolling window.
Functions
isTripped
Returns whether the circuit breaker for key is currently tripped.
function isTripped(bytes32 key) external view returns (bool);Parameters
| Name | Type | Description |
|---|---|---|
| key | bytes32 | The circuit breaker key to query. |
Returns
| Name | Type | Description |
|---|---|---|
| <none> | bool | bool True if the circuit breaker is tripped, false otherwise. |
getThreshold
Returns the configured threshold and window for key.
function getThreshold(bytes32 key) external view returns (uint256 threshold, uint48 windowSeconds);Parameters
| Name | Type | Description |
|---|---|---|
| key | bytes32 | The circuit breaker key to query. |
Returns
| Name | Type | Description |
|---|---|---|
| threshold | uint256 | The trip threshold (0 means unconfigured). |
| windowSeconds | uint48 | The rolling window duration in seconds. |
getCumulative
Returns the current cumulative value and window start time for key.
function getCumulative(bytes32 key) external view returns (uint256 cumulative, uint48 windowStart);Parameters
| Name | Type | Description |
|---|---|---|
| key | bytes32 | The circuit breaker key to query. |
Returns
| Name | Type | Description |
|---|---|---|
| cumulative | uint256 | The accumulated value within the current window. |
| windowStart | uint48 | The timestamp when the current window started. |
setThreshold
Configures or updates the threshold and rolling window for key.
Requires DEFAULT_ADMIN_ROLE. Resets cumulative and tripped state.
Reverts with CircuitBreakerInvalidThreshold if threshold == 0.
Reverts with CircuitBreakerInvalidWindow if windowSeconds == 0.
function setThreshold(bytes32 key, uint256 threshold, uint48 windowSeconds) external;Parameters
| Name | Type | Description |
|---|---|---|
| key | bytes32 | The circuit breaker key to configure. |
| threshold | uint256 | The trip threshold value (must be > 0). |
| windowSeconds | uint48 | The rolling window duration in seconds (must be > 0). |
recordObservation
Records an observation for key, rolling the window if necessary.
Requires DEFAULT_ADMIN_ROLE. If block.timestamp >= windowStart + windowSeconds,
the window resets before accumulating. If the new cumulative value meets or exceeds
the threshold the circuit trips and emits CircuitBreakerTripped.
Reverts with CircuitBreakerNotConfigured if the key has not been set up.
Reverts with CircuitBreakerTrippedError if the circuit is already tripped;
call reset() to clear the tripped state before recording further observations.
function recordObservation(bytes32 key, uint256 value) external;Parameters
| Name | Type | Description |
|---|---|---|
| key | bytes32 | The circuit breaker key. |
| value | uint256 | The value to add to the current window's cumulative. |
reset
Resets the tripped state and cumulative for key.
Requires DEFAULT_ADMIN_ROLE. Reverts with CircuitBreakerNotConfigured if the key
has not been configured yet (windowSeconds == 0).
Note: the tripped flag is sticky — it is NOT automatically cleared when the rolling
window expires. An explicit reset() or setThreshold() call is required to untrip
the circuit. This is intentional so that operational incidents are never silently
resolved without a human action.
Emits CircuitBreakerReset.
function reset(bytes32 key) external;Parameters
| Name | Type | Description |
|---|---|---|
| key | bytes32 | The circuit breaker key to reset. |
Events
CircuitBreakerTripped
Emitted when a circuit breaker is tripped because the cumulative value crossed the threshold.
event CircuitBreakerTripped(bytes32 indexed key, uint256 value, uint256 threshold);Parameters
| Name | Type | Description |
|---|---|---|
| key | bytes32 | The circuit breaker key. |
| value | uint256 | The cumulative value at the time of tripping. |
| threshold | uint256 | The configured threshold that was exceeded. |
CircuitBreakerReset
Emitted when an admin resets a tripped circuit breaker.
event CircuitBreakerReset(bytes32 indexed key);Parameters
| Name | Type | Description |
|---|---|---|
| key | bytes32 | The circuit breaker key that was reset. |
CircuitBreakerThresholdSet
Emitted when the threshold and window for a key are configured or updated.
event CircuitBreakerThresholdSet(bytes32 indexed key, uint256 threshold, uint48 windowSeconds);Parameters
| Name | Type | Description |
|---|---|---|
| key | bytes32 | The circuit breaker key. |
| threshold | uint256 | The new threshold value. |
| windowSeconds | uint48 | The new rolling window duration in seconds. |
Errors
CircuitBreakerNotConfigured
Thrown when an operation is attempted on a key that has not been configured yet.
error CircuitBreakerNotConfigured(bytes32 key);Parameters
| Name | Type | Description |
|---|---|---|
| key | bytes32 | The unconfigured circuit breaker key. |
CircuitBreakerTrippedError
Thrown when an operation is blocked because the circuit breaker is tripped.
error CircuitBreakerTrippedError(bytes32 key);Parameters
| Name | Type | Description |
|---|---|---|
| key | bytes32 | The tripped circuit breaker key. |
CircuitBreakerInvalidWindow
Thrown when windowSeconds == 0 is passed to setThreshold.
error CircuitBreakerInvalidWindow();CircuitBreakerInvalidThreshold
Thrown when threshold == 0 is passed to setThreshold.
error CircuitBreakerInvalidThreshold();