Foundry

Warning

Consider that features like Anvil (Foundry's local blockchain) and forge test (for running Solidity tests) are not yet supported in foundry-polkadot.

Overview

Foundry is a fast, modular, and extensible toolkit for Ethereum application development written in Rust. It provides a suite of command-line tools, including forge for compiling, testing, and deploying smart contracts and cast for interacting with blockchains.

foundry-polkadot is an adaptation explicitly engineered for the Polkadot Hub, tailored for developers already familiar with Foundry who seek to leverage its capabilities within the Polkadot ecosystem. Additionally, this guide offers detailed information on the forge and cast commands supported within foundry-polkadot, complete with simple, runnable examples for quick reference.

Installation

The installation process is tailored for the Polkadot variant:

• foundry-polkadot is installed via foundryup-polkadot, its dedicated installer. To get started, open your terminal and execute:

  curl -L https://raw.githubusercontent.com/paritytech/foundry-polkadot/refs/heads/master/foundryup/install | bash
  

  This command starts the installation of foundryup-polkadot. After installation, run the following command to download the precompiled foundry-polkadot binaries:

  foundryup-polkadot
  

  This command will install the forge and cast binaries, which are explained below. Windows users must use a Unix-like terminal environment such as Git BASH or Windows Subsystem for Linux (WSL), as PowerShell and Command Prompt are not currently supported by foundryup.

Compiler Integration

A core divergence lies in the underlying Solidity compiler.

• foundry is built to interface with the solc compiler, which targets Ethereum's Ethereum Virtual Machine (EVM).

• foundry-polkadot, in contrast, introduces and primarily utilizes the resolc compiler to compile down Solidity contracts into PolkaVM bytecode.

  • Command-Line Flag: For commands that involve compilation (e.g., forge build), you can use the --resolc flag to enable resolc compilation. For example:

    forge build --resolc
    

    This command instructs Forge to use resolc instead of solc, generating bytecode compatible with PolkaVM.

  • Configuration File: Alternatively, you can configure resolc usage in the foundry.toml file by adding:

    [profile.default.resolc]
    resolc_compile = true
    

    Setting resolc_compile = false reverts to using solc, ensuring compatibility with Ethereum projects. By default, foundry-polkadot uses solc unless resolc is explicitly enabled. resolc also exposes specific options for fine-tuning the compilation process, such as --use-resolc <RESOLC_VERSION> for specifying a compiler version or path, -O, --resolc-optimizer-mode <LEVEL> for setting optimization levels, and --heap-size <SIZE> and --stack-size <SIZE> for configuring contract memory.

Command-Line Interface (CLI)

foundry-polkadot preserves the familiar forge and cast subcommand structure. However, it's crucial to note that commands which involve compilation (such as create, bind, build, and inspect) will yield different output when resolc is utilized, as the generated bytecode is specifically designed for PolkaVM rather than the EVM.

Unsupported or Modified Features

Not all functionalities from the original Foundry are present or behave identically in foundry-polkadot:

• Currently Unsupported:
  • Compilation of Yul code is not yet supported.
  • Support for factory contracts deployment is a known issue that is currently unresolved.
• Broader Feature Limitations: Integration with Anvil and Chisel (Foundry's local blockchain and EVM toolkit, respectively) is not available. This limitation directly impacts the support for several key commands, including forge test for running tests, forge snapshot for creating blockchain state snapshots, and forge script for complex deployment and interaction scripts.
• Modified Feature: The most notable modification is in the compilation output. When resolc is employed, the resulting bytecode will fundamentally differ from that generated by solc, reflecting PolkaVM's distinct architectural requirements.

Set up a Project

Initialize a new project using forge init:

forge init my-polkadot-project
cd my-polkadot-project

This command creates a complete project structure with the following components:

• src/ - Contains the Solidity smart contracts (includes a sample Counter.sol contract by default)
• lib/ - Houses external dependencies and libraries (forge-std testing library is included)
• script/ - Stores deployment and interaction scripts (includes Counter.s.sol deployment script by default)
• test/ - Contains your contract tests (includes Counter.t.sol test file by default)
• foundry.toml - Main configuration file for compiler settings, network configurations, and project preferences

The default project includes a simple Counter contract that demonstrates basic state management through increment and decrement functions, along with corresponding tests and deployment scripts to help you get started quickly.

Compile a Project

Compile contracts using forge build:

forge build --resolc

Note

You can still use forge build for compiling to regular EVM bytecode.

PolkaVM bytecode starts with 0x505 prefix. Inspect compiled artifacts with:

forge inspect Counter bytecode --resolc

If successful, you will see the following output:

forge inspect Counter bytecode --resolc 0x50564d00008213000000000000010700c13000c0008004808f08000000000e0000001c0000002a0000003500000040000000520000005d00000063616c6c5f646174615f636f707963616c6c5f646174615f6c6f616463616c6c5f646174615f73697a65676574...

Deploy a Contract

Deploy contracts using forge create:

forge create Counter \
    --rpc-url <INSERT_RPC_URL> \
    --private-key <INSERT_PRIVATE_KEY> \
    --resolc

If the operation completes successfully, you'll see the following output (for example, to deploy to the Passet Hub chain):

forge create Counter \   --rpc-url https://testnet-passet-hub-eth-rpc.polkadot.io \   --private-key <INSERT_PRIVATE_KEY> \   --resolc
[:] Compiling... Compiler run successful!

For contracts with constructor arguments:

forge create MyToken \
    --rpc-url <INSERT_RPC_URL> \
    --private-key <INSERT_PRIVATE_KEY> \
    --constructor-args "MyToken" "MTK" 1000000 \
    --resolc

Network Compatibility

Use the --resolc flag when deploying to PolkaVM-compatible networks. Omit it for Ethereum-compatible networks.

Supported foundry-polkadot Commands

This section provides a detailed breakdown of the forge and cast commands supported in foundry-polkadot.

Forge Commands

• init

  • Command: forge init <PROJECT_NAME>
  • Description: Initializes a new Foundry project in the current directory, setting up the basic project structure and installing standard libraries.

• bind

  • Command: forge bind [--resolc]
  • Description: Generates type-safe Rust bindings for your Solidity contracts. Use --resolc to ensure compilation with the resolc compiler for PolkaVM compatibility.

• bind-json

  • Command: forge bind-json [--resolc]
  • Description: Generates JSON bindings for your Solidity contracts. Use --resolc for resolc-based compilation.

• build

  • Command: forge build [--resolc]
  • Description: Compiles all Solidity contracts in your project. Specify --resolc to compile for PolkaVM.

• cache clean

  • Command: forge cache clean
  • Description: Clears the Foundry cache directory.

• cache ls

  • Command: forge cache ls
  • Description: Lists the contents of the Foundry cache.

• clean

  • Command: forge clean
  • Description: Removes all build artifacts from the project's out directory.

• compiler resolve

  • Command: forge compiler resolve [--resolc]
  • Description: Resolves and displays the versions of Solidity compilers Foundry is using. Use --resolc to also check for resolc.

• config

  • Command: forge config
  • Description: Displays the current Foundry project configuration, including settings from foundry.toml.

• create

  • Command: forge create [OPTIONS] <CONTRACT>
  • Required Parameters: <CONTRACT> (the name of the contract to deploy)
  • Description: Deploys a new contract to a specified blockchain network. The --resolc flag ensures it's compiled for PolkaVM. You'll typically need to provide an RPC URL, a private key for the deployer account, and potentially constructor arguments.

• doc

  • Command: forge doc
  • Description: Generates documentation for your Solidity contracts.

• flatten

  • Command: forge flatten [OPTIONS] <PATH>
  • Required Parameters: <PATH> (the path to the Solidity file)
  • Description: Combines all imports of a Solidity file into a single file, useful for deployment or verification.

• fmt

  • Command: forge fmt
  • Description: Formats Solidity code according to a predefined style.

• geiger

  • Command: forge geiger <PATH>
  • Required Parameters: <PATH> (the path to the Solidity file)
  • Description: Analyzes Solidity code for potential security vulnerabilities and gas inefficiencies.

• generate test

  • Command: forge generate test --contract-name <CONTRACT_NAME>
  • Required Parameters: --contract-name <CONTRACT_NAME> (the name of the contract for which to generate a test)
  • Description: Creates a new test file with boilerplate code for a specified contract.

• generate-fig-spec

  • Command: forge generate-fig-spec
  • Description: Generates a Fig specification for CLI autocompletion tools.

• inspect

  • Command: forge inspect <CONTRACT_NAME> <ARTIFACT> [--resolc]
  • Required Parameters: <CONTRACT_NAME> (the contract to inspect), <ARTIFACT> (e.g., bytecode, abi, methods, events)
  • Description: Displays various artifacts of a compiled contract. Use --resolc to inspect resolc-compiled artifacts; the bytecode will start with 0x505.

• install

  • Command: forge install <REPOSITORY>
  • Description: Installs a Solidity library or dependency from a Git repository.

• update

  • Command: forge update [<REPOSITORY>]
  • Description: Updates installed dependencies. If a repository is specified, only that one is updated.

• remappings

  • Command: forge remappings
  • Description: Lists the currently configured Solidity compiler remappings.

• remove

  • Command: forge remove <REPOSITORY>
  • Description: Removes an installed Solidity dependency. Use --force to remove without confirmation.

• selectors upload

  • Command: forge selectors upload [--all]
  • Description: Uploads function selectors from compiled contracts to OpenChain. Use --all to upload for all contracts.

• selectors list

  • Command: forge selectors list
  • Description: Lists all known function selectors for contracts in the project.

• selectors find

  • Command: forge selectors find <SELECTOR>
  • Description: Searches for a function signature given its 4-byte selector.

• selectors cache

  • Command: forge selectors cache
  • Description: Caches function selectors for faster lookup.

• tree

  • Command: forge tree
  • Description: Displays the dependency tree of your Solidity contracts.

Non-working Commands

Consider that some foundry commands are not yet supported in foundry-polkadot:

• clone: This command is not supported in foundry-polkadot.
• coverage: Code coverage analysis is not supported.
• snapshot: Creating blockchain state snapshots is not supported.
• test: Running Solidity tests is not supported.

Cast Commands

• 4byte

  • Command: cast 4byte [OPTIONS] [TOPIC_0]
  • Description: Decodes a 4-byte function selector into its human-readable function signature.

• 4byte-event

  • Command: cast 4byte-event [OPTIONS] [TOPIC_0]
  • Description: Decodes a 4-byte event topic into its human-readable event signature.

• abi-encode

  • Command: cast abi-encode <SIG> [ARGS]...
  • Required Parameters: <SIG> (the function signature), [ARGS] (arguments to encode)
  • Description: ABI-encodes function arguments according to a given signature.

• address-zero

  • Command: cast address-zero
  • Description: Returns the zero address (0x00...00).

• age

  • Command: cast age [OPTIONS] [BLOCK]
  • Description: Converts a block number or tag (e.g., latest) into its timestamp.

• balance

  • Command: cast balance [OPTIONS] <WHO>
  • Required Parameters: <WHO> (the address to check)
  • Description: Retrieves the native token balance of a given address on the specified RPC network.

• base-fee

  • Command: cast base-fee [OPTIONS] [BLOCK]
  • Description: Retrieves the base fee per gas for a specific block (defaults to latest).

• block

  • Command: cast block [OPTIONS] [BLOCK]
  • Description: Retrieves comprehensive details about a specific block (defaults to latest).

• block-number

  • Command: cast block-number [OPTIONS] [BLOCK]
  • Description: Retrieves the number of the latest or a specified block.

• call

  • Command: cast call [OPTIONS] <TO> <SIG> [ARGS]...
  • Description: Executes a read-only (constant) function call on a contract. No transaction is sent to the network.

• chain

  • Command: cast chain [OPTIONS]
  • Description: Displays the human-readable name of the connected blockchain.

• chain-id

  • Command: cast chain-id [OPTIONS]
  • Description: Displays the chain ID of the connected blockchain.

• client

  • Command: cast client [OPTIONS]
  • Description: Retrieves information about the connected RPC client (node software).

• code

  • Command: cast code [OPTIONS] <WHO>
  • Required Parameters: <WHO> (the contract address)
  • Description: Retrieves the bytecode deployed at a given contract address.

• codesize

  • Command: cast codesize [OPTIONS] <WHO>
  • Required Parameters: <WHO> (the contract address)
  • Description: Retrieves the size of the bytecode deployed at a given contract address.

• compute-address

  • Command: cast compute-address [OPTIONS] <WHO>
  • Required Parameters: <WHO> (the deployer's address)
  • Description: Computes the predicted contract address based on the deployer's address and nonce.

• decode-abi

  • Command: cast decode-abi <SIG> <CALLDATA>
  • Required Parameters: <SIG> (the function signature), <CALLDATA> (the ABI-encoded data)
  • Description: Decodes ABI-encoded output data from a contract call given its signature.

• decode-calldata

  • Command: cast decode-calldata <SIG> <CALLDATA>
  • Required Parameters: <SIG> (the function signature), <CALLDATA> (the raw calldata)
  • Description: Decodes raw calldata into human-readable arguments using a function signature.

• decode-error

  • Command: cast decode-error <DATA> [--sig <SIGNATURE>]
  • Required Parameters: <DATA> (the error data)
  • Description: Decodes a custom error message from a transaction revert. You may need to provide the error signature.

• decode-event

  • Command: cast decode-event <DATA> [--sig <SIGNATURE>]
  • Required Parameters: <DATA> (the event data)
  • Description: Decodes event data from a transaction log.

• estimate

  • Command: cast estimate [OPTIONS] [TO] [SIG] [ARGS]...
  • Required Parameters: [TO] (the recipient address or contract), [SIG] (function signature), [ARGS] (arguments)
  • Description: Estimates the gas cost for a transaction or function call.

• find-block

  • Command: cast find-block [OPTIONS] <TIMESTAMP>
  • Required Parameters: <TIMESTAMP> (a Unix timestamp)
  • Description: Finds the closest block number to a given Unix timestamp.

• gas-price

  • Command: cast gas-price [OPTIONS]
  • Description: Retrieves the current average gas price on the network.

• generate-fig-spec

  • Command: cast generate-fig-spec
  • Description: Generates a Fig specification for CLI autocompletion.

• index-string

  • Command: cast index-string <STRING> <INDEX>
  • Description: Computes the Keccak-256 hash of a string, useful for event topics.

• index-erc7201

  • Command: cast index-erc7201 <VALUE>
  • Description: Computes the hash for an ERC-7201 identifier.

• logs

  • Command: cast logs [OPTIONS] [SIG_OR_TOPIC] [TOPICS_OR_ARGS]...
  • Required Parameters: [SIG_OR_TOPIC] (a signature or topic hash)
  • Description: Filters and displays event logs from transactions.

• max-int

  • Command: cast max-int
  • Description: Displays the maximum value for a signed 256-bit integer.

• max-uint

  • Command: cast max-uint
  • Description: Displays the maximum value for an unsigned 256-bit integer.

• min-int

  • Command: cast min-int
  • Description: Displays the minimum value for a signed 256-bit integer.

• mktx

  • Command: cast mktx [OPTIONS] [TO] [SIG] [ARGS]...
  • Required Parameters: [TO] (the recipient address or contract)
  • Description: Creates a raw, signed transaction that can be broadcast later.

• decode-transaction

  • Command: cast decode-transaction [OPTIONS] [TX]
  • Required Parameters: [TX] (the raw transaction hex string)
  • Description: Decodes a raw transaction hex string into its human-readable components.

• namehash increment

  • Command: cast namehash <NAME>
  • Description: Computes the ENS (Ethereum Name Service) namehash for a given name.

• nonce

  • Command: cast nonce [OPTIONS] <WHO>
  • Required Parameters: <WHO> (the address to check)
  • Description: Retrieves the transaction count (nonce) for a given address.

• parse-bytes32-address

  • Command: cast parse-bytes32-address <VALUE>
  • Description: Parses a 32-byte hex string (e.g., from bytes32) into an Ethereum address.

• parse-bytes32-string

  • Command: cast parse-bytes32-string <VALUE>
  • Description: Parses a 32-byte hex string into a human-readable string.

• parse-units

  • Command: cast parse-units <AMOUNT> [UNIT]
  • Description: Converts a human-readable amount into its smallest unit (e.g., Ether to Wei). Defaults to ether.

• pretty-calldata

  • Command: cast pretty-calldata [OPTIONS] <DATA>
  • Required Parameters: <DATA> (the calldata hex string)
  • Description: Attempts to pretty-print and decode a raw calldata string into possible function calls.

• publish

  • Command: cast publish [OPTIONS] <RAW_TX>
  • Description: Broadcasts a raw, signed transaction to the network.

• receipt

  • Command: cast receipt [OPTIONS] <TX_HASH>
  • Description: Retrieves the transaction receipt for a given transaction hash, including status, gas usage, and logs.

• rpc

  • Command: cast rpc [OPTIONS] <METHOD> [PARAMS]...
  • Required Parameters: <METHOD> (the RPC method to call), [PARAMS] (parameters for the method)
  • Description: Makes a direct RPC call to the connected blockchain node.

• send

  • Command: cast send [OPTIONS] <TO> <SIG> [ARGS]...
  • Required Parameters: <TO> (the recipient address or contract)
  • Description: Sends a transaction to a contract or address, executing a function or transferring value.

• sig

  • Command: cast sig <FUNCTION_SIGNATURE>
  • Required Parameters: <FUNCTION_SIGNATURE> (the full function signature string)
  • Description: Computes the 4-byte function selector for a given function signature.

• sig-event

  • Command: cast sig-event <EVENT_SIGNATURE>
  • Required Parameters: <EVENT_SIGNATURE> (the full event signature string)
  • Description: Computes the Keccak-256 hash (topic) for a given event signature.

• storage

  • Command: cast storage [OPTIONS] <ADDRESS> [SLOT]
  • Required Parameters: <ADDRESS> (the contract address)
  • Description: Retrieves the raw value stored at a specific storage slot of a contract.

• tx

  • Command: cast tx [OPTIONS] <TX_HASH>
  • Description: Retrieves comprehensive details about a specific transaction.

• upload-signature

  • Command: cast upload-signature [OPTIONS] <SIGNATURE_STRING>
  • Required Parameters: <SIGNATURE_STRING> (the function or event signature)
  • Description: Uploads a function or event signature to the OpenChain registry.

• wallet

  • Command: cast wallet new
  • Description: Generates a new random Ethereum keypair (private key and address).

• wallet new-mnemonic

  • Command: cast wallet new-mnemonic
  • Description: Generates a new BIP-39 mnemonic phrase and derives the first account from it.

• wallet address

  • Command: cast wallet address [OPTIONS]
  • Description: Derives and displays the Ethereum address from a private key or mnemonic (if provided).

Non-working Commands

Consider that some foundry commands are not yet supported in foundry-polkadot:

• proof: This command, used for generating Merkle proofs, is not supported.
• storage-root: This command, used for retrieving the storage root of a contract, is not supported.

Last update: July 1, 2025
| Created: July 1, 2025