proxmox/docs/08-monitoring/BLOCKSCOUT_VERIFICATION_GUIDE.md

# Blockscout Contract Verification Guide - ChainID 138

**Last Updated:** 2026-01-31  
**Document Version:** 1.0  
**Status:** Active Documentation

---

**Purpose**: Guide for verifying smart contracts on ChainID 138 using Blockscout  
**Block Explorer**: `https://explorer.d-bis.org`

---

## Overview

ChainID 138 uses **Blockscout** (self-hosted) as its block explorer. This guide covers how to verify smart contracts deployed on ChainID 138 using Foundry's verification tools.

---

## Prerequisites

1. **Foundry** installed and configured
2. **Deployed contracts** on ChainID 138
3. **Access to contract source code** and constructor arguments
4. **Blockscout instance** accessible at `https://explorer.d-bis.org`

---

## Blockscout Configuration

### Block Explorer Information

- **URL**: `https://explorer.d-bis.org`
- **API Endpoint**: `https://explorer.d-bis.org/api`
- **Type**: Self-hosted Blockscout
- **Chain ID**: 138
- **API Key**: Not required (self-hosted instance)

---

## Verification Methods

### Method 1: Using Foundry Script with Verification

When deploying contracts with Foundry, add Blockscout verification flags:

```bash
forge script script/YourDeploymentScript.s.sol:YourScript \
  --rpc-url https://rpc-core.d-bis.org \
  --private-key $PRIVATE_KEY \
  --broadcast \
  --verify \
  --verifier blockscout \
  --verifier-url https://explorer.d-bis.org/api \
  -vvvv
```

### Method 2: Manual Verification with `forge verify-contract`

After deployment, verify contracts manually:

```bash
forge verify-contract \
  <CONTRACT_ADDRESS> \
  <CONTRACT_NAME> \
  --chain-id 138 \
  --rpc-url https://rpc-core.d-bis.org \
  --verifier blockscout \
  --verifier-url https://explorer.d-bis.org/api \
  --constructor-args $(cast abi-encode "constructor(<ARGS>)" <ARG1> <ARG2> ...) \
  --compiler-version <VERSION>
```

### Method 3: Using Foundry.toml Configuration

Add Blockscout configuration to `foundry.toml`:

```toml
[etherscan]
chain138 = { 
  url = "https://explorer.d-bis.org/api",
  verifier = "blockscout"
}
```

Then use:

```bash
forge verify-contract \
  <CONTRACT_ADDRESS> \
  <CONTRACT_NAME> \
  --chain chain138 \
  --rpc-url https://rpc-core.d-bis.org
```

---

## Verification Examples

### Example 1: Simple Contract (No Constructor Arguments)

```bash
forge verify-contract \
  0x1234567890123456789012345678901234567890 \
  SimpleContract \
  --chain-id 138 \
  --rpc-url https://rpc-core.d-bis.org \
  --verifier blockscout \
  --verifier-url https://explorer.d-bis.org/api \
  --compiler-version 0.8.20
```

### Example 2: Contract with Constructor Arguments

```bash
# First, encode constructor arguments
CONSTRUCTOR_ARGS=$(cast abi-encode "constructor(address,uint256)" \
  0x1111111111111111111111111111111111111111 \
  1000000000000000000)

# Then verify
forge verify-contract \
  0x1234567890123456789012345678901234567890 \
  ComplexContract \
  --chain-id 138 \
  --rpc-url https://rpc-core.d-bis.org \
  --verifier blockscout \
  --verifier-url https://explorer.d-bis.org/api \
  --constructor-args "$CONSTRUCTOR_ARGS" \
  --compiler-version 0.8.20
```

### Example 3: Verify with Libraries

If your contract uses libraries, specify them:

```bash
forge verify-contract \
  <CONTRACT_ADDRESS> \
  <CONTRACT_NAME> \
  --chain-id 138 \
  --rpc-url https://rpc-core.d-bis.org \
  --verifier blockscout \
  --verifier-url https://explorer.d-bis.org/api \
  --libraries <LIBRARY_NAME>:<LIBRARY_ADDRESS> \
  --compiler-version <VERSION>
```

---

## When proxy returns "Invalid JSON"

If you run `./scripts/verify/run-contract-verification-with-proxy.sh` and get **Invalid JSON, result=None**, Blockscout may have returned a non-JSON response.

**Note:** Using `--verifier-url https://explorer.d-bis.org/api` **directly** with Forge (no proxy) fails with *Params 'module' and 'action' are required* — Blockscout's Etherscan-compatible API expects these as query parameters, which the **forge-verification-proxy** adds. So verification must use either (1) the proxy from a host that can reach Blockscout, or (2) manual UI below.

From a host where **explorer.d-bis.org** is reachable, you can try the proxy again, or verify manually. If you have a custom client that sends `module=contract&action=verifysourcecode`, you can verify directly:

```bash
cd smom-dbis-138
RPC="${RPC_URL_138:-https://rpc-core.d-bis.org}"
VERIFIER="https://explorer.d-bis.org/api"

# CCIPSender
forge verify-contract 0x105F8A15b819948a89153505762444Ee9f324684 \
  contracts/ccip/CCIPSender.sol:CCIPSender \
  --chain-id 138 --rpc-url "$RPC" --verifier blockscout --verifier-url "$VERIFIER" --flatten

# Oracle Proxy
forge verify-contract 0x3304b747e565a97ec8ac220b0b6a1f6ffdb837e6 \
  contracts/oracle/Proxy.sol:Proxy \
  --chain-id 138 --rpc-url "$RPC" --verifier blockscout --verifier-url "$VERIFIER" --flatten

# CCIPWETH9Bridge
forge verify-contract 0xcacfd227A040002e49e2e01626363071324f820a \
  contracts/ccip/CCIPWETH9Bridge.sol:CCIPWETH9Bridge \
  --chain-id 138 --rpc-url "$RPC" --verifier blockscout --verifier-url "$VERIFIER" --flatten

# CCIPWETH10Bridge
forge verify-contract 0xe0E93247376aa097dB308B92e6Ba36bA015535D0 \
  contracts/ccip/CCIPWETH10Bridge.sol:CCIPWETH10Bridge \
  --chain-id 138 --rpc-url "$RPC" --verifier blockscout --verifier-url "$VERIFIER" --flatten
```

Or run the batch script with the proxy pointing at the public explorer URL (from a host that can reach it): `FORGE_VERIFIER_URL=https://explorer.d-bis.org/api ./scripts/verify-contracts-blockscout.sh` (from repo root, after `cd smom-dbis-138` as needed for paths). See also [OPERATOR_OPTIONAL_CHECKLIST](../11-references/OPERATOR_OPTIONAL_CHECKLIST.md) § Blockscout.

---

## Troubleshooting

### Issue: Verification Fails with "Contract Not Found"

**Solution**: 
- Ensure the contract is deployed and confirmed on ChainID 138
- Verify the contract address is correct
- Check that the RPC endpoint is accessible

### Issue: "Invalid Source Code"

**Solution**:
- Ensure compiler version matches the deployment compiler version
- Verify all source files are accessible
- Check that constructor arguments are correctly encoded

### Issue: "Already Verified"

**Solution**:
- The contract is already verified on Blockscout
- Check the contract on the explorer: `https://explorer.d-bis.org/address/<CONTRACT_ADDRESS>`

### Issue: Blockscout API Timeout

**Solution**:
- Check if Blockscout instance is running and accessible
- Verify network connectivity to `https://explorer.d-bis.org`
- Try again after a few moments (Blockscout may be indexing)

### Issue: Verification returns HTML or 502

**Symptom:** Proxy or Forge reports "Invalid JSON", "Blockscout returned HTML", or 502 Bad Gateway.

**Causes:** Blockscout (VMID 5000) may be down, DB not migrated, or thin pool full. The proxy converts non-JSON responses into a clear error message.

**Solutions**:
1. **From LAN:** Ensure Blockscout is reachable: `curl -s -o /dev/null -w "%{http_code}" http://192.168.11.140:4000/api?module=stats&action=eth_price` (expect 200 or 404, not 502).
2. **Fix Blockscout:** Follow [BLOCKSCOUT_FIX_RUNBOOK.md](../03-deployment/BLOCKSCOUT_FIX_RUNBOOK.md) (SSL/migrations, thin pool, start stack).
3. **Verify via UI:** Use **Verify & Publish** in the explorer (see section below) when the site is up; no proxy needed.

---

## Manual Verification via Blockscout UI

If automated verification fails, you can verify contracts manually through the Blockscout web interface:

1. Navigate to the contract address: `https://explorer.d-bis.org/address/<CONTRACT_ADDRESS>`
2. Click on **"Verify & Publish"** tab
3. Select verification method:
   - **Via Standard JSON Input** (recommended)
   - **Via Sourcify**
   - **Via Multi-file**
4. Upload contract source code and metadata
5. Provide constructor arguments (if any)
6. Submit for verification

---

## Verification Best Practices

1. **Verify Immediately After Deployment**: Verify contracts right after deployment while deployment details are fresh
2. **Use Standard JSON Input**: Most reliable method for complex contracts
3. **Document Constructor Arguments**: Keep a record of constructor arguments used during deployment
4. **Test Verification Locally**: Test your verification command before deploying to production
5. **Keep Source Code Organized**: Maintain clean source code structure for easier verification

---

## Related Documentation

- **Block Explorer**: `https://explorer.d-bis.org`
- **RPC Endpoint**: `https://rpc-core.d-bis.org`
- **API Keys Documentation**: See `docs/CROSS_CHAIN_BRIDGE_ADDRESSES.md`
- **Contract Deployment Guide**: See `docs/CONTRACT_DEPLOYMENT_GUIDE.md`

---

## Quick Reference

### Blockscout API Endpoints

- **API Base URL**: `https://explorer.d-bis.org/api`
- **Contract Verification**: `POST /api/v2/smart-contracts/<ADDRESS>/verification`
- **Contract Info**: `GET /api/v2/smart-contracts/<ADDRESS>`

### Common Verification Flags

```bash
--verifier blockscout                    # Use Blockscout verifier
--verifier-url https://explorer.d-bis.org/api  # Blockscout API URL
--chain-id 138                           # Chain ID 138
--compiler-version 0.8.20                # Solidity compiler version
--constructor-args <ENCODED_ARGS>        # Encoded constructor arguments
--libraries <LIB>:<ADDR>                 # Library addresses
```

---

**Last Updated**: 2026-02-23  
**Status**: ✅ Ready for use with ChainID 138