Build / Development Frameworks

Verifying via Explorer

This document explains how to verify smart contracts on Somnia Mainnet using Blockscout. It replaces the old explorer-based verification flow.

How It Works

Somnia Mainnet Explorer is Blockscout-based and uses Blockscout verification endpoints.

There are 4 primary verification methods:

  1. Verification via Explorer UI
  2. Verification via Blockscout Smart Contract Verification API
  3. Verification via Hardhat plugin
  4. Verification via Foundry (forge)

Note

Recommendation: For production contracts, use Standard JSON Input whenever possible. It includes full compiler metadata and gives the most reliable results.

1. Explorer UI

Go to the explorer

Go to https://explorer.somnia.network/ .

Open the verification page

Open Other -> Verify Contract.

Enter contract details

Enter your contract address and select a verification method.

Match compilation parameters

Match all compilation parameters exactly with your deployment settings:

  • Compiler version
  • EVM version
  • Optimizer and runs
  • Constructor args
  • License type

Verify and publish

Click Verify and Publish to complete the process.

Main UI verification options

  • Solidity (Flattened source code)
  • Solidity (Standard JSON input)
  • Solidity (Multi-part files)
  • Solidity (Sourcify)
  • Vyper (Single contract file)
  • Vyper (Multi-part files)
  • Vyper (Standard JSON input)

2. API Verification (Blockscout v2)

Base URL

https://mainnet.somnia.w3us.site/api/v2

Service health check

To check whether the verification service is active:

curl -L "https://mainnet.somnia.w3us.site/api/v2/smart-contracts/verification/config"

If healthy, it returns 200.

2.1 Flattened Solidity verification

curl -L \
  --request POST \
  --url "https://mainnet.somnia.w3us.site/api/v2/smart-contracts/<CONTRACT_ADDRESS>/verification/via/flattened-code" \
  --header "Content-Type: application/json" \
  --data '{
    "compiler_version": "v0.8.24+commit.e11b9ed9",
    "license_type": "mit",
    "source_code": "// SPDX-License-Identifier: MIT\npragma solidity ^0.8.24;\ncontract A { }",
    "is_optimization_enabled": true,
    "optimization_runs": 200,
    "contract_name": "A",
    "evm_version": "paris",
    "autodetect_constructor_args": true
  }'

2.2 Standard JSON Input verification

curl -L \
  --request POST \
  --url "https://mainnet.somnia.w3us.site/api/v2/smart-contracts/<CONTRACT_ADDRESS>/verification/via/standard-input" \
  --header "Content-Type: multipart/form-data" \
  --form "compiler_version=v0.8.24+commit.e11b9ed9" \
  --form "contract_name=MyContract" \
  --form "files[0]=@./standard-input.json" \
  --form "autodetect_constructor_args=true" \
  --form "license_type=mit"

2.3 Multi-part Solidity verification

curl -L \
  --request POST \
  --url "https://mainnet.somnia.w3us.site/api/v2/smart-contracts/<CONTRACT_ADDRESS>/verification/via/multi-part" \
  --header "Content-Type: multipart/form-data" \
  --form "compiler_version=v0.8.24+commit.e11b9ed9" \
  --form "license_type=mit" \
  --form "is_optimization_enabled=true" \
  --form "optimization_runs=200" \
  --form "evm_version=paris" \
  --form "files[0]=@./contracts/MyContract.sol" \
  --form "files[1]=@./contracts/Lib.sol"

License values (example)

In Blockscout API, license_type is sent as a string:

  • none
  • unlicense
  • mit
  • gnu_gpl_v2
  • gnu_gpl_v3
  • gnu_lgpl_v2_1
  • gnu_lgpl_v3
  • bsd_2_clause
  • bsd_3_clause
  • mpl_2_0
  • osl_3_0
  • apache_2_0
  • gnu_agpl_v3
  • bsl_1_1

3. Hardhat Verification

For Somnia Blockscout, use the @nomicfoundation/hardhat-verify plugin.

Installation

npm install --save-dev @nomicfoundation/hardhat-verify

Example hardhat.config.ts

import { HardhatUserConfig } from "hardhat/config";
import "@nomicfoundation/hardhat-verify";

const config: HardhatUserConfig = {
  solidity: "0.8.24",
  networks: {
    "somnia-mainnet": {
      url: "<SOMNIA_RPC_URL>",
      accounts: ["<PRIVATE_KEY>"]
    }
  },
  etherscan: {
    apiKey: {
      // A real API key is not required for Blockscout verification
      "somnia-mainnet": "abc"
    },
    customChains: [
      {
        network: "somnia-mainnet",
        chainId: 5031,
        urls: {
          apiURL: "https://mainnet.somnia.w3us.site/api",
          browserURL: "https://mainnet.somnia.w3us.site/"
        }
      }
    ]
  },
  sourcify: {
    enabled: false
  }
};

export default config;

Verification command

npx hardhat verify \
  --network somnia-mainnet \
  <DEPLOYED_CONTRACT_ADDRESS> \
  "<CONSTRUCTOR_ARG_1>" "<CONSTRUCTOR_ARG_2>"

4. Foundry Verification

Use Blockscout verifier in Foundry as follows:

forge verify-contract \
  --rpc-url <SOMNIA_RPC_URL> \
  <DEPLOYED_CONTRACT_ADDRESS> \
  src/MyContract.sol:MyContract \
  --verifier blockscout \
  --verifier-url https://mainnet.somnia.w3us.site/api/

To verify at deployment time:

forge create \
  --rpc-url <SOMNIA_RPC_URL> \
  --private-key $PRIVATE_KEY \
  src/MyContract.sol:MyContract \
  --verify \
  --verifier blockscout \
  --verifier-url https://mainnet.somnia.w3us.site/api/

Troubleshooting

  • Compiler version must match exactly (0.8.24 vs 0.8.24+commit... matters).
  • Optimizer settings must exactly match deployment settings.
  • Verification fails if constructor arguments are incorrect or missing.
  • For multi-file projects, prefer Standard JSON Input or Multi-part over Flattened.
  • If errors persist, retry first via UI and then via API, and compare payload differences.

Copied from docs.somnia.network (somnia-main-docs) by scripts/import-gitbook.mts, until it finds a home in a product's docs.Edit this page