base / base/skills

Proposal: add `verifying-contracts-on-basescan` skill

Open
#35 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
119
Forks
125
Avg merge
22h 30m
Merged PRs (30d)
2

Description

## Proposal

Add a new skill `verifying-contracts-on-basescan` covering contract verification on Base Mainnet and Sepolia.

## Why this keeps breaking in practice

The most common failure mode — for both developers and AI coding agents — is using the deprecated Basescan V1 API. V1 was fully deactivated on **August 15, 2025**, and the error it returns is:

```
You are using a deprecated V1 endpoint, switch to Etherscan API V2
using https://docs.etherscan.io/v2-migration
```

Stale docs, LLM training data, and blog posts keep surfacing `api.basescan.org/api` and per-chain Basescan keys. The correct path is the unified Etherscan V2 endpoint (`https://api.etherscan.io/v2/api`) with `chainid=8453` / `84532` and a single Etherscan key. A dedicated skill is the cleanest fix: one authoritative reference that agents can be pointed to.

## This is already tested — not just proposed

I verified the full flow on Base Sepolia before opening this issue:

- Deployed `SimpleStorage` with a constructor argument
- Verified via **Etherscan V2** (`forge verify-contract --verifier-url "https://api.etherscan.io/v2/api?chainid=84532"`): [`0xA6E4e2977dD3470Fa3E9683B98DC30B888755D0a`](https://sepolia.basescan.org/address/0xa6e4e2977dd3470fa3e9683b98dc30b888755d0a) → `Pass - Verified`
- Verified the same contract via **Sourcify** (`--verifier sourcify`, no API key): [`0xF0E6DF13b99525f9144D82f23b9DF860BAB4EE1e`](https://sepolia.basescan.org/address/0xF0E6DF13b99525f9144D82f23b9DF860BAB4EE1e) → `exact_match`
- Confirmed the V1 endpoint returns exactly the error above
- Confirmed Foundry's `already verified. Skipping verification` behavior (graceful, not an error)

The skill content is already drafted and matches the structure and tone of existing skills.

## Scope (small, focused)

- V1 → V2 migration table with the exact error message
- Foundry `forge verify-contract` (Mainnet/Sepolia, constructor args, `--watch`, linked libraries)
- `foundry.toml` V2 config replacing the deprecated per-chain basescan URLs
- Hardhat `@nomicfoundation/hardhat-verify` — `apiKey` as single string + `customChains` pointing to V2
- Manual UI verification on basescan.org (single file vs standard JSON input)
- Sourcify as a decentralized alternative (no API key)
- Common errors table with causes and fixes
- Cross-reference to `deploying-contracts-on-base` for deploy+verify flow — no duplication

## Out of scope

Deployment itself — that lives in `deploying-contracts-on-base`.

## On CONTRIBUTING.md

I noticed it currently says contributions are limited to the Base core team. Happy to work within whatever process you prefer — if you'd rather take the content and merge it internally that's fine too, just say the word. cc @youssefea @soheimam

Contributor guide

Open the contributing guide

Research direction

Read CONTRIBUTING.md and compare the structure and tone of existing skills, especially deploying-contracts-on-base. Locate the skill directory and add the drafted verifying-contracts-on-basescan content, covering the stated V1/V2, Foundry, Hardhat, UI, Sourcify, error, and cross-reference sections without duplicating deployment guidance.

Written by the indexing model from the issue text.

Assessment

Tech stack
solidity
Domain
blockchain, documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
66/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.