Etherscan Etherscan contract verification matches compiled source to deployed bytecode
Etherscan contract verification recompiles source code and compares the resulting bytecode with a deployed contract. A successful match publishes readable source and compilation details on the contract address page. Reproducing the deployment requires the original compiler settings and dependencies; constructor inputs matter for deployment-level matching. Exact Match, Similar Match and Runtime Match establish different relationships between the displayed source and onchain code. Security assessment remains a separate task.
Prepare the deployment build before requesting publication
Recover the original source and compiler input before opening Verify and Publish on the contract address page. For a hypothetical unverified deployment whose rebuilt bytecode differs from the onchain code, pause submission while you recover the original build inputs and resolve the mismatch.
The request must target the deployed address on the correct network and use a supported compiler. Check dependencies before submission. A saved build can preserve settings a current project checkout has changed, including imported source and library mappings.
- If the selected address has no deployed code, resolve the address, network or deployment issue first.
- If the build links external libraries, recover their original names and deployed addresses.
-
If compilation used custom metadata settings or
viaIR, choose Standard JSON input. - If required imports are missing, restore the dependency files from the deployment build.
- If you need the source to remain private, stop before submitting it for publication.
When the inputs match, submit the source and deployment details through the selected verification method. Successful verification makes the source available on the target address's Code tab, alongside its match type and compilation details.
A failed bytecode comparison calls for recovering the original inputs and correcting the submission. Correcting a verification request leaves the existing deployment in place. Etherscan generally does not allow a verified contract to become unverified again.
Compiler inputs determine a reproducible match
A reproducible build needs the original compiler release, compilation settings and source files.
Compiler release and optimization
Use the exact compiler version from the deployment build, including its release identifier. A Solidity version pragma defines an allowed compiler range; it does not identify the compiler used for deployment. Match optimization settings and the Ethereum Virtual Machine (EVM) target too. The viaIR option changes the compilation pipeline. A newer compiler or different optimization choice can produce different bytecode from the same source.
Source files and metadata
The Solidity compiler generates metadata containing source hashes, compiler details and compilation settings. By default, the compiler appends a metadata hash to runtime bytecode. Changing a filename, source path or even whitespace can therefore change the bytecode when that hash is included. Preserve the files and settings the deployment build used, including dependencies. A metadata mismatch calls for restoring the original metadata configuration. Turning off the hash in a verification submission only matches a deployment whose build used that setting; it does not repair an unrelated mismatch.
Constructor inputs and libraries complete the deployment context
Constructor arguments supply the initial inputs used during deployment and follow the contract's Application Binary Interface (ABI) encoding. Provide the encoded values the constructor originally received, with the correct types and order. A constructor with no parameters needs no argument payload. Current storage values can differ from those initial inputs. Creation bytecode includes deployment logic; runtime bytecode is the code left at the address afterward. Solidity creation code embeds immutable values into runtime bytecode before storing it onchain. A runtime comparison must account for those substitutions.
Externally linked libraries contribute addresses to the compiled contract. Verification needs the library identifiers and deployed addresses used for that build. Imported library source and a linked library address serve different purposes: one supplies compilation code, the other resolves a bytecode reference. Recovering source while substituting a different linked address changes the verification inputs.
Exact, similar and runtime matches cover different evidence
The match label defines what Etherscan established about the code shown for an address.
Exact Match
An Exact Match covers the deployed contract code and its constructor arguments. The Code tab presents its verified source and deployment details, including encoded and decoded constructor values when arguments apply.
Similar Match
Similar Match associates a contract with source already verified for matching creation bytecode, excluding constructor arguments from the match. Those inputs or initialization can differ. Cross-Chain Similar Match offers this route when suitable verified code exists on another Etherscan explorer; its result remains a similar match.
Runtime Match
Runtime Match establishes a match for the code stored at the contract address and executed during calls. It excludes deployment bytecode and constructor arguments from verification. A runtime match supports inspection of executable logic while leaving the original deployment details outside that match's scope.
Submission formats preserve different build details
The submission format determines which parts of the compiler configuration the verification service can reproduce. Choose a format matching the source language and original build.
Source files and Standard JSON input
Single-file verification takes flattened source with imports resolved. Multi-file submission preserves separate files. Solidity Standard JSON input bundles source content and settings, including custom metadata options and viaIR. Submit the JSON input the compiler received; a compilation output artifact has a different structure. The contract selection must name the intended compilation target, with its source path where the method requires it. Etherscan also supports Vyper verification through its language-specific JSON format.
API submission and result fields
API verification requires an API key, the selected chain and the deployment inputs. A successful submission response contains a GUID, an identifier for checking the request's status. That response acknowledges the submission. The status check reports the verification result, with Pass - Verified indicating success. An HTTP response alone cannot establish that Etherscan accepted the source as a match.
Proxy verification depends on the active implementation
Proxy verification concerns the relationship between a forwarding contract and the implementation code handling its calls. Verifying the proxy's source alone does not verify every implementation it may use. Etherscan can associate a detected implementation with the proxy page and expose its ABI through proxy interaction tabs. Its API also offers an expected implementation parameter to constrain that association.
Upgradeable proxies can change implementation while retaining the proxy address. Some patterns resolve the implementation through a beacon, and some route different functions to different implementation contracts. The deployed proxy design determines which arrangement applies. The source match belongs to an implementation address, while the proxy's active routing can change. Detection also uses heuristics, so a proxy interaction tab does not by itself prove which code executes. Inspect the active routing and the corresponding verified source before treating a proxy listing as the complete execution logic.
Inspect the matched code before considering a signed call
Published source supports inspection of function bodies, access controls and external calls. The ABI describes how applications encode interactions; it does not expose every behavior by itself. A verification badge confirms a code match within its stated scope. Security audits and the contract's current permissions answer different questions. For an ERC-20 token approval, matched source can reveal the relevant logic, while the live allowance records the remaining spending authorization an account has granted.
Read-only queries inspect exposed data without changing blockchain state. Write Contract actions require signing and can change state.
Etherscan contract verification: what people ask
Does source code verification cost gas?
Submitting source for verification does not require an Ethereum transaction or a gas payment. Etherscan makes contract verification endpoints available on its Free API tier. Deployment and signed state-changing contract calls have their own gas costs; those costs are separate from publishing a source-code match.
How long should I wait when Etherscan cannot locate a newly deployed contract?
Etherscan must index the deployment before its verification service can locate the contract. Indexing usually takes a few blocks, although high chain activity can delay it. If the code remains missing after a few minutes, confirm a successful deployment to the correct address on the intended network before contacting Etherscan support. A successful deployment can exist before the explorer displays it. The same error can also indicate a wrong address, wrong network or failed deployment, so elapsed time alone cannot distinguish an indexing delay from an incorrect target.
Can a Similar Match become an Exact Match?
Yes. Verify contract address ownership with your Etherscan account, then request reverification access from Etherscan support. Once Etherscan enables that access, resubmit the original source and accurate deployment inputs for Exact Match verification. A Similar Match error can therefore reflect an existing match with restricted updating, rather than incorrect source.
What does the optimizer runs setting represent?
Solidity's optimizer runs parameter estimates how often each opcode will execute over the contract's lifetime. The value guides the trade-off between code size and execution cost. It does not count optimizer iterations or verification attempts. Verification needs the original setting even if another value appears more efficient.
Is source verification the same as verifying contract address ownership?
Source verification and contract address ownership verification serve different purposes. Source verification establishes a code match. Ownership verification associates a contract address with an Etherscan account and typically requires a message signed by the deployer address. It enables token information update requests; an ownership claim does not substitute for matching bytecode.
Will verification automatically add a token logo or project details?
Source verification does not automatically publish a token logo or other submitted project information. It is a prerequisite for token information updates, which follow a separate ownership and submission process. Etherscan reviews those update requests before publishing them, so a code match cannot establish approval of the token's branding.
When should I retry a temporary verification error?
A temporary service error calls for retrying after the disruption, without changing a build that already reproduces the deployment. A persistent bytecode, library or compiler error needs corrected submission inputs. Repeating the same incompatible payload will not repair it, and a temporary error does not establish that verification succeeded.
What happens if the deployment used an unsupported compiler version?
An unsupported compiler version can prevent automated verification even when the recovered source is correct. Recompiling with a newer compiler can produce different bytecode and therefore fail to establish the original match. Historical compiler builds may require assistance from Etherscan support rather than substitution with a different compiler release.
Last updated ยท