Foundry Example

Work in Progress -- This guide provides a starting point for using Foundry (Forge) for smart contract testing on the Lithosphere network. Full examples will be added as the contract suite grows.

Overview

Foundry is used alongside Hardhat in the Lithosphere development stack as defined in ADR-002 (Technology Stack). While Hardhat serves as the primary TypeScript-native development framework, Foundry provides fast fuzz testing through Forge.

Tool

Role in Lithosphere

Forge

Fast compilation and fuzz testing of Solidity contracts

Cast

Command-line tool for interacting with deployed contracts

Anvil

Local testnet node (alternative to Hardhat Network)

Basic Setup

Install Foundry

# Install Foundryup (the Foundry installer)
curl -L https://foundry.paradigm.xyz | bash

# Install/update Foundry tools
foundryup

This installs forge, cast, and anvil.

Initialize a Foundry Project

# Create a new Foundry project
forge init my-litho-foundry
cd my-litho-foundry

This generates the following structure:

my-litho-foundry/
├── src/              # Solidity source files
├── test/             # Solidity test files
├── script/           # Deployment scripts
├── lib/              # Dependencies (git submodules)
└── foundry.toml      # Configuration

Configure for Lithosphere

Edit foundry.toml:

[profile.default]
src = "src"
out = "out"
libs = ["lib"]
solc_version = "0.8.20"
optimizer = true
optimizer_runs = 200

[rpc_endpoints]
litho_testnet = "https://testnet-rpc.lithosphere.network"
litho_mainnet = "https://mainnet-rpc.lithosphere.network"

Building Contracts

# Compile all contracts
forge build

# Force recompile
forge build --force

# Build with sizes displayed
forge build --sizes

Running Tests

Standard Tests

# Run all tests
forge test

# Run with verbosity for more output
forge test -vvv

# Run a specific test file
forge test --match-path test/LEP100.t.sol

# Run a specific test function
forge test --match-test testTransfer

Fuzz Testing

Fuzz testing is a key reason Foundry is included in the Lithosphere stack. Forge automatically fuzzes any test function that takes parameters:

// test/LEP100.t.sol
pragma solidity ^0.8.20;

import "forge-std/Test.sol";

contract LEP100Test is Test {
    // This test is automatically fuzzed with random uint256 values
    function testFuzzTransfer(uint256 amount) public {
        // Bound the amount to a reasonable range
        amount = bound(amount, 1, 1e18);
        // ... test logic
    }
}

Run fuzz tests with a high number of runs for thorough coverage:

# Run fuzz tests with 10,000 iterations
forge test --fuzz-runs 10000

This is the same configuration used in the Lithosphere CI pipeline for contract auditing.

Security Analysis

Slither Static Analysis

Run Slither and output results in SARIF format for integration with CI tools:

# Install Slither
pip install slither-analyzer

# Run analysis with SARIF output
slither . --sarif output.sarif

# Run standard analysis
slither .

Contract CI Pipeline

The full contract audit pipeline used in the Lithosphere CI (from ADR-002):

# 1. Compile with Hardhat
hardhat compile

# 2. Run Hardhat tests in parallel
hardhat test --parallel

# 3. Run Foundry fuzz tests
forge test --fuzz-runs 10000

# 4. Static analysis with Slither
slither . --sarif output.sarif

# 5. Deep analysis with Mythril
mythril analyze contracts/*.sol

Gas Snapshots

Foundry can generate gas snapshots for tracking gas usage over time:

# Generate a gas snapshot
forge snapshot

# Compare against a previous snapshot
forge snapshot --diff

Deploying with Forge

# Deploy to Lithosphere testnet
forge script script/Deploy.s.sol --rpc-url litho_testnet --broadcast

# Deploy to mainnet (use with caution)
forge script script/Deploy.s.sol --rpc-url litho_mainnet --broadcast --verify