DevTools Summit | Human-friendly Contract Interactions with Sourcify Verification - Kaan Uzdogan

[Applause] [Music] this is a very timely question and a talk i want to bring on khan who's going to be talking about sourcify simplifying a lot of your needs on making sure your contracts are safe and easy to read and verified so without further ado please welcome yeah thank you kartik hello everyone um as kartik mentioned um i will be talking about sourcify and source by verification we at sourcify uh also are doing uh source code verification but more in an open and decentralized way but we are actually more than that we are also actually an initiative for more human friendly contract interactions and that's now i'll talk about how you can do this so i'll start with just a normal day in webtree just an example uh that you have probably already seen if you have been in web3 space for a while and it's this so it's a daily thing now um although this has improved slightly that we every day we encounter interactions with contracts that we have no idea so when you see this this is like what is happening what am i doing am i talking to the right contract am i doing the right thing and at the end of the day this basically is the same thing as telling the contract just shut up and take my money i have no idea what i'm doing and the good thing is we can change this so it is a difficult task it's a difficult thing but that's what we are striving for but as i said a typical web pre-interaction nowadays is still a yolo signing nightmare what we like to call this interaction signing on the wallet and just hoping we're the best and at the end of the day what we want to achieve is something on the right instead of something on the left i know these have changed recently in most of the wallets but still we don't have really comprehensive messages that regular users or even the developers can understand easily so let's dive into what you can do to achieve this there are two sides of the equation there are things that you can do as a smart contract developer and as a wallet developer so let's dive into what you can do as a smart contract developer first thing you can do is to use the nat spec documentation so the nat spec documentation is um part of the solidity uh specification is part of a solidity documentation and it is a rich documentation for functions between variables and it's a special special form called ethereum natural language specification so it looks like this it is similar to jstoc if you are familiar with the jstoc and you can find the that spec on in your contract it's uh mostly in the on top of the functions uh it has it has a dev field which is for the developer documentation which then we have notice fields for the user documentation then we have the documentation for the parameters and the nice thing about nat spec is that it supports dynamic expressions what does it mean it means that the fields you can see here for instance the old owner and new owner of this user documentation can become this so when you are showing the users the user documentation you can fill these arrivals dynamically and instead show the values to the user and even better you can show something more human readable to the users if you have for example a reverse ens name okay so we know what's user doc and dev dock is but where can we find it where can we leverage find and leverage these fields um these fields are in the solidity contract metadata and i'm not sure i probably probably most of you are not familiar with the contract metadata it is actually introduced in 2016 with the earlier versions of the solidity but it was actually not picked up by the community so it is a json file generated by the solidity compiler which contains metadata as the name suggests but it consists of four main fields firstly api then userdoc devdock as we have seen in the previous slides then we also have the compilation information and the information about source files so the first two fields are concerned with how to interact with this contract the metadata contract of the metadata and the second two field the next two fields are concerned with how to reproduce a contract compilation and the file looks like this it is a json file as i told you and it is let me show it [Music] i'm sorry i can just write this yeah oh there we go so um it is a file like this and in the output fields you have the api dev dock and user dock and you can see the not spec fields are embedded here for example the one we talked about the nut spec comment we talked about is here replaces the owner all done with the safe in safe with the new owner and the other information here are as usual the compiler settings the evm version the optimizer settings source information and the source information also contains the content of the source file although not always and the hash of the source okay now we know where to find the dev dock and user dock but where is the metadata where can we find the metadata we can find this file um if you use the solidity compiler it's uh obtainable with the metadata flag so if you pass the metadata flag to the compiler on a terminal and the contract you will get the metadata file it is also available on frameworks um if you're using truffle uh after you compile the files you can access the metadata so you can access the compiler artifacts actually and in the artifacts you can find the metadata in the json fields if you are using hardhat it is also in the artifacts and since hardhat version028 you can find the metadata of each contract in the large build file and is also embedded somewhere and within the contract bytecode but not the metadata itself but the ipfs hash of the metadata file is appended to the bytecode of the contract when compiled so the solidity compiler by default actually embeds this information along several inform several other information at the end of your bytecode and this is also deployed to the blockchain um you can turn this off but by default actually this additional field is appended at the end of the bytecode alongside the functional part of the code that corresponds to the contract we have written and this ipfs hash of the metadata file acts as a somehow as a compilation print or a digest of the whole compilation that you have done and if you publish this metadata files that means you can access it through its bytecode so as we said this is an ipfs hash of the metadata file so if you get the contract bytecode and decode this ipfs hash then it's available on ipfs if it's published or pinned by the author of the contract um there's actually a nice tool to see this in action that we call playgrounds in here we can you can go to you can fetch your contracts and i'll we also have some example contracts here let's have a look at this for instance if if we want to see the code byte code and the metadata of the ethereum deposit contract it will fetch the bytecode of the contract then we'll decode these parts the highlighted parts which corresponds to the fields that we talked about and then we if we decode this we see there is ipfs hash and solidity version of the contract and here using this this hash the metadata files actually fetch from the ipfs and we can see the metadata file here okay um so we use the nut spec documentation and the second thing we can do is the source code verification on source file so before diving into more maybe uh let's let's have a look at what source code verification is i'm pretty sure everyone has seen this green check mark if you are interacting with a contract or looking at the source code of a contract and you see this and you're happy because then you know everything's verified everything is checked marked and this is what you see in the easter scan when you are looking for the source code of a contract um but how do we know that actually a random code on github is not is is this actually correspond how does it correspond to the uh code of this contract on blockchain so if i give you this code for example how do you make sure if this is actually the code corresponding to the contract on blockchain and not just a random contract so this is how is how it works so we have the solidity files which are our source code then we also have the compilation settings this is when you are compiling your contracts this is just a default thing and what we do is we take the source code files then we take the compilation settings and we feed these into the compiler and we recompile everything this is actually when the second part of the metadata file comes in handy because this part gives us the information about how to reproduce a contract compilation and if we have this in hand then now we can make use of this and see if we can reproduce the whole contract compilation so we get the source code files if you are verifying a contract you you give us source code files you give us the settings you have then we recompile everything then the compiler outputs the byte code of the contract the the code that the machines understand not not the human readable source code but the bytecode that is deployed on blockchain and then we also have the contract that we want to verify for instance if we have this contract at this address then we get the code of this contract from the blockchain then we see if these codes match so if these match then it means the source code you provided in these in these slides and these settings are actually matching the contract on the blockchain and in source supply we actually have two types of matches one is the partial match when the byte codes match and the second one is the perfect match as we call this is when the bytecode plus the metadata match and if you recall the highlighted fields at the end of the contract byte code this corresponds to these fields so when the black fields only match that would be a partial match but for a perfect match you need the byte codes to match as well as the metadata match and if you recall the metadata acts as a compilation fingerprint that means if we have the metadata fields matching as well the compilation as whole is exactly the same as the original contract and yes this crystal this will cryptographically guarantee the whole compilation is exactly the same as the original contract so even the solidity files are exactly the same even the comments variable names even the white spaces are the same and how does it work so let's let's see in the case when something matches so we again have the source code files then these files are hashed by the solidity compiler the compiler hashes it actually when you are compiling the contract then the hashes of these files are embedded in your metadata so when we looked at the metadata file we saw that the hash of the source files are also included so the hash is embedded in the fields of this source file and as well as the other files then to hash the ipfs hash of this whole file is taken metadata file and then the ipfs hash is embedded and encoded at the end of the contract bytecode as we have seen before then we see if the one on the left the one we recompiled is actually matching the one from the blockchain and if it's matching it's a full match it's a perfect match as we call now let's see what happens when you make a change when you add a comment change your variable name anything so again we have the source code files but this time a different source code file with a slight difference and that causes these source files hash to change then the hash in the metadata file will change and consequently the hash of the metadata file will change now we have a different hash and this different hash will be embedded at there will be appended at the end of the bytecode so the last field will also change and this time you will be having only a partial match not a perfect match but excluding the last part of the contract bytecode this will give us a partial match okay then now we know how what source code verification is and how can you verify uh contracts uh one way to do this is to use the source file ui we have a ui for you to verify contracts you can here provide us with the metadata file as well as the source code files and give the contracts address and the chain then we can recompile the whole thing and see if it's a match and we have uh several chains i think at the moment close to 30 different evm chains that we support and where a contract verification is possible we also have an api where you can provide the same information through an api programmatically and we also have the documentation where you can see how to make use of the api we also have extra tooling for example with the hardheads we have the hard deploy plugin that you can easily verify your contracts after deploying so if you have deployed a contract on mainnet you can pass artheads network mainnet sourcify and this will verify the deployed contract on source file we also have a remix plugin if you deploy your contracts over remix you can easily pass the contract address and contract chain and the plugin will verify the deployed contracts we recently also have the foundry support so using foundry now you can also verify the contracts by passing the verifier flag and sourcify this will also verify your deployed contracts on foundry we also have a nice feature called automatic verification also as monitoring so this as the name suggests automatically verified the contracts that are deployed on the blockchain so i'll do a short demo about this so here on remix i have a simple contract called storage stall and this contract itself as well as its metadata is already on ipfs so i'm going to deploy this contract on the gurley test network um then we will see how the automatic verification actually works in action so we are waiting for our transaction to be mined right so our contract is deployed so i'm going to specify and i'm going to check the contract if it's verified on source file it is currently not um so this makes use of the ipfs hash that is deployed and it listens to the blockchain for new contracts on the blockchain if it finds a new contract then it will check the metadata at the end of the contract then tries to pull every information all the source files and everything then it will do a recompilation itself so this should actually work in seconds so yeah as we can see the source five monitor has captured this contract creation and automatically verified the contract because the metadata file was already published on ipfs and the source file was already there on iphones uh yeah currently this is only done for the ethereum mainnet and the test nets and yeah this automatically verified verifies the files so that means actually the second step was the source code verification on sourcify then it actually becomes publishing metadata and source files on ipfs so you don't even have to go to sourcify and verify the contracts the only thing you have to do is publish your source file as well as the metadata in a reasonable amount of time so it has to be done when the contracts are deployed we have a buffer i guess around five to ten minutes so you have to publish that uh five or ten minutes after the deployment or even before maybe and this is only done on the ethereum and testnets um so we also have the contract repository uh which is both served over the http and ipfs so every file that we verify we serve also on the ipfs for later for later fetching and it is under an ips name with a dns link under ripple.sourcifieddev and it's updated every six hours currently so you can also see it here right now i'm showing the repo that staging source by dev because the main server has just got an update but it will be also available in a couple of hours so you can also hear download the whole repo or explore the repo how the contracts are structured so we have the contracts we have the full match then uh we also have the contracts sorted by chain id but i guess um this is taking some time to load yeah ipfs is not always the fastest network unfortunately but most of the time if you want to search with an ipfs hash that worked pretty well okay so these were the things that you can do as a smart contract developer now there is the other side of the coin what can you do as a wallet developer for your users um so again remember the first two fields of the metadata file and they were concerning how to interact with the contract so these are api user doc and dev doc and as a wallet developer what you want to do when your users are talking to a contract you want to decode the contract call which is in byte code and show your users meaningful message so what you want to do is get the user doc and decode avi on contract interactions and for that remember what you need is the metadata file because the metadata file contains the api as well as the user documentation so what do you do you fetch the metadata from sourcify's repo right no please don't do that because actually the information you need is already there so you don't even need us need sourcify to do that you already have the ipfs hash of the metadata file on the contract bytecode so what you do what you should do actually is to get the contract byte code fetch the metadata with ipfsh because remember that and in this field you can get the ipfs hash of the metadata file then fetch it over ipfs then you have the api and the user documentation then you can show the users more human-friendly messages so using this information of a verified contract you can actually show something on the right instead of something on the left um so our way of human friendliness so to say is just one way so we make use of human readable descriptions with nut spec comments in the metadata but there are more ways to do that to achieve this for instance there is the eip 4430 and eip 3324 which where the idea is to have a describer function inside the contract which upon when when they are called it returns a human readable description and then runs the function that is called so the advantage is that it can decode things like an ens commit but this also means you have to have extra data in your contract that is deployed there is also a recent eip draft by dan finley there the idea is to give the user the information about the contract on the first point of contact so when you for instance visit uniswap.org then you will receive you will receive the api and the method describers from the website then this will be saved on your wallet and the nice thing about this is it's backwards compatible and it's flexible but it's not bound to the contract itself um yeah but also apart from being a human friendly there are many more ways for a better ux uh so you can do you can decode the contract calls you can warn the user if they never interacted with the address you can say if the contract is verified block if the known scam address if there is a large amount or if there are large fees with the amounts additionally you can show the users how many times this contract was interacted with because a quote-unquote safe contract will have more users and a scammer would maybe have a less use less less interactions and when was this contract deployed an older contract is probably more legit and as well as if this contract is audited uh or and if it's or and by whom it supported it so there are a lot of things actually we can do and we can do better so let's have a recap what is sourcify technically we are an open sourced automatic smart contract verification service we have a user interface an api and tooling to verify contracts we also have a public decentralized content address storage of verified contracts for everyone to access and more generally we are an initiative we act as a base layer and public good for other tools to build on top of an initiative to foster the use of the contract metadata not spec and full verification and we are also an ongoing effort to improve smart contracts ux safety and transparency so thank you very much for listening and i'll be happy to answer questions if you have any thank you so much um i'm looking at the q a i don't think we have any that are specific to this but people want to be able to kind of see the slide decks if we're able to also share that with us uh we'd love to uh make uh i'll just uh there you go um there you go so i'll be able to kind of relay that to to the audience and also we'll be able to put the links up but this was really good source of is getting better and better we've seen uh this happen uh the stock uh talking about every kind of few months to in the past year and uh massive improvements and that's awesome so thank you so much