CircuitBreakerLib
Title: CircuitBreaker Library
Author: David Dada <daveproxy80@gmail.com> (https://github.com/dadadave80)
Library implementing a multi-key threshold-based circuit breaker for Diamond facets.
Each key tracks an independent cumulative metric within a rolling time window.
When the cumulative value meets or exceeds the configured threshold the key trips,
blocking any consumer that calls checkNotTripped. An admin can reset a tripped key
or reconfigure its threshold/window at any time.
Functions
circuitBreakerStorage
Returns the storage struct for CircuitBreaker at its ERC-7201 slot.
function circuitBreakerStorage() internal pure returns (CircuitBreakerStorage storage $);Returns
| Name | Type | Description |
|---|---|---|
| $ | CircuitBreakerStorage |
registerInterface
Registers support for the ICircuitBreaker interface via ERC-165.
Writes true to the precomputed ERC-165 map slot.
function registerInterface() internal;__CircuitBreaker_init
Initializes the CircuitBreaker module.
Must be called inside an initializer-guarded function (see Initializable).
Registers the ICircuitBreaker interface ID for ERC-165 discovery.
function __CircuitBreaker_init() internal;setThreshold
Configures or updates the threshold and rolling window for key.
Requires DEFAULT_ADMIN_ROLE. Resets cumulative and tripped state on reconfiguration.
Emits CircuitBreakerThresholdSet.
Reverts CircuitBreakerInvalidThreshold if threshold == 0.
Reverts CircuitBreakerInvalidWindow if windowSeconds == 0.
function setThreshold(bytes32 key, uint256 threshold, uint48 windowSeconds) internal;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 when expired.
Requires DEFAULT_ADMIN_ROLE. Rolls the window if block.timestamp >= windowStart + windowSeconds.
Accumulates value and trips the breaker if cumulative >= threshold.
Reverts CircuitBreakerNotConfigured if threshold == 0.
Reverts CircuitBreakerTrippedError if the circuit is already tripped; call reset() first.
function recordObservation(bytes32 key, uint256 value) internal;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. Emits CircuitBreakerReset.
function reset(bytes32 key) internal;Parameters
| Name | Type | Description |
|---|---|---|
| key | bytes32 | The circuit breaker key to reset. |
checkNotTripped
Reverts with CircuitBreakerTrippedError if the circuit breaker for key is tripped.
Consumer modules call this to gate protected operations.
function checkNotTripped(bytes32 key) internal view;Parameters
| Name | Type | Description |
|---|---|---|
| key | bytes32 | The circuit breaker key to check. |
isTripped
Returns whether the circuit breaker for key is currently tripped.
function isTripped(bytes32 key) internal 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) internal 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) internal 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
Internal — sets threshold + window, resets cumulative and tripped state.
function _setThreshold(bytes32 key, uint256 threshold, uint48 windowSeconds) internal;Parameters
| Name | Type | Description |
|---|---|---|
| key | bytes32 | |
| threshold | uint256 | |
| windowSeconds | uint48 |
_recordObservation
Internal — records observation, rolls window if needed, trips if threshold crossed.
Reverts with CircuitBreakerTrippedError if the circuit is already tripped — callers
must invoke reset() before submitting new observations after a trip.
function _recordObservation(bytes32 key, uint256 value) internal;Parameters
| Name | Type | Description |
|---|---|---|
| key | bytes32 | |
| value | uint256 |
_reset
Internal — clears tripped flag and cumulative, emits reset event.
function _reset(bytes32 key) internal;Parameters
| Name | Type | Description |
|---|---|---|
| key | bytes32 |