Introduction to Canon Guard
Relevant source files
The following files were used as context for generating this wiki page:
Canon Guard (also referred to as Safer Safe) is a multisig security enhancement solution designed to minimize reliance on external services while simplifying the verification of recurring transactions. Built on top of Safe (formerly Gnosis Safe) smart contracts, it introduces fully on-chain "Actions" contracts and dynamic timelocks to ensure a transparent and resilient execution environment.
Sources: README.md:3-5, CLAUDE.md:5-7
The system aims to provide a safer execution path for transactions by implementing approval mechanisms, time delays, and specialized transaction patterns. By leveraging on-chain logic rather than off-chain coordination for specific action types, Canon Guard reduces the surface area for errors and unauthorized executions.
Sources: README.md:3-5, CLAUDE.md:11-17
Core Architecture
The Canon Guard architecture revolves around a centralized entrypoint that interacts with specialized "Action Builders" to execute transactions on a Safe. It utilizes a modular approach where different types of transaction logic are separated into distinct contracts.
Key Components
| Component | Description |
|---|---|
| SafeEntrypoint | The primary contract allowing transaction execution on a Safe with time delays and approval logic. |
| ActionHub | An abstract management layer for Action Builders, defining how specific transaction patterns are handled. |
| Action Builders | Implementation contracts for specific transaction types like SimpleActions or CappedTokenTransfers. |
| SafeManageable | Base contract providing integration functionality with the underlying Safe. |
| EmergencyModeHook | A security mechanism used to pause system operations during emergencies. |
| OnlyEntrypointGuard | A guard contract ensuring that transactions only originate from the authorized entrypoint. |
Sources: CLAUDE.md:11-17
High-Level System Flow
The following diagram illustrates how a transaction request moves from a user through the Canon Guard components to the final Safe execution.
The flow shows the validation path where the Entrypoint coordinates between Action Builders and the Safe while adhering to security constraints like Guards and Hooks.
Sources: CLAUDE.md:11-17, CLAUDE.md:53-57
Transaction Lifecycle and Security
Canon Guard implements a rigorous lifecycle for transactions, focusing on queuing, delays, and expiry to prevent "instant" malicious executions.
Execution Delays
Transactions are categorized by their risk level, which determines the required delay before execution:
- SHORT_TX_EXECUTION_DELAY: Used for pre-approved transactions or low-risk actions.
- LONG_TX_EXECUTION_DELAY: The default delay for standard queued transactions.
- TX_EXPIRY_DELAY: The window during which a transaction remains executable after its delay period has passed.
Sources: test/invariants/PROPERTIES.md:43-48, CLAUDE.md:53-57
Transaction States
The following sequence diagram outlines the process of queuing and executing a transaction:
This diagram demonstrates the mandatory waiting period and the validation checks performed at both the queuing and execution stages.
Sources: test/invariants/PROPERTIES.md:20-27, CLAUDE.md:11-13
Safety Invariants
The system is designed to maintain specific security properties even under adversarial conditions, tested through symbolic execution and fuzzing.
- Cap & Accounting: Limits (caps) defined in hubs must never be exceeded, even across epoch boundaries.
- Approval Consistency: Queued transactions must only exist for builders that have valid, non-expired approvals.
- Timing Integrity: The relationship
queuedAt <= executableAt < expiresAtmust always hold true. - Queue Integrity: The internal queue must remain free of duplicates and synchronized with the transaction mapping.
Sources: test/invariants/PROPERTIES.md:10-36, CLAUDE.md:42-47
Technical Implementation Details
Development Environment
Canon Guard uses the Foundry toolchain for development, testing, and deployment.
| Tool | Purpose |
|---|---|
| Forge | Compiling, testing, and deploying Solidity contracts. |
| Medusa | Fuzzing campaign for invariant testing. |
| Halmos | Symbolic execution for formal verification. |
| Bulloak | Checking .tree files for unit test specifications. |
Sources: package.json:11-26, README.md:10-35, CLAUDE.md:42-47
Deployment and Configuration
The project supports multi-chain deployments, specifically targeting Ethereum and Optimism. It uses CREATE3 for deterministic address deployment to ensure consistent contract addresses across different networks.
Sources: README.md:53-65, CLAUDE.md:53-57, foundry.toml:34-36
Summary
Canon Guard provides a structured, on-chain framework for Safe multisig operations. By moving transaction logic into verifiable Action Builders and enforcing strictly timed execution windows through a central Entrypoint, it significantly reduces the risks associated with manual multisig management and off-chain coordination.
Sources: README.md:3-5, CLAUDE.md:5-7