On-Chain Actions
Relevant source files
The following files were used as context for generating this wiki page:
On-Chain Actions represent a core architectural component of the Canon Guard (formerly Safer Safe) multisig solution. This system enhances standard Safe multisig security by utilizing fully on-chain "Action" contracts and dynamic timelocks. These actions allow for the definition of specific, verifiable transaction patterns that can be executed with granular control, reducing reliance on external services and simplifying the verification process for recurring transactions.
The system is built as a layer on top of Safe smart contracts, employing a modular approach where specific transaction types are encapsulated within dedicated "Action Builder" contracts. This architecture ensures that all execution logic is transparently hosted on-chain, allowing for rigorous validation through automated guards and approval mechanisms.
Sources: README.md:1-5, CLAUDE.md:5-10
Architecture and Components
The On-Chain Actions framework operates through a hierarchical relationship between the Safe entry point, management hubs, and specific action builders.
Core Component Overview
| Component | Description |
|---|---|
| SafeEntrypoint | The primary gateway for executing transactions with time delays and approval logic. |
| ActionHub | An abstract management contract used to coordinate and approve various Action Builders. |
| Action Builders | Specific contract implementations (e.g., SimpleActions, SimpleTransfers) that define transaction logic. |
| OnlyEntrypointGuard | A security contract ensuring transactions originate only from the authorized entry point. |
| EmergencyModeHook | A global security mechanism capable of pausing operations across action modules. |
Sources: CLAUDE.md:14-25, test/invariants/PROPERTIES.md:5-10
Transaction Flow Logic
The system distinguishes between standard and pre-approved actions. Transactions are typically queued, subject to specific delays, and then executed once the timelock expires.
The diagram above illustrates the path from transaction initiation through the varying delay mechanisms before final execution on the Safe.
Sources: CLAUDE.md:50-60, test/invariants/PROPERTIES.md:23-28
Action Builders and Hubs
Action Builders are the modular units of the system. They define the specific parameters and logic for on-chain interactions.
Supported Action Types
The repository identifies several specialized action builders:
- SimpleActions: General-purpose action logic.
- SimpleTransfers: Standardized token transfer logic.
- CappedTokenTransfers: Transfers governed by volume or value limits within specific epochs.
- AllowanceClaimor: Logic dedicated to managing and claiming token allowances.
Sources: test/invariants/PROPERTIES.md:6-12, CLAUDE.md:16-18
Security Constraints and Invariants
To ensure the integrity of On-Chain Actions, the system enforces several critical invariants during the queue and execution phases:
- Approval Validity: Queued transactions must correspond to builders or hubs with active, non-expired approvals.
- Timing Integrity: Transactions must follow a strict chronological order where
queuedAt<executableAt<expiresAt. - Cap Enforcement: For capped builders (like
CappedTokenTransfers), epoch-based limits are strictly enforced to prevent exceeding defined thresholds. - Queue Consistency: The system maintains sync between the queue array and the
transactionsInfomapping, ensuring no duplicate entries or orphaned builders.
Sources: test/invariants/PROPERTIES.md:15-38
Execution Lifecycle
The execution of an on-chain action is governed by specific delays configured in the entry point.
Delay Parameters
| Parameter | Purpose |
|---|---|
SHORT_TX_EXECUTION_DELAY | Used for pre-approved transactions or actions originating from trusted hubs. |
LONG_TX_EXECUTION_DELAY | The default delay for standard, non-pre-approved on-chain actions. |
TX_EXPIRY_DELAY | The window of time after becoming executable during which the action must be processed. |
Sources: test/invariants/PROPERTIES.md:43-52, CLAUDE.md:53-55
Transaction State Machine
The state machine above represents the lifecycle of an on-chain action from its initial queueing to final resolution.
Sources: test/invariants/PROPERTIES.md:23-38, CLAUDE.md:53-55
Implementation Details
The project uses solady utilities and Safe's core contracts as dependencies to manage these actions. Deterministic deployment via CREATE3 is used to ensure that Action Builders and Hubs can be deployed at predictable addresses across different chains.
"dependencies": {
"@safe-global/safe-contracts": "github:safe-global/safe-smart-account#b75e250",
"solady": "github:vectorized/solady#v0.1.26"
}
Sources: package.json:37-40, CLAUDE.md:51-52, remappings.txt:1-8
Summary
On-Chain Actions in Canon Guard provide a structured, delay-governed framework for multisig operations. By moving transaction logic into specific "Action Builder" contracts and enforcing strict timing and approval invariants, the system creates a transparent and highly secure environment for managing Safe assets. This approach minimizes the risk of "blind signing" and ensures that all recurring or high-value transactions are subject to verifiable on-chain rules.