ITimelockBatchQueue
Title: ITimelockBatchQueue
Interface for contracts that queue, execute, and cancel atomic batched timelocked actions.
Each queued action represents a batch of one or more BatchAction sub-actions. A
batch of length one is the single-action case. Implementations are expected to
enforce action-specific authorization and execution checks in the concrete contract.
Standard queued-action state checks, timestamp checks, and terminal sub-action
clearing are handled by the abstract implementation.
Atomicity is a property of the batch lifecycle: a revert in any sub-action validator or executor reverts the entire batch.
Ordering is a property of a single batch only: sub-actions execute in array order within their batch, but no ordering is enforced across separately queued actions, so independently queued batches may execute in any order once their timelocks elapse. Actions with execution-order dependencies must be queued within a single batch; independent batches must not be assumed to execute in queue order.
Functions
timelockDelay
Current timelock delay in seconds.
function timelockDelay() external view returns (uint48);
Returns
| Name | Type | Description |
|---|---|---|
| <none> | uint48 |
nextActionId
Next queued action ID.
function nextActionId() external view returns (uint64);
Returns
| Name | Type | Description |
|---|---|---|
| <none> | uint64 |
getQueuedAction
Get a queued action.
Returns the historical record of the action for audit purposes. After the action
has been executed or cancelled the actions array is empty; the metadata fields
(proposer, timestamps, executed, cancelled) are still populated.
Reverts if the action does not exist.
function getQueuedAction(uint64 actionId_) external view returns (QueuedAction memory action);
Parameters
| Name | Type | Description |
|---|---|---|
| actionId_ | uint64 | The queued action ID. |
Returns
| Name | Type | Description |
|---|---|---|
| action | QueuedAction | The queued action. |
getQueuedActionLength
Get the number of sub-actions stored for a queued action.
Reverts if:
- The action does not exist
- The action has already been executed
- The action has been cancelled
function getQueuedActionLength(uint64 actionId_) external view returns (uint256 length);
Parameters
| Name | Type | Description |
|---|---|---|
| actionId_ | uint64 | The queued action ID. |
Returns
| Name | Type | Description |
|---|---|---|
| length | uint256 | The number of sub-actions stored for the action. |
getQueuedSubAction
Get a single sub-action of a queued action.
Reverts if:
- The action does not exist
- The action has already been executed
- The action has been cancelled
- The sub-action index is out of bounds
function getQueuedSubAction(
uint64 actionId_,
uint256 index_
) external view returns (address target, bytes4 selector, bytes memory payload);
Parameters
| Name | Type | Description |
|---|---|---|
| actionId_ | uint64 | The queued action ID. |
| index_ | uint256 | The sub-action index. |
Returns
| Name | Type | Description |
|---|---|---|
| target | address | The contract expected to receive the sub-action. |
| selector | bytes4 | The function selector for the sub-action. |
| payload | bytes | Encoded parameters for the sub-action. |
executeQueuedAction
Execute a queued action after its timelock has elapsed.
Implementations must revert from implementation-specific hooks if the caller or
any sub-action should not be executed. Standard action state and timestamp
checks revert from the abstract implementation: the action is executable at any
block timestamp in the closed window [executableAt, expiresAt], and expired
once the block timestamp is past expiresAt. The batch is atomic: a revert
in any sub-action reverts the entire batch. Cross-batch ordering is not
enforced: once their timelocks elapse, separately queued actions may be
executed in any order, regardless of the order in which they were queued.
function executeQueuedAction(uint64 actionId_) external;
Parameters
| Name | Type | Description |
|---|---|---|
| actionId_ | uint64 | The queued action ID. |
cancelQueuedAction
Cancel a queued action.
Implementations must revert from implementation-specific hooks if the caller is not authorized to cancel the queued action.
function cancelQueuedAction(uint64 actionId_) external;
Parameters
| Name | Type | Description |
|---|---|---|
| actionId_ | uint64 | The queued action ID. |
Events
TimelockActionQueued
Emitted when a batched action is queued.
Emitted once to close the batch, after one TimelockSubActionQueued event has
been emitted per sub-action.
event TimelockActionQueued(
uint64 indexed actionId,
address indexed proposer,
bytes32 batchHash,
uint48 executableAt,
uint48 expiresAt
);
Parameters
| Name | Type | Description |
|---|---|---|
| actionId | uint64 | The queued action ID. |
| proposer | address | The account that queued the action. |
| batchHash | bytes32 | Hash of the encoded batch of sub-actions. |
| executableAt | uint48 | Timestamp at which the action can first be executed. |
| expiresAt | uint48 | The last timestamp at which the action can be executed, inclusive. |
TimelockSubActionQueued
Emitted once per sub-action when a batched action is queued.
target and selector are indexed so off-chain consumers can filter by either
without decoding the batch.
event TimelockSubActionQueued(
uint64 indexed actionId,
address indexed target,
bytes4 indexed selector,
uint256 index,
bytes32 payloadHash
);
Parameters
| Name | Type | Description |
|---|---|---|
| actionId | uint64 | The queued action ID. |
| target | address | The contract expected to receive the sub-action. |
| selector | bytes4 | The function selector for the sub-action. |
| index | uint256 | The position of the sub-action within the batch. |
| payloadHash | bytes32 | Hash of the encoded sub-action payload. |
TimelockActionExecuted
Emitted when a batched action is executed.
Emitted once at the end of execution, after every TimelockSubActionExecuted
event for the same action.
event TimelockActionExecuted(uint64 indexed actionId, address indexed executor);
Parameters
| Name | Type | Description |
|---|---|---|
| actionId | uint64 | The queued action ID. |
| executor | address | The account that executed the action. |
TimelockSubActionExecuted
Emitted once per sub-action immediately after that sub-action runs.
Emitted inside the execution loop after the corresponding sub-action handler
returns, so it is interleaved with any events emitted by the sub-action target.
target and selector are indexed so off-chain consumers can filter by either
without decoding the batch.
event TimelockSubActionExecuted(
uint64 indexed actionId,
address indexed target,
bytes4 indexed selector,
uint256 index
);
Parameters
| Name | Type | Description |
|---|---|---|
| actionId | uint64 | The queued action ID. |
| target | address | The contract that received the sub-action. |
| selector | bytes4 | The function selector for the sub-action. |
| index | uint256 | The position of the sub-action within the batch. |
TimelockActionCancelled
Emitted when a queued batched action is cancelled.
event TimelockActionCancelled(uint64 indexed actionId, address indexed canceller);
Parameters
| Name | Type | Description |
|---|---|---|
| actionId | uint64 | The queued action ID. |
| canceller | address | The account that cancelled the action. |
TimelockDelaySet
Emitted when the timelock delay is changed.
event TimelockDelaySet(uint48 delay);
Parameters
| Name | Type | Description |
|---|---|---|
| delay | uint48 | The new timelock delay in seconds. |
Errors
ITimelockBatchQueue_ActionNotFound
Thrown when a queued action does not exist.
error ITimelockBatchQueue_ActionNotFound(uint64 actionId);
Parameters
| Name | Type | Description |
|---|---|---|
| actionId | uint64 | The queued action ID. |
ITimelockBatchQueue_ActionAlreadyExecuted
Thrown when a queued action has already been executed.
error ITimelockBatchQueue_ActionAlreadyExecuted(uint64 actionId);
Parameters
| Name | Type | Description |
|---|---|---|
| actionId | uint64 | The queued action ID. |
ITimelockBatchQueue_ActionCancelled
Thrown when a queued action has been cancelled.
error ITimelockBatchQueue_ActionCancelled(uint64 actionId);
Parameters
| Name | Type | Description |
|---|---|---|
| actionId | uint64 | The queued action ID. |
ITimelockBatchQueue_ActionNotReady
Thrown when a queued action is executed before its timelock has elapsed.
error ITimelockBatchQueue_ActionNotReady(uint64 actionId, uint48 executableAt);
Parameters
| Name | Type | Description |
|---|---|---|
| actionId | uint64 | The queued action ID. |
| executableAt | uint48 | Timestamp at which the action can first be executed. |
ITimelockBatchQueue_ActionExpired
Thrown when a queued action is executed after expiresAt, the last executable
timestamp.
error ITimelockBatchQueue_ActionExpired(uint64 actionId, uint48 expiresAt);
Parameters
| Name | Type | Description |
|---|---|---|
| actionId | uint64 | The queued action ID. |
| expiresAt | uint48 | The last timestamp at which the action can be executed, inclusive. |
ITimelockBatchQueue_ActionInvalid
Thrown when a queued sub-action has an unsupported target or selector.
error ITimelockBatchQueue_ActionInvalid(address target, bytes4 selector);
Parameters
| Name | Type | Description |
|---|---|---|
| target | address | The queued target address. |
| selector | bytes4 | The queued function selector. |
ITimelockBatchQueue_TimelockDelayInvalid
Thrown when a proposed timelock delay is outside the accepted range.
error ITimelockBatchQueue_TimelockDelayInvalid(uint48 delay, uint48 minimum, uint48 maximum);
Parameters
| Name | Type | Description |
|---|---|---|
| delay | uint48 | The proposed delay. |
| minimum | uint48 | The minimum accepted delay. |
| maximum | uint48 | The maximum accepted delay. |
ITimelockBatchQueue_BatchEmpty
Thrown when an empty batch is queued.
error ITimelockBatchQueue_BatchEmpty();
ITimelockBatchQueue_BatchTooLarge
Thrown when a queued batch exceeds the maximum allowed size.
error ITimelockBatchQueue_BatchTooLarge(uint256 length, uint256 maximum);
Parameters
| Name | Type | Description |
|---|---|---|
| length | uint256 | The length of the queued batch. |
| maximum | uint256 | The maximum batch size. |
ITimelockBatchQueue_SubActionIndexOutOfBounds
Thrown when a queried sub-action index is out of bounds for the action.
error ITimelockBatchQueue_SubActionIndexOutOfBounds(
uint64 actionId,
uint256 index,
uint256 length
);
Parameters
| Name | Type | Description |
|---|---|---|
| actionId | uint64 | The queued action ID. |
| index | uint256 | The requested sub-action index. |
| length | uint256 | The number of sub-actions stored for the action. |
Structs
BatchAction
A single sub-action within a batched queued action.
struct BatchAction {
address target;
bytes4 selector;
bytes payload;
}
Properties
| Name | Type | Description |
|---|---|---|
| target | address | The contract expected to receive the sub-action. |
| selector | bytes4 | The function selector for the sub-action. |
| payload | bytes | Encoded parameters for the sub-action. |
QueuedAction
Queued timelock action.
A queued action is always a batch of one or more BatchAction sub-actions.
Length-1 batches represent single actions. Sub-actions are executed in array
order. After an action has been executed or cancelled the actions array is
emptied; metadata fields (proposer, timestamps, executed, cancelled) remain
readable for audit purposes.
struct QueuedAction {
address proposer;
uint48 queuedAt;
uint48 executableAt;
uint48 expiresAt;
bool executed;
bool cancelled;
BatchAction[] actions;
}
Properties
| Name | Type | Description |
|---|---|---|
| proposer | address | The account that queued the action. |
| queuedAt | uint48 | Timestamp at which the action was queued. |
| executableAt | uint48 | Timestamp at which the action can first be executed. |
| expiresAt | uint48 | The last timestamp at which the action can be executed; the execution window is [executableAt, expiresAt], both ends included. |
| executed | bool | Whether the action has been executed. |
| cancelled | bool | Whether the action has been cancelled. |
| actions | BatchAction[] | The sub-actions of the batch. |