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:

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

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 \x3Cpkg:ver>      # Run a deployed package (shorthand: cannon \x3Cpkg:ver>)
cannon test               # Run forge tests with deployment context
cannon inspect \x3Cpkg: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

\x3Cpackage-name>:\x3Cversion>@\x3Cpreset>

Examples:

• greeter-foundry:2.24.0
• safe:1.4.1
• synthetix-omnibus:3.1.4@main

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 = ["\x3C%= settings.owner %>"]

Invoke Function

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

Import/Clone Package

[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

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

Access: \x3C%= imports.usdc.contracts.USDC.address %>

Template Strings

Use ERB-style templates to reference values:

• \x3C%= settings.varName %> — settings
• \x3C%= contracts.ContractName.address %> — deployed contract address
• \x3C%= contracts.ContractName.abi %> — contract ABI
• \x3C%= imports.pkg.contracts.Contract.address %> — imported contract

Actions

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

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.

[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 = "\x3C%= 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:

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

Trace

Get human-readable stack traces for transactions:

cannon trace \x3Ctx-hash> --chain-id 1 --rpc-url $RPC_URL

Interact

Send transactions to deployed contracts through the CLI:

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

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

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:

   # Set the package URL to local template
   cannon alter my-package --chain-id 1 set-url \x3Cipfs-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
• Cannonfile specification: See references/cannonfile.md
• Testing patterns: See references/testing.md
• Registry and publishing: See references/registry.md

Troubleshooting

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