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
• INLINECODE2 — publishes to on-chain registry (permanent)
• INLINECODE3 — registers package names on-chain
• INLINECODE4 — manages package publisher permissions

Safe commands: cannon build --dry-run, cannon inspect, cannon run, cannon test, cannon decode, cannon trace, INLINECODE11

Rules:

1. 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:

CODEBLOCK0

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 - INLINECODE16
• Foundry (forge, anvil, cast) - INLINECODE17
• Cannon CLI - INLINECODE18

Verify installation:
CODEBLOCK1

Quick Reference

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

CLI Commands

CODEBLOCK2

Package Reference Format

<package-name>:<version>@<preset>

Examples:

• - INLINECODE19
• INLINECODE20
• INLINECODE21

Cannonfile Syntax

Package Metadata & Includes

CODEBLOCK4

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

CODEBLOCK5

Deploy Contract

CODEBLOCK6

Invoke Function

CODEBLOCK7

Import/Clone Package

CODEBLOCK8

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

CODEBLOCK9

Access: INLINECODE28

Template Strings

Use ERB-style templates to reference values:

• - <%= settings.varName %> — settings
• INLINECODE30 — deployed contract address
• INLINECODE31 — contract ABI
• INLINECODE32 — imported contract

Actions

Action	Description
INLINECODE33	Deploy a contract
INLINECODE34

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)

CODEBLOCK10

On-Chain Deployment

⚠️ Always use --dry-run first to verify deployments before executing on real networks.

CODEBLOCK11

Testing

CODEBLOCK12

Use cannon-std in Forge tests:
CODEBLOCK13

Storage Locations

Directory	Contents
INLINECODE43	Package reference files
INLINECODE44

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.

CODEBLOCK14

Diamond Pattern (EIP-2535)

CODEBLOCK15

Linked Libraries

CODEBLOCK16

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

Trace

Get human-readable stack traces for transactions: CODEBLOCK18

Interact

Send transactions to deployed contracts through the CLI: CODEBLOCK19

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
INLINECODE50	Import existing artifacts into a deployment step (for migrations)
INLINECODE51

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

CODEBLOCK20

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. 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 <ipfs-hash>

   # Import each deployed contract/transaction
   cannon alter my-package --chain-id 1 import deploy MyContract 0x...txhash
   

1. 4. Verify by running build (no steps should execute): INLINECODE59

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

Issue	Solution
"deployment not found"	Package not published for this chain ID. Check INLINECODE60
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. 1. Develop contracts with Foundry
2. Write cannonfile.toml to define deployment
3. Build locally with cannon build (chain 13370)
4. Test with INLINECODE65
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 INLINECODE68
8. Publish with cannon publish ⚠️ PERMANENT ON-CHAIN

Key Files

File	Purpose
INLINECODE70	Package definition
INLINECODE71

Locked dependencies | | .cannon/ | Build cache (gitignored) | | deployments/ | Deployment artifacts |