etherscan-verification

Overview

Contract verification on Etherscan-compatible explorers using Foundry's forge verify-contract. Covers standard verification, unsupported chains via Etherscan V2 API, proxy patterns, and factory-created contracts.

When to Use

Verify deployed smart contracts on Etherscan-compatible explorers
Verify proxy contracts (ERC1967, UUPS)
Verify factory-created contracts (CREATE2)
Extract constructor arguments from deployment data

Prerequisites

Requirement	How to Get
Foundry ≥1.3.6	Run `forge -V` to check version
Contract address	From deployment broadcast or user
Chain ID	From explorer or network configuration
Explorer API key	From Etherscan account (works for V2 multi-chain)
Source code	Must match deployed bytecode exactly

Version Check

Before proceeding, verify Foundry version:

forge -V

Stop if version is below 1.3.6.

Verification Methods

Method 1: Standard (Native Support)

For chains Foundry supports natively:

FOUNDRY_PROFILE=optimized forge verify-contract \
  <CONTRACT_ADDRESS> \
  src/<Contract>.sol:<Contract> \
  --rpc-url <chain_name> \
  --verifier etherscan \
  --etherscan-api-key $ETHERSCAN_API_KEY \
  --watch

Method 2: Etherscan V2 API (Unsupported Chains on Foundry)

When Foundry shows "No known Etherscan API URL for chain X":

FOUNDRY_PROFILE=optimized forge verify-contract \
  <CONTRACT_ADDRESS> \
  src/<Contract>.sol:<Contract> \
  --verifier etherscan \
  --verifier-url "https://api.etherscan.io/v2/api?chainid=<CHAIN_ID>" \
  --etherscan-api-key $ETHERSCAN_API_KEY \
  --watch

Supported chains: https://docs.etherscan.io/supported-chains

Method 3: With Constructor Arguments

For contracts with constructor parameters:

FOUNDRY_PROFILE=optimized forge verify-contract \
  <CONTRACT_ADDRESS> \
  src/<Contract>.sol:<Contract> \
  --verifier etherscan \
  --verifier-url "https://api.etherscan.io/v2/api?chainid=<CHAIN_ID>" \
  --etherscan-api-key $ETHERSCAN_API_KEY \
  --constructor-args <ABI_ENCODED_ARGS> \
  --watch

Generate constructor args with cast abi-encode:

cast abi-encode "constructor(address,uint256)" 0x123... 1000

Special Cases

Reference: ./references/special-cases.md

Proxy Contracts

Verify implementation and proxy separately. See reference for ERC1967 pattern.

Factory-Created Contracts

Extract constructor args from broadcast initCode using scripts/extract_constructor_args.py.

Library Verification

For libraries, use full path:

src/libraries/<Library>.sol:<Library>

Troubleshooting

Reference: ./references/troubleshooting.md

Common Issues

Error	Cause	Solution
"No known Etherscan API URL"	Chain not in Foundry	Use `--verifier-url` with V2 API
"Bytecode does not match"	Compilation drift	Checkout deployment commit + reinstall deps
"Constructor args mismatch"	Wrong/missing args	Extract from broadcast or encode manually
"Already verified"	Previously verified	No action needed

Output

After successful verification:

Contract source visible on explorer
ABI available for interaction
Constructor args decoded
"Contract Source Code Verified" badge

Examples

Reference: ./references/examples.md for real-world verification examples from Monad deployment.