> ## Documentation Index
> Fetch the complete documentation index at: https://l2docs.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.

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

* [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/)