Architecture Overview

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• CLAUDE.md
• package.json
• test/invariants/PROPERTIES.md
• foundry.toml

Canon Guard (also referred to as Safer Safe) is a multisig enhancement solution designed to augment Safe smart accounts with increased security, transparency, and resilience. It minimizes reliance on external services by leveraging fully on-chain Actions contracts and dynamic timelocks to manage recurring and high-stakes transactions.

The system is built on top of the @safe-global/safe-contracts framework, introducing a layer of approval-based execution and time delays. This architecture ensures that transactions are not only multi-signed but also validated against specific patterns defined in "Action Builders" and subjected to configurable execution windows.

Sources: README.md:3-5, CLAUDE.md:7-10

Core System Components

The architecture consists of a primary entrypoint, an management hub for transaction logic, and various guard mechanisms.

Component Breakdown

Component	Description
SafeEntrypoint	The central contract for executing transactions on a Safe with time delays and approval mechanisms.
ActionHub	An abstract management contract for Action Builders, defining which transaction patterns are permitted.
Action Builders	Modular contracts (e.g., SimpleActions, CappedTokenTransfers) that define specific transaction logic.
SafeManageable	A base contract providing integration logic for Safe accounts.
EmergencyModeHook	A security mechanism used to pause system operations during critical incidents.
OnlyEntrypointGuard	A transaction guard ensuring that all Safe interactions occur strictly through the authorized entrypoint.

Sources: CLAUDE.md:14-20, test/invariants/PROPERTIES.md:5-10

Transaction Lifecycle and Flow

Transactions in Canon Guard follow a structured lifecycle: queueing, waiting (delay), and execution. This flow is governed by the relationship between the Entrypoint and Action Builders.

The diagram above illustrates the path of a transaction from initiation to final execution on the Safe account.

Sources: CLAUDE.md:14-20, test/invariants/PROPERTIES.md:31-35

Execution Delays

The system utilizes two primary delay types to balance security and flexibility:

• SHORT_TX_EXECUTION_DELAY: Used for pre-approved transactions or specific trusted builders.
• LONG_TX_EXECUTION_DELAY: The default delay for standard or high-risk transactions.
• TX_EXPIRY_DELAY: Ensures that queued transactions cannot be executed after a certain timeframe, preventing "stale" transaction execution.

Sources: test/invariants/PROPERTIES.md:27-30, test/invariants/PROPERTIES.md:46-51

Security and Invariants

The architecture enforces strict consistency between the queue state and the permissions granted to action builders.

Key Invariants

Invariant Category	Logic Description
Cap & Accounting	Cap limits (e.g., in CappedTokenTransfers) are never exceeded, even across epoch boundaries.
Approval Integrity	Queued transactions must correspond to builders with valid, non-expired approvals.
Timing Logic	expiresAt must always be greater than executableAt, and executableAt must be greater than or equal to queuedAt.
Queue Consistency	The queue array and transaction mapping must remain in sync; no duplicate builders are allowed in the queue.

Sources: test/invariants/PROPERTIES.md:14-41

Technical Implementation Details

The project uses a modern Solidity stack for deployment and verification.

Development Stack

• Solidity Version: 0.8.30 (per foundry.toml) or 0.8.29 (per CLAUDE.md).
• EVM Version: prague.
• Optimization: 10,000 runs with via_ir enabled for optimized profiles.
• Deployment: Uses CREATE3 for deterministic addressing across different chains like Ethereum and Optimism.

Sources: foundry.toml:13-22, CLAUDE.md:47-51, package.json:13-14

Directory Structure

src/
├── contracts/       # Core implementation (Entrypoint, Hubs, Builders)
└── interfaces/      # Solidity interface definitions
test/
├── unit/            # Isolated logic tests (using .tree/bulloak)
├── integration/     # Fork-based blockchain tests
└── invariants/      # Medusa fuzzing and Halmos symbolic execution

Sources: CLAUDE.md:24-30, package.json:15-21

Summary

Canon Guard's architecture transforms a standard Safe multisig into a more robust governance tool by enforcing on-chain transaction patterns through Action Builders and mandatory time delays. By utilizing a Guard-based approach, it ensures that no transaction bypasses the defined security parameters, while the modular Builder system allows for extensible functionality like capped transfers and claim mechanisms.