Welcome to Sourcify's first short FAQ! If your questions around source verification haven't been answered after reading this post, please feel free to drop by the Sourcify Gitter channel and ask us any question there. Also stay tuned on more tutorials and developer focused content to follow here and on the Remix blog!
Source Verification
What is source verification?
Solidity contract source code can be verified by checking whether the on-chain deployed code is matching with published source code files. In order to allow for source verification, the source and metadata files need to be published, thus enabling developers to verify that the deployed bytecode is an exact match to the published files. By doing so, it can be verified that the contract code is exactly the same as when it was deployed on the blockchain and has not been adjusted or tampered with before deploying it.
Why is source verification important?
Without open source contracts it is hard to tell what the application you are using will actually be doing. One of the decentralized web's biggest aspirations is to build a trustless infrastructure, aiming to reduce the need to trust third parties and service providers and decreasing censorship opportunities. It should, by design, not be required to "blindly" trust a dapp developer or web3 project. It should always be possible to verify it for yourself, or if you're not tech-savvy enough, leverage the power of the crowd of other developers who can look at and call out malicious code once it's open source.
Why should I publish my source code / open-source it?
Closed source contract code cannot easily be verified since the trustless setup is not maintained if you have to rely on a third party which verifies the code for you. In that scenario, the verification service providers could be an attack vector and would need to be trusted.
Metadata
What is bytecode metadata?
Metadata is data that describes and gives information about other data. Bytecode (contract) metadata in Solidity is supported since version 0.4.7 and is automatically generated by the Solidity compiler in the form of a JSON file. The metadata file contains information about the compiled contract, e.g. the used compiler version, the sources used, the ABI and the NatSpec documentation. The metadata file also contains IPFS and SWARM hashes of the source code, which allows to retrieve them if they are available.
Metadata files can also contain literal sources, which means that the actual code of the contract is present in the metadata file's source section. Literal sources will be covered by the Sourcify verification in future, too.
What is NatSpec?
NatSpec is short for Ethereum Natural Language Specification Format. Solidity contracts can use NatSpec comments to provide rich documentation for functions, return variables and more. The comments are categorized into developer-focused and end-user-focused messages. The end-user-focused messages can be crucial to users since they describe what the contract interaction will do in plain language. It is highly recommended to fully annotate Solidity contracts using NatSpec for all public interfaces.
NatSpec comments can be displayed to the user at the time of interaction, e.g. by being prompted in the wallet interface before signing a transaction, or later as a comment, e.g. in a list of past transactions.
Sourcify
What is Sourcify?
Sourcify is an initiative which aims to make interacting with smart contracts on the blockchain safer and more transparent for users.
To achieve this goal, Sourcify supports several efforts to foster adoption of open-source source verification, metadata files and NatSpec comments.
At its core, Sourcify currently maintains
- an interface that helps developers to verify metadata and contract source code.
- a contract repository of all verified contracts.
- a monitoring & verifier service that checks for new contracts on Ethereum blockchains (mainnet and testnets) and tries to verify them automatically.
Sourcify basically provides the base layer, which allows other tools to be built on top of it. Its main purpose is to keep metadata and source files available via IPFS and Swarm (preventing that the links in the bytecode turn into dead links).
Besides the technical infrastructure, Sourcify is also a collective movement to bring transparency and awareness to the space. We try to educate and build bridges between development tools, wallets, interfaces and other components which all play an important role in demystifying interaction with smart contracts for the end user and hence making blockchain interactions safer.
How does the Sourcify monitoring & verifier service work?
The monitoring and verifier component...
- listens for new blocks on blockchains and fetches transactions from them.
- checks to see if their metadata and source code is published on IPFS or Swarm.
- recompiles the code.
- checks that it is the same as the deployed code.
- permanently stores the source code, ABI and other metadata on IPFS.
How is the Sourcify verifier different to verifying my contracts on EtherScan?
Before we dive into the differences: EtherScan is doing invaluable work for the ecosystem with their contract verification service, which we are very grateful for!
However, there are some minor problems with the current setup in the EtherScan verification: EtherScan often "flattens" the code which makes it impossible to verify the metadata. At this point, not even EtherScan could recompile the code to the last byte. You'd have to trust whoever uploaded the source code that this is the original source code with the correct NatSpec comments and variable names.
Sourcify adds the option to make any contract independently verifiable. It also covers another important aspect: the availability of the code. Should EtherScan ever go down, there's no way to access their verified contracts anymore. Sourcify tries to solve this by making the storage of the source files and the processes around the verification more decentralized, independent and hence more resilient.
How is source verification & commenting your code with NatSpec connected and why is it more powerful if you do both?
If you verified that the code you deployed is an exact match to what you open-sourced that is great! Developers now can verify themselves that your dapp is actually doing what it promised.
However, it will still be hard for end-users to understand what they are doing when interacting with your code. Only by translating what the contract interactions mean into NatSpec you can help them comprehend what's going on under the hood. To ensure that you don't comment code with inadequate comments to mislead the users, all of the comments and metadata also get published and verified. Malicious actors could of course still use "wrong" NatSpec comments, however, Sourcify would guarantee that the comments match those used at compilation time. Other developers could now check the NatSpec comments in the open-source code and verify their accuracy.
Source Verification & NatSpec go hand-in-hand for greater transparency in contract interactions!
It's simple:
- Only verifying source code: 📝🔍 + 🤔❓= ❌ (code is transparent, but end user does not understand it = bad)
- Only using NatSpec: 🤓💡 + 📝🙈 = ❌ (end user understands, but NatSpec could be lying since code isn't verified = bad)
- Using source verification and NatSpec: 📝🔍 + 🤓💡 = ✅ (code is transparent, end users can understand it = awesome!)
How decentralized is Sourcify?
- Contract repo: The Sourcify contract repository is published both via HTTPS as well as on IPFS.
- Interfaces: If you are using the Sourcify UI then you are verifying via our verification service backend. However, you could also run this service yourself. All code is available in the EF Sourcify repository and the Sourcify GitHub organization. Additionally, the Sourcify CLI will soon be published.
The User Side: Improving Dapp UX with Sourcify?
What's wrong about the current UX when signing transactions?
You probably already stumbled over a transaction which had random hex string in the description. If you went ahead and signed this transaction you blindly trusted the developer of the dapp to do what they promised.
Wouldn't it be great to have the option to verify what is happening and take an informed decision instead?
Sourcify aims to add that needed context to signing decisions by displaying whether the source code has been verified and what the contract interaction actually means in layman's terms.
How can we improve the UX using Sourcify?
Developers can help users take an informed decision by commenting their code using NatSpec. To verify that their NatSpec comments are actually accurate, they should publish the source files to an open directory.
It's important that interface tools like wallets display the NatSpec comments to make them visible to the user before the contract interaction.
How can I check whether a contract has been verified?
Currently, contracts that have been verified via Sourcify don't yet get a special label or tag on wallets or interfaces (like blockexplorers). It would be great it that were the case in future though!
For now, you can use the Sourcify contract repository. It can be accessed via HTTPS or IPFS.
Use the contract's address and search for it in the repository. If it is there, it is a match (aka verified). 🎉
What are full matches?
Full matches mean that the source files as well as the metadata files were an exact match between the deployed bytecode and the published files.
What are partial matches?
Partial matches occur when the metadata hash does not match. This means that the source code compiles to the same bytecode and thus the contract behaves in the same way, but the source code can be different: Variables can have misleading names, comments can be different and especially the NatSpec comments could have been modified.
The Tooling Side
What tooling is needed to make source verification more convenient?
The right support by existing and new tools can help make source verification much easier and more convenient for developers.
Quick wins on the tooling side include:
- Encourage auto-publishing of source files via deployment tools and make publishing the default option if license is specified as open source (licence identifiers are supported as of Solidity v0.6.8).
- Create libraries (in different languages) that wallets can use to easily recompile bytecode.
What is needed on the wallet / UI side to make users aware of verified contracts?
Wallets and user interfaces are a crucial puzzle piece to bring awareness and broader adoption to source verification and NatSpec comments. To make users aware of verified contracts, wallets and other user interfaces could:
- Show which contracts are verified and which are not during contract interaction.
- Warn users if a contract has not been verified.
- Always display the NatSpec comments, if available.
- Warn users if NatSpec comments have not been verified and educate about the fact, that those explanations could potentially lie.
- Educate users to only sign an interaction which is not NatSpec-commented if they know what they are doing.