### Install and Verify Foundry

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/setup.mdx

Instructions for installing Foundry, a prerequisite for Cannon development, and verifying its successful installation using the command line. Foundry provides essential tools for smart contract development.

```bash
curl -L https://foundry.paradigm.xyz | bash
```

```bash
foundry --version
```

--------------------------------

### Initialize shadcn project with CLI

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/example.mdx

Executes the `shadcn` CLI `init` command to set up a new project, installing dependencies and configuring `tailwind.config.js` and CSS variables.

```bash
npx shadcn@latest init
```

--------------------------------

### Run Next.js Development Server

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/README.md

Commands to start the local development server for a Next.js application, allowing you to view and test the project in a browser. The server typically runs on http://localhost:3000.

```bash
npm run dev
# or
yarn dev
# or
pnpm dev
```

--------------------------------

### Install Cannon CLI Globally

Source: https://github.com/usecannon/cannon/blob/dev/examples/router-architecture/README.md

This command installs the Cannon command-line interface globally on your system, allowing you to execute `cannon` commands from any directory. It's a prerequisite for working with Cannon projects.

```bash
npm i -g @usecannon/cli
```

--------------------------------

### Install Dependencies and Build Project with pnpm

Source: https://github.com/usecannon/cannon/blob/dev/packages/safe-app-backend/README.md

This command sequence uses pnpm to first install all required project dependencies. Following installation, it builds the application, compiling source code and preparing the distribution files for execution. This step is essential before running the backend service.

```pnpm
pnpm i
pnpm run build
```

--------------------------------

### shadcn init CLI Command Reference

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/example.mdx

Detailed documentation for the `shadcn init` command, including its arguments and available options for project initialization.

```APIDOC
Usage: shadcn init [options] [components...]

initialize your project and install dependencies

Arguments:
  components         the components to add or a url to the component.

Options:
  -d, --defaults    use default values i.e new-york, zinc and css variables. (default: false)
  -f, --force       force overwrite of existing components.json. (default: false)
  -y, --yes         skip confirmation prompt. (default: false)
  -c, --cwd <cwd>   the working directory. defaults to the current directory.
  -h, --help       display help for command
```

--------------------------------

### Install Cannon CLI globally

Source: https://github.com/usecannon/cannon/blob/dev/examples/diamond-architecture/README.md

This command installs the Cannon command-line interface globally on your system, allowing you to use Cannon commands from any directory. It is a prerequisite for building or deploying Cannon projects.

```bash
npm i -g @usecannon/cli
```

--------------------------------

### Start the Safe App Backend Service with pnpm

Source: https://github.com/usecannon/cannon/blob/dev/packages/safe-app-backend/README.md

Once the project dependencies are installed and the application is built, this command initiates the Safe App Backend service. It uses pnpm to run the configured start script, making the backend operational and ready to process requests.

```pnpm
pnpm start
```

--------------------------------

### Install and Verify Cannon CLI

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/setup.mdx

Commands to install the Cannon Command-Line Interface (CLI) using different popular package managers (pnpm, npm, yarn). The CLI is crucial for deploying, upgrading, and configuring protocols. Instructions for verifying the installation are also included.

```pnpm
pnpm add -g @usecannon/cli
```

```npm
npm install -g @usecannon/cli
```

```yarn
yarn global add @usecannon/cli
```

```bash
cannon --version
```

--------------------------------

### shadcn init interactive configuration

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/example.mdx

Shows the interactive prompts presented by the `shadcn init` command for configuring `components.json`, including style, base color, and CSS variables.

```txt
Which style would you like to use? › New York
Which color would you like to use as base color? › Zinc
Do you want to use CSS variables for colors? › no / yes
```

--------------------------------

### shadcn add CLI Command Reference

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/example.mdx

Detailed documentation for the `shadcn add` command, including its arguments and available options for adding components to a project.

```APIDOC
Usage: shadcn add [options] [components...]

add a component to your project

Arguments:
  components         the components to add or a url to the component.

Options:
  -y, --yes          skip confirmation prompt. (default: false)
  -o, --overwrite    overwrite existing files. (default: false)
  -c, --cwd <cwd>    the working directory. defaults to the current directory.
  -a, --all          add all available components. (default: false)
  -p, --path <path>  the path to add the component to.
  -h, --help         display help for command
```

--------------------------------

### Install Cannon Standard Library for Foundry

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/test-with-cannon.mdx

This command installs the `cannon-std` helper library, which provides utilities for accessing build data within Foundry tests, using the `forge install` command.

```bash
forge install usecannon/cannon-std
```

--------------------------------

### Initialize shadcn project in monorepo

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/example.mdx

Demonstrates how to initialize a `shadcn` project within a specific workspace of a monorepo using the `--cwd` option.

```bash
npx shadcn@latest init -c ./apps/www
```

--------------------------------

### shadcn add interactive component selection

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/example.mdx

Illustrates the interactive prompt for selecting components when using the `shadcn add` command, allowing users to choose from a list of available components.

```txt
Which components would you like to add? › Space to select. A to toggle all.
Enter to submit.

◯  accordion
◯  alert
◯  alert-dialog
◯  aspect-ratio
◯  avatar
◯  badge
◯  button
◯  calendar
◯  card
◯  checkbox
```

--------------------------------

### Install or Upgrade Cannon CLI

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/debug.mdx

Instructions to install or upgrade the Cannon command-line interface globally using npm, which is a prerequisite for using Cannon's debugging features.

```bash
npm i -g @usecannon/cli
```

--------------------------------

### Add shadcn components with CLI

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/example.mdx

Executes the `shadcn` CLI `add` command to incorporate new components and their dependencies into an existing project.

```bash
npx shadcn@latest add [component]
```

--------------------------------

### Preview Website Updates Locally

Source: https://github.com/usecannon/cannon/blob/dev/README.md

This command navigates to the website package directory and starts the development server. It allows developers to preview changes made to the Cannon website locally, enabling real-time feedback during development.

```bash
cd ./packages/website && pnpm dev
```

--------------------------------

### Install Cannon CLI

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/router.mdx

Installs or upgrades the Cannon command-line interface globally, providing access to Cannon's functionalities.

```bash
npm i -g @usecannon/cli
```

--------------------------------

### Install Cannon CLI using npm

Source: https://github.com/usecannon/cannon/blob/dev/packages/cli/README.md

This command installs the Cannon Command Line Interface globally on your system using npm, making the 'cannon' command available from any directory.

```bash
npm i -g @usecannon/cli
```

--------------------------------

### Add shadcn component in monorepo

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/example.mdx

Demonstrates how to add a `shadcn` component to a specific workspace within a monorepo using the `--cwd` option.

```bash
npx shadcn@latest add alert-dialog -c ./apps/www
```

--------------------------------

### Deploy Cannon project to a live network

Source: https://github.com/usecannon/cannon/blob/dev/examples/diamond-architecture/README.md

This command deploys the Cannon project to a specified live blockchain network. You must provide the chain ID of the target network and a private key for the deployment account. Remember to replace `<0xPRIVATE_KEY>` with your actual private key.

```bash
cannon build --chain-id 10 --private-key <0xPRIVATE_KEY>
```

--------------------------------

### Deploy Cannon Project to Live Network

Source: https://github.com/usecannon/cannon/blob/dev/examples/router-architecture/README.md

This command builds and deploys the Cannon project to a specified live blockchain network. It requires a chain ID to identify the target network and a private key for authentication and signing deployment transactions.

```bash
cannon build --chain-id 10 --private-key <0xPRIVATE_KEY>
```

--------------------------------

### Build Cannon project locally

Source: https://github.com/usecannon/cannon/blob/dev/examples/diamond-architecture/README.md

This command builds the Cannon project defined in your cannonfile locally. It compiles and prepares the project for deployment or testing without interacting with a live blockchain network.

```bash
cannon build
```

--------------------------------

### Example Counter Smart Contract

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/create-a-project.mdx

This Solidity smart contract, typically generated by Forge, provides a basic 'Counter' functionality with public functions to set and increment a numerical value.

```solidity
// ./src/Counter.sol

// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.13;

contract Counter {
    uint256 public number;

    function setNumber(uint256 newNumber) public {
        number = newNumber;
    }

    function increment() public {
        number++;
    }
}
```

--------------------------------

### Cannon Local Node Startup Output

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/build-with-cannon.mdx

This output confirms that Cannon has successfully started a local blockchain node (Anvil) and deployed the specified package. It also provides helpful keyboard shortcuts for interacting with the local node, such as viewing logs or interacting with contracts.

```bash
Starting local node...

Anvil instance running on: http://127.0.0.1:64228

learn-cannon:0.0.1@main has been deployed to a local node.

Press h to see help information for this command.
Press a to toggle displaying the logs from your local node.
Press i to interact with contracts via the command line.
Press v to toggle display verbosity of transaction traces as they run.
```

--------------------------------

### Install Project Dependencies with pnpm

Source: https://github.com/usecannon/cannon/blob/dev/README.md

This command installs all necessary dependencies for the Cannon monorepo from the root directory. It utilizes pnpm, a fast and disk space efficient package manager, to manage project dependencies.

```bash
pnpm i
```

--------------------------------

### Example Conventional Commit Messages

Source: https://github.com/usecannon/cannon/blob/dev/CONTRIBUTING.md

Provides concrete examples of valid commit messages adhering to the Conventional Commits standard used in the Cannon project. These examples demonstrate how to structure simple commits (e.g., documentation updates) and more complex ones (e.g., bug fixes with detailed explanations) including the header and body components, ensuring consistency and clarity in the project's commit history.

```APIDOC
docs(changelog): update changelog
```

```APIDOC
fix(release): need to depend on latest hardhat

The version in our package.json gets copied to the one we publish, and users need the latest of these dependencies.
```

--------------------------------

### Build Cannon Project Locally

Source: https://github.com/usecannon/cannon/blob/dev/examples/router-architecture/README.md

This command builds the Cannon project defined in your cannonfile locally. It compiles contracts and prepares artifacts without deploying them to a live blockchain network, useful for local development and testing.

```bash
cannon build
```

--------------------------------

### Install Hardhat Cannon Plugin via npm

Source: https://github.com/usecannon/cannon/blob/dev/packages/hardhat-cannon/README.md

Installs the `hardhat-cannon` npm package, which provides the Cannon Hardhat plug-in functionality for your project.

```bash
npm install hardhat-cannon
```

--------------------------------

### Cannon Build Output: Foundry Project Compilation

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/build-with-cannon.mdx

This snippet shows the initial phase of Cannon's build process, where it compiles smart contracts using Foundry and starts a local Anvil blockchain instance for development and testing.

```bash
Building the foundry project...
forge build succeeded

Anvil instance running on: http://127.0.0.1:59576
```

--------------------------------

### Node.js Heap Overflow Error Log Example

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/troubleshooting.mdx

An example log output from a Node.js application indicating a 'JavaScript heap out of memory' error, typically occurring when the application attempts to allocate more memory than available. This often happens with large build processes.

```text
Executing [invoke.doSomething]...

<--- Last few GCs --->

[30530:0xff72ac4c0000]   387503 ms: Mark-Compact 4040.7 (4128.9) -> 4023.9 (4132.1) MB, pooled: 0 MB, 950.20 / 0.00 ms  (average mu = 0.146, current mu = 0.108) allocation failure; scavenge might not succeed
[30530:0xff72ac4c0000]   388582 ms: Mark-Compact 4039.7 (4132.1) -> 4021.7 (4128.6) MB, pooled: 4 MB, 1049.12 / 0.00 ms  (average mu = 0.089, current mu = 0.028) allocation failure; scavenge might not succeed


<--- JS stacktrace --->

FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory
----- Native stack trace -----

 1: 0xe07548 node::OOMErrorHandler(char const*, v8::OOMDetails const&) [/usr/bin/node]
 2: 0x11d041c v8::Utils::ReportOOMFailure(v8::internal::Isolate*, char const*, v8::OOMDetails const&) [/usr/bin/node]
 3: 0x11d05cc v8::internal::V8::FatalProcessOutOfMemory(v8::internal::Isolate*, char const*, v8::OOMDetails const&) [/usr/bin/node]
 4: 0x13f4e5c  [/usr/bin/node]
 5: 0x13f4e8c  [/usr/bin/node]
 6: 0x140c860  [/usr/bin/node]
 7: 0x140f44c  [/usr/bin/node]
 8: 0x1bcc924  [/usr/bin/node]
```

--------------------------------

### Publish Cannon Package to Registry

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/migrate.mdx

This command publishes the specified Cannon package to the Cannon registry for a given chain ID. Publishing makes the package available for others to use or reference, completing the migration process for a particular network.

```shell
cannon publish <my-package> --chain-id <chain id>
```

--------------------------------

### Common Hardhat Project Tasks and Utilities

Source: https://github.com/usecannon/cannon/blob/dev/examples/sample-hardhat-project/README.md

This snippet provides a collection of frequently used shell commands for interacting with a Hardhat project. It includes commands for listing accounts, compiling contracts, cleaning artifacts, running tests, starting a local Hardhat node, accessing help, generating gas reports, checking code coverage, executing deployment scripts, and performing linting and formatting across various file types (JavaScript, TypeScript, Solidity, JSON, Markdown).

```shell
npx hardhat accounts
npx hardhat compile
npx hardhat clean
npx hardhat test
npx hardhat node
npx hardhat help
REPORT_GAS=true npx hardhat test
npx hardhat coverage
npx hardhat run scripts/deploy.ts
TS_NODE_FILES=true npx ts-node scripts/deploy.ts
npx eslint '**/*.{js,ts}'
npx eslint '**/*.{js,ts}' --fix
npx prettier '**/*.{json,sol,md}' --check
npx prettier '**/*.{json,sol,md}' --write
npx solhint 'contracts/**/*.sol'
npx solhint 'contracts/**/*.sol' --fix
```

--------------------------------

### Example Output of Cannon Test Execution

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/test-with-cannon.mdx

This snippet shows the typical console output after successfully running `cannon test`. It includes compilation status, individual test results (pass/fail), and a summary of the test suite execution.

```bash
Writing deployment artifacts to ./deployments/test
[⠊] Compiling...
No files changed, compilation skipped

Ran 2 tests for test/Counter.t.sol:CounterTest
[PASS] testFuzz_SetNumber(uint256) (runs: 256, μ: 31054, ~: 31288)
[PASS] test_Increment() (gas: 31303)
Suite result: ok. 2 passed; 0 failed; 0 skipped; finished in 19.96ms (11.97ms CPU time)

Ran 1 test suite in 135.12ms (19.96ms CPU time): 2 tests passed, 0 failed, 0 skipped (2 total tests)
forge exited with code 0
```

--------------------------------

### Interact with Protocols via Cannon CLI

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/debug.mdx

Example of initiating an interactive session with a protocol using the Cannon CLI. This allows users to call view functions and send transactions directly from the command line, similar to a package explorer's interact tab.

```bash
cannon interact synthetix --chain-id 1 --rpc-url https://ethereum.publicnode.com
```

--------------------------------

### Deploy Cannon Project to Sepolia Network

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/deploy-onchain.mdx

Deploys a Cannon project to the specified live blockchain network (Sepolia in this example). This command executes the actual on-chain transactions using the provided RPC URL and private key, making the protocol live on the network.

```bash
cannon build --rpc-url https://rpc2.sepolia.org --private-key 0xd8...ad
```

--------------------------------

### Run Development Version of Cannon CLI

Source: https://github.com/usecannon/cannon/blob/dev/README.md

This command navigates into the CLI package directory and then starts the development version of the Cannon CLI. It allows developers to test local changes to the CLI with a specified package and version, facilitating iterative development.

```bash
cd ./packages/cli && pnpm start -- <package:version>
```

--------------------------------

### Example: Cannon Package Not Found Error

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/troubleshooting.mdx

Illustrates a common error message displayed when a Cannon package cannot be located, often due to misspellings, incorrect chain IDs, or deployment issues. It indicates that the specified deployment does not exist for the given network.

```bash
> cannon run reye
Error: deployment not found: reye:latest@main. please make sure it exists for the network 13370
```

--------------------------------

### Import Existing Artifacts into Cannon Package

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/alter.mdx

Example of using `cannon alter import` to bring existing deployed contract artifacts into a specified step within a Cannon package.

```bash
cannon alter mypackage:1.0.0@main import deploy.MyContract MyContract --chain-id 1
```

--------------------------------

### Example: Cannon RPC Connection Error (BlockNotFoundError)

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/troubleshooting.mdx

Demonstrates an unusual RPC error, specifically a 'BlockNotFoundError', which often indicates an issue with the configured Ethereum RPC provider. This can happen when the RPC cannot find a referenced block hash.

```bash
Executing [invoke.setSomething]...
⚠️ Skipping [invoke.setSomething] (BlockNotFoundError: Block at hash "0x532f8ec74bc0e43c050b4c9b51a11a6e6f2e81dcf199c45e96601200fa09af49" could not be found.
```

--------------------------------

### Alter Subpackage Contract Address in Cannon

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/alter.mdx

Example of using `cannon alter set-contract-address` with the `--subpkg` option to modify a contract's address within a nested subpackage.

```bash
cannon alter mypackage:1.0.0@main set-contract-address MyContract 0x1234567890123456789012345678901234567890 --chain-id 1 --subpkg clone.dependency
```

--------------------------------

### Update Contract Address in Cannon Package

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/alter.mdx

Example of using `cannon alter set-contract-address` to change a contract's address within a specified Cannon package and chain ID.

```bash
cannon alter mypackage:1.0.0@main set-contract-address MyContract 0x1234567890123456789012345678901234567890 --chain-id 1
```

--------------------------------

### Trace Transaction Execution with Cannon

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/debug.mdx

Demonstrates using Cannon's 'trace' command to get a full stack trace for a transaction, whether it resulted in an error or not. It accepts a transaction hash or hex-encoded transaction data and allows simulation under different conditions, requiring an archive node for historical blocks.

```bash
cannon trace --chain-id 10 synthetix-omnibus 0x2fb8ff2400000000000000000000000000000000000000000000000000000000000000010000000000000000000000008700daec35af8ff88c16bdf0418774cb3d7599b4 --to 0xffffffaEff0B96Ea8e4f94b2253f31abdD875847 --rpc-url https://optimism.publicnode.com
```

--------------------------------

### Example: Cannon IPFS Resolution Error

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/troubleshooting.mdx

Shows an error message indicating a problem with downloading Cannon package data from IPFS, typically due to artifacts not being properly pinned to the IPFS network or network timeouts. This error suggests the artifact is inaccessible.

```bash
> cannon inspect ipfs://QmdDu3qvRVyBuCmWygy5g17tE4ZpcZ9AMWaUuUweTUJCNx
Error: could not download cannon package data from "QmdDu3qvRVyBuCmWygy5g17tE4ZpcZ9AMWaUuUweTUJCNx": AxiosError: Request failed with status code 404
```

--------------------------------

### Build Cannon Package for Network Validation

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/migrate.mdx

This command builds the Cannon package for a specified chain ID. Its primary purpose is to validate the package's health and ensure that no steps are unexpectedly executed, especially after importing existing deployments from a previous framework.

```shell
cannon build --chain-id <chain id>
```

--------------------------------

### Reference AccessManager Artifact in Cannonfile

Source: https://github.com/usecannon/cannon/blob/dev/examples/foundry-artifacts/README.md

This TOML configuration snippet illustrates how to declare an external contract artifact, 'AccessManager', within a 'cannonfile.toml'. It specifies the artifact's name and provides initial arguments for its deployment or configuration within the Cannon project.

```TOML
 [contract.AccessManager]
 artifact = "AccessManager"
 args = ["0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"]
```

--------------------------------

### Alter Cannon Package for Network Configuration

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/migrate.mdx

This command creates or modifies a Cannon package for a specific network, linking it to a local network template using its URL. It's the first step in adapting a built package for a target chain, allowing you to set network-specific parameters.

```shell
cannon alter <my-package> --chain-id <chain id> set-url <local network pkg url>
```

--------------------------------

### Initialize Foundry Project

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/router.mdx

Sets up a new Foundry project, a development framework for Ethereum, which will host the smart contracts.

```bash
forge init
```

--------------------------------

### Initialize Foundry Project

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/create-a-project.mdx

This command initializes a new Foundry project, setting up the basic directory structure and configuration files required for development.

```bash
forge init
```

--------------------------------

### Decode Hex Error Data with Cannon

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/debug.mdx

Example of using Cannon's 'decode' command to interpret a raw hex string representing error data from a protocol. This command helps in understanding function calls, outputs, event data, and error data when traditional ABI tools are not sufficient.

```bash
cannon decode synthetix-omnibus --chain-id 84531 --preset competition 0xb87daa32000000000000000000000000000000000000000000000000000000006502188b00000000000000000000000000000000000000000000000000000000650218190000000000000000000000000000000000000000000000000000000065021855
```

--------------------------------

### Set up Cannon for building protocols and packages

Source: https://github.com/usecannon/cannon/blob/dev/packages/cli/README.md

This command prepares your environment for deploying custom protocols and creating your own Cannon packages (Cannonfiles). It's the first step for developers looking to build on the Cannon platform.

```bash
cannon setup
```

--------------------------------

### Run Hardhat CLI Commands

Source: https://github.com/usecannon/cannon/blob/dev/examples/sample-hardhat-toolbox/README.md

Demonstrates common Hardhat command-line interface tasks for development, testing, and deployment, including help, testing, gas reporting, node execution, and script deployment.

```shell
npx hardhat help
npx hardhat test
REPORT_GAS=true npx hardhat test
npx hardhat node
npx hardhat run scripts/deploy.ts
```

--------------------------------

### Initiate Cannon Package Publishing

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/publish.mdx

Demonstrates the `cannon publish` command syntax, specifying the package name, version, and the target blockchain chain ID for deployment.

```bash
cannon publish learn-cannon:0.0.1 --chain-id 11155111
```

--------------------------------

### Cannon Build Output: Package Initialization

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/build-with-cannon.mdx

This output illustrates Cannon initializing a new package, displaying details such as the package name, version, preset, and the chain ID it's building for, along with the Anvil instance URL.

```bash
Checking for existing package...
Starting fresh build...

Initializing new package...
Name: learn-cannon
Version: 0.0.1
Preset: main (default)
Chain ID: 13370

Building the chain (ID 13370) via http://127.0.0.1:59576/...
```

--------------------------------

### Run a Cannon package from the registry

Source: https://github.com/usecannon/cannon/blob/dev/packages/cli/README.md

This command executes a specified package, such as 'greeter', directly from the Cannon registry. It allows users to quickly run pre-built Cannon protocols.

```bash
cannon greeter
```

--------------------------------

### Build Cannon Project

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/router.mdx

Compiles and builds the Cannon project based on the configurations specified in the `cannonfile.toml`, preparing it for deployment.

```bash
cannon build
```

--------------------------------

### Define Cannonfile Configuration

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/create-a-project.mdx

This TOML configuration defines the essential metadata for your Cannon project, including its name, version, and a brief description, acting as a deployment plan.

```toml
name = 'learn-cannon'
version = '0.0.1'
description = 'Cannon learn - Sample Foundry Project'
```

--------------------------------

### Create New Project Directory

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/create-a-project.mdx

This command creates a new directory for your Cannon project and navigates into it, preparing your workspace.

```bash
mkdir learn-cannon
cd learn-cannon
```

--------------------------------

### Deploy Contract to Ethereum Test Network

Source: https://github.com/usecannon/cannon/blob/dev/examples/sample-hardhat-project/README.md

This command demonstrates how to deploy a smart contract to a specified Ethereum test network, such as Ropsten, using Hardhat. It executes a deployment script, typically written in TypeScript, to manage the contract deployment process. This step is a prerequisite for verifying the contract on Etherscan.

```shell
hardhat run --network ropsten scripts/sample-script.ts
```

--------------------------------

### Build Cannon Package with `cannon build` (Foundry)

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/build-with-cannon.mdx

Illustrates the process of building a Cannon package using the `cannon build` command, which prepares a local image based on `cannonfile.toml`. The provided output showcases a successful build for a Foundry project, detailing contract deployment, transaction costs, and IPFS deployment data. An optional `--keep-alive` flag is mentioned for persistent node execution.

```bash
cannon build
```

```bash
Building the foundry project...
forge build succeeded

Anvil instance running on: http://127.0.0.1:59576

Checking for existing package...
Starting fresh build...

Initializing new package...
Name: learn-cannon
Version: 0.0.1
Preset: main (default)
Chain ID: 13370

Building the chain (ID 13370) via http://127.0.0.1:59576/...

Executing [deploy.Counter]...
  ✔ Successfully deployed Counter
  Contract Address: 0xACEbBC3E0D8BC1bB13a35b40f3714A7c78C158f7
  Transaction Hash: 0x0abfae8229490349f80230414259ca1fcc60eecead61212733154fb3c80feae1
  Transaction Cost: 0.000213466 ETH (106,733 gas)

Executing [var.ProtocolSettings]...
  Setting: number = 420

Executing [invoke.SetNumber]...
  ✔ Successfully called setNumber(420)
  Signer: 0xEB045D78d273107348b0300c01D29B7552D622ab
  Contract Address: 0xACEbBC3E0D8BC1bB13a35b40f3714A7c78C158f7
  Transaction Hash: 0x4ceea742fecb9ba8adce1d364beb01f17dc93125b740e532bbdd8ff1068b96eb
  Transaction Cost: 0.00007268124780963 ETH (43,506 gas)

Writing upgrade info...
💥 learn-cannon:0.0.1@main built for Cannon (Chain ID: 13370)
This package can be run locally and cloned in cannonfiles.

Package data has been stored locally
╔═════════════════╤═══════════════════════════════════════════════════════╗
║ Deployment Data │ ipfs://QmVpLGJMKqAd5hD3LgM3oh37NfbmzTS9FUyjCZx1LcB8yW ║
╟─────────────────┼───────────────────────────────────────────────────────╢
║ Package Code    │ ipfs://QmVhGysWPz2toaL9FVWoyTTgp2Atf4UMESz4Dj5dKvRhWb ║
╟─────────────────┼───────────────────────────────────────────────────────╢
║ Metadata        │ ipfs://QmRsYpSHrvjVmktXJtLYZbmiHD8GNKp64qxoZ2hbGcqEDf ║
╚═════════════════╧═══════════════════════════════════════════════════════╝

Publish learn-cannon:0.0.1 to the registry and pin the IPFS data to
> cannon publish learn-cannon:0.0.1 --chain-id 13370

Run this package
> cannon learn-cannon:0.0.1
```

--------------------------------

### Provide Private Key for Publishing

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/publish.mdx

Shows the CLI prompt requesting the private key of the wallet that will be used to sign the transaction for publishing the Cannon package.

```bash
? Enter the private key of the address you want to use:
```

--------------------------------

### Cannon Build Output: Action Execution Details

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/build-with-cannon.mdx

This snippet details the execution of various actions defined in `cannonfile.toml`, including contract deployment, variable setting, and function invocation. It provides critical information like contract addresses, transaction hashes, and gas costs for each executed action.

```bash
Executing [deploy.Counter]...
  ✔ Successfully deployed Counter
  Contract Address: 0xACEbBC3E0D8BC1bB13a35b40f3714A7c78C158f7
  Transaction Hash: 0x0abfae8229490349f80230414259ca1fcc60eecead61212733154fb3c80feae1
  Transaction Cost: 0.000213466 ETH (106,733 gas)

Executing [var.ProtocolSettings]...
  Setting: number = 420

Executing [invoke.SetNumber]...
  ✔ Successfully called setNumber(420)
  Signer: 0xEB045D78d273107348b0300c01D29B7552D622ab
  Contract Address: 0xACEbBC3E0D8BC1bB13a35b40f3714A7c78C158f7
  Transaction Hash: 0x4ceea742fecb9ba8adce1d364beb01f17dc93125b740e532bbdd8ff1068b96eb
  Transaction Cost: 0.00007268124780963 ETH (43,506 gas)
```

--------------------------------

### Run Cannon Project Locally

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/router.mdx

Executes the Cannon project, deploying the defined contracts and router. The `--registry-priority local` option ensures that the locally built version of the package is used.

```bash
cannon sample-router-project --registry-priority local
```

--------------------------------

### Define Cannonfile Actions for Counter Contract Deployment

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/create-a-project.mdx

This TOML configuration defines a Cannon package and specifies actions for deploying and interacting with a 'Counter' smart contract. It includes package metadata (name, version, description), defines a variable 'number' under 'ProtocolSettings', deploys the 'Counter' contract, and then invokes the 'setNumber' function on the deployed contract, using the previously defined variable as an argument. Cannon automatically resolves dependencies and executes actions in the correct order.

```toml
# The top of the file defines basic package information 
name = "learn-cannon"

# The version can be any human readable value representative of your project's version. Note that cannon internally tracks the version
version = "0.0.1"

# Longer, human readable description of the package
description = "Sample Cannon + Foundry Project"

# Each of the square bracketed headers below defines a new section defining a particular resource that should be invoked for the deployment.
# These can be specified in any order, irrespective of dependencies. Cannon will automatically execute steps in the order that is required to complete the deployment.
[var.ProtocolSettings]
number = "420"

[deploy.Counter]
artifact = "Counter"

[invoke.SetNumber]
target = ["Counter"]
func = "setNumber"
args = ["<%= settings.number %>"]
```

--------------------------------

### Select Cannon Registry Network

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/publish.mdx

Illustrates the interactive CLI prompt for choosing the preferred blockchain network (e.g., Optimism Mainnet, Ethereum Mainnet) to host the Cannon package registry entry.

```bash
? Which registry would you like to use? (Cannon will find the package on either):
▸  OP Mainnet (Chain ID: 10)
   Ethereum Mainnet (Chain ID: 1)
```

--------------------------------

### Run Cannon Package Locally

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/build-with-cannon.mdx

This command demonstrates how to run a previously built Cannon package locally. It initiates a local node with the package's deployed data, enabling interaction with the smart contracts.

```bash
cannon run learn-cannon:0.0.1
```

--------------------------------

### Cannon Contract Verification Command Parameters

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/troubleshooting.mdx

Documentation for the `cannon verify` command, outlining key parameters and common issues. It details how to provide API keys and custom API URLs for services like Etherscan to ensure successful contract verification.

```APIDOC
cannon verify command:
  Purpose: Verify contracts on Etherscan or similar API services.
  Parameters:
    --api-key: string
      Description: Required API key for the verification service.
    --api-url: string (optional)
      Description: Custom API URL if not using a default service (e.g., Etherscan).
  Common Issues:
    - Incorrect API key provided.
    - Exceeding the rate limit of the verification service.
```

--------------------------------

### Confirm Cannon Publishing Details

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/publish.mdx

Presents a summary of the publishing transaction parameters, including gas settings, the publishing address, package versions, and total estimated fees, requiring user confirmation to proceed.

```bash
Settings:
 - Max Fee Per Gas: default
 - Max Priority Fee Per Gas: default
 - Gas Limit: default
 - To alter these settings use the parameters '--max-fee-per-gas', '--max-priority-fee-per-gas', '--gas-limit'.

Publishing with 0x88e224762460f5aAcA3Bde86dA4EFa9B13662b80

This will publish **learn-cannon** to the registry:
 - 0.0.1 (preset: main)
 - latest (preset: main)

Total Publishing Fees: 0.0025 ETH

? Proceed? › (y/N)
```

--------------------------------

### Define Contracts and Router in Cannonfile

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/router.mdx

Configures the `cannonfile.toml` to declare two smart contracts (`Counter` and `AnotherCounter`) and define a router operation that combines their functionalities into a single entry point.

```toml
name = "sample-router-project"
version = "0.1"
description = "Sample Router Project"

[contract.Counter]
artifact = "Counter"

[contract.AnotherCounter]
artifact = "AnotherCounter"

[router.Router]
contracts = [
  "Counter",
  "AnotherCounter"
]
```

--------------------------------

### Monitor Cannon Package Publishing Output

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/publish.mdx

Shows the detailed CLI output during the package publishing process, including progress messages, package URL, estimated gas, transaction fees, and the final transaction hash.

```bash
Publishing package...
This may take a few minutes.

Publishing packages to the registry on-chain...

Package: learn-cannon
Tags: 0.0.1, latest
Package URL: ipfs://QmU4UqpWg7JJGS3fquRevDhm5G2nMGxMaDKWyEK2mtmRvM

Estimated gas: 162977 wei
Gas price: 0.000000006634068496 ETH
Estimated transaction Fee: 0.001081200581272592 ETH

Transactions:
 - 0x5f3ac83ff8624f745b5e2b8669e1e0119efce5594893ff6a3d8d1e1a10ab6e00
```

--------------------------------

### Run Safe App Backend as a Docker Container

Source: https://github.com/usecannon/cannon/blob/dev/packages/safe-app-backend/README.md

This command pulls and runs the Safe App Backend from its official Docker image. The `--rm` flag ensures the container is removed upon exit, and `-it` provides an interactive terminal. It demonstrates how to pass environment variables like `RPC_URLS` to configure the containerized application.

```docker
docker run -it --rm ghcr.io/usecannon/safe-app-backend -e RPC_URLS=...
```

--------------------------------

### Handle Unregistered Cannon Package

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/publish.mdx

Displays the CLI message indicating that a package name is not yet registered and prompts the user to initiate the `cannon register` command on Ethereum Mainnet if necessary.

```bash
Package "learn-cannon" not yet registered, please use "cannon register" to register your package first. You need enough gas on Ethereum Mainnet to register the package on Cannon Registry

? Would you like to register the package now? › (Y/n)
```

--------------------------------

### Mark Cannon Deployment Step as Complete

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/alter.mdx

Demonstrates how to use `cannon alter mark-complete` to manually mark a specific deployment step as complete, setting its hash to `SKIP`.

```bash
cannon alter mypackage:1.0.0@main mark-complete deploy.MyContract --chain-id 1
```

--------------------------------

### Run end-to-end tests with pnpm

Source: https://github.com/usecannon/cannon/blob/dev/packages/cli/README.md

This command initiates the end-to-end test suite for the project, which uses bats as the underlying testing infrastructure. It's crucial for verifying the overall system functionality.

```bash
pnpm run test-e2e
```

--------------------------------

### Verify Deployed Contract on Etherscan

Source: https://github.com/usecannon/cannon/blob/dev/examples/sample-hardhat-project/README.md

This command facilitates the verification of a deployed smart contract on Etherscan for a given network. It requires the address of the deployed contract and any constructor arguments used during its deployment. Successful verification makes the contract's source code publicly visible and auditable on the blockchain explorer.

```shell
npx hardhat verify --network ropsten DEPLOYED_CONTRACT_ADDRESS "Hello, Hardhat!"
```

--------------------------------

### Add Transparent Upgradable Proxy to Cannonfile

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/router.mdx

Extends the `cannonfile.toml` to include a transparent upgradable proxy. This configuration sets an admin address and links the proxy to the deployed router contract, enabling future upgrades.

```toml
[setting.admin]
defaultValue = "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"

[provision.proxy]
source = "transparent-upgradable-proxy:4.9.3"
options.admin = "<%= settings.admin %>"
options.implementation = "<%= contracts.Router.address %>"
options.abi = "<%= JSON.stringify(contracts.Router.abi) %>"
```

--------------------------------

### Cannon Build Output: Package Data Generation

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/build-with-cannon.mdx

This final build output shows Cannon generating and storing package data locally, including deployment data, package code, and metadata, often referenced via IPFS hashes, indicating the package is ready for local use or publishing.

```bash
Writing upgrade info...
💥 learn-cannon:0.0.1@main built for Cannon (Chain ID: 13370)
This package can be run locally and cloned in cannonfiles.

Package data has been stored locally
╔═════════════════╤═══════════════════════════════════════════════════════╗
║ Deployment Data │ ipfs://QmVpLGJMKqAd5hD3LgM3oh37NfbmzTS9FUyjCZx1LcB8yW ║
╟─────────────────┼───────────────────────────────────────────────────────╢
║ Package Code    │ ipfs://QmVhGysWPz2toaL9FVWoyTTgp2Atf4UMESz4Dj5dKvRhWb ║
╟─────────────────┼───────────────────────────────────────────────────────╢
║ Metadata        │ ipfs://QmRsYpSHrvjVmktXJtLYZbmiHD8GNKp64qxoZ2hbGcqEDf ║
╚═════════════════╧═══════════════════════════════════════════════════════╝
```

--------------------------------

### Test Hardhat Plugin Changes in Sample Project

Source: https://github.com/usecannon/cannon/blob/dev/README.md

This command changes the directory to a sample Hardhat project and then executes the `cannon:build` task using the local Hardhat plugin. It's specifically used to verify changes made to the `hardhat-cannon` module within a realistic project context.

```bash
cd ./examples/sample-hardhat-project && pnpm hardhat cannon:build
```

--------------------------------

### Cannon Alter Command Basic Usage

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/alter.mdx

Illustrates the basic syntax for the `cannon alter` command, showing placeholders for package reference, command, and options.

```bash
cannon alter <packageRef> <command> [options...]
```

--------------------------------

### Cannon CLI Interaction: Select Contract

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/build-with-cannon.mdx

This snippet shows the interactive command-line interface (CLI) of Cannon when running a package. After pressing 'i', the user is prompted to select a deployed contract, displaying available options like 'Counter'.

```bash
================================================================================
> Gas price: provider default
> Block tag: latest
> Read/Write: 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266
> Signer Balance: 10000
================================================================================

? Pick a CONTRACT: ›
❯  ↩ BACK
      Counter
```

--------------------------------

### Publish Alpha Release to npm

Source: https://github.com/usecannon/cannon/blob/dev/README.md

From the `main` branch, this command publishes the alpha release packages to npm. It follows the prompts to complete the publishing workflow for the Cannon monorepo's alpha versions, making pre-release versions available for testing.

```bash
pnpm publish-alpha
```

--------------------------------

### Perform a Dry Run Deployment with Cannon

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/deploy-onchain.mdx

Simulates the deployment of a Cannon project to a live network without executing transactions. This command uses the `--dry-run` flag to verify deployment steps, contract addresses, transaction hashes, and gas costs, allowing for pre-deployment validation.

```bash
cannon build --rpc-url https://rpc2.sepolia.org --private-key 0xd8...ad --dry-run
```

--------------------------------

### Cannon CLI Interaction: Select Contract Function

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/build-with-cannon.mdx

Following contract selection, the Cannon CLI presents a list of available functions for the chosen contract. This allows users to interact with the smart contract by calling specific methods like `increment()`, `number()`, or `setNumber()`.

```bash
? Pick a FUNCTION: ›
❯  ↩ BACK
      function increment()
      function number()
      function setNumber(uint256 newNumber)
```

--------------------------------

### Deploy Synthetix Protocol Locally with Hardhat Cannon

Source: https://github.com/usecannon/cannon/blob/dev/packages/hardhat-cannon/README.md

Deploys the latest version of the Synthetix protocol to a local blockchain using the Hardhat Cannon plug-in, facilitating local development and testing.

```bash
npx hardhat cannon synthetix:latest
```

--------------------------------

### Publish Stable Release to npm

Source: https://github.com/usecannon/cannon/blob/dev/README.md

After versioning, this command publishes the stable release packages to npm. It follows the prompts to complete the publishing workflow for the Cannon monorepo, making the new stable version available to users.

```bash
pnpm run publish
```

--------------------------------

### Foundry Counter Test Contract with Cannon Integration

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/test-with-cannon.mdx

Solidity code for `Counter.t.sol` demonstrating a Foundry test contract. It imports `cannon-std/Cannon.sol` to use `vm.getAddress("Counter")` for retrieving the address of a built artifact, enabling interaction with the deployed contract within tests.

```solidity
// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.13;

import "cannon-std/Cannon.sol"; # Import the library

import { Test } from "forge-std/Test.sol";
import { Counter } from "../src/Counter.sol";

contract CounterTest is Test {
    using Cannon for Vm;
    Counter public counter;

    Counter counter

    function setUp() public {
        counter = Counter(vm.getAddress("Counter")); # Get the address for the built artifact
        counter.setNumber(0);
    }

    function test_Increment() public {
        counter.increment();
        assertEq(counter.number(), 1);
    }

    function testFuzz_SetNumber(uint256 x) public {
        counter.setNumber(x);
        assertEq(counter.number(), x);
    }
}
```

--------------------------------

### Mark Cannon Deployment Step as Incomplete

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/alter.mdx

Shows how to use `cannon alter mark-incomplete` to force a specific deployment step to be re-executed during the next build.

```bash
cannon alter mypackage:1.0.0@main mark-incomplete deploy.MyContract --chain-id 1
```

--------------------------------

### Basic CSS Layout Styling for Fixed Structure

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/test/index.html

This CSS snippet defines the foundational styles for a fixed layout, including a universal reset, body dimensions, and specific styles for header, main content area, sidebar, and footer elements. It ensures sticky positioning for the header and sidebar, and proper sizing for layout components.

```css
/* Reset básico */
* {
  margin: 0;
  padding: 0;
  box-sizing: border-box;
}

body {
  position: relative;
  min-height: 100%;
  max-width: 100vw;
}

/* Header styles */
.header {
  position: sticky;
  top: 0;
  height: 60px;
  background-color: #333;
  color: white;
  padding: 1rem;
  z-index: 100;
}

.main {
  display: block;
  min-height: 100vh;
}

/* Main content area */
.layout {
  display: flex;
  min-height: calc(100vh - 60px);
  margin: 0 auto;
  position: relative;
}

/* Sidebar styles */
.sidebar {
  position: sticky;
  top: 60px;
  height: calc(100vh - 60px);
  width: 250px;
  background-color: #f1f1f1;
  overflow-y: auto;
  padding: 1rem;
  flex-shrink: 0;
}

/* Main content styles */
.main-content {
  padding: 1rem;
  display: flex;
}

/* Footer styles */
.footer {
  display: block;
  background-color: #333;
  color: white;
  padding: 1rem;
  height: 60px;
}
```

--------------------------------

### Publish Hardhat Cannon Plugin to npm

Source: https://github.com/usecannon/cannon/blob/dev/packages/hardhat-cannon/README.md

Commands to bootstrap the Lerna monorepo and publish a new patch version of the package to npm, assuming the user has appropriate npm permissions.

```bash
npx lerna bootstrap
npx lerna publish patch
```

--------------------------------

### CLI Command: Configure RPC URL for Cannon Commands

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/troubleshooting.mdx

Command to specify a custom Ethereum RPC URL for various Cannon operations like `build`, `inspect`, `run`, or `alter`. This allows users to override the default public RPC, which is recommended for more reliable connections.

```bash
cannon build --rpc-url http://evm-mainnet.com
```

--------------------------------

### JSON Configuration: Override Default Cannon Registry RPC

Source: https://github.com/usecannon/cannon/blob/dev/packages/website/guides/troubleshooting.mdx

JSON structure for modifying the `~/.local/share/cannon/settings.json` file to override the default RPC providers used for Cannon's registry lookups. This allows specifying custom RPC URLs for OP Mainnet and Ethereum Mainnet registries.

```json
{
    "registries": [
        {
            "name": "OP Mainnet",
            "chainId": 10,
            "rpcUrl": ["<https://your optimism RPC URL>"],
            "address": "0x8E5C7EFC9636A6A0408A46BB7F617094B81e5dba"
        },
        {
            "name": "Ethereum Mainnet",
            "chainId": 1,
            "rpcUrl": ["<https://your ethereum RPC URL>"],
            "address": "0x8E5C7EFC9636A6A08A46BB7F617094B81e5dba"
        }
  ]
}
```

--------------------------------

### Bump Package Versions for Stable Release

Source: https://github.com/usecannon/cannon/blob/dev/README.md

This command initiates the version bumping process for a stable release using Lerna's workflow. It prompts the user to select a desired patch, minor, or major version increment for the monorepo packages, preparing them for a new stable release.

```bash
pnpm run version
```