ConfigTimelockBatchQueue

Inherits: TimelockBatchQueue, IConfigTimelockBatchQueue

Title: ConfigTimelockBatchQueue

Base contract for configuration timelocks. It prevents conflicting changes from being queued together and prevents queued changes from executing after their underlying configuration has changed.

Each sub-action identifies its destination and the configuration it depends on with one or more keys. The contract scopes every key to that destination, reserves the scoped keys, and records their current state hashes at queue time. A reserved key cannot be used by another unresolved action. At execution, the destination and every current state hash must still match. Keys are released only after the whole batch executes or is cancelled. Product contracts customize validation, destinations, keys, hashes, and dispatch through the config-specific hooks below.

State Variables

_pendingActionIds

The unresolved action holding a destination-scoped configuration key.

mapping(bytes32 key => uint64 actionId) internal _pendingActionIds;

_queuedConfigStates

Configuration states recorded for each sub-action at queue time, by local key.

mapping(uint64 actionId => mapping(uint256 index => QueuedConfigState[] states))
        internal _queuedConfigStates;

_queuedConfigDestinations

Destination recorded for each sub-action at queue time.

mapping(uint64 actionId => mapping(uint256 index => address destination))
        internal _queuedConfigDestinations;

Functions

constructor

constructor(uint48 initialTimelockDelay_) TimelockBatchQueue(initialTimelockDelay_);

Parameters

Name	Type	Description
initialTimelockDelay_	`uint48`

pendingActionId

Return the unresolved action that owns a destination-scoped key, or zero if free.

function pendingActionId(bytes32 key_) external view returns (uint64 actionId);

Parameters

Name	Type	Description
key_	`bytes32`

Returns

Name	Type	Description
actionId	`uint64`

maxConfigKeysPerBatch

Return the maximum total configuration keys a batch may reserve.

function maxConfigKeysPerBatch() external view returns (uint256 maximum);

Returns

Name	Type	Description
maximum	`uint256`

getQueuedConfigStateCount

Return the number of configuration guards stored for a sub-action.

function getQueuedConfigStateCount(
        uint64 actionId_,
        uint256 index_
    ) external view returns (uint256 length);

Parameters

Name	Type	Description
actionId_	`uint64`
index_	`uint256`

Returns

Name	Type	Description
length	`uint256`

getQueuedConfigDestination

Return the destination selected by the subclass when a sub-action was queued.

function getQueuedConfigDestination(
        uint64 actionId_,
        uint256 index_
    ) external view returns (address destination);

Parameters

Name	Type	Description
actionId_	`uint64`
index_	`uint256`

Returns

Name	Type	Description
destination	`address`

getQueuedConfigState

Return a stored destination-scoped key and its queue-time canonical state hash.

function getQueuedConfigState(
        uint64 actionId_,
        uint256 index_,
        uint256 configStateIndex_
    ) external view returns (bytes32 key, bytes32 expectedStateHash);

Parameters

Name	Type	Description
actionId_	`uint64`
index_	`uint256`
configStateIndex_	`uint256`

Returns

Name	Type	Description
key	`bytes32`
expectedStateHash	`bytes32`

_onSubActionQueued

Hook invoked once per sub-action at queue time, before the batch is stored.

Derived contracts must revert on failure. Implementations are expected to validate the target, selector, and payload of the sub-action in isolation, and may record per-sub-action state. Cross sub-action invariants belong in _onBatchQueued. The caller is passed explicitly for clarity and to support derived contracts that centralize authorization around actor params.

function _onSubActionQueued(
        address caller_,
        uint64 actionId_,
        uint256 index_,
        ITimelockBatchQueue.BatchAction memory action_
    ) internal override;

Parameters

Name	Type	Description
caller_	`address`	The account queueing the action.
actionId_	`uint64`	The id the batch will be stored under.
index_	`uint256`	The position of the sub-action within the batch.
action_	`ITimelockBatchQueue.BatchAction`	The sub-action being queued.

_onBatchQueued

function _onBatchQueued(
        address caller_,
        uint64 actionId_,
        ITimelockBatchQueue.BatchAction[] memory actions_
    ) internal view override;

Parameters

Name	Type	Description
caller_	`address`
actionId_	`uint64`
actions_	`ITimelockBatchQueue.BatchAction[]`

_executeSubAction

Execute a single sub-action of a batched queued action.

Derived contracts must revert on failure. Called by the base contract once per sub-action in array order; the action has already been marked executed, so a revert in any iteration reverts the entire batch and rolls back that flag. Derived contracts must not rely on the base contract calling this hook in any other order.

function _executeSubAction(
        uint64 actionId_,
        uint256 index_,
        ITimelockBatchQueue.BatchAction memory action_
    ) internal override;

Parameters

Name	Type	Description
actionId_	`uint64`	The queued action ID.
index_	`uint256`	The position of the sub-action within the batch.
action_	`ITimelockBatchQueue.BatchAction`	The sub-action to execute.

_onActionExecuted

Hook invoked once after every sub-action has executed successfully and before the stored sub-actions are cleared.

Default implementation is a no-op. A revert rolls back the complete batch, including target state changes and the action's executed flag. Derived contracts may use this hook to clear state that must remain available throughout execution.

function _onActionExecuted(uint64 actionId_, uint256 subActionCount_) internal override;

Parameters

Name	Type	Description
actionId_	`uint64`	The executed action ID.
subActionCount_	`uint256`	The number of successfully executed sub-actions.

_onActionCancelled

Hook invoked once when a queued action is cancelled, after the stored sub-actions have been cleared.

Default implementation is a no-op. Derived contracts override to clear any per-sub-action state recorded at queue time by _onSubActionQueued. The sub-action count is captured before the stored array is deleted, so implementations can iterate the indices that were recorded.

function _onActionCancelled(uint64 actionId_, uint256 subActionCount_) internal override;

Parameters

Name	Type	Description
actionId_	`uint64`	The cancelled action ID.
subActionCount_	`uint256`	The number of sub-actions the action held before clearing.

_releaseConfigKeys

function _releaseConfigKeys(uint64 actionId_, uint256 subActionCount_) private;

Parameters

Name	Type	Description
actionId_	`uint64`
subActionCount_	`uint256`

_queuedConfigKeyCount

function _queuedConfigKeyCount(
        uint64 actionId_,
        uint256 endIndex_
    ) private view returns (uint256 count);

Parameters

Name	Type	Description
actionId_	`uint64`
endIndex_	`uint256`

Returns

Name	Type	Description
count	`uint256`

_validateConfigQueue

Validates queue-wide authorization and lifecycle requirements.

Called once, before the first sub-action acquires configuration keys. Implementations must revert when the caller or current product lifecycle cannot queue the batch.

function _validateConfigQueue(address caller_) internal view virtual;

Parameters

Name	Type	Description
caller_	`address`	Account queueing the batch.

_validateConfigSubAction

Validates one sub-action before its destination and configuration keys are stored.

Implementations must revert for unsupported targets, selectors, payloads, or product state. Any state recorded by an earlier sub-action is rolled back if validation fails.

function _validateConfigSubAction(
        address caller_,
        uint64 actionId_,
        uint256 index_,
        ITimelockBatchQueue.BatchAction memory action_
    ) internal view virtual;

Parameters

Name	Type	Description
caller_	`address`	Account queueing the batch.
actionId_	`uint64`	Action ID reserved for the batch.
index_	`uint256`	Position of the sub-action within the batch.
action_	`ITimelockBatchQueue.BatchAction`	Sub-action to validate.

_configDestination

Selects the destination that namespaces this sub-action's configuration keys.

The base stores this address at queue time and requires the hook to return the same address at execution. Returning a new address after rotation creates a distinct key namespace for new actions and makes existing actions non-executable.

function _configDestination(
        ITimelockBatchQueue.BatchAction memory action_
    ) internal view virtual returns (address destination);

Parameters

Name	Type	Description
action_	`ITimelockBatchQueue.BatchAction`

Returns

Name	Type	Description
destination	`address`

_configKeys

Selects the destination-local configuration domains used by a sub-action.

The base rejects zero or duplicate local keys and scopes every key with the address returned by _configDestination before acquiring ownership.

function _configKeys(
        ITimelockBatchQueue.BatchAction memory action_
    ) internal view virtual returns (bytes32[] memory keys);

Parameters

Name	Type	Description
action_	`ITimelockBatchQueue.BatchAction`

Returns

Name	Type	Description
keys	`bytes32[]`

_currentConfigStateHash

Hashes the live configuration state guarded by one local key.

Called when queueing to store the expected hash and again immediately before execution to detect stale state. Implementations must hash the same canonical fields on both paths and exclude values that may legitimately change during the timelock delay.

function _currentConfigStateHash(
        uint64 actionId_,
        uint256 index_,
        bytes32 key_,
        ITimelockBatchQueue.BatchAction memory action_
    ) internal view virtual returns (bytes32 stateHash);

Parameters

Name	Type	Description
actionId_	`uint64`	ID of the queued action.
index_	`uint256`	Position of the sub-action within the batch.
key_	`bytes32`	Destination-local configuration key being guarded.
action_	`ITimelockBatchQueue.BatchAction`	Sub-action whose live configuration state is hashed.

Returns

Name	Type	Description
stateHash	`bytes32`	Canonical hash of the guarded live state.

_validateConfigBatch

Validates invariants spanning the complete batch after all guards are acquired.

The default implementation is a no-op. An override must revert on invalid cross-action state; the revert rolls back every guard acquired for the batch.

function _validateConfigBatch(
        address caller_,
        uint64 actionId_,
        ITimelockBatchQueue.BatchAction[] memory actions_
    ) internal view virtual;

Parameters

Name	Type	Description
caller_	`address`	Account queueing the batch.
actionId_	`uint64`	Action ID reserved for the batch.
actions_	`ITimelockBatchQueue.BatchAction[]`	Complete ordered set of queued sub-actions.

_executeConfigSubAction

Subclasses must not perform a state-changing external call before the intended target dispatch. Such a call could make the already-validated state stale.

function _executeConfigSubAction(
        uint64 actionId_,
        uint256 index_,
        ITimelockBatchQueue.BatchAction memory action_
    ) internal virtual;

Parameters

Name	Type	Description
actionId_	`uint64`
index_	`uint256`
action_	`ITimelockBatchQueue.BatchAction`

_maxConfigKeysPerBatch

Maximum aggregate number of configuration keys a batch may reserve.

Defaults to the maximum number of sub-actions. Products supporting composite multi-domain sub-actions should override this batch-wide bound.

function _maxConfigKeysPerBatch() internal view virtual returns (uint256 maximum);

Returns

Name	Type	Description
maximum	`uint256`

supportsInterface

Query if a contract implements an interface.

Does not revert.

function supportsInterface(
        bytes4 interfaceId_
    ) public view virtual override(TimelockBatchQueue) returns (bool);

Parameters

Name	Type	Description
interfaceId_	`bytes4`	The interface identifier, as specified in ERC-165.

Returns

Name	Type	Description
<none>	`bool`	bool True if the contract implements `interfaceId_`.

Structs

QueuedConfigState

struct QueuedConfigState {
        bytes32 localKey;
        bytes32 expectedStateHash;
    }

Properties

Name	Type	Description
localKey	`bytes32`
expectedStateHash	`bytes32`

ConfigTimelockBatchQueue

State Variables​

_pendingActionIds​

_queuedConfigStates​

_queuedConfigDestinations​

Functions​

constructor​

pendingActionId​

maxConfigKeysPerBatch​

getQueuedConfigStateCount​

getQueuedConfigDestination​

getQueuedConfigState​

_onSubActionQueued​

_onBatchQueued​

_executeSubAction​

_onActionExecuted​

_onActionCancelled​

_releaseConfigKeys​

_queuedConfigKeyCount​

_validateConfigQueue​

_validateConfigSubAction​

_configDestination​

_configKeys​

_currentConfigStateHash​

_validateConfigBatch​

_executeConfigSubAction​

_maxConfigKeysPerBatch​

supportsInterface​

Structs​

QueuedConfigState​

State Variables

_pendingActionIds

_queuedConfigStates

_queuedConfigDestinations

Functions

constructor

pendingActionId

maxConfigKeysPerBatch

getQueuedConfigStateCount

getQueuedConfigDestination

getQueuedConfigState

_onSubActionQueued

_onBatchQueued

_executeSubAction

_onActionExecuted

_onActionCancelled

_releaseConfigKeys

_queuedConfigKeyCount

_validateConfigQueue

_validateConfigSubAction

_configDestination

_configKeys

_currentConfigStateHash

_validateConfigBatch

_executeConfigSubAction

_maxConfigKeysPerBatch

supportsInterface

Structs

QueuedConfigState