Contribution Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
This document outlines the development standards, tooling, and verification processes for contributing to the Canon Guard project. Canon Guard is a multisig security enhancement layer utilizing on-chain Actions contracts and dynamic timelocks. Contributors are expected to follow specific testing strategies and code quality requirements to maintain the security and transparency of the system.
Sources: CLAUDE.md:1-10, README.md:1-5
Development Environment Setup
To contribute to Canon Guard, developers must configure a local environment with Solidity and Node.js tooling. The project utilizes Foundry for smart contract development and Yarn for dependency management.
Prerequisites and Installation
- Foundry: Install via the official installation script.
- Node Dependencies: Install using
yarn install. - Rust Dependencies: Install
lintspecviacargo install lintspec. - Environment: Copy
.env.exampleto.envand configure the required RPC endpoints and deployment variables.
Sources: README.md:7-12, CLAUDE.md:76-80
Build Profiles
The project supports different compilation profiles managed through foundry.toml.
| Command | Profile | Description |
|---|---|---|
yarn build | Default | Fast development build. |
yarn build:optimized | Optimized | Build using via-IR codegen for deployment. |
Sources: package.json:16-17, foundry.toml:16-24
Testing Strategy
Canon Guard employs a multi-layered testing strategy to ensure contract reliability and invariant safety.
Test Categories
- Unit Tests: Isolated tests found in
test/unit/. These often utilize.treefiles and thebulloaktool for specification. - Integration Tests: Fork-based tests in
test/integration/that simulate blockchain environments. - Invariant/Fuzzing: Uses Medusa to verify system properties over long sequences of operations.
- Symbolic Execution: Uses Halmos to mathematically prove contract properties.
Sources: CLAUDE.md:21-27, README.md:27-51
Execution Commands
The flow above illustrates the available testing paths for developers.
Sources: package.json:23-31, CLAUDE.md:33-40
Invariant Verification
Contributors modifying core logic in CanonGuard, ActionHub, or specific ActionBuilders must ensure that the following security invariants are maintained:
- Cap Invariants: Limits must never be exceeded across epoch boundaries.
- Timing Invariants:
expiresAt>executableAt, andexecutableAt>=queuedAt. - Approval Invariants: Queued transactions must have valid approvals from authorized hubs or builders.
Sources: test/invariants/PROPERTIES.md:1-25
Code Quality and Linting
Strict linting and formatting rules are enforced via husky and lint-staged.
Commit Standards
The project follows conventional commit messages, enforced by @commitlint/config-conventional.
Sources: commitlint.config.js:1, package.json:51-52
Linting Tools
| Tool | Purpose | Command |
|---|---|---|
| Forge Fmt | Solidity formatting | yarn lint:check |
| Solhint | Solidity linting | yarn lint:sol |
| Bulloak | .tree file verification | yarn lint:bulloak |
| Lintspec | Specialized Solidity checks | lintspec (triggered via lint-staged) |
Sources: package.json:19-22, package.json:34-40
Solidity Configuration
The project targets Solidity 0.8.30 with the prague EVM version. The optimizer is configured for 10,000 runs to balance deployment cost and execution efficiency.
Sources: foundry.toml:12-15, CLAUDE.md:60-63
Deployment and Verification
Contributions involving deployment scripts or infrastructure must use the established Foundry script patterns.
This sequence ensures secure handling of deployment keys and automated verification on Etherscan.
Sources: README.md:55-75, package.json:19-21
Deployment Targets
The project supports deployment to Ethereum and Optimism. Deployment logs and artifacts are stored in the ./broadcast directory.
Sources: README.md:73, CLAUDE.md:47-50
Conclusion
Following these guidelines ensures that all contributions to Canon Guard maintain the high security standards required for a multisig enhancement solution. Prioritize passing invariant tests and adhering to the established linting rules before submitting any pull requests.