Skip to content

Commit f9676bd

Browse files
t-proctormarceljay
t-proctor
and
marceljay
authored
Add Grafting Article (#210)
* add grafting * add url fix * article fixes * new title * Update pages/en/cookbook/grafting.mdx Co-authored-by: Marcel Jackisch <[email protected]> * more fixes based on feedback Co-authored-by: Marcel Jackisch <[email protected]>
1 parent b78d5f4 commit f9676bd

File tree

2 files changed

+189
-0
lines changed

2 files changed

+189
-0
lines changed

‎navigation/navigation.ts

+3
Original file line numberDiff line numberDiff line change
@@ -169,6 +169,9 @@ export const navigation = (locale: AppLocale): NavItemDefinition[] => [
169169
{
170170
slug: 'arweave',
171171
},
172+
{
173+
slug: 'grafting',
174+
},
172175
],
173176
},
174177
{

‎pages/en/cookbook/grafting.mdx

+186
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
---
2+
title: Replace a Contract and Keep its History With Grafting
3+
---
4+
5+
In this guide, you will learn how to build and deploy new subgraphs by grafting existing subgraphs.
6+
7+
## What is Grafting?
8+
9+
Grafting reuses the data from an existing subgraph and starts indexing it at a later block. This is useful during development to get past simple errors in the mappings quickly or to temporarily get an existing subgraph working again after it has failed. Also, it can be used when adding a feature to a subgraph that takes long to index from scratch.
10+
11+
The grafted subgraph can use a GraphQL schema that is not identical to the one of the base subgraph, but merely compatible with it. It has to be a valid subgraph schema in its own right, but may deviate from the base subgraph's schema in the following ways:
12+
13+
- It adds or removes entity types
14+
- It removes attributes from entity types
15+
- It adds nullable attributes to entity types
16+
- It turns non-nullable attributes into nullable attributes
17+
- It adds values to enums
18+
- It adds or removes interfaces
19+
- It changes for which entity types an interface is implemented
20+
21+
For more information, you can check:
22+
23+
- [Grafting](https://thegraph.com/docs/en/developing/creating-a-subgraph#grafting-onto-existing-subgraphs)
24+
25+
In this tutorial, we will be covering a basic usecase. We will replace an existing contract with an identical contract (with a new address, but the same code). Then, graft the existing subgraph onto the "base" subgraph that tracks the new contract.
26+
27+
## Building an Existing Subgraph
28+
29+
Building subgraphs is an essential part of The Graph, described more in depth [here](http://localhost:3000/en/cookbook/quick-start/). To be able to build and deploy the existing subgraph used in this tutorial, the following repo is provided:
30+
31+
- [Subgraph example repo](https://github.com/t-proctor/grafting-tutorial)
32+
33+
> Note: The contract used in the subgraph was taken from the following [Hackathon Starterkit](https://github.com/schmidsi/hackathon-starterkit).
34+
35+
## Subgraph Manifest Definition
36+
37+
The subgraph manifest `subgraph.yaml` identifies the data sources for the subgraph, the triggers of interest, and the functions that should be run in response to those triggers. See below for an example subgraph manifest that you will use:
38+
39+
```yaml
40+
specVersion: 0.0.4
41+
schema:
42+
file: ./schema.graphql
43+
dataSources:
44+
- kind: ethereum
45+
name: Lock
46+
network: goerli
47+
source:
48+
address: '0x4Ed995e775D3629b0566D2279f058729Ae6EA493'
49+
abi: Lock
50+
startBlock: 7674603
51+
mapping:
52+
kind: ethereum/events
53+
apiVersion: 0.0.6
54+
language: wasm/assemblyscript
55+
entities:
56+
- Withdrawal
57+
abis:
58+
- name: Lock
59+
file: ./abis/Lock.json
60+
eventHandlers:
61+
- event: Withdrawal(uint256,uint256)
62+
handler: handleWithdrawal
63+
file: ./src/lock.ts
64+
```
65+
66+
- The `Lock` data source is the abi and contract address we will get when we compile and deploy the contract
67+
- The network should correspond to a indexed network being queried. Since we're running on Goerli testnet, the network is `goerli`
68+
- The `mapping` section defines the triggers of interest and the functions that should be run in response to those triggers. In this case, we are listening for the `Withdrawal` event and calling the `handleWithdrawal` function when it is emitted.
69+
70+
## Grafting Manifest Definition
71+
72+
Grafting requires adding two new items to the original subgraph manifest:
73+
74+
```yaml
75+
---
76+
features:
77+
- grafting # feature name
78+
graft:
79+
base: Qm... # subgraph ID of base subgraph
80+
block: 1502122 # block number
81+
```
82+
83+
- `features:` is a list of all used [feature names](developing/creating-a-subgraph/#experimental-features).
84+
- `graft:` is a map of the `base` subgraph and the block to graft on to. The `block` is the block number to start indexing from. The Graph will copy the data of the base subgraph up to and including the given block and then continue indexing the new subgraph from that block on.
85+
86+
The `base` and `block` values can be found by deploying two subgraphs: one for the base indexing and one with grafting
87+
88+
## Deploying the Base Subgraph
89+
90+
1. Go to [The Graph Studio UI](https://thegraph.com/studio/) and create a subgraph on Goerli testnet called `graft-example`
91+
2. Follow the directions in the `AUTH & DEPLOY` section on your subgraph page in the `graft-example` folder from the repo
92+
3. Once finished, verify the subgraph is indexing properly. If you run the following command in The Graph Playground
93+
94+
```graphql
95+
{
96+
withdrawals(first: 5) {
97+
id
98+
amount
99+
when
100+
}
101+
}
102+
```
103+
104+
It returns something like this:
105+
106+
```
107+
{
108+
"data": {
109+
"withdrawals": [
110+
{
111+
"id": "0x13098b538a61837e9f29b32fb40527bbbe63c9120c250242b02b69bb42c287e5-5",
112+
"amount": "0",
113+
"when": "1664367528"
114+
},
115+
{
116+
"id": "0x800c92fcc0edbd26f74e19ad058c62008a47c7789f2064023b987028343dd498-3",
117+
"amount": "0",
118+
"when": "1664367648"
119+
}
120+
]
121+
}
122+
}
123+
```
124+
125+
Once you have verified the subgraph is indexing properly, you can quickly update the subgraph with grafting.
126+
127+
## Deploying the Grafting Subgraph
128+
129+
The graft replacement subgraph.yaml will have a new contract address. This could happen when you update your dapp, redeploy a contract, etc.
130+
131+
1. Go to [The Graph Studio UI](https://thegraph.com/studio/) and create a subgraph on Goerli testnet called `graft-replacement`
132+
2. Create a new manifest. The `subgraph.yaml` for `graph-replacement` contains a different contract address and new information about how it should graft. These are the `block` of the [last event emitted](https://goerli.etherscan.io/tx/0x800c92fcc0edbd26f74e19ad058c62008a47c7789f2064023b987028343dd498) you care about by the old contract and the `base` of the old subgraph. The `base` subgraph ID is the `Deployment ID` of your original `graph-example` subgraph. You can find this in The Graph Studio UI.
133+
3. Follow the directions in the `AUTH & DEPLOY` section on your subgraph page in the `graft-replacement` folder from the repo
134+
4. Once finished, verify the subgraph is indexing properly. If you run the following command in The Graph Playground
135+
136+
```graphql
137+
{
138+
withdrawals(first: 5) {
139+
id
140+
amount
141+
when
142+
}
143+
}
144+
```
145+
146+
It should return the following:
147+
148+
```
149+
{
150+
"data": {
151+
"withdrawals": [
152+
{
153+
"id": "0x13098b538a61837e9f29b32fb40527bbbe63c9120c250242b02b69bb42c287e5-5",
154+
"amount": "0",
155+
"when": "1664367528"
156+
},
157+
{
158+
"id": "0x800c92fcc0edbd26f74e19ad058c62008a47c7789f2064023b987028343dd498-3",
159+
"amount": "0",
160+
"when": "1664367648"
161+
},
162+
{
163+
"id": "0xb4010e4c76f86762beb997a13cf020231778eaf7c64fa3b7794971a5e6b343d3-22",
164+
"amount": "0",
165+
"when": "1664371512"
166+
}
167+
]
168+
}
169+
}
170+
```
171+
172+
You can see that the `graft-replacement` subgraph is indexing from older `graph-example` data and newer data from the new contract address. The original contract emitted two `Withdrawal` events, [Event 1](https://goerli.etherscan.io/tx/0x800c92fcc0edbd26f74e19ad058c62008a47c7789f2064023b987028343dd498) and [Event 2](https://goerli.etherscan.io/address/0x4ed995e775d3629b0566d2279f058729ae6ea493). The new contract emitted one `Withdrawal` after, [Event 3](https://goerli.etherscan.io/tx/0xb4010e4c76f86762beb997a13cf020231778eaf7c64fa3b7794971a5e6b343d3). The two previously indexed transactions (Event 1 and 2) and the new transaction (Event 3) were combined together in the `graft-replacement` subgraph.
173+
174+
Congrats! You have succesfully grafted a subgraph onto another subgraph.
175+
176+
## Additional Resources
177+
178+
If you want more experience with grafting, here's a few examples for popular contracts:
179+
180+
- [Curve](https://github.com/messari/subgraphs/blob/master/subgraphs/curve-finance/protocols/curve-finance/templates/curve.template.yaml)
181+
- [ERC-721](https://github.com/messari/subgraphs/blob/master/subgraphs/erc721-metadata/subgraph.yaml)
182+
- [Uniswap](https://github.com/messari/subgraphs/blob/master/subgraphs/uniswap-v3/protocols/uniswap-v3/config/templates/uniswap.v3.template.yaml),
183+
184+
To become even more of a Graph expert, consider learning about other ways to handle changes in underlying datasources. Alternatives like [Data Source Templates](developing/creating-a-subgraph/#data-source-templates) can achieve similar results
185+
186+
> Note: A lot of material from this article was taken from the previously published [Arweave article](/cookbook/arweave/)

0 commit comments

Comments
 (0)