> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whitechain.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Deploy with Foundry

> Deploy and verify a smart contract on Whitechain Sepolia using Foundry and forge from the command line.

This page shows how to deploy and verify a contract on Whitechain Sepolia using Foundry. You pass the RPC URL and the explorer URL directly to `forge`, so `forge` needs no chain config file. It is for developers who use Foundry and work from the command line.

Ready-made template: [**`Foundry`**](https://github.com/whitechain-labs/templates/tree/main/Foundry) in the Whitechain templates repository. The fastest path below clones it and deploys. The companion Hardhat template is [**`Hardhat`**](https://github.com/whitechain-labs/templates/tree/main/Hardhat).

## Fastest path

The Foundry template is a finished project for Whitechain Sepolia: the RPC alias
is configured, `forge-std` is vendored so the folder builds with no `forge install`
step, and the contract, tests, and deploy script are in place. You need Foundry and
a funded key. The walkthrough after this section builds the same project by hand,
if you would rather see every step.

1. Get the `Foundry` folder.

   ```bash theme={null}
   npx degit whitechain-labs/templates/Foundry whitechain-foundry
   cd whitechain-foundry
   ```

2. Copy the environment file, then load it into your shell.

   ```bash theme={null}
   cp .env.example .env
   source .env
   ```

   Set `PRIVATE_KEY` to a throwaway key funded from the [faucet](/learn/get-started/get-testnet-wbt). `WHITECHAIN_SEPOLIA_RPC_URL` already points at the public endpoint. `forge build` and `forge test` both run before you fill anything in.

3. Deploy.

   ```bash theme={null}
   forge script script/DeployStorage.s.sol:DeployStorage \
     --rpc-url whitechain_sepolia \
     --private-key $PRIVATE_KEY \
     --broadcast
   ```

   `forge` prints the deployed address under `Contract Address`.

4. Verify, using that address.

   ```bash theme={null}
   forge verify-contract <contract_address> src/Storage.sol:Storage \
     --rpc-url whitechain_sepolia \
     --verifier blockscout \
     --verifier-url https://explorer.testnet.whitechain.io/api/
   ```

Source: [whitechain-labs/templates](https://github.com/whitechain-labs/templates/tree/main/Foundry).

## Before you deploy

* A funded testnet account. Claim test WBT from the [faucet](/learn/get-started/get-testnet-wbt).
* The private key for that account. Use a throwaway key for testing.

<Warning>
  Never commit a private key, and never reuse a mainnet key for testing. Anyone with the key controls the funds.
</Warning>

## 1. Install Foundry

Foundryup requires a Unix shell. macOS and Linux work directly. On Windows, run Foundry inside WSL.

<Tabs>
  <Tab title="macOS / Linux">
    Install Foundry, then run `foundryup` to fetch `forge`, `cast`, and `anvil`.

    ```bash Terminal theme={null}
    curl -L https://foundry.paradigm.xyz | bash
    foundryup
    ```

    <Note>
      If `foundryup` is not found after the first command, restart your terminal and run it again.
    </Note>
  </Tab>

  <Tab title="Windows">
    PowerShell and Command Prompt cannot run Foundry. Install WSL first, then work from the Ubuntu terminal.

    Open PowerShell as administrator and install WSL with Ubuntu. Reboot if prompted, then set a Linux username and password.

    ```powershell PowerShell theme={null}
    wsl --install
    ```

    Open the Ubuntu terminal and install the build tools Foundry needs.

    ```bash WSL terminal theme={null}
    sudo apt update && sudo apt install -y curl git build-essential
    ```

    Install Foundry, then run `foundryup` to fetch `forge`, `cast`, and `anvil`.

    ```bash WSL terminal theme={null}
    curl -L https://foundry.paradigm.xyz | bash
    foundryup
    ```

    <Note>
      Run every remaining step from this same Ubuntu terminal. If `foundryup` is not found, run `source ~/.bashrc` or restart the terminal.
    </Note>
  </Tab>
</Tabs>

## 2. Create a project

Scaffold a project and move into it.

```bash Terminal theme={null}
forge init whitechain-foundry
cd whitechain-foundry
```

Pin the Solidity version in `foundry.toml` so the compiler matches the contract. Verification fails if the compiler version differs.

```toml foundry.toml theme={null}
[profile.default]
src = "src"
out = "out"
libs = ["lib"]
solc = "0.8.30"
```

## 3. Add the contract

Create `src/Storage.sol`. You can delete the sample `Counter` files that `forge init` created.

```solidity src/Storage.sol theme={null}
// SPDX-License-Identifier: GPL-3.0
pragma solidity ^0.8.30;

contract Storage {
    uint256 number;

    function store(uint256 num) public {
        number = num;
    }

    function retrieve() public view returns (uint256) {
        return number;
    }
}
```

## 4. Set environment variables

Create a `.env` file with the private key, then load it into the shell.

```bash .env theme={null}
PRIVATE_KEY=your_private_key_here
```

```bash Terminal theme={null}
source .env
```

<Note>
  For a safer setup, import the key into an encrypted keystore with `cast wallet import`, then pass `--account <name>` instead of `--private-key`.
</Note>

## 5. Add a deploy script

Create `script/DeployStorage.s.sol`.

```solidity script/DeployStorage.s.sol theme={null}
// SPDX-License-Identifier: GPL-3.0
pragma solidity ^0.8.30;

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

contract DeployStorage is Script {
    function run() public {
        vm.startBroadcast();
        new Storage();
        vm.stopBroadcast();
    }
}
```

## 6. Deploy the contract

```bash Terminal theme={null}
forge script script/DeployStorage.s.sol \
  --rpc-url https://rpc.testnet.whitechain.io/ \
  --private-key $PRIVATE_KEY \
  --broadcast
```

<Warning>
  `forge script` only sends transactions when `--broadcast` is present. Without it, `forge` runs a simulation and deploys nothing.
</Warning>

`forge` prints the deployed address under `Contract Address`. Copy it for verification.

## 7. Verify the contract

Verify the deployed contract on the Whitechain Blockscout explorer.

```bash Terminal theme={null}
forge verify-contract <contract_address> src/Storage.sol:Storage \
  --rpc-url https://rpc.testnet.whitechain.io/ \
  --verifier blockscout \
  --verifier-url https://explorer.testnet.whitechain.io/api/
```

<Note>
  The Blockscout verifier URL ends with `/api/`. A missing or wrong suffix makes the request fail. To verify during deployment instead, add `--verify --verifier blockscout --verifier-url https://explorer.testnet.whitechain.io/api/` to the `forge script` command in step 6.
</Note>

## Verify the result

Open the contract address on the [explorer](https://explorer.testnet.whitechain.io). A verified contract shows its source code and a verified marker.

## Troubleshooting

<AccordionGroup>
  <Accordion title="`forge script` deploys nothing">
    The `--broadcast` flag is missing. Add `--broadcast` to send the transaction.
  </Accordion>

  <Accordion title="The transaction fails with insufficient funds">
    The account holds no WBT. Claim test WBT from the [faucet](/learn/get-started/get-testnet-wbt). Do not send mainnet WBT to the testnet.
  </Accordion>

  <Accordion title="Verification reports a compiler mismatch">
    The solc version differs from the pragma. Pin `solc = "0.8.30"` in `foundry.toml`, rebuild, and verify again.
  </Accordion>

  <Accordion title="The verification request is rejected">
    The `--verifier-url` is missing the `/api/` suffix. Use `https://explorer.testnet.whitechain.io/api/`.
  </Accordion>

  <Accordion title="Deployment or verification fails with no clear cause">
    The explorer or RPC may be experiencing an outage. Check the [status page](https://status.whitechain.io/).
  </Accordion>
</AccordionGroup>

## Related

* [`Foundry` template on GitHub](https://github.com/whitechain-labs/templates/tree/main/Foundry)
* [Deploy a contract](/learn/get-started/deploy-a-contract)
* [Connect to Whitechain Sepolia](/learn/get-started/connect-wallet)
* [Deploy with Hardhat](/build/deploy/deploy-with-hardhat)
* [Deploy with Remix](/build/deploy/deploy-with-remix)
* [Verify a proxy contract](/build/deploy/verify-proxy-contracts)
* [Faucet](/learn/get-started/get-testnet-wbt)
* [Service status](https://status.whitechain.io/)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.