# All you need to know about Sourcify

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](https://gitter.im/ethereum/source-verify) and ask us any question there!

## Source Verification
### What is source verification?

In a software development context, the term source verification describes the process of verifying the legitimacy of code before interacting with it. 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 code owners need to publish the source and metadata files, thus enabling other developers to verify that the deployed bytecode is an exact match to the published files. By doing so, it can be verfied that the contract code is exactly the same as when it was deployed on blockchain and has not been adjusted or tampered with before deploying it.

### Why is source verification important?

Without open source contracts it's hard to tell what the (decentralized) application you are using will actually be doing. One of the decentralized web's biggest aspriations 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 shall, in the best case, always be possible to verify it for yourself, or if you're not tech savy enough, leverage the power of the crowd of other developers which can always look at and call out malicious code when it's open source.

### Why should I publish my source code / open-source it?

Closed source contract code cannot easily be verified since there is no way to design a trustless setup 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 in.

## Metadata

### What is bytecode metadata?

Metadata is data that describes and gives information about other data. [Bytecode (contract) metadata](https://solidity.readthedocs.io/en/latest/metadata.html) in Solidity is supported since version 0.4.7 and is automatically generated by the Solidity compiler in 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 metadatafile 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 acutal code of the contract is present in the metadata file in the sources section. Literal sources will be covered for verification [in future](https://github.com/ethereum/sourcify/issues/187), too.

### What is NatSpec?

[NatSpec](https://solidity.readthedocs.io/en/latest/natspec-format.html) 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 by developer-focused and end-user-focused messages. The end-user-focused messages can be useful to users since they can describe what the contract interaction will do in easy 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 promted in the wallet interface before signing a transaction.

## 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](https://verification.komputing.org/) that helps developers to verify metadata and contract source code.
- a [contract repository](https://contractrepo.komputing.org/) of all verified contracts.
- a [monitoring & verifier service](https://github.com/ethereum/sourcify) checks for new blocks on the blockchain (mainnet and testnets) and tries to verify them automatically.

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 and other components which all play an important role to demystify interaction with smart contracts for the end user and hence make it safer.

### How does Sourcify verifier and monitoring 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 details: EtherScan is doing invaluable work for the ecosystem with their [contract verficiation](https://etherscan.io/verifyContract) service, which we are very grateful for.

Here are the minor problems with the current setup in EtherScan: EtherScan "flattens" the code which means you can't access the metadata anymore. You have to trust EtherScan with the accuracy of the validation, since you cannot recompile and re-verify it.

Sourcify adds the option to make any contract idenpendently verifyable. It also covers another important aspect: the availability of the code. Should EtherScan 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 verfication more decentralized, independent and hence more resilient.

### How is source verification & commeting your code with NatSpec connected and why is it more powerful if you do both?

If you verfied 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 gets published and verified.

**Source Verification & NatSpec go-hand-in hand for greater transparency in contract interactions!**

* 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)
* Source verification and NatSpec: 📝🔍 + 🤓💡 = ✅ (code is transparent, end users can understand it = great!)

### How decentralized is Sourcify?

- Contract repo: The Sourcify contract repository is published both on [https](https://contractrepo.komputing.org/) as well as on [IPFS](https://gateway.ipfs.io/ipns/QmNmBr4tiXtwTrHKjyppUyAhW1FQZMJTdnUrksA9hapS4u).
- [Interfaces](https://verification.komputing.org/) to help verify source code: If you are using the Sourcify UI then you are verifying via our verification service backend. However, you can also run it yourself if you want. Additionally, the Sourcify CLI will soon be [published](https://github.com/ethereum/sourcify/pull/184).

## The User Side: Improving 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 make this better?

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 (see **link to** --> How is source verification & commeting your code with NatSpec connected and why is it more powerful if you do both?).

It's important that interface tools like wallets display the NatSpec comments to make them visible to the user during 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!

For now, you can use the Sourcify contract repository. It can be accessed via [https](https://contractrepo.komputing.org/) or [IPFS](https://gateway.ipfs.io/ipns/QmNmBr4tiXtwTrHKjyppUyAhW1FQZMJTdnUrksA9hapS4u).

Use the contract's address and search for it in the repository. If is is there, it is a match (aka verified). 🎉

### What are full matches?

Full matches mean that both the source files as well as the meta data 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 easier and more convenient.

- 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](https://github.com/ethereum/solidity/releases/tag/v0.6.8))
- Create libraries that wallets can use to easily recompile bytecode (libs in different languages)

### What is needed on the wallet / UI side to make users aware of verified contracts?

Walltes and user interfaces are a crucial puzzle piece to bring awareness and broader adoption to source verification & NatSpec comments. To make users aware of verified contracts, wallets / user interfaces could:

- Show which contracts are verified and which 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 people to only sign an interaction which is not NatSpec commented if they know what they are doing.

# For Later / Next Round of FAQ

## Dev focused FAQ & Tutorials

### How can you retrieve the metadata?

Which projects we want to cover here?
* plain solidity
* remix
* truffle
* ...(add to list)

@chriseth could point us to the projects that he tested so I can reproduce it and create a mini tutorial for it.

plain solidity:
solc --metadata
standard-io:

> Help needed. :)
[name=franzi] [color=red]