> For the complete documentation index, see [llms.txt](https://whitepaper.litho.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://whitepaper.litho.ai/docs/developers/examples/foundry-example.md).

# 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

```bash
# 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

```bash
# 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`:

```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

```bash
# Compile all contracts
forge build

# Force recompile
forge build --force

# Build with sizes displayed
forge build --sizes
```

***

## Running Tests

### Standard Tests

```bash
# 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:

```solidity
// 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:

```bash
# 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:

```bash
# 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):

```bash
# 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:

```bash
# Generate a gas snapshot
forge snapshot

# Compare against a previous snapshot
forge snapshot --diff
```

***

## Deploying with Forge

```bash
# 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
```

***

## Further Reading

* [Hardhat Example](/docs/developers/examples/hardhat-example.md) -- Primary development framework with TypeScript support
* [Smart Contracts](/docs/developers/smart-contracts.md) -- Lithosphere smart contract architecture
* [CI/CD Guide](/docs/developers/ci-cd-guide.md) -- How Foundry fits into the automated pipeline
* [Foundry Book](https://book.getfoundry.sh/) -- Official Foundry documentation


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://whitepaper.litho.ai/docs/developers/examples/foundry-example.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.