Cannon

Cannon

⚠️ CRITICAL: Read This First

Some Cannon commands are IRREVERSIBLE and handle real value. Be careful with:

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:

For editor validation, add the schema reference at the top of your cannonfile.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:

Verify installation:

node --version && pnpm --version
forge --version && anvil --version
cannon --version

Quick Reference

For complete CLI options, see references/cli.md.

CLI Commands

cannon build              # Build package locally (starts anvil, deploys contracts)
cannon run       # Run a deployed package (shorthand: cannon )
cannon test               # Run forge tests with deployment context
cannon inspect   # 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

:@

Cannonfile Syntax

Package Metadata & Includes

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

[var.chainId]
defaultValue = 1
[var.owner]
defaultValue = "0x..."

Deploy Contract

[deploy.MyContract]
artifact = "MyContract"
args = ["<%= settings.owner %>"]

Invoke Function

[invoke.initialize]
target = ["<%= contracts.MyContract.address %>"]
func = "initialize"
args = ["<%= settings.owner %>"]

Import/Clone Package

[clone.safe]
source = "safe:1.4.1"
target = "safe"

When to use clone vs import:

Pull Data from Package

[pull.usdc]
source = "usdc:1.0.0@main"

Access: <%= imports.usdc.contracts.USDC.address %>

Template Strings

Use ERB-style templates to reference values:

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)

# 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.

# 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

# Run tests with forge
cannon test
Test specific contract
cannon test --match-path "test/MyContract.t.sol"

Use cannon-std in Forge tests:

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)

[deploy.CoreImplementation]
artifact = "Core"
[deploy.AnotherImplementation]
artifact = "Another"
[router.CoreRouter]
dependencies = ["CoreImplementation", "AnotherImplementation"]

Diamond Pattern (EIP-2535)

[deploy.Diamond]
artifact = "Diamond"
[deploy.FacetA]
artifact = "FacetA"
[deploy.FacetB]
artifact = "FacetB"
[diamond.Diamond]
facets = ["FacetA", "FacetB"]

Linked Libraries

[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

cannon decode synthetix-omnibus --chain-id 8453 --preset main 0x...

Trace

cannon trace  --chain-id 1 --rpc-url $RPC_URL

Interact

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

# 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

See: https://usecannon.com/deploy

Deployments Repository

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:

   # Set the package URL to local template
   cannon alter my-package --chain-id 1 set-url 
   # Import each deployed contract/transaction
   cannon alter my-package --chain-id 1 import deploy MyContract 0x...txhash
   

Advanced Topics

For detailed information on:

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 ⚠️ 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 |

Before using this skill, ensure these tools are installed:

Verify installation:

node --version && pnpm --version
forge --version && anvil --version
cannon --version

| 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 |