The Graph 🛠 Building Decentralised GraphQL APIs on Ethereum

[Applause] [Music] hey everyone welcome again we have wish we're here from the craft with us and you're going to learn how to build decentralized craft ul apis on ethereum if you have any questions feel free to pop them in the chat and wish well i'll let you take this stage thanks awesome thank you so much i will share my screen all right hope everyone can see this fine cool hey everyone thank you so much for tuning in uh today we're going to be learning how to build decentralized graphql apis on ethereum with the graph and we will be um going over an example of how to use the zora nfd marketplace protocol to build our nft api um but before we get started a little bit about me i am wish and i'm a developer relations engineer at the graph and my passion is building deeply engaged dev communities and i invest a lot of my time helping developers become successful with the frameworks and the tools that they're using um through my content um moving on let's learn oops let's learn about the graph the graph is a web 3 indexing and querying protocol for blockchain networks like ethereum and ipfs and the graph community plays a prominent role in supporting tap developers by making open decentralized data easily accessible with graphql so as an analogy in simpler terms the graph does for open data on the blockchain but basically google does for the web um you can index and query that data in a more efficient way so that you can serve it to your dapps on the front end now using the graph anyone can build and publish open apis known as subgraphs subgraphs is what we call them that make data on the blockchain more accessible so with subgraphs as the main api layer you can see this like nifty diagram on the screen and subgraphs it between the ui layer and the contracts so which is like the data layer basically all your decentralized data from smart contracts so with subgraphs as the main api layer that sits between these two layers the graph is quickly becoming a default part of the web 3 stack and subgraphs are now becoming a web 3 standard for building depths so whenever i talk about this i get this question very often is where does graph come into picture like in in theory it sounds all good but like how does it fit into the web3 stack so this is how it goes um in the data-driven world that we live in our data is stored across huge storage networks and blockchains and um the blockchain of course gets huge huge number of transactions per day um so the applications that we build obviously needs index data for high performance and great ui ux especially if these are decentralized applications so as a solution to this um developers have been for for a long long time developers have been building proprietary indexing servers um to serve it to their adapts and make them more high performance and give it a better ui ux the problem with proprietary indexing servers is that writing this business logic like writing these servers is expensive and the code is also error prone so another problem that you can see here is that it also has a single point of failure so if you're writing your own indexing server code it definitely means that there's like there's a single point of failure so if one thing goes wrong it just crashes and of course it needs engineering and hardware resources as well so it's not very easy to manage there's a lot of infrastructure that you need to manage that comes along with it and of course in the end it disrupts the core idea of decentralization so enter the graph the graph is a global open api that is being used for use cases that include but aren't limited to things like nfd marketplaces galleries and meta versus music video social and community platforms communication platforms um which is why we say that the graph is the easiest way to index and query blockchain data efficiently and serve it to your tabs to make it to give it a better ui and a ui ux um but it is not just that it's not just a global open api it is also a transparent and open network of participants and these participants make up the decentralized network of the graph and they include subgraph developers curators indexers and delegators um on top of that the api that we see is decentralized robust um discoverable it's more performant but not just that it's also built on top of graphql which as a technology comes with its own benefits um for the developer um the graph has also been powering d5 use cases for a long time so default apps that query on chain data like trades and exchange volumes total borrowed supplied staked yield farming total value logged and so much more um some of the complex applications that are running in production that you can see online that are powered by the graph are use cases like um you know websites some of the popular ones like coin gecko coin market cap there are also nft and taos uh nfts and down use cases like the foundation juicebox dao there's also the graph um as i said earlier graph also powers d5 use cases so there's of course also unit swap and synthetics um but these are just to name a few um and last but not the least uh graph the hosted service has been supporting creators across 25 different networks so the graphs hosted service is supporting all of these networks that you may have seen and so many more like ethereum near polygon arbitrary optimism avalanche and so many more so that is basically um some gist of like some brief about what the graph is where it sits in your stack what subgraphs are why they are beneficial for um developers in their web3 stack so now that we've learned a bit about what the graph is and what the benefits of building subgraphs are um i want to take you over build over the process of building your first sub graph which is basically a decentralized graphql api that you can use to index and query data from the blockchain um so if there's networks such as ethereum and there is a smart contract that you want to query data from then you build this decentralized graphql api which is super performance super discoverable um using the graph and then you can query that data from the smart chain uh sorry the blockchain um the smart contract and then serve it on the front end to your um to your dap so we will be going through the process of how to build this now i usually do this um uh you know as a live demo like a full workshop um initializing a subgraph designing it with all of the code like explaining the functions and events and whatnot and then finally deploying it um today i'll be doing something different um just to be very brief very crisp and concise i'll be sharing the code i already have just like five ten minutes ago i've already deployed um a brand new subgraph on the zora uh smart contract um using the zora smart contract and i will be sharing code um so let's see it together i'm actually not sharing my entire screen so let me quickly share my desktop so that we can start seeing the code together yeah uh awesome cool so um some time ago um the team has launched this um when we launched the subgraph studio which is basically um the ide like that that you can use to build sub graphs we also launched this guide that you can use to um learn how to like the entire process from a to c you can learn how to build sub graphs all of the prerequisites that you need all the commands are in there and specifically it uses the example that i have spoken about um which uses the zora nfd marketplace smart contract um and you can find out everything about this here so let me actually just open this link here so anyone who wants to go over it they can just like start going like going through this um in real time so um quickly before starting some of the prerequisites um are node.js you should have node.js installed on your machine um and a metamorph mask wallet just to make sure that you can get the best out of this workshop um when you get back to it and get get into the coding um so make sure that you have those two things set up apart from that i would personally say that some knowledge of typescript and graphql would come in really handy when you're writing the assembly script code and the graphql schema and um when i start sharing the code you'll learn why but if you have some basic like foundation knowledge of those two things it would be really helpful to like grasp some of the concepts of like why we're writing like particular code um and what does it do um so getting started let me show you the subgraph studio the first thing that you should be able to see is when you go to the graph dot com website uh and navigate to product that there are three things the graph explorer the subgraph studio and the hosted service something that's pertaining to us currently for this demo is the subgraph studio where you can create manage and public publish your subgraphs and your api keys so when you click on sub graph studio it's going to oh okay yeah so it is connected with your wallet and i have connected it using my meta mask wallet so make sure that you have a meta mask extension just to make things a bit cleaner and easier while you're using the subgrass studio and if you have a chrome extension you just sign the message it's basically like you logging in to the subgraph studio using your wallet um so if you can see here i'm already logged in using my wallet um and this is my subgraph studio dashboard um and you can tell that i do these workshops a lot from the amount of demos that i have here but um yeah let's go ahead and create our first subgraph and here you might want to name it something like i don't know nifty api it's available thankfully ethereum mainnet click on continue and what this is going to do is it will create your subgraph um on the dashboard and this is yet not on your local in your local machine you're yet to initialize it using a command but this is the first and foremost step so you go into the subgraph studio and you create um like a skeleton of your graphql api i've just named it nfd api you should know this this is going to going to be the name and the slug of your subgraph that you will be using later in commands now another very important thing if this is your first time using the graph and creating a subgraph is that there is some documentation here on the right and the first part of it is going to be um installing the graph cli so if this is the first time you should definitely go in and install the graph cli it comes with a lot of important commands that you can use to then initialize your subgraph deploy it um authenticate it and different things like that so you should be able to do that using both npm and yarn and all of the commands are given here good thing about the subgraph studio and the subgraph dashboard here is that you already have these commands that you can just like copy and paste in ps code so let me shift this yeah so i've already set everything up here so that i can just take you over the code um and i have the graph cli installed i've also initialized my subgraph and to be able to do that you go in and copy this command graph init studio nft api now one thing here is that this is a very short command but there's a longer version to this command here in this guide and it has a few different let me bump up the yeah there there are a few different flags in this command that i want to talk about is that um each flag has some purpose and you pass um some argument for each flag and what that's going to do is the graph init command basically creates a subgraph it initializes a new sub graph for you so basically like boilerplate code that you can instantly get started with get your hands dirty um to try it out and this comes in very handy if this is your first time so you want to make sure that you know what each of these flags do so that when you're scaffolding your subgraph using the graph init command then you're entering the right kind of information that will be feeded into each of the files that you will then further be working with so the first one here is the contract name um but before that let me talk about the from contract flag which is um which is going to make things clearer now the from contract flag is the flag to which you pass the argument um of yours like the address of your smart contract so as the argument here i have passed the smart contract address and now this is basically the the zora nfd smart contract public address that you can get from the zora documentation and that will be passed in the from contract flag similarly there is also a contract name flag which is token so this will then be fed into your subgraph dot yaml file so token there are different types of contracts in your smart contract and the one that we are using here is the token uh the token contract so we'll be passing that here two other flags are the index events and studio we don't need to um pass any arguments in these two flags um just one thing to know is that the index events flag basically um gives you all of the code that you need to um start to like handle all of the events um it just makes sure that the subgraph is you can you're able to define um your mappings file in a way that maps your um your smart contract events to your entities that you will be defining in graphql and this might be a little bit confusing right now but once we see the code in the subgraph uh folder then it will be clearer and the and finally the studio flag is the flag that we will be passing um just to make sure that um our local code knows that we will be using the subgraph studio for building our subgraph and done once you have entered this command um it should show you some kind of like feedback here that shows you that the subgraph is being scaffolded it might take a few seconds and then once your subgraph has been scaffolded it will give you some bare bones boilerplate code which which is pretty um important to know and learn what it gives you right out of the box just so that you can start editing those kind of um um you know functions and those uh those those parameters later on so three main things that we will be working with three main files that we will be editing whenever you want to define your subgraph uh and design it um to then able to be to deploy it later on is um the first one is subgraph.yaml subgraph.graphql and the source the mappings.

ts file in the source folder now what subgraph.yaml does is it's your generic yaml file it's a configuration file that helps you define your subgraph um tells you what kind of data what kind of smart contract it is dealing with what the start block of the smart contract is going to be what kind of events your smart contract is going to be emitting and where does it have the code to handle it stuff like that um and then the second one again a pretty important file that we are supposed to be dealing with while building a sub graph is the schema.graphql file so if you know graphql already um as the name suggests this is your graphql schema file and what this does is it defines your data basically so from the smart contract on the blockchain any data that you want to query using your subgraph should be described in this file you describe that data along with how to query it um to your front end so these are the two entities that we will be defining i've already defined them here and i will explain later what each of these things does but finally there is a mappings file that we deal with um and this mappings file as i briefly mentioned earlier it has all of the code the business logic that we need to map the events being emitted from the smart contract on the blockchain um and map it to the local code to the functions that we are writing here as part of our subgraph design which is that is the mappings file and i will go deeper into it um just in a in a bit yeah so that is basically the folder structure and we can i think we're good to start getting into each of these files so i've made a few quick changes in um the subgraph.yaml file specific to our subgraph uh since we're using the zora smart contract in the address field i have passed the smart contract address this was passed earlier as part of the graph init command so if you use the shorter version the only difference is that this field you will have to later on come into it after scaffolding the sub graph you will have to come into this file and then add the sub the smart contract address but if you've already passed it as part of the from contract flag as an argument to it then it will be passed in already and this will be what you see when you come into this file um and the abi that you see you if you remember you pass the contract name flag and you pass the argument as token to that flag so this is that another important thing here is the start block and you can go on ether scan search for the last transaction on the zora nft smart contract and um that should give you the start block of that smart contract what this basically means is that the um instead of starting from the genesis of that smart contract you want a particular start block from which it should start indexing um so that it doesn't take like long long amount of time to sync when you've deployed the subgraph so that's basically the start block that i've passed in another quick thing that uh edit that i've made here is the entities now this is super important entities pertain to the graphql schema so anything that you pass at as part of the entities um it is basically the kind of data that you want to deal with that you want your subgraph or your graph your api to query from the smart contract and it will then later on be defined in the graphql schema so in this example i want to deal with token data which is basically all of the nfts that every user um mints and holds and then finally the user metadata so these are the two entities that we'll be working with and we want our subgraph to be able to then query from the smart contract and provide to our um front end and then finally the last change that i made in the subraft on yaml file is the event handlers so every smart contract um just to keep this very simple every smart contract emits a few events now when you start indexing that smart contract it will uh there will be an event that will happen for example a transfer event so if you transfer the ownership if the ownership of an nft has been transferred from one user to another um then this is the kind of event that will be emitted so there can be two cases in this one um whether the ownership of the nft has been transferred from one user to another or a new nft has been minted so in that kind of an event being emitted on our subgraph side we want some kind of code some kind of business logic that we want to be executed to handle this event which is why we have defined the handle transfer function as the event handler here so in the event handlers we want to define a handler for each event that will then be emitted from the smart contract now you don't necessarily have to handle each event from the smart contract the sub graph should only have um the business logic for the events that you want to be interacting with with so um basically in our example i have taken the example of two events which is the token uri updated event so in case of the uri of an nfd being updated or changed this is the event that will happen and we will be writing a function some business logic to handle this event and similarly for the transfer event that i already explained a bit so that is about the subgraph dot yaml file now moving on next um there is the schema.graphql file now this schema.

graphql file as i mentioned earlier is your graphql schema where you will be describing the data that your subgraph will be querying and for any entity entity is basically like a collection of data fields data entries or data points um in your api that you want to be querying right um so these are all of the top level fields that we can see under each entity this is entity token there's another entity user if you remember from our entities section in our yaml file and so here in this schema file we are defining these two entities using the at entity directive which is a graphql directive so if you've used graphql before you should know that this is um the directive that we use to define uh each entity declare something as an entity this type uh token as an entity and these are the fields that we want to be uh want our graphql api to be querying um which is the id the token id which is the nft id uh content uri which is basically the link to the nfd metadata uri some metadata for the nft created at time stamp so if there's a particular time at which the nfd is being created then this timestamp will give you that creator and owner so creator will be the user as you can see we pass the object user here um so this uh every nft will have a creator and an owner and both those types will be users and in the user entity we are basically defining it as a relationship here and you can use the at derived from directive which is again just like entity it is a graphql directive that you can use to define um a one-to-many relationship um between two different fields so there's a tokens field and there's a created field and what we want to do is that in the user entity which is basically our user metadata we want to define two things which is tokens so tokens that are being owned by owners and tokens that are being created by creators so we're defining that kind of a one-to-many relationship um using the at derived from directive and i won't be going deeper into this this because uh it's very graphql specific but the reason why instead of an array you can also use an array for defining this kind of a relationship for saving this kind of data but instead of defining an array we are using this directive for performance benefits and all of that has been explained briefly here in this guide as well so make sure if you want to understand it deeper as to why we're using this derived from directive make sure you come back to it later so basically this is our graphql schema and we're done defining all of our data and the last step that we want to do is define our mappings.ts file now before we go into what is being described in the mappings.ts file i want to make sure that you know about the graph code gen command um again this is a command that has been um given by the graph cli so when you um once you're done defining your schema or graphql file um you then run your graphql code and sorry your graph coding command that i've already run here um earlier when i was defining as you can see here i was working on my subgraph what this does is basically um the graph cli gives a typescript library to be able to interact with the smart contract and the graph node and it also gives some assembly script code and helper functions that can be used to be to make sure that you can map the events happening on the smart contract to the event logic that you're writing in assembly script um as part of your subgraph development process so once you run the graph code gen command there are some files and some code that is being generated which is why it's called the graph code gen there's some code being generated and this is specifically typescript and assembly script code and helper functions and we are then um importing importing that code those functions um here um as you can see importing from generated token token which is this file here and then importing from generated schema which is this file so what this code does is it lets you interact with the graph node which basically saves data or reads data um reads data or writes data um on the graph node and it also lets you interact with the smart contract itself so you cannot write data on it but you can definitely read data from the smart contract which is why we um use the graph quotient command to help us with the spoiler plate code now if you remember from our subgraph.yaml file we already have defined our events that we want to deal with and so what we want to do is we want to write two handler functions so whenever this event this particular event for example the token uri updated event whenever it is being emitted we want to handle that so we want some business logic or some function to be executed and we are basically writing that function here so this function handle transfer handles the transfer event so in case of the ownership of an of an nft being transferred from one user to another or a new nfd being minted this function will be executed and similarly in case of the uri of a particular nfd being updated um we want this function to be executed and since we're running out of time super fast i won't be going deeper into this function into each of this but if you have uh if you once you go through it if you have any questions uh feel free to ping me on discord and i would love to take you over it um and then the specifics of how we're writing each of these functions and what it does um basically we're retrieving information from the smart contract and then saving it saving the new information to the graph node uh for example in this one we're retrieving the information from the smart contract um since the uri has been updated and then we're saving it on the graph node to be able to then retrieve it later on um query it through our subgraph to our front end sorry um and finally the last part of once we're done doing all of this editing and code changes writing all of this code here in our subgraph folder we want to be um authenticating our subgraph and then deploying it and that is the final part of um of um building your subgraph and it is here so it's you can also see it here just to make it a little bit clearer the last part is authenticating and deploying so to be able to authenticate your sub graph what this does is like it connects this local code here to your dashboard here your subgraph dashboard um and there's a deploy key that you can use as an auth key um when you're authenticating your sub graph so you just copy this command and run it and it should be able to authenticate your graph in the c using the cli and then finally um deploy the sub graph using this command graph deploy studio along with your sub graph slug which is basically nft api in this case and once that is done i've already deployed it once that is done um the deployed subgraph is here so ran ft as you can see the undeployed subgraphs will be written as undeployed and the deployed ones will have the flag deployed and in when it's synced it will say progress 100 synced the nifty thing that i love about the subgraph studio the dashboard here is that it also has a graphql playground integrated um so it has like various example queries the first one is here um what this does is it retrieves the first five tokens and the first five users the token data basically five nfds on the smart contract the first five and the user metadata for each of those nfts and this is a typical graphql query so if you've worked with graphql before you know how this works and what um this query does and so if you click on run this should be able to test your sub graph and this is the response that you see as opposed to your query in your playground and on the right you can see the entire schema so you already know that we defined these two entities token and user as part of our graphql schema and so which is why we have that here and you can go in and see the different top-level fields that we've defined in each entity and um as you can see this is the data that we retrieved id token id content uri so this is just the testing part um you can then go ahead and integrate this in your front end using different front-end clients for graphql such as apollo apollo client um and then you can make sure that you get you're able to retrieve all of this data in your dap so yeah this is it for the subgraph building um part like this is how you build your first sub graph first decentralized graphql api um if you want to be involved more into the web3 movement and whatever the craft is working on make sure that you check out our website this is the official website which also has the docs the graph.com docs follow us on graph protocol ad graph protocol on twitter and we also have our own official discord which is the graph.

com discord this is the invite public invite that you should be able to use to join it um so if you have any questions if you want to meet the team behind all of these features and the things that we're working on make sure that you connect with us um and of course we are offering 5k in bounty at about these at hack fs this year um 2.5 k usd for usdc for um best new subgraphs so if you build a new subgraph then you get um a price from that first price and second price and then there are two prices grand prize and runner-up for existing use of existing subgraphs so you can also query on existing sub graphs um and those are the two categories of the bounties so i'd love to see how you folks use the graph and the subgraph studio to start building with the graph and start using it in your projects so thank you so much for tuning in