Restructure docs to make the right information more easily findable #51
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,9 @@ | ||
| --- | ||
| id: intro | ||
| slug: /intro | ||
| title: Intro | ||
| --- | ||
|
|
||
| Sourcify ([sourcify.dev](https://sourcify.dev)) is a source-code verification service for Ethereum smart contracts supporting Solidity and Vyper. Sourcify is fully commited to Open-source, Open-data and Open-standards in smart-contract verification instead of siloed, propriety services. We foster these values across the ecosystem and work actively to push the status-quo in this direction. | ||
|
|
||
| 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)). | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,31 @@ | ||||||
| --- | ||||||
| id: what-is-source-code-verification | ||||||
| slug: /what-is-source-code-verification | ||||||
| title: What is source code verification? | ||||||
| --- | ||||||
|
|
||||||
| **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. | ||||||
|
|
||||||
| 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. | ||||||
|
|
||||||
| :::info | ||||||
| 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. | ||||||
| ::: | ||||||
|
|
||||||
| 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. | ||||||
|
|
||||||
| ``` | ||||||
| 0x608060405234801561001057600080fd5b50600436106100365760003560e01c80632e64cec11461003b5780636057361d14610059575b600080fd5b610043610075565b60405161005091906100d9565b60405180910390f35b610073600480360381019061006e919061009d565b61007e565b005b60008054905090565b8060008190555050565b60008135905061009781610103565b92915050565b6000602082840312156100b3576100b26100fe565b5b60006100c184828501610088565b91505092915050565b6100d3816100f4565b82525050565b60006020820190506100ee60008301846100ca565b92915050565b6000819050919050565b600080fd5b61010c816100f4565b811461011757600080fd5b5056fea2646970667358221220404e37f487a89a932dca5e77faaf6ca2de3b991f93d230604b1b8daaef64766264736f6c63430008070033 | ||||||
| ``` | ||||||
|
|
||||||
| <div style={{textAlign: "center", fontStyle: "italic", marginTop: "-0.75rem", marginBottom: "1rem", fontSize: "0.9rem"}}> | ||||||
| How a contract looks like on Ethereum - <a href="https://holesky.otterscan.io/address/0x7ecedB5ca848e695ee8aB33cce9Ad1E1fe7865F8/contract">0x7ecedB5ca848e695ee8aB33cce9Ad1E1fe7865F8</a> on Ethereum Holesky Testnet | ||||||
|
Member
There was a problem hiding this comment.
Suggested change
the otterscan link is down |
||||||
| </div> | ||||||
|
|
||||||
| We can go from Solidity/Vyper code to bytecode, but not the other way around. This information is lost during compilation and we need the original source-code that compiles down to this bytecode. | ||||||
|
|
||||||
| In simple terms, source code verification works by: | ||||||
|
|
||||||
| 1. Taking a smart-contract written in a human-readable programming language (Solidity/Vyper) | ||||||
| 2. Compiling it down to bytecode | ||||||
| 3. Comparing the compiled bytecode with the on-chain bytecode that is deployed at a certain chain and address. | ||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,179 @@ | ||
| --- | ||
| id: how-to-verify | ||
| slug: /how-to-verify | ||
| title: Verify via UI | ||
| --- | ||
|
|
||
| import TOCInline from "@theme/TOCInline"; | ||
| import chainAddress from "./chain-address.png"; | ||
| import importSources from "./import-sources.png"; | ||
| import verificationMethods from "./methods.png"; | ||
| import buildInfo from "./build-info.png"; | ||
| import jobError from "./job-error.png"; | ||
| import bytecodeDiff from "./bytecode-diff.png"; | ||
|
|
||
| # Verify via UI | ||
|
|
||
| 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). | ||
|
|
||
| First choose the chain you want to verify the contract on and provide the contract address. | ||
|
|
||
| <div | ||
| style={{ | ||
| display: "flex", | ||
| flexDirection: "row", | ||
| gap: "10px", | ||
| justifyContent: "center", | ||
| }} | ||
| > | ||
| <img | ||
| src={chainAddress} | ||
| alt="Chain and address" | ||
| style={{ width: "100%", maxWidth: "600px" }} | ||
| /> | ||
| </div> | ||
|
|
||
| This will automatically check if the contract is verified on Sourcify on the same chain and all other supported chains. | ||
|
|
||
| ### Importing a contract | ||
|
|
||
| You can import a verified contract from different sources: | ||
|
|
||
| - **Etherscan**: Enter the chain and contract address to import the contract. You need an Etherscan API key to use this feature. Open the "Settings" on top right to add your API key. API keys are used locally in the browser and are not sent to Sourcify servers. | ||
| <div | ||
| style={{ | ||
| display: "flex", | ||
| flexDirection: "row", | ||
| gap: "10px", | ||
| justifyContent: "center", | ||
| }} | ||
| > | ||
| <img | ||
| src={importSources} | ||
| alt="Import sources" | ||
| style={{ width: "100%", maxWidth: "600px" }} | ||
| /> | ||
| </div> | ||
|
|
||
| ### Verification Methods | ||
|
|
||
| For both Solidity and Vyper contracts you can choose between the following verification methods: | ||
|
|
||
| - **Single file**: Provide single .sol or .vy file, alongside compiler settings. | ||
| - **Multiple files**: Provide multiple .sol or .vy files, alongside compiler settings. | ||
| - (preferred) **Standard JSON**: Provide a [standard JSON input file](https://docs.soliditylang.org/en/v0.8.30/using-the-compiler.html#input-description). | ||
|
|
||
| Prefer using the standard JSON or framework commands directly (see below) to maintain the full compilation and avoid any changes. Different compiler settings can break the verification. Flattening the sources also breaks the metadata hashes and you won't be able to get an ["Exact Match"](/docs/exact-match-vs-match). | ||
|
|
||
| Additionally the following option is available for Solidity contracts: | ||
|
|
||
| - **Metadata.json**: Provide a [metadata.json file](/docs/metadata) to verify the contract in the first file input field. Provide all the source files in the second file input field. This option checks the source hashes in the metadata.json provided and compares them with the hashes of the source files provided before submitting the verification. | ||
|
|
||
| <div | ||
| style={{ | ||
| display: "flex", | ||
| flexDirection: "column", | ||
| gap: "10px", | ||
| alignItems: "center", | ||
| }} | ||
| > | ||
| <img | ||
| src={verificationMethods} | ||
| alt="Verification methods" | ||
| style={{ width: "100%", maxWidth: "600px" }} | ||
| /> | ||
| <div style={{ fontSize: "12px", color: "gray", fontStyle: "italic" }}> | ||
| Available verification methods | ||
| </div> | ||
| </div> | ||
|
|
||
| ### Contract Identifier | ||
|
|
||
| From the files and contracts provided, we will ask you to select the contract you want to verify. Ie. if you've written a contract called `MyContract.sol` using other contracts `Ownable.sol` and `ERC20.sol`, you will be asked to select `MyContract.sol` as the contract to verify. | ||
|
|
||
| The format of the contract identifier is path:contractName e.g. | ||
|
|
||
| ``` | ||
| path/to/contractName.sol:contractName | ||
| ``` | ||
|
|
||
| The verification UI will parse the files and give you a list of contracts to choose from. You can always input the contract identifier manually. | ||
|
|
||
| ### (Optional) Creation Transaction Hash | ||
|
|
||
| Sourcify needs to find the transaction the contract was deployed in to get the creation bytecode. We get this information from different sources like block explorers (see [here](https://github.com/argotorg/sourcify/blob/staging/services/server/src/sourcify-chains-default.json)). You can still provide a creation transaction hash manually if you want to, or if Sourcify fails to verify via creation bytecode. | ||
|
|
||
| ### Hardhat/Foundry build-info files | ||
|
|
||
| If you’re using Hardhat or Foundry, the best way to verify is to use the framework’s CLI directly (see the respective documentation page to learn how). However, it is also possible to use the Sourcify build-info files to verify. | ||
|
|
||
| The build-info files are generated by the frameworks and contain the compilation information. This can be parsed and used by the verify.sourcify.dev UI to verify the contract. | ||
|
|
||
| You can find the build-info files in: | ||
|
|
||
| - Hardhat: `artifacts/build-info/<build-hash>.json` | ||
| - Foundry: `out/build-info/<build-hash>.json` | ||
|
|
||
| <div | ||
| style={{ | ||
| display: "flex", | ||
| flexDirection: "column", | ||
| gap: "10px", | ||
| alignItems: "center", | ||
| }} | ||
| > | ||
| <img | ||
| src={buildInfo} | ||
| alt="Build info" | ||
| style={{ width: "100%", maxWidth: "600px" }} | ||
| /> | ||
| <div style={{ fontSize: "12px", color: "gray", fontStyle: "italic" }}> | ||
| Build info files toggle | ||
| </div> | ||
| </div> | ||
|
|
||
| Click on the toggle to "Upload build-info file" and select the build-info file. | ||
|
|
||
| ## Verification Job | ||
|
|
||
| Once you've provided all the information, you can submit the verification. This will create a verification job. You can see the job in the UI and get the verification result. | ||
|
|
||
| If the verification fails you can see the error message and why it failed. | ||
|
|
||
| <div | ||
| style={{ | ||
| display: "flex", | ||
| flexDirection: "column", | ||
| gap: "10px", | ||
| alignItems: "center", | ||
| }} | ||
| > | ||
| <img | ||
| src={jobError} | ||
| alt="Job error" | ||
| style={{ width: "100%", maxWidth: "600px" }} | ||
| /> | ||
| <div style={{ fontSize: "12px", color: "gray", fontStyle: "italic" }}> | ||
| Example of a verification job that failed | ||
| </div> | ||
| </div> | ||
|
|
||
| You can see the diffs of the bytecodes if the compilation succeeds but the bytecodes did not match. | ||
|
|
||
| <div | ||
| style={{ | ||
| display: "flex", | ||
| flexDirection: "column", | ||
| gap: "10px", | ||
| alignItems: "center", | ||
| }} | ||
| > | ||
| <img | ||
| src={bytecodeDiff} | ||
| alt="Bytecode diff" | ||
| style={{ width: "100%", maxWidth: "600px" }} | ||
| /> | ||
| <div style={{ fontSize: "12px", color: "gray", fontStyle: "italic" }}> | ||
| Bytecode diffs | ||
| </div> | ||
| </div> |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,21 @@ | ||||||
| --- | ||||||
| id: verify-via-remix | ||||||
| slug: /verify-via-remix | ||||||
| title: Verify via Remix | ||||||
| --- | ||||||
|
|
||||||
| You can use the "unified verification plugin" written by the Sourcify team to verify on multiple verifiers on Remix. | ||||||
|
Member
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| 1. Click on the "Plugins" tab in bottom of the sidebar and search for "Contract Verification" | ||||||
| 2. Enable the plugin "Contract Verification" | ||||||
| 3. Click on the "Contract Verification" tab in the sidebar | ||||||
| 4. Enter the contract address and select a chain | ||||||
| 5. Select the contract to verify (you need to have compiled a contract on Remix first) | ||||||
| 6. By default all verifiers are enabled. For Etherscan you need to add your API key in the "Settings" tab | ||||||
| 7. You can see the verification result in the "Receipts" tab | ||||||
|
|
||||||
| <div> | ||||||
| <video width="100%" height="100%" playsinline autoplay muted controls> | ||||||
| <source src="/videos/remix.mp4" type="video/mp4" /> | ||||||
| </video> | ||||||
| </div> | ||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,27 @@ | ||
| --- | ||
| id: verify-via-hardhat | ||
| slug: /verify-via-hardhat | ||
| title: Verify via Hardhat | ||
| --- | ||
|
|
||
| The Hardhat plugin [@nomicfoundation/hardhat-verify](https://hardhat.org/hardhat-runner/plugins/nomicfoundation-hardhat-verify#verifying-on-sourcify) has official Sourcify support. | ||
|
|
||
| (This is still using the legacy Sourcify API) | ||
|
|
||
| In order to enable Sourcify support, add this to `hardhat.config.js`: | ||
|
|
||
| ```js title="hardhat.config.js" | ||
| sourcify: { | ||
| enabled: true, | ||
| // Optional: specify a different Sourcify server | ||
| apiUrl: "https://sourcify.dev/server", | ||
| // Optional: specify a different Sourcify repository | ||
| browserUrl: "https://repo.sourcify.dev", | ||
| } | ||
| ``` | ||
|
Comment on lines
+13
to
+21
Member
There was a problem hiding this comment. Wasn't this enabled by default?
Member
There was a problem hiding this comment. We also have different v2 and v3 commands on our main page. How does it relate to this? |
||
|
|
||
| After deploying your contracts you can verify on Sourcify with: | ||
|
|
||
| ```bash title="Verify a contract" | ||
| npx hardhat verify --network mainnet DEPLOYED_CONTRACT_ADDRESS | ||
| ``` | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,33 @@ | ||
| --- | ||
| id: verify-via-foundry | ||
| slug: /verify-via-foundry | ||
| title: Verify via Foundry | ||
| --- | ||
|
|
||
| Foundry natively supports Sourcify verification. You can verify contracts with the additional verify flags in Forge. | ||
|
|
||
| (This is still using the legacy Sourcify API) | ||
|
|
||
| ```bash title="Deploy and verify a contract" | ||
| forge create --rpc-url <your_rpc_url> \ | ||
| --constructor-args "ForgeUSD" "FUSD" 18 1000000000000000000000 \ | ||
| --private-key <your_private_key> \ | ||
| src/MyToken.sol:MyToken \ | ||
| --verify \ | ||
| --verification-provider sourcify | ||
| --verifier-url https://localhost:5555 # optional, defaults to https://sourcify.dev/server/ | ||
| ``` | ||
|
|
||
| ```bash title="Verify an already deployed (and compiled) contract" | ||
| forge verify-contract 0x55f7d4279CE387067f12561e7E0c194f5186cFba \ | ||
| src/MyToken.sol:MyToken \ | ||
| --chain-id 11155111 \ | ||
| --verifier sourcify | ||
| --verifier-url https://localhost:5555 # optional, defaults to https://sourcify.dev/server/ | ||
| ``` | ||
|
|
||
| ```bash title="Check if a contract is verified" | ||
| forge verify-check 0x55f7d4279CE387067f12561e7E0c194f5186cFba \ | ||
| --chain-id 11155111 \ | ||
| --verifier sourcify | ||
| ``` |
|
Member
There was a problem hiding this comment. Let's change "Verify via API" to "Verify via Sourcify API" (just the file name and title, not the slug) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,7 @@ | ||
| --- | ||
| id: verify-via-api | ||
| slug: /verify-via-api | ||
| title: Verify via API | ||
| --- | ||
|
|
||
| See the [API docs](/docs/api) for more information. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,15 @@ | ||
| --- | ||
| id: supported-languages | ||
| slug: /supported-languages | ||
| title: Supported languages | ||
| --- | ||
|
|
||
| # Supported languages | ||
|
|
||
| Sourcify supports Solidity, Vyper, and Yul. The table below summarizes the current level of support per language. | ||
|
|
||
| | Language | Supported | Exact match support | Monitoring | Metadata/ABI | IPFS data | | ||
| | --- | --- | --- | --- | --- | --- | | ||
| | Solidity | ✅ | ✅ | Similarity and IPFS | Both | ✅ | | ||
| | Vyper | ✅ | ❌ | Similarity | ABI | ❌ | | ||
| | Yul | ✅ | ❌ | Similarity | ❌ | ❌ | | ||
|
Comment on lines
+11
to
+15
Member
There was a problem hiding this comment. Can we separate Metadata and ABI into two columns? The IPFS data column isn't clear to me. Is it for monitor? Don't we also pin Vyper and Yul sources to IPFS?
Member
There was a problem hiding this comment. I also don't get the Monitoring: Similarity and IPFS part. This table is a bit confusing overall. I think we can even remove this page completely. |
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,3 @@ | ||
| { | ||
| "collapsed": false | ||
| } |
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
File renamed without changes
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Below this paragraph, we could add a short explanation how the docs are structured and where to go next.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes I think this page should give a nice overview of Sourcify, source code verification and the docs specifically.
We can skip it for now and I can look at this later