Deploy with Foundry

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 in the Whitechain templates repository. The fastest path below clones it and deploys. The companion Hardhat template is 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.

Get the Foundry folder.

npx degit whitechain-labs/templates/Foundry whitechain-foundry
cd whitechain-foundry

Copy the environment file, then load it into your shell.
cp .env.example .env source .env
Set PRIVATE_KEY to a throwaway key funded from the faucet. WHITECHAIN_SEPOLIA_RPC_URL already points at the public endpoint. forge build and forge test both run before you fill anything in.

Deploy.

forge script script/DeployStorage.s.sol:DeployStorage \
  --rpc-url whitechain_sepolia \
  --private-key $PRIVATE_KEY \
  --broadcast

forge prints the deployed address under Contract Address.

Verify, using that address.

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.

Before you deploy

A funded testnet account. Claim test WBT from the faucet.
The private key for that account. Use a throwaway key for testing.

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

1. Install Foundry

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

macOS / Linux
Windows

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

Terminal

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

If foundryup is not found after the first command, restart your terminal and run it again.

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

wsl --install

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

WSL terminal

sudo apt update && sudo apt install -y curl git build-essential

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

WSL terminal

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

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

2. Create a project

Scaffold a project and move into it.

Terminal

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.

foundry.toml

[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.

src/Storage.sol

// 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.

.env

PRIVATE_KEY=your_private_key_here

Terminal

source .env

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

5. Add a deploy script

Create script/DeployStorage.s.sol.

script/DeployStorage.s.sol

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

Terminal

forge script script/DeployStorage.s.sol \
  --rpc-url https://rpc.testnet.whitechain.io/ \
  --private-key $PRIVATE_KEY \
  --broadcast

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

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.

Terminal

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/

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.

Verify the result

Open the contract address on the explorer. A verified contract shows its source code and a verified marker.

Troubleshooting

`forge script` deploys nothing

The --broadcast flag is missing. Add --broadcast to send the transaction.

The transaction fails with insufficient funds

The account holds no WBT. Claim test WBT from the faucet. Do not send mainnet WBT to the testnet.

Verification reports a compiler mismatch

The solc version differs from the pragma. Pin solc = "0.8.30" in foundry.toml, rebuild, and verify again.

The verification request is rejected

The --verifier-url is missing the /api/ suffix. Use https://explorer.testnet.whitechain.io/api/.

Deployment or verification fails with no clear cause

The explorer or RPC may be experiencing an outage. Check the status page.

Wallet

Dapps

Deploy

Bridge

Block Explorer

Ecosystem

Fastest path

Before you deploy

1. Install Foundry

2. Create a project

3. Add the contract

4. Set environment variables

5. Add a deploy script

6. Deploy the contract

7. Verify the contract

Verify the result

Troubleshooting

​Fastest path

​Before you deploy

​1. Install Foundry

​2. Create a project

​3. Add the contract

​4. Set environment variables

​5. Add a deploy script

​6. Deploy the contract

​7. Verify the contract

​Verify the result

​Troubleshooting

​Related

Fastest path

Before you deploy

1. Install Foundry

2. Create a project

3. Add the contract

4. Set environment variables

5. Add a deploy script

6. Deploy the contract

7. Verify the contract

Verify the result

Troubleshooting

Related