Human-Friendly Contract Interactions by Kaan | Devcon Bogotá

foreign [Music] foundation on the project sourcify and today I will be talking about how we can enable more human friendly contract interactions using source5 verification I'll start with uh showing you guys something you're all familiar with I would say if you're a web 3 user for a while um just a normal day in webtree and I guess this will this will be like something you see every day and you see every day in webg you see things like this and you basically have no idea you're not a machine you don't understand what's going on you're like trying to make sense of it am I doing the right thing am I talking to the right contract is this doing actually what I want to do and basically what you do is telling them to like shut up and take your money like you have no idea what's going on you're just giving out your money and we say today a typical web pre-interaction is still a yellow signing nightmare what we call Yellow signing it's just they give you things to sign and you just like sign and hope for the best so at the end of the day what we want to have is more to do something on the right hand side from left hand side to right hand side so I know this has changed actually for many wallets so many wallets actually started to decode things like metamask using truffle um and decoding API but still we have a long way to go and we have a lot of things that we can improve the human the the user experience so what can you do to achieve this there are two sides of of this coin so you can there are things you can do as the wallet developer and there are things you can do as the um as the smart contract developer so let's dive in what you can do as a smart contract developer the first thing you can do is using a nutspec documentation and as well as doing the source code verification on sourceify so what is not spec documentation not spec documentation is what is called ethereum natural language specification format it's actually part of the solidity spec and probably you have seen this if you have seen a contract before this is how it looks like you put the comment the documentation above the function and you have the developer documentation you have the user documentation with the at notice field and you have the documentation for the parameters uh so another nice thing about nutspec is it has the specification for dynamic expression so the field you see here the old owner and new owner parameters in back quotes these actually can be filled dynamically with the value they are being called so this replaces the owner the address gets filled can get filled and the new one can also get filled in in the parameters okay so you you did you did your job you made the user documentation developer documentation so where do you find it then why can I can find it it is uh in the solid contract metadata so who actually knows what solidity contract metadata is anyone just a few people cool that's why I'm here um so contract metadata is actually something introduced early on in 2016 in the earlier versions but it was actually not really picked up by the community it is actually a Json file uh generated by the compiler itself and it contains the metadata okay but what is metadata it has the ABI the user talk Dev doc as well as compilation info and source file info so the first two it feels actually is concerned with how to interact with the contract so how to interface with the contract and then the second two is about how to reproduce a contract compilation so it's uh embed the information during the contract compilation so that can be reproduced the file looks like this it's a Json file it has a set it says compiler language settings source file information and here for example in the output you can see the user Doc and Dev Dock and if we open that field those fields again you have the methods and with the methods for each method you have the notice field or the dev doc field if there's a devdoc and you have the for example in this case the replaces the new owner with the old owner with new owner the comment we have seen before uh you can get the con the metadata with the metadata flag on the compiler itself uh on with the Frameworks you can find it inside the build files so travel for example put this inside the build contracts the contract name Json under that you can find the metadata fields and the the metadata is there hard hat also started to Output metadata for inside the build file again you can find the metadata here yeah yeah you can also find the traces of the metadata in inside the bytecode so the bytecode this is an example contract byte code and the bytecode has actually a special field at the end of the bytecode it is appended by the compiler again a question who knows what this is okay again just a few people and again what's that's why I'm here so this field uh the compiler actually takes the ipfs hash of the metadata file the file we saw and it encodes the ipfs hash of that file here alongside some other information maybe I'll pull this as well alongside some other information and yeah you can see how this works in our playground playground Source Phi Dev we basically show how the encoding is done what the encoding contains and we also try to metadata from ipfs it's already there so it's a nice tool there are some example contracts you can click on or you can just provide us with the contract address or just paste the contract bytecode and we will try to visualize how this thing works all right let's let's go down to the second thing source code verification on source5 but before what is source code verification so this is for all of you know this is like you probably have seen this if you have seen a contract before and you see a green check mark you're happy you know the contract right um okay but how does this work um maybe before that like it is uh the reason we need why we need source code verification is that the contracts actually live on blockchain as byte codes like they are we write the humans write code in human language but the machines really didn't bite so the code gets compiled and deployed to the blockchain and this information is lost in the process so we need to somehow make sure uh just a random code you see is actually the same the code behind the contract so that's the process of knowing this course is actually the one that is running the contract is source code verification so how does this work uh you have the contracts solidity files in this case you have a Target contract you also have compilation settings like the version the optimizer settings the other things and we feed those into a compiler and we recompile the contract and remember this is actually when the second part of the Meta Meta data information comes in handy so we use this compilation info to reproduce the compilation of the contract again so we feed this into the compiler and the compiler gives us a byte code and we also have the contract that we want to verify so we get the code of the contract from the blockchain this will give us a bytecode then we'll see if these actually match and in source5 you also have two types of matches we have the partial match when bytecode match and we have the full match when both the byte code and the metadata field field match so in right now today when you are verifying on YouTube scan or any other verifier they actually ignore this field like they don't make use of this field they just trim it out and actually that there have been cases that this was um exploited so it wasn't a serious thing but this could this wasn't really doing was being done properly but yeah with the full match you have a complete match of the bytecode uh and here the metadata actually acts as a compilation fingerprint so if you match the metadata as well the compilation is exactly the same as the original or as when the contract was deployed so and the full matches actually cryptographically guarantee that the whole compilation is exactly the same including the solidity files comments spaces variable names anything like you even if you change a space a variable name it will break the match so how does this work let's see how this actually works again when you are compiling your contract the compiler takes the hash of each file each each solidity file than the hashes of these files are actually embedded inside the metadata file or the the metadata file that we saw as well as the other sources not just one then as said the compiler takes the ipfs hash of this whole file and then this ipfs hash is embedded at the end of the bytecode and then we see if these match if it's say full match it's a match it's a full match if they match and let's see what happens when you change something when you make a slight change change the space change your variable name any comments so we have it my contract diff this time so the hash of the file will change then the hash inside the metadata will change and in in turn the hash of the metadata file itself will change so this field will be different this time and that means this will not be a full match and but this will be a partial match assuming you didn't make a change that will change the functionality of the contract just a comment or variable okay but then how to verify so you can use the source file UI you can give us the source code and the metadata file we need the metadata file to be able to verify either from your computer or etherscan remote GitHub however you like then you give us the contract address contract chain we try to wait file you can use the API we have an endpoint and other several API endpoints as well you can check them out in docs.ify Dev uh we have some detailed talks about this and we also have the tooling so if you are using hard hat there's a hard hat deploy plugin and with the plugin when after you deploy your contract you can just pass the network and then say sourcify and use the verify your contract we have the remix plugin if you are using remix you can provide the contract address the chain when we will verify we recently have a Foundry support so using Foundry you can also easily verify your contracts and we also have some automatic verification so what we call monitor so we have a monitor running that is listening on on several chains we are right now listening to ethereum main net test Nets as well as some Roll-Ups out as far as remember so the monitor what it does it catches contract creations and then when it finds a contract creation it will fetch the metadata as you remember it's like ipfs hash is over there so it will get the ipfs try to fetch it from ipfs and also the metadata file has the source hashes source ipfs hashes it will try to get the source files from ipfs as well if it finds them then it will automatically compile and try to verify the contract so that means actually the Second Step here the source code verification on Source Phi has become publishing your metadata so you don't even have to take the extra step and go to sourcify and verify your contract if you just publish it and pin it on ipfs we'll just do it for you yeah um so we have this contract repo of all verified contracts it is served over HTTP and ipfs under report.sourceify Dev um so we pin the verified Source verified contract source file and the metadata so that they will be accessible by decoding the bytecode so here remember there is the ipfs high here and anyone if it's verified on source5 we will be pinning it and there are other people uh pinning our repo as well so you they will be accessible by their ipfs hash and yeah we also served repo under an ipns name so you can also see the contract repo and see the files access all of them download the whole repo if you want so yeah uh okay so we have seen what you can do as a smart contract Dev let's see what you can do as a wallet developer so maybe a short recap what we are trying to do again so we have a contract call we are talking to a contract and instead of showing instead of this byte string we want to show something more user friendly so one thing to do is obviously to decode this call the despite string call via the API Json you can show the function name the variable names Etc and then you want to show some human readable description of what the user is trying to do if you have documented your code well um so what you what you can do as a vault developer you go to sourcify your report.sourcify Dev you get a chain ID the code track and the metadata no please don't do that you don't come to us because it's already in ipfs and it is the neat thing is it is content content address so you know the file you're getting is actually the right file so you just your wallet just gets the byte code of the contract decodes the ipfs hash here at the end of the bytecode fetched metadata that we pinned it for you and the metadata file has as we have seen the API and the documentation yeah this is where the first two Fields come in handy how to interface with the contract and then decode the API and populate the not spec comments of the track so hopefully at the end of today we will have something more on the right rather than something on the left but source file is actually not the only way for human friendliness the idea behind sourceify is to have human readable descriptions via nut spec comments found in the metadata there are other ways to achieve this as well so one is for example these two eips by Richard Moore and Nick Johnson so the idea there is to have an extra function name an extra function a described function so to say that will return the user something unreadable so it can be anything any custom any custom string and uh the contract will return the string to the user and continue executing the executing the actual function and here the nice thing is it can decode things like ens commit that is normally uh like it's it's a hash commit and it doesn't have a meaning to the user but you can add actually some more custom strings custom messages to the user that they can make sense of it but hopefully this discuss extra gas uh the other one is the other MP proposal by Dan Finley the there the idea is uh to give the user this information at the first point of contact so say you want to do an exchange for the first time in at uniswap uniswap app.uniswap will give you the contract metadata your Vault will store it and then you your wallet will have the API and the describers so that it can show you some something more human readable uh the advantage here is it's backwards compatible so we don't need to change change the contracts right now most of the contracts don't have any documentation or anything and or they are not actually documented with the human friendliness in mind so this will be backwards compatible but at the same time this means it's mutable so it's like it can be changed so it's a trade-off but yeah and also there are many ways to better ux so we can actually show the users many things so is it you can decode the contract call you can warn if the user has never been talked to this contract uh show the user if the contract is verified uh block if it's a scam address many things as well as other types of things such as how many times this contract was interacted with when was it deployed because a scam the contract would be like likely more recent and less interacted with um is this contract audited and is it by audit by whom so there are actually many ways we can do better so as I recap what is sourceify technically it is an open source automatic smart contract verification service our monitor it's a user interface server API and tooling to verify contracts manually it's a public decentralized content address storage of verified contracts our repo and more generally we are a base layer and a public good for other tools to build on top of us and we are an initiative to Foster the use of solidity metadata nut spec and full verification and as well as we are an ongoing effort to improve smart contracts UI safety and transparency so thank you for listening uh if you have if you're interested you can find us in Twitter join our Matrix chats our code is also at here it's your terms sourcify visit our website and yeah I'll be happy to take any other questions if you have thank you I'm wondering how well these Solutions can handle translation and internationalizations to provide descriptions in multiple languages yeah uh that's also one consideration there uh we have the idea of maybe having a custom not spec field for translations and in that field you can actually link to another translations file so that would be inside the metadata for example the translations file and that will be another ipfs hash so that you can fetch it and you can have other languages and translations are you thinking about ux regression testing automation somehow sorry um are you thinking about end-to-end regression testing automation with sourceify so being able to include um the depths in the whole cycle of testing how things look like like what can dabs do to make things easier for end users to so having I'm sorry is it having the sourceify at the whole development pipeline you mean or I'm not sure if I get customers correct um like currently in order for a developer to somehow test the end-to-end user experience it's nearly impossible to include the web app and the wallet interaction and the onshine interactions I'm not sure if I get the question correctly but we are more like a um well so we're not we just say people here it is here are the tools here are the files just please make use of it so we don't actively get involved in the ux contract interactions or that's not not in your complete pipeline I would say for user protection am I right in thinking that the reputational and statistical characteristics you mentioned are really important um who's talking right here because I'm just thinking and correct me if I'm wrong but I'm malicious deployer could create a malicious contract this uh describe it in a malicious way with Matt Speck and then yeah take advantage of the user yeah um I mean obviously we have the assumption that the contract deployer is uh nine it's not malicious so it's uh we verify the content of the uh the contract but there are as I said there are other ways to do that for example audits scam lists so this is another aspect so we have like this neutral eye to what's inside the contract and it's up to the community and the other types of methods to actually see it's not a malicious contract uh thanks for the talk so question I had was for contract coverage like what is it like is it limited to what's verified on ether scan or um like like yeah in terms of like abis that might not be fully complete like what is sourceify fully covered what what do you mean by cover in terms of like contract coverage like if someone deploys a new contract it's not verified on either scan then do you guys still provide the human readable aspect or yes I mean source5 is a completely different thing than eaterscan if the scan is both a verification service and a block Explorer but source file is not a block Explorer we just we are just a contract verification service and I would say we have different contract sets than it can so you can actually import but it's a different contract set so even for like new contracts you guys instantly get into the pipeline verify and then make it readable yeah exactly gotcha and any contract that is deployed we can just verify okay okay and even also different chains like we don't we have I think like 30 something evm chains right now so you can even verify contracts on other chains but at the end of the day actually we we have support for different chains but we actually want everyone at some point to run their own source file for their own chains cool okay thank you maybe last question um is it in the scope of sortsify to like maintain reputation of the commands or maybe even validate the comments actually reflect the code like sound here is not so good uh is it in the scope of source if I to uh maintain like a reputation scope for the comments or to validate if the comments reflect the code the application commits you say yeah the comments comments um I mean no we just as I said we are a tool to achieve this and at the end of the day the developers have to document and comment their code so they have to keep in mind that this will this might be a user-facing method and properly document it thanks yeah um I think we're out of time uh just find me after the talk or also you can yeah find sourceify and reach us out there thank you