Foundry¶

Introduction¶

Foundry is a blazing fast, portable, and modular toolkit for Ethereum application development written in Rust. It consists of:

• Forge: Command-line tool to test, build, and deploy smart contracts
• Cast: Swiss army knife for interacting with contracts, sending transactions, and getting chain data
• Anvil: Local Ethereum node for development and testing
• Chisel: Solidity REPL for testing code snippets

This page demonstrates how to set up Foundry to work with Polkadot Hub, including installation, compilation, deployment, and verification.

Prerequisites¶

Before setting up Foundry, make sure you have:

• A Unix-based operating system (Linux or macOS) or Windows with WSL
• Git installed
• A funded account on Polkadot Hub (see the Connect to Polkadot guide to get TestNet tokens)

Install Foundry¶

To install the Foundry nightly build, run:

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

This installs foundryup, the Foundry toolchain installer. Then, run:

foundryup --version nightly

This installs the latest nightly versions of forge, cast, anvil, and chisel.

To verify the installation:

Initialize a Foundry Project¶

Create a new Foundry project:

forge init my-foundry-project
cd my-foundry-project

This creates a new directory with the following structure:

• src/: Contains your Solidity smart contracts
• script/: Holds deployment scripts
• test/: Contains test files written in Solidity
• lib/: Stores project dependencies
• foundry.toml: Configuration file for Foundry settings

A sample Counter.sol contract will be created in the src/ directory along with a corresponding test file.

Compile Contracts¶

To compile your contracts, run:

forge build

You should see output similar to:

Forge compiles all contracts in the src/ directory and outputs the artifacts to the out/ directory.

Configure Foundry for Polkadot Hub¶

Foundry's nightly build includes native support for Polkadot chains with polkadot-testnet, polkadot, and kusama as recognized chains with default RPC endpoints.

Create or modify your foundry.toml file:

[profile.default]
src = "src"
out = "out"
libs = ["lib"]
solc_version = "0.8.28"

[etherscan]
polkadot-testnet = { key = "verifyContract", url = "https://api.routescan.io/v2/network/testnet/evm/420420417/etherscan" }

With this configuration, you can use --chain polkadot-testnet in your commands without specifying the RPC URL explicitly.

Available Networks and RPC Endpoints¶

Foundry's nightly build supports three Polkadot chains:

Deploy a Contract¶

Set Up Environment Variables¶

Create a .env file in your project root (make sure to add it to .gitignore):

PRIVATE_KEY=INSERT_PRIVATE_KEY_HERE

Load the environment variables:

source .env

Deploy Using Forge¶

To deploy a contract to Polkadot Hub TestNet:

forge create src/Counter.sol:Counter \
    --chain polkadot-testnet \
    --rpc-url https://services.polkadothub-rpc.com/testnet \
    --private-key $PRIVATE_KEY \
    --broadcast

You'll see output with the deployed contract address:

Deploy Using Scripts¶

For more complex deployments, create a deployment script in the script/ directory:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.28;

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

contract CounterScript is Script {
    function run() external {
        // Get the deployer's private key from environment
        uint256 deployerPrivateKey = vm.envUint("PRIVATE_KEY");

        // Start broadcasting transactions
        vm.startBroadcast(deployerPrivateKey);

        // Deploy the contract
        Counter counter = new Counter();

        // Stop broadcasting
        vm.stopBroadcast();
    }
}

Run the deployment script:

forge script script/Counter.s.sol:CounterScript \
    --chain polkadot-testnet \
    --broadcast

The --broadcast flag tells Forge to submit the transactions to the network.

Verify a Contract¶

To verify your deployed contract on Polkadot Hub, use the verification feature with the Polkadot Hub explorer verifier.

Basic Verification¶

forge verify-contract INSERT_CONTRACT_ADDRESS \
    src/Counter.sol:Counter \
    --verifier-url 'https://api.routescan.io/v2/network/testnet/evm/420420417/etherscan' \
    --etherscan-api-key "verifyContract" \
    --chain polkadot-testnet

Replace INSERT_CONTRACT_ADDRESS with your deployed contract's address.

The --verifier-url is the URL of the Polkadot Hub explorer verifier. The Routescan API v2 structure is https://api.routescan.io/v2/network/{testnet|mainnet}/evm/{CHAIN_ID}/etherscan.

You should see output similar to:

Verification with Constructor Arguments¶

For contracts with constructor arguments:

forge verify-contract INSERT_CONTRACT_ADDRESS \
    src/Counter.sol:Counter \
    --verifier-url 'https://api.routescan.io/v2/network/testnet/evm/420420417/etherscan' \
    --etherscan-api-key "verifyContract" \
    --chain polkadot-testnet \
    --constructor-args $(cast abi-encode "constructor(uint256,address)" 42 INSERT_DEPLOYER_ADDRESS)

Replace INSERT_CONTRACT_ADDRESS with your deployed contract's address.

Interact with Contracts¶

Using Cast¶

Cast is a powerful command-line tool for interacting with deployed contracts.

Read from a Contract¶

cast call INSERT_CONTRACT_ADDRESS "number()(uint256)" \
    --chain polkadot-testnet

Write to a Contract¶

cast send INSERT_CONTRACT_ADDRESS "setNumber(uint256)" 42 \
    --chain polkadot-testnet \
    --private-key $PRIVATE_KEY

Get Account Balance¶

cast balance INSERT_ACCOUNT_ADDRESS --chain polkadot-testnet

Using Forge Scripts¶

For more complex interactions, create scripts in the script/ directory that can read and write contract state programmatically.

Run Tests¶

Foundry uses Solidity for writing tests, allowing you to test your contracts in the same language they're written in:

forge test

For verbose output showing gas usage and detailed logs:

forge test -vvv

Run specific tests:

forge test --match-test testIncrement

Run tests with gas reporting:

forge test --gas-report

Additional Resources¶

• Foundry Book: Comprehensive Foundry documentation
• Forge Documentation: Detailed guide to the Forge tool
• Cast Documentation: Learn about Cast commands
• Foundry GitHub: Source code and issue tracker

Where to Go Next¶