Skip to content

Commit 996eef8

Browse files
MichaelMacaulaybenfaceidalithb
authored
Multiple networks and templates.yaml (#761)
* Initial commit * Moving to deploying section * Adding subgraph health * Update website/pages/en/deploying/multiple-networks.mdx Co-authored-by: Benoît Rouleau <[email protected]> * Update website/pages/en/deploying/multiple-networks.mdx Co-authored-by: Benoît Rouleau <[email protected]> * Update website/pages/en/deploying/multiple-networks.mdx Co-authored-by: Benoît Rouleau <[email protected]> * Update website/pages/en/deploying/multiple-networks.mdx Co-authored-by: Benoît Rouleau <[email protected]> * Update website/pages/en/deploying/multiple-networks.mdx Co-authored-by: Benoît Rouleau <[email protected]> * Update website/pages/en/deploying/multiple-networks.mdx Co-authored-by: Benoît Rouleau <[email protected]> * Update website/pages/en/deploying/multiple-networks.mdx Co-authored-by: Benoît Rouleau <[email protected]> * Update website/pages/en/deploying/multiple-networks.mdx Co-authored-by: Benoît Rouleau <[email protected]> * Final tweaks * Fixing lint errors * adding page to multiple languages * slight correction --------- Co-authored-by: Benoît Rouleau <[email protected]> Co-authored-by: Idalith Bustos <[email protected]>
1 parent b8c1764 commit 996eef8

File tree

25 files changed

+5785
-0
lines changed

25 files changed

+5785
-0
lines changed

‎website/pages/ar/deploying/multiple-networks.mdx

Lines changed: 241 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,241 @@
1+
---
2+
title: Deploying a Subgraph to Multiple Networks
3+
---
4+
5+
This page explains how to deploy a subgraph to multiple networks. To deploy a subgraph you need to first install the [Graph CLI](https://github.com/graphprotocol/graph-tooling/tree/main/packages/cli). If you have not created a subgraph already, see [Creating a subgraph](/developing/creating-a-subgraph).
6+
7+
## Deploying the subgraph to multiple networks
8+
9+
In some cases, you will want to deploy the same subgraph to multiple networks without duplicating all of its code. The main challenge that comes with this is that the contract addresses on these networks are different.
10+
11+
### Using `graph-cli`
12+
13+
Both `graph build` (since `v0.29.0`) and `graph deploy` (since `v0.32.0`) accept two new options:
14+
15+
```sh
16+
Options:
17+
18+
...
19+
--network <name> Network configuration to use from the networks config file
20+
--network-file <path> Networks config file path (default: "./networks.json")
21+
```
22+
23+
You can use the `--network` option to specify a network configuration from a `json` standard file (defaults to `networks.json`) to easily update your subgraph during development.
24+
25+
> Note: The `init` command will now auto-generate a `networks.json` based on the provided information. You will then be able to update existing or add additional networks.
26+
27+
If you don't have a `networks.json` file, you'll need to manually create one with the following structure:
28+
29+
```json
30+
{
31+
"network1": { // the network name
32+
"dataSource1": { // the dataSource name
33+
"address": "0xabc...", // the contract address (optional)
34+
"startBlock": 123456 // the startBlock (optional)
35+
},
36+
"dataSource2": {
37+
"address": "0x123...",
38+
"startBlock": 123444
39+
}
40+
},
41+
"network2": {
42+
"dataSource1": {
43+
"address": "0x987...",
44+
"startBlock": 123
45+
},
46+
"dataSource2": {
47+
"address": "0xxyz..",
48+
"startBlock": 456
49+
}
50+
},
51+
...
52+
}
53+
```
54+
55+
> Note: You don't have to specify any of the `templates` (if you have any) in the config file, only the `dataSources`. If there are any `templates` declared in the `subgraph.yaml` file, their network will be automatically updated to the one specified with the `--network` option.
56+
57+
Now, let's assume you want to be able to deploy your subgraph to the `mainnet` and `sepolia` networks, and this is your `subgraph.yaml`:
58+
59+
```yaml
60+
# ...
61+
dataSources:
62+
- kind: ethereum/contract
63+
name: Gravity
64+
network: mainnet
65+
source:
66+
address: '0x123...'
67+
abi: Gravity
68+
mapping:
69+
kind: ethereum/events
70+
```
71+
72+
This is what your networks config file should look like:
73+
74+
```json
75+
{
76+
"mainnet": {
77+
"Gravity": {
78+
"address": "0x123..."
79+
}
80+
},
81+
"sepolia": {
82+
"Gravity": {
83+
"address": "0xabc..."
84+
}
85+
}
86+
}
87+
```
88+
89+
Now we can run one of the following commands:
90+
91+
```sh
92+
# Using default networks.json file
93+
yarn build --network sepolia
94+
95+
# Using custom named file
96+
yarn build --network sepolia --network-file path/to/config
97+
```
98+
99+
The `build` command will update your `subgraph.yaml` with the `sepolia` configuration and then re-compile the subgraph. Your `subgraph.yaml` file now should look like this:
100+
101+
```yaml
102+
# ...
103+
dataSources:
104+
- kind: ethereum/contract
105+
name: Gravity
106+
network: sepolia
107+
source:
108+
address: '0xabc...'
109+
abi: Gravity
110+
mapping:
111+
kind: ethereum/events
112+
```
113+
114+
Now you are ready to `yarn deploy`.
115+
116+
> Note: As mentioned earlier, since `graph-cli 0.32.0` you can directly run `yarn deploy` with the `--network` option:
117+
118+
```sh
119+
# Using default networks.json file
120+
yarn deploy --network sepolia
121+
122+
# Using custom named file
123+
yarn deploy --network sepolia --network-file path/to/config
124+
```
125+
126+
### Using subgraph.yaml template
127+
128+
One way to parameterize aspects like contract addresses using older `graph-cli` versions is to generate parts of it with a templating system like [Mustache](https://mustache.github.io/) or [Handlebars](https://handlebarsjs.com/).
129+
130+
To illustrate this approach, let's assume a subgraph should be deployed to mainnet and Sepolia using different contract addresses. You could then define two config files providing the addresses for each network:
131+
132+
```json
133+
{
134+
"network": "mainnet",
135+
"address": "0x123..."
136+
}
137+
```
138+
139+
and
140+
141+
```json
142+
{
143+
"network": "sepolia",
144+
"address": "0xabc..."
145+
}
146+
```
147+
148+
Along with that, you would substitute the network name and addresses in the manifest with variable placeholders `{{network}}` and `{{address}}` and rename the manifest to e.g. `subgraph.template.yaml`:
149+
150+
```yaml
151+
# ...
152+
dataSources:
153+
- kind: ethereum/contract
154+
name: Gravity
155+
network: mainnet
156+
network: {{network}}
157+
source:
158+
address: '0x2E645469f354BB4F5c8a05B3b30A929361cf77eC'
159+
address: '{{address}}'
160+
abi: Gravity
161+
mapping:
162+
kind: ethereum/events
163+
```
164+
165+
In order to generate a manifest to either network, you could add two additional commands to `package.json` along with a dependency on `mustache`:
166+
167+
```json
168+
{
169+
...
170+
"scripts": {
171+
...
172+
"prepare:mainnet": "mustache config/mainnet.json subgraph.template.yaml > subgraph.yaml",
173+
"prepare:sepolia": "mustache config/sepolia.json subgraph.template.yaml > subgraph.yaml"
174+
},
175+
"devDependencies": {
176+
...
177+
"mustache": "^3.1.0"
178+
}
179+
}
180+
```
181+
182+
To deploy this subgraph for mainnet or Sepolia you would now simply run one of the two following commands:
183+
184+
```sh
185+
# Mainnet:
186+
yarn prepare:mainnet && yarn deploy
187+
188+
# Sepolia:
189+
yarn prepare:sepolia && yarn deploy
190+
```
191+
192+
A working example of this can be found [here](https://github.com/graphprotocol/example-subgraph/tree/371232cf68e6d814facf5e5413ad0fef65144759).
193+
194+
**Note:** This approach can also be applied to more complex situations, where it is necessary to substitute more than contract addresses and network names or where generating mappings or ABIs from templates as well.
195+
196+
This will give you the `chainHeadBlock` which you can compare with the `latestBlock` on your subgraph to check if it is running behind. `synced` informs if the subgraph has ever caught up to the chain. `health` can currently take the values of `healthy` if no errors occurred, or `failed` if there was an error which halted the progress of the subgraph. In this case, you can check the `fatalError` field for details on this error.
197+
198+
## Subgraph Studio subgraph archive policy
199+
200+
A subgraph version in Studio is archived if and only if it meets the following criteria:
201+
202+
- The version is not published to the network (or pending publish)
203+
- The version was created 45 or more days ago
204+
- The subgraph hasn't been queried in 30 days
205+
206+
In addition, when a new version is deployed, if the subgraph has not been published, then the N-2 version of the subgraph is archived.
207+
208+
Every subgraph affected with this policy has an option to bring the version in question back.
209+
210+
## Checking subgraph health
211+
212+
If a subgraph syncs successfully, that is a good sign that it will continue to run well forever. However, new triggers on the network might cause your subgraph to hit an untested error condition or it may start to fall behind due to performance issues or issues with the node operators.
213+
214+
Graph Node exposes a GraphQL endpoint which you can query to check the status of your subgraph. On the hosted service, it is available at `https://api.thegraph.com/index-node/graphql`. On a local node, it is available on port `8030/graphql` by default. The full schema for this endpoint can be found [here](https://github.com/graphprotocol/graph-node/blob/master/server/index-node/src/schema.graphql). Here is an example query that checks the status of the current version of a subgraph:
215+
216+
```graphql
217+
{
218+
indexingStatusForCurrentVersion(subgraphName: "org/subgraph") {
219+
synced
220+
health
221+
fatalError {
222+
message
223+
block {
224+
number
225+
hash
226+
}
227+
handler
228+
}
229+
chains {
230+
chainHeadBlock {
231+
number
232+
}
233+
latestBlock {
234+
number
235+
}
236+
}
237+
}
238+
}
239+
```
240+
241+
This will give you the `chainHeadBlock` which you can compare with the `latestBlock` on your subgraph to check if it is running behind. `synced` informs if the subgraph has ever caught up to the chain. `health` can currently take the values of `healthy` if no errors occurred, or `failed` if there was an error which halted the progress of the subgraph. In this case, you can check the `fatalError` field for details on this error.

0 commit comments

Comments
 (0)