Skill: dbeal-eth/cannon (version 2.26.0)

--- name: cannon description: Cannon package manager for Ethereum deployments. Use when building, testing, deploying, or inspecting Cannon packages. Covers cannonfile syntax, CLI commands (build, run, test, publish, inspect), actions (deploy, invoke, clone, pull, router, diamond), and package workflows. NOT for general Solidity development questions. --- # Cannon ## ⚠️ CRITICAL: Read This First **Some Cannon commands are IRREVERSIBLE and handle real value.** Be careful with: - `cannon build` (without `--dry-run`) — deploys contracts on real networks - `cannon publish` — publishes to on-chain registry (permanent) - `cannon register` — registers package names on-chain - `cannon publishers` — manages package publisher permissions Safe commands: `cannon build --dry-run`, `cannon inspect`, `cannon run`, `cannon test`, `cannon decode`, `cannon trace`, `cannon clean` Rules: 1. **Always use `--dry-run` first** — Simulate before executing on real networks 2. **Make every operation clear to the user** — Explain what will happen before running 3. **Confirm before deploying** — Never use a real private key without explicit approval 4. **Test locally first** — Use chain 13370 (Cannon Network) before target chains 5. **Protect private keys** — Use `CANNON_PRIVATE_KEY` env var or `--impersonate` (recommended) ## Model Recommendation **Use state-of-the-art models for Cannon tasks.** Deployment scripts handle real value — don't skimp on model quality. Prefer Claude, GPT-4, or equivalent high-capability models over cheaper alternatives. ## Schema Reference For complete cannonfile syntax validation and autocomplete, refer to the official JSON schemas: - **Full schema:** https://raw.githubusercontent.com/usecannon/cannon/refs/heads/dev/packages/lsp/src/schema.json - **Fragment schema:** https://raw.githubusercontent.com/usecannon/cannon/refs/heads/dev/packages/lsp/src/schema-fragment.json For editor validation, add the schema reference at the top of your `cannonfile.toml`: ```toml #:schema https://raw.githubusercontent.com/usecannon/cannon/refs/heads/dev/packages/lsp/src/schema.json name = "my-package" version = "1.0.0" ... ``` This enables autocomplete and validation in editors with TOML LSP support (like taplo). --- Cannon is a package manager and deployment system for Ethereum smart contracts. It uses declarative cannonfiles to define deployment workflows and supports both local development and on-chain deployments. ## Prerequisites Before using this skill, ensure these tools are installed: - **Node.js 18+** and **pnpm** - `npm install -g pnpm` - **Foundry** (forge, anvil, cast) - `curl -L https://foundry.paradigm.xyz | bash && foundryup` - **Cannon CLI** - `pnpm add -g @usecannon/cli` Verify installation: ```bash node --version && pnpm --version forge --version && anvil --version cannon --version ``` ## Quick Reference For complete CLI options, see [references/cli.md](references/cli.md). ### CLI Commands ```bash cannon build # Build package locally (starts anvil, deploys contracts) cannon run <pkg:ver> # Run a deployed package (shorthand: cannon <pkg:ver>) cannon test # Run forge tests with deployment context cannon inspect <pkg:ver> # View package details cannon publish # Publish to on-chain registry + IPFS ⚠️ IRREVERSIBLE cannon clean # Delete cache directories cannon verify # Verify contracts on Etherscan/Sourcify ``` ### Package Reference Format ``` <package-name>:<version>@<preset> ``` Examples: - `greeter-foundry:2.24.0` - `safe:1.4.1` - `synthetix-omnibus:3.1.4@main` ## Cannonfile Syntax ### Package Metadata & Includes ```toml name = "my-package" version = "1.0.0" description = "My package description" tags = ["defi", "token"] preset = "main" # Include additional files containing actions (for larger packages) include = ["./deposits.toml", "./withdrawals.toml"] ``` Use `include` to split large cannonfiles into multiple files. Included files use the fragment schema and can contain any actions (deploy, invoke, clone, etc.). Modern syntax uses `[var.label]` for settings (deprecated: `[setting.name]`). ### Variables ```toml [var.chainId] defaultValue = 1 [var.owner] defaultValue = "0x..." ``` ### Deploy Contract ```toml [deploy.MyContract] artifact = "MyContract" args = ["<%= settings.owner %>"] ``` ### Invoke Function ```toml [invoke.initialize] target = ["<%= contracts.MyContract.address %>"] func = "initialize" args = ["<%= settings.owner %>"] ``` ### Import/Clone Package ```toml [clone.safe] source = "safe:1.4.1" target = "safe" ``` **When to use clone vs import:** - **`clone`** — Use another package as a "blueprint" to deploy it anew. Always set `target` appropriately (same as source if you own it, or a new name if not). - **`import`** — Pull in data from an already-deployed package without re-deploying. ### Pull Data from Package ```toml [pull.usdc] source = "usdc:1.0.0@main" ``` Access: `<%= imports.usdc.contracts.USDC.address %>` ## Template Strings Use ERB-style templates to reference values: - `<%= settings.varName %>` — settings - `<%= contracts.ContractName.address %>` — deployed contract address - `<%= contracts.ContractName.abi %>` — contract ABI - `<%= imports.pkg.contracts.Contract.address %>` — imported contract ## Actions | Action | Description | |--------|-------------| | `deploy` | Deploy a contract | | `invoke` | Call a contract function | | `clone` | Deploy another package as a blueprint | | `import` | Pull data from an already-deployed package | | `pull` | (deprecated) Alias for import | | `var` | Define computed variables | | `router` | Create a router contract to bypass size limits (pairs well with UUPS proxy) | | `diamond` | Create an EIP-2535 Diamond with facets | ## Local Development **⚠️ Always use chain 13370 (Cannon Network) for local testing before deploying to target chains.** Default chain ID: **13370** (Cannon Network) ```bash # Build with local anvil cannon build # Build for specific chain cannon build --chain-id 1 --rpc-url $RPC_URL # Dry run (simulation only) cannon build --dry-run --impersonate-all # Run a package locally cannon run greeter-foundry:2.24.0 ``` ## On-Chain Deployment **⚠️ Always use `--dry-run` first to verify deployments before executing on real networks.** ```bash # Deploy to mainnet cannon build --chain-id 1 --rpc-url $RPC_URL --private-key $KEY # Publish to registry cannon publish --chain-id 1 --rpc-url $RPC_URL --private-key $KEY # For simulation before actual deploy cannon build --chain-id 1 --rpc-url $RPC_URL --dry-run ``` ## Testing ```bash # Run tests with forge cannon test # Test specific contract cannon test --match-path "test/MyContract.t.sol" ``` Use `cannon-std` in Forge tests: ```solidity import {Cannon} from "cannon-std/Test.sol"; contract MyTest is Cannon { function setUp() public { // Load deployed contracts address myContract = getAddress("MyContract"); } } ``` ## Storage Locations | Directory | Contents | |-----------|----------| | `~/.local/share/cannon/tags/` | Package reference files | | `~/.local/share/cannon/ipfs_cache/` | Cached IPFS artifacts | | `~/.local/share/cannon/build_results/` | Build outputs | | `~/.local/share/cannon/blobs/` | Large binary blobs | ## Common Patterns ### Router Pattern (Bypass Contract Size Limits) Create a router contract that efficiently passes calls to downstream contracts. Powerful when combined with a UUPS proxy. ```toml [deploy.CoreImplementation] artifact = "Core" [deploy.AnotherImplementation] artifact = "Another" [router.CoreRouter] dependencies = ["CoreImplementation", "AnotherImplementation"] ``` ### Diamond Pattern (EIP-2535) ```toml [deploy.Diamond] artifact = "Diamond" [deploy.FacetA] artifact = "FacetA" [deploy.FacetB] artifact = "FacetB" [diamond.Diamond] facets = ["FacetA", "FacetB"] ``` ### Linked Libraries ```toml [deploy.Library] artifact = "Library" [deploy.Contract] artifact = "Contract" libraries = { Library = "<%= contracts.Library.address %>" } ``` ## Debugging Tools Cannon provides commands to decode bytecode, trace transactions, and interact with deployed contracts. ### Decode Decode hex data (function calls, events, errors) using package ABIs: ```bash cannon decode synthetix-omnibus --chain-id 8453 --preset main 0x... ``` ### Trace Get human-readable stack traces for transactions: ```bash cannon trace <tx-hash> --chain-id 1 --rpc-url $RPC_URL ``` ### Interact Send transactions to deployed contracts through the CLI: ```bash cannon interact synthetix-omnibus --chain-id 8453 --contract CoreProxy ``` ## Package State Manipulation (`alter`) The `alter` command modifies existing Cannon packages outside the regular build process. Use for troubleshooting, migrations, or fixing broken package state. ⚠️ **Only use `alter` when no other option exists.** ### Subcommands | Command | Description | |---------|-------------| | `import` | Import existing artifacts into a deployment step (for migrations) | | `set-contract-address` | Change a contract's address in the deployment | | `mark-complete` | Mark a deployment step as complete | | `mark-incomplete` | Mark a deployment step as incomplete | | `set-url` | Update the deployment URL reference | | `set-misc` | Update miscellaneous data URL | | `clean-unused` | Remove unused deployment states | | `migrate-212` | Migrate packages from version 2.12 format | ### Example: Import existing deployment ```bash # Import a deployed contract by its creation transaction cannon alter my-package:1.0.0 --chain-id 1 import deploy MyContract 0x...txhash # Import an executed transaction cannon alter my-package:1.0.0 --chain-id 1 import invoke initialize 0x...txhash ``` ## GitOps Workflows Cannon supports GitOps-style deployments through the website interface. ### Queue with GitOps Deploy packages directly from GitHub repositories or IPFS hashes via the Cannon website: - Preview transactions before execution - View Git Diff of changes - Execute through Safe multisig wallets - Publish to registry after deployment See: https://usecannon.com/deploy ### Deployments Repository Create a dedicated Git repository for deployment configurations (separate from source code): - Keep smart contract source private while maintaining transparent deployments - Enable team collaboration on deployments - Maintain clear audit trail ## Migration from Other Tools Migrating from hardhat-deploy, Foundry scripts, or other deployment frameworks: 1. **Recreate deployment as cannonfile.toml** (manual but usually quick) 2. **Build locally** to create template: `cannon build` (save the IPFS hash) 3. **For each network**, import existing deployments: ```bash # Set the package URL to local template cannon alter my-package --chain-id 1 set-url <ipfs-hash> # Import each deployed contract/transaction cannon alter my-package --chain-id 1 import deploy MyContract 0x...txhash ``` 4. **Verify** by running build (no steps should execute): `cannon build --chain-id 1` ## Advanced Topics For detailed information on: - **CLI reference**: See [references/cli.md](references/cli.md) - **Cannonfile specification**: See [references/cannonfile.md](references/cannonfile.md) - **Testing patterns**: See [references/testing.md](references/testing.md) - **Registry and publishing**: See [references/registry.md](references/registry.md) ## Troubleshooting | Issue | Solution | |-------|----------| | "deployment not found" | Package not published for this chain ID. Check `--chain-id` | | Build fails with "artifact not found" | Run `forge build` first, or check `artifact` path | | IPFS timeout | Check network connection, may need IPFS gateway | | Registry publish fails | Verify you have write permissions for the package name | | **Wrong chain deployed** | Always double-check `--chain-id` — deployments cannot be undone | | **Published incorrect package** | Registry publishes are permanent — verify version and artifacts first | ## Development Workflow 1. **Develop contracts** with Foundry 2. **Write cannonfile.toml** to define deployment 3. **Build locally** with `cannon build` (chain 13370) 4. **Test** with `cannon test` 5. **Simulate** with `--dry-run` for target chain ⚠️ ALWAYS DO THIS FIRST 6. **Deploy** with `cannon build --chain-id <id>` ⚠️ IRREVERSIBLE on non-local networks (safe on chain 13370) 7. **Verify** contracts on Etherscan with `cannon verify` 8. **Publish** with `cannon publish` ⚠️ PERMANENT ON-CHAIN ## Key Files | File | Purpose | |------|---------| | `cannonfile.toml` | Package definition | | `cannonfile.lock` | Locked dependencies | | `.cannon/` | Build cache (gitignored) | | `deployments/` | Deployment artifacts |


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)