The Graph is a protocol for indexing and querying Blockchain data. Currently, The Graph has the legacy version and the decentralized version. The legacy version is a centralized and managed service hosted by The Graph, and it will eventually be shut down in the future. The decentralized version (aka The Graph Network) consists of 4 major roles: Developers, Indexers, Curators, and Delegators.<\/p>\n
ref: Video from Finematics A subgraph defines one or more entities of indexed data: what kind of data on the blockchain you want to index for faster querying. Once deployed, subgraphs could be queried by dApps to fetch blockchain data to power their frontend interfaces. Basically, a subgraph is like a database, and an entity (a GraphQL type) is like a table in RDBMS.<\/p>\n A subgraph definition consists of 3 files:<\/p>\n First, we need to design our GraphQL entity schemas (the data model) which mainly depends on how you want to query the data instead of how the data are emitted from the blockchain. GraphQL schemas are defined using the GraphQL schema language.<\/p>\n Here're some notes about subgraph's GraphQL schema:<\/p>\n An example of ref: It's also worth noting that The Graph supports Time-travel queries. We can query the state of your entities for an arbitrary block in the past:<\/p>\n ref: Second, we must provide a manifest to tell The Graph which contracts we would like to listen to, which contract events we want to index. Also a mapping file that instructs The Graph on how to transform blockchain data into GraphQL entities.<\/p>\n A template file of Since we would usually deploy our contracts to multiple chains (at least one for mainnet and one for testnet), so we could use a template engine (like It's worth noting that The Graph Legacy (the Hosted Service) supports most of common networks, for instance, You could find the full list of supported networks on the document: Mappings are written in AssemblyScript and will be compiled to WebAssembly (WASM) when deploying. AssemblyScript's syntax is similar to TypeScript, but it's actually a completely different language. <\/p>\n For each event handler defined in We can also access contract states and call contract functions at the current block. Though the functionality of calling contract functions is limited by ref: In addition to event handlers, we're also able to define call handlers and block handlers. A call handler listens to a specific contract function call, and receives input and output of the call as the handler argument. On the contrary, a block handler will be called after every block or after blocks that match a predefined filter - for every block which contains a call to the contract listed in ref: Here're references to how other projects organize their subgraphs: Before deploying your subgraph to the Legacy Explorer (the centralized and hosted version of The Graph), we need to create it on the Legacy Explorer dashboard.<\/p>\n Then run the following commands to deploy:<\/p>\n ref: When we deploy a subgraph to Subgraph Studio (the decentralized version of The Graph), we just push it to the Studio where we're able to test it. In contrast, when we "publish" a subgraph in Subgraph Studio, we are publishing it on-chain. Unfortunately, Subgraph Studio only supports Ethereum Mainnet and Rinkeby testnet currently.<\/p>\n ref: Before we talk about the token economics of GRT token, it's important to know that the following description only applies to The Graph Network, the decentralized version of The Graph. Also, the name of The Graph Network is a bit ambiguous, it is not a new network or a new blockchain, instead, it is a web service that charges HTTP\/WebSocket API calls in GRT token.<\/p>\n To make GRT token somehow valuable, when you query data (through GraphQL APIs) from The Graph Network, you need to pay for each query in GRT. First, you have to connect your wallet and create an account on Subgraph Studio to obtain an API key, then you deposit some GRT tokens into the account's billing balance on Polygon since their billing contract is built on Polygon. At the end of each week, if you used your API keys to query data, you will receive an invoice based on the query fees you have generated during this period. This invoice will be paid using GRT available in your balance.<\/p>\n ref: When it comes to token economics:<\/p>\n ref: The price of queries will be set by indexers and vary based on cost to index the subgraph, the demand for queries, the amount of curation signal and the market rate for blockchain queries. Though querying data from the hosted version of The Graph is free now.<\/p>\n The Graph has developed a Cost Model (Agora) for pricing queries, and there is also a microtransaction system (Scalar) that uses state channels to aggregate and compress transactions before being finalized on-chain.<\/p>\n ref: The Graph is a protocol for indexing and querying Blockchain data.<\/p>\n","protected":false},"author":1,"featured_media":836,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[137],"tags":[138,139,141,140],"class_list":["post-835","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-blockchain","tag-ethereum","tag-graphql","tag-subgraph","tag-typescript"],"_links":{"self":[{"href":"https:\/\/vinta.ws\/code\/wp-json\/wp\/v2\/posts\/835","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/vinta.ws\/code\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/vinta.ws\/code\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/vinta.ws\/code\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/vinta.ws\/code\/wp-json\/wp\/v2\/comments?post=835"}],"version-history":[{"count":0,"href":"https:\/\/vinta.ws\/code\/wp-json\/wp\/v2\/posts\/835\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/vinta.ws\/code\/wp-json\/wp\/v2\/media\/836"}],"wp:attachment":[{"href":"https:\/\/vinta.ws\/code\/wp-json\/wp\/v2\/media?parent=835"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/vinta.ws\/code\/wp-json\/wp\/v2\/categories?post=835"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/vinta.ws\/code\/wp-json\/wp\/v2\/tags?post=835"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}
\nhttps:\/\/thegraph.com\/<\/a><\/p>\n
\nhttps:\/\/finematics.com\/the-graph-explained\/<\/a><\/p>\nTerminologies<\/h2>\n
\n
\n
\n
\n
Define a Subgraph<\/h2>\n
\n
subgraph.yaml<\/code>: a YAML file that defines the subgraph manifest and metadata.<\/li>\nschema.graphql<\/code>: a GraphQL schema that defines what data (entities) are stored, and how to query it via GraphQL.<\/li>\nmappings.ts<\/code>: AssemblyScript code that translates blockchain data (events, blocks, or contract calls) to GraphQL entities.<\/li>\n<\/ul>\nGraphQL Schema<\/h3>\n
\n
id<\/code> field is required and it must be a string.<\/li>\n!<\/code> suffix means it's required, otherwise it's optional.\n\n
Bytes<\/code> for storing Ethereum hashes and addresses.\n\n
\n
\n
schema.graphql<\/code>:<\/p>\ntype Market @entity {\n id: ID!\n baseToken: Bytes!\n pool: Bytes!\n feeRatio: BigInt!\n tradingFee: BigDecimal!\n tradingVolume: BigDecimal!\n blockNumberAdded: BigInt!\n timestampAdded: BigInt!\n}\n\ntype Trader @entity {\n id: ID!\n realizedPnl: BigDecimal!\n fundingPayment: BigDecimal!\n tradingFee: BigDecimal!\n badDebt: BigDecimal!\n totalPnl: BigDecimal!\n positions: [Position!]! @derivedFrom(field: \"traderRef\")\n}\n\ntype Position @entity {\n id: ID!\n trader: Bytes!\n baseToken: Bytes!\n positionSize: BigDecimal!\n openNotional: BigDecimal!\n openPrice: BigDecimal!\n realizedPnl: BigDecimal!\n tradingFee: BigDecimal!\n badDebt: BigDecimal!\n totalPnl: BigDecimal!\n traderRef: Trader!\n}<\/code><\/pre>\n
\nhttps:\/\/thegraph.com\/docs\/developer\/create-subgraph-hosted#the-graphql-schema<\/a>
\nhttps:\/\/thegraph.com\/docs\/developer\/graphql-api<\/a>
\nhttps:\/\/graphql.org\/learn\/schema\/<\/a><\/p>\n{\n positions(\n block: {\n number: 1234567\n },\n where: {\n trader: \"0x5abfec25f74cd88437631a7731906932776356f9\"\n }\n ) {\n id\n trader\n baseToken\n positionSize\n openNotional\n openPrice\n realizedPnl\n fundingPayment\n tradingFee\n badDebt\n totalPnl\n blockNumber\n timestamp\n }\n}<\/code><\/pre>\n
\nhttps:\/\/thegraph.com\/docs\/developer\/graphql-api#time-travel-queries<\/a><\/p>\nSubgraph Manifest<\/h3>\n
subgraph.yaml<\/code>:<\/p>\nspecVersion: 0.0.2\ndescription: Test Subgraph\nrepository: https:\/\/github.com\/vinta\/my-subgraph\nschema:\n file: .\/schema.graphql\ndataSources:\n - kind: ethereum\/contract\n name: ClearingHouse\n network: {{ network }}\n source:\n abi: ClearingHouse\n address: {{ clearingHouse.address }}\n startBlock: {{ clearingHouse.startBlock }}\n mapping:\n kind: ethereum\/events\n apiVersion: 0.0.4\n language: wasm\/assemblyscript\n file: .\/src\/mappings\/clearingHouse.ts\n entities:\n - Protocol\n - Market\n - Trader\n - Position\n abis:\n - name: ClearingHouse\n file: .\/abis\/ClearingHouse.json\n eventHandlers:\n - event: PoolAdded(indexed address,indexed uint24,indexed address)\n handler: handlePoolAdded\n - event: PositionChanged(indexed address,indexed address,int256,int256,uint256,int256,uint256)\n handler: handlePositionChanged<\/code><\/pre>\nmustache.js<\/code>) to facilitate deployment.<\/p>\n$ cat configs\/arbitrum-rinkeby.json\n{\n \"network\": \"arbitrum-rinkeby\",\n \"clearingHouse\": {\n \"address\": \"0xYourContractAddress\",\n \"startBlock\": 1234567\n }\n}\n\n# generate the subgraph manifest for different networks\n$ mustache configs\/arbitrum-rinkeby.json subgraph.template.yaml > subgraph.yaml\n$ mustache configs\/arbitrum-one.json subgraph.template.yaml > subgraph.yaml<\/code><\/pre>\nmainnet<\/code>, rinkeby<\/code>, bsc<\/code>, matic<\/code>, arbitrum-one<\/code>, and optimism<\/code>. However, The Graph Network (the decentralized version) only supports Ethereum mainnet<\/code> and rinkeby<\/code>.<\/p>\n
\nhttps:\/\/thegraph.com\/docs\/developer\/create-subgraph-hosted#from-an-existing-contract<\/a><\/p>\nMappings<\/h3>\n
subgraph.yaml<\/code> under mapping.eventHandlers<\/code>, we must create an exported function of the same name. What we do in an event handler is basically: <\/p>\n\n
id<\/code>.<\/li>\n\n
export function handlePoolAdded(event: PoolAdded): void {\n \/\/ upsert Protocol\n const protocol = getOrCreateProtocol()\n protocol.publicMarketCount = protocol.publicMarketCount.plus(BI_ONE)\n\n \/\/ upsert Market\n const market = getOrCreateMarket(event.params.baseToken)\n market.baseToken = event.params.baseToken\n market.pool = event.params.pool\n market.feeRatio = BigInt.fromI32(event.params.feeRatio)\n market.blockNumberAdded = event.block.number\n market.timestampAdded = event.block.timestamp\n\n \/\/ commit changes\n protocol.save()\n market.save()\n}\n\nexport function handlePositionChanged(event: Swapped): void {\n \/\/ upsert Market\n const market = getOrCreateMarket(event.params.baseToken)\n market.tradingFee = market.tradingFee.plus(swappedEvent.fee)\n market.tradingVolume = market.tradingVolume.plus(abs(swappedEvent.exchangedPositionNotional))\n ...\n\n \/\/ upsert Trader\n const trader = getOrCreateTrader(event.params.trader)\n trader.tradingFee = trader.tradingFee.plus(swappedEvent.fee)\n trader.realizedPnl = trader.realizedPnl.plus(swappedEvent.realizedPnl)\n ...\n\n \/\/ upsert Position\n const position = getOrCreatePosition(event.params.trader, event.params.baseToken)\n const side = swappedEvent.exchangedPositionSize.ge(BD_ZERO) ? Side.BUY : Side.SELL\n ...\n\n \/\/ commit changes\n market.save()\n trader.save()\n position.save()\n}<\/code><\/pre>\n@graphprotocol\/graph-ts<\/code>, it's not as powerful as libraries like ethers.js<\/code>. And no, we cannot import ethers.js<\/code> in mappings, as mappings are written in AssemblyScript. However, contract calls are quite "expensive" in terms of indexing performance. In extreme cases, some indexers might avoid syncing a very slow subgraph, or charge a premium for serving queries.<\/p>\nexport function handlePoolAdded(event: PoolAdded): void {\n ...\n const pool = UniswapV3Pool.bind(event.params.pool)\n market.poolTickSpacing = pool.tickSpacing()\n ...\n}<\/code><\/pre>\n
\nhttps:\/\/thegraph.com\/docs\/developer\/create-subgraph-hosted#writing-mappings<\/a>
\nhttps:\/\/thegraph.com\/docs\/developer\/assemblyscript-api<\/a><\/p>\ndataSources<\/code>.<\/p>\n
\nhttps:\/\/thegraph.com\/docs\/developer\/create-subgraph-hosted#defining-a-call-handler<\/a>
\nhttps:\/\/thegraph.com\/docs\/developer\/create-subgraph-hosted#block-handlers<\/a><\/p>\n
\nhttps:\/\/github.com\/Uniswap\/uniswap-v3-subgraph<\/a>
\nhttps:\/\/github.com\/Synthetixio\/synthetix-subgraph<\/a>
\nhttps:\/\/github.com\/mcdexio\/mai3-perpetual-graph<\/a><\/p>\nDeploy a Subgraph<\/h2>\n
Deploy to Legacy Explorer<\/h3>\n
$ mustache configs\/arbitrum-rinkeby.json subgraph.template.yaml > subgraph.yaml\n\n$ graph auth --product hosted-service <YOUR_THE_GRAPH_ACCESS_TOKEN>\n$ graph deploy --product hosted-service <YOUR_GITHUB_USERNAME>\/<YOUR_SUBGRAPH_REPO><\/code><\/pre>\n
\nhttps:\/\/thegraph.com\/docs\/developer\/deploy-subgraph-hosted<\/a><\/p>\nDeploy to Subgraph Studio<\/h3>\n
$ graph auth --studio <YOUR_SUBGRAPH_DEPLOY_KEY>\n$ graph deploy --studio <YOUR_SUBGRAPH_SLUG><\/code><\/pre>\n
\nhttps:\/\/thegraph.com\/docs\/developer\/deploy-subgraph-studio<\/a><\/p>\nToken Economics<\/h2>\n
\nhttps:\/\/thegraph.com\/docs\/studio\/billing<\/a><\/p>\n\n
\nhttps:\/\/thegraph.com\/blog\/the-graph-grt-token-economics<\/a>
\nhttps:\/\/thegraph.com\/blog\/the-graph-network-in-depth-part-1<\/a>
\nhttps:\/\/thegraph.com\/blog\/the-graph-network-in-depth-part-2<\/a><\/p>\nQuery Fee<\/h3>\n
\nhttps:\/\/github.com\/graphprotocol\/agora<\/a>
\nhttps:\/\/thegraph.com\/blog\/scalar<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"