You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Docs update: clarity, structure, and content improvements (#56)
* Enhance API documentation with detailed API descriptions and update contract data viewing link format. Adjust CI report message for clarity.
* Reorder contract dataset docs and update export frequency wording
* Update contract dataset documentation for improved clarity and formatting
- Emphasize the repository UI access link by bolding it.
- Adjust font sizes for section titles in the repository UI documentation for consistency.
- Reorganize the signatures database section to highlight API and Playground links more prominently while maintaining the schema and download information.
* Add example Colab Notebook link to BigQuery documentation
* Refactor source code verification documentation for clarity
- Split long paragraphs for better readability.
- Emphasize the distinction between verification and contract safety.
- Add links to relevant blog posts and talks on source code verification.
* Enhance verification documentation for clarity and consistency
- Bold the verification UI link for better visibility.
- Update terminology for match types to reduce confusion, clarifying "Exact Matches" and "Matches" with previous names for context.
- Remove redundant info box regarding previous terminology to streamline content.
* Refactor monitoring service and transformations documentation for clarity
- Remove outdated sections from the monitoring service documentation to streamline content.
- Update library and immutable variable examples with correct links for better accessibility.
- Enhance overall readability and consistency across documentation sections.
* Update immutables documentation with correct contract references and bytecode examples
- Replace Görli contract reference with Sepolia contract for accuracy.
- Update bytecode examples to reflect the correct immutable variable values.
- Enhance clarity in the explanation of bytecode modifications during contract deployment.
* Update libraries documentation to include new examples for manually linked libraries
- Replace outdated Görli and Rinkeby examples with new Optimism and Base contract references.
- Clarify the section title to emphasize the focus on manually linked libraries.
* Update intro page with Why Sourcify section and problem statement
* Extend intro
* Apply suggestions from code review
Co-authored-by: Manuel Wedler <manuel@wedler.dev>
* Remove Vyper in exact match wording
---------
Co-authored-by: Manuel Wedler <manuel@wedler.dev>
Copy file name to clipboardExpand all lines: docs/0. Intro.md
+22-2Lines changed: 22 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,13 +1,33 @@
1
1
---
2
2
id: intro
3
3
slug: /intro
4
-
title: Intro
4
+
title: Intro & Why Sourcify?
5
5
---
6
6
7
-
Sourcify ([sourcify.dev](https://sourcify.dev)) is a source-code verification service for Ethereum smart contracts supporting Solidity, Vyper, and Yul. Sourcify is fully committed to Open-source, Open-data, and Open-standards in smart-contract verification instead of siloed, proprietary services. We foster these values across the ecosystem and work actively to push the status quo in this direction.
7
+
Sourcify ([sourcify.dev](https://sourcify.dev)) is a source-code verification service for Ethereum smart contracts supporting Solidity, Vyper, and Yul. Sourcify is fully committed to:
8
+
- Open-source
9
+
- Open-data
10
+
- Open-standards
11
+
in smart-contract verification.
12
+
13
+
We foster these values across the ecosystem and work actively to push the status quo in this direction.
14
+
15
+
## Why Sourcify?
16
+
17
+
We believe the current smart contract verification ecosystem hasn't been able to progress due to several key problems:
18
+
19
+
-**Closed source**: The dominant verification service is not open source, operating as a black box, yet most assume it is.
20
+
-**Centralization**: Contracts are typically verified in only one place; any single verifier will have bugs and mistakes with no fallback.
21
+
-**Siloed data**: Contract data is locked in proprietary services, blocking bulk research, vulnerability analysis, and AI training, and risking permanent loss of Ethereum's history if a service shuts down.
22
+
-**Stagnant APIs**: Existing APIs don't expose useful artifacts like `storageLayout`, `sourceMaps`, or `cborAuxdata` that would enable better tooling.
23
+
-**No standards**: No common verification standards exist, and verifiers don't share knowledge or learnings publicly.
24
+
25
+
Read more about the problems in the [Roadmap 2025](/blog/roadmap-2025) blog post.
8
26
9
27
Different than other verification services, Sourcify leverages the [Solidity metadata](/docs/metadata/) and its integrity hash to find [exact matches](/docs/exact-match-vs-match/) of Solidity contracts (see [the playground](https://playground.sourcify.dev)).
10
28
29
+
Our complete stack is open-source and we daily share our whole dataset in modern data formats (see [Contract dataset](/docs/repository/)). We also share new verifications with all known verifiers (see [External verifiers](/docs/external-verifiers/)) and share contracts via the [Verifier Alliance](https://verifieralliance.org/).
30
+
11
31
## How the docs are structured
12
32
13
33
- Start with [What is source code verification](/docs/what-is-source-code-verification) for verification basics and methods (UI, Remix, Hardhat, Foundry, API).
Copy file name to clipboardExpand all lines: docs/1. API.md
+11-7Lines changed: 11 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,18 +10,22 @@ import SwaggerContainer from "../src/components/SwaggerContainer";
10
10
11
11
# API Documentation
12
12
13
-
## Table of Contents and resources
13
+
Sourcify has two APIs:
14
14
15
-
-[Basic usage](#basic-usage)
16
-
-[Server API Documentation](#server-api-documentation)
17
-
-[4byte (Signature) Service API Documentation](#4byte-signature-service-api-documentation)
18
-
-[Documentation in JSON format for LLMs](https://sourcify.dev/server/api-docs/swagger.json)
15
+
-[Server API](#server-api-documentation): The main API for Sourcify, used to verify contracts and get information about verified contracts under `https://sourcify.dev/server`.
16
+
-[4byte (Signature) Service API](#4byte-signature-service-api-documentation): The API for the 4byte signature service to query and submit Ethereum function, event, and error signatures under `https://api.4byte.sourcify.dev`.
17
+
18
+
If you are an LLM or an AI agent, check out:
19
+
-[OpenAPI JSON spec for Sourcify Server API Documentation ](https://sourcify.dev/server/api-docs/swagger.json)
20
+
-[OpenAPI JSON spec for 4byte (Signature) Service API Documentation](https://api.4byte.sourcify.dev/api-docs/swagger.json)
19
21
20
22
## Basic usage
21
23
22
24
### Verification
23
25
24
-
The main Sourcify API for verification is `/v2/verify/{chainId}/{address}`, it either returns a `verificationId` or an error. The status of the verification process can be tracked by `/v2/verify/${verificationId}`. For additional details, please check the [documentation below](#server-api-documentation).
26
+
The main Sourcify API for verification is `/v2/verify/{chainId}/{address}`, it either returns a a ticket with a `verificationId` or an error.
27
+
28
+
The status of the verification process can be tracked by `/v2/verify/${verificationId}`. For additional details, please check the [documentation below](#server-api-documentation).
25
29
26
30
<Tabs>
27
31
<TabItem value="curl" label="curl">
@@ -97,7 +101,7 @@ The main Sourcify API for verification is `/v2/verify/{chainId}/{address}`, it e
97
101
98
102
Verified contracts data can be fetched using the `/v2/contract/{chainId}/{address}?fields=all` API. For the full list of fields and additional parameters please check the [documentation below](#server-api-documentation).
99
103
100
-
Contract data can also be viewed in the web application at https://repo.sourcify.dev/{chainId}/{address}. This URL is intended only for browsing contract data through the UI.
104
+
Contract data can also be viewed in the web application at [https://repo.sourcify.dev/11155111/0x2738d13E81e30bC615766A0410e7cF199FD59A83](https://repo.sourcify.dev/11155111/0x2738d13E81e30bC615766A0410e7cF199FD59A83). This URL is intended only for browsing contract data through the UI.
Copy file name to clipboardExpand all lines: docs/4. Contract dataset/1. Download the dataset.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,7 +10,7 @@ The previous Parquet export format v1 is now deprecated. See the [note](/docs/re
10
10
11
11
:::
12
12
13
-
The entire Sourcify Database is exported continuously as [Parquet](https://github.com/apache/parquet-format) files, a modern columnar data format. Parquet files are compressed, efficient to query, and widely supported by data tools. ([Quick tutorial](https://www.datacamp.com/tutorial/apache-parquet)).
13
+
The entire Sourcify Database is exported regularly as [Parquet](https://github.com/apache/parquet-format) files, a modern columnar data format. Parquet files are compressed, efficient to query, and widely supported by data tools. ([Quick tutorial](https://www.datacamp.com/tutorial/apache-parquet)).
14
14
15
15
The export is hosted on Google Cloud Storage and accessible via an S3-compatible API at [export.sourcify.dev](https://export.sourcify.dev/). The export is based on the structure of the [Verifier Alliance database export](https://verifieralliance.org/docs/download).
Copy file name to clipboardExpand all lines: docs/4. Contract dataset/2. Repo UI.mdx
+4-4Lines changed: 4 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,7 +9,7 @@ import sources from "./sources.png";
9
9
importstorageLayoutfrom"./storage-layout.png";
10
10
11
11
The Repository UI is Sourcify's web interface for browsing verified contracts. Use it to inspect contract details and artifacts across supported chains.
12
-
You can access it at [repo.sourcify.dev](https://repo.sourcify.dev).
12
+
You can access it at **[repo.sourcify.dev](https://repo.sourcify.dev)**.
13
13
14
14
The repository data model follows the [Verifier Alliance](https://verifieralliance.org) schema with Sourcify-specific extensions, and verified artifacts are available through Sourcify's repository and IPFS.
15
15
@@ -37,7 +37,7 @@ Every contract's repository page shows compilation settings, ABI, metadata, and
Copy file name to clipboardExpand all lines: docs/4. Contract dataset/4. Signatures database.md
+5-4Lines changed: 5 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,9 +6,10 @@ title: Signatures database
6
6
7
7
We also build an Ethereum signature database from our verified contracts. When you verify a contract, the function, event, and error signatures are extracted from its ABI and stored in the database.
8
8
9
-
The data is stored in the same database as the verified contracts. The `signatures` table holds the signature in text and their keccak256 hashes. The `compiled_contracts_signatures` holds the mappings of signatures to compilations in a many-to-many relationship.
-**Schema**: Check [docs/repository/sourcify-database/#schema](/docs/repository/sourcify-database/#schema) for the schema.
12
-
-**API**: Check [docs/api/](/docs/api/) for the API.
13
13
-**Download**: You can download the related tables in Parquet format from [export.sourcify.dev](https://export.sourcify.dev). See [Download the Dataset](/docs/repository/download-dataset/) for more details.
14
-
-**Playground**: Visit [4byte.sourcify.dev](https://4byte.sourcify.dev) to search for signatures.
14
+
15
+
The data is stored in the same database as the verified contracts. The `signatures` table holds the signature in text and their keccak256 hashes. The `compiled_contracts_signatures` holds the mappings of signatures to compilations in a many-to-many relationship.
**Transparency**, **verifiability**, and **trustlessness** are the core values of blockchains and Ethereum especially. We want the smart contracts we are interacting with to be open-source. However you can't be sure if the open-source code you see is actually the one that lives on chain. Somone can show you a benign code on GitHub etc. and convince you to send your assets to a contract, but in reality it could be a malicious contract that's actually deployed at this address.
7
+
**Transparency**, **verifiability**, and **trustlessness** are the core values of blockchains and Ethereum especially. We want the smart contracts we are interacting with to be open-source.
8
+
9
+
However you can't be sure if the open-source code you see is actually the one that lives on chain. Somone can show you a benign code on GitHub etc. and convince you to send your assets to a contract, but in reality it could be a malicious contract that's actually deployed at this address.
8
10
9
11
This is where source code verification comes in. Source code verification makes sure the human-readable source code you see is the same as the one that was deployed on chain.
10
12
11
13
:::info
12
-
A verified contract does not necessarily mean it is safe to interact with it. The verification does not look into _what_ the contract does, but only that it corresponds to this source-code. The source-code itself can be malicious and contain bugs. It is the auditors' and the community's responsibility to verify the code's security.
14
+
A verified contract does not necessarily mean it is safe to interact with it. The verification does not look into _what_ the contract does, but only that it corresponds to this source-code.
15
+
16
+
The source-code itself can be malicious and contain bugs. It is the auditors' and the community's responsibility to verify the code's security.
13
17
:::
14
18
15
19
Smart contracts are written in human-readable programming languages like [Vyper](https://vyperlang.org/) or [Solidity](https://solidity.org/). But they are compiled to and deployed in bytecode (`1`s and `0`s), so they are not human-readable.
@@ -29,3 +33,13 @@ In simple terms, source code verification works by:
29
33
1. Taking a smart-contract written in a human-readable programming language (Solidity/Vyper)
30
34
2. Compiling it down to bytecode
31
35
3. Comparing the compiled bytecode with the on-chain bytecode that is deployed at a certain chain and address.
36
+
37
+
See our blog posts about source code verification:
38
+
-[A Technical Walkthrough of Source Code Verification](/blog/technical-verification-walkthrough)
39
+
-[Verify Contracts Perrrrrfectly: Why and How?](/blog/verify-contracts-perfectly)
40
+
-[Finding Auxdatas in Bytecode](/blog/finding-auxdatas-in-bytecode)
41
+
42
+
See our talks about source code verification:
43
+
- Solidity Summit 2025: [The State of Source Code Verification Closed, Painful, and Ready for Change](https://www.youtube.com/watch?v=4DLWcGtzh8A)
44
+
- Trustless://eil 2025: [Why Contract Verification Needs to Open Up](https://www.youtube.com/watch?v=S8QarbmvpcA)
45
+
- Open Source Hub Devconnect 2025: [Sourcify & Open Contract Verification](https://www.youtube.com/watch?v=G4oCJGwPOcI)
Copy file name to clipboardExpand all lines: docs/5. Verify on Sourcify/2. Verify via UI.mdx
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -14,7 +14,7 @@ import bytecodeDiff from "./bytecode-diff.png";
14
14
15
15
# Verify via UI
16
16
17
-
You can verify using our new verification UI at https://verify.sourcify.dev. See the Github repo [here](https://github.com/sourcifyeth/verify.sourcify.dev).
17
+
You can verify using our new verification UI at **[verify.sourcify.dev](https://verify.sourcify.dev)**. See the Github repo [here](https://github.com/sourcifyeth/verify.sourcify.dev).
18
18
19
19
First choose the chain you want to verify the contract on and provide the contract address.
Copy file name to clipboardExpand all lines: docs/6. Sourcify in depth/1. Exact match vs match.md
+5-18Lines changed: 5 additions & 18 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -19,26 +19,15 @@ Different compilation settings i.e. compiler versions, optimization runs result
19
19
20
20
:::
21
21
22
-
If the bytecode from recompiling the contract with the given source code files and the metadata correspond to the bytecode of the contract of the given address and chain, it will be a **match**. Sourcify defines two types of matches upon verifying contracts: **Exact Matches** and **Matches**.
22
+
If the bytecode from recompiling the contract with the given source code files and the metadata correspond to the bytecode of the contract of the given address and chain, it will be a **match**.
23
23
24
-
:::info Info
25
-
26
-
The match levels used a different terminology previously:
27
-
28
-
- Exact Match was called **Full / Perfect Match**
29
-
- Match was called **Partial Match**
30
-
31
-
This only concerns the naming. Their semantics are the same as before.
32
-
33
-
:::
24
+
Sourcify defines two types of matches upon verifying contracts: **Exact Matches** (prev. called "perfect match") and **Matches** (prev. called "partial match"). We renamed them, as "partial" often causes confusion leading users to think their contract is not verified.
34
25
35
26
## Exact Matches
36
27
37
-
<AvailableOnlyForSolidityAdmonitiondescription="Vyper contracts don't support exact matches because Vyper doesn't include the metadata hash in the bytecode."/>
38
-
39
-
Exact Matches refer to the cases when the bytecode of the deployed contract is byte-by-byte the same (excluding libraries and immutables) as the compilation output of the given source code files under the compilation settings defined in the [Metadata file](/docs/metadata).
28
+
Exact Matches (prev. called "perfect match") refer to the cases when the bytecode of the deployed contract is byte-by-byte the same (excluding libraries and immutables) as the compilation output of the given source code files under the compilation settings defined in the [Metadata file](/docs/metadata).
40
29
41
-
Most importantly, the fingerprints (metadata hashes) of the onchain code and the recompilation are exactly matching. The Metadata file includes the integrity hash of the source files, such that it is guaranteed that the contents of the source code files are exactly the same as when the contract author compiled and deployed the contract. If you were to add a comment, change a variable or function name, the exact match will be broken.
30
+
Most importantly, the fingerprints (metadata hashes for Solidity) of the onchain code and the recompilation are exactly matching. The Metadata file includes the integrity hash of the source files, such that it is guaranteed that the contents of the source code files are exactly the same as when the contract author compiled and deployed the contract. If you were to add a comment, change a variable or function name, the exact match will be broken.
42
31
43
32
Note that the addresses of the used [libraries](/docs/libraries) can differ in the bytecode if they were linked after the compilation. Similarly, any [immutables](/docs/immutables) will differ in the recompiled bytecode, as they are only placed into the runtime bytecode during deployment.
44
33
@@ -86,10 +75,8 @@ However, the only thing that changes in the bytecode when making a non-functiona
86
75
87
76
## Matches
88
77
89
-
Matches refer to cases when the deployed bytecode of the onchain contract match the bytecode resulting from the recompilation with the metadata and the source files **except the metadata hash**.
78
+
Matches (prev. called "partial match") refer to cases when the deployed bytecode of the onchain contract match the bytecode resulting from the recompilation with the metadata and the source files **except the metadata hash**.
90
79
91
80
In other words, the deployed contract and the given source code + metadata _function_ as the same but there are differences in source code comments, variable names, or other metadata fields such as source paths.
92
81
93
82
Note that here too, [libraries](/docs/libraries) and [immutables](/docs/immutables) can differ between the onchain bytecode and the recompilation.
94
-
95
-
This type of match is similar to how Etherscan verifies contracts. Yes, the matching source code in theory functions the same as the deployed contract but the displayed source code can be misleading or the bytecode can contain [excecutable instructions not seen in the source code](https://samczsun.com/hiding-in-plain-sight/).
@@ -28,10 +28,10 @@ These contract addresses for linked libraries need to be [passed to the compiler
28
28
29
29
However some tools and frameworks do regex replace the placeholders in the bytecode. This causes the addresses not to be found in the metadata. In that case, Sourcify compares the onchain deployed bytecode with the compiled deployed bytecode (with placeholders) to extract the linked library addresses.
30
30
31
-
Check out these examples:
31
+
Check out these examples with "Manually Linked Libraries":
0 commit comments