Skip to content

Commit 93c32c1

Browse files
kruspykruspy
authored
Merge pull request #1 from figment-networks/cosmos-docs
Cosmos documentation draft
2 parents 1fe2c24 + 5a01daa commit 93c32c1

File tree

2 files changed

+243
-0
lines changed

2 files changed

+243
-0
lines changed

‎navigation/navigation.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -135,6 +135,9 @@ export const navigation: (locale: AppLocale) => NavItemDefinition[] = (locale) =
135135
{
136136
slug: 'near',
137137
},
138+
{
139+
slug: 'cosmos',
140+
},
138141
],
139142
},
140143
]

‎pages/en/supported-networks/cosmos.mdx‎

Lines changed: 240 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,240 @@
1+
---
2+
title: Building Subgraphs on Cosmos
3+
---
4+
5+
This guide is an introduction on building subgraphs indexing [Cosmos](https://docs.cosmos.network/) based blockchains.
6+
7+
## What are Cosmos subgraphs?
8+
9+
Cosmos subgraphs are a new type of subgraph that [Graph Node](https://github.com/graphprotocol/graph-node) is now able to process. This allows subgraph developers to easily index on-chain events into a useful data set, easily available to query via GraphQL.
10+
11+
There are currently three types of handlers supported for the Cosmos subgraphs:
12+
13+
- Block handlers.
14+
- [Event](https://docs.cosmos.network/master/core/events.html) handlers.
15+
- [Transaction](https://docs.cosmos.network/master/core/transactions.html) handlers.
16+
17+
Based on the [official Cosmos documentation](https://docs.cosmos.network/):
18+
19+
> Events are objects that contain information about the execution of the application. They are mainly used by service providers like block explorers and wallet to track the execution of various messages and index transactions.
20+
21+
> Transactions are objects created by end-users to trigger state changes in the application.
22+
23+
## Building a Cosmos subgraph
24+
25+
### Subgraph Main Components
26+
27+
There are three main key parts or files when it comes to defining a subgraph:
28+
29+
**subgraph.yaml**: a YAML file containing the subgraph manifest, which identifies which events to track and how to process them.
30+
31+
**schema.graphql**: a GraphQL schema that defines what data is stored for your subgraph, and how to query it via GraphQL.
32+
33+
**AssemblyScript Mappings**: [AssemblyScript](https://github.com/AssemblyScript/assemblyscript) code that translates from blockchain data to the entities defined in your schema.
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 (`handlers`) that should be run in response to those triggers. See below for an example subgraph manifest for a Cosmos subgraph:
38+
39+
```yaml
40+
specVersion: 0.0.5
41+
description: Cosmos Subgraph Example
42+
schema:
43+
file: ./schema.graphql # link to the schema file
44+
dataSources:
45+
- kind: cosmos
46+
name: CosmosHub
47+
network: cosmoshub-4 # This will change for each cosmos-based blockchain. In this case the example uses the CosmosHub mainnet.
48+
source:
49+
startBlock: 0 # Required for Cosmos, set this to 0 to start indexing from chain genesis
50+
mapping:
51+
apiVersion: 0.0.7
52+
language: wasm/assemblyscript
53+
blockHandlers:
54+
- handler: handleNewBlock # the function name in the mapping file
55+
eventHandlers:
56+
- event: rewards # the type of the event that will be handled
57+
handler: handleReward # the function name in the mapping file
58+
transactionHandlers:
59+
- handler: handleTransaction # the function name in the mapping file
60+
file: ./src/mapping.ts # link to the file with the Assemblyscript mappings
61+
```
62+
63+
- Cosmos subgraphs introduce a new `kind` of data source (`cosmos`).
64+
- The `network` should correspond to a network on the hosting Graph Node. In the example, the CosmosHub mainnet is used.
65+
66+
Cosmos data sources support three types of handlers:
67+
68+
- `blockHandlers`: run on every new block appended to the chain. The handler will receive a full block and all its data containing, among other things, all the events and transactions.
69+
- `eventHandlers`: run on every event contained in a block that matches the event type specified in the manifest. Block data is also passed onto the mapping in order to have context of the event within the chain.
70+
- `transactionHandlers`: run for every transaction executed. The mapping is provided with all the relevant data related to the transaction and a block abstraction that can be used to acquire context of the transaction within a block and within the chain.
71+
72+
Event and Transaction handlers are a way to process meaningful data from the chain without the need of processing a whole block. The data processed by them can also be found in the block handlers, since events and transactions are also part of a block, but removes the need of processing unnecessary data.
73+
74+
### Schema Definition
75+
76+
Schema definition describes the structure of the resulting subgraph database, and the relationships between entities. This is agnostic of the original data source. There are more details on subgraph schema definition [here](https://thegraph.com/docs/en/developer/create-subgraph-hosted/#the-graph-ql-schema).
77+
78+
### AssemblyScript Mappings
79+
80+
The handlers for processing events are written in [AssemblyScript](https://www.assemblyscript.org/).
81+
82+
Cosmos indexing introduces Cosmos-specific data types to the [AssemblyScript API](https://thegraph.com/docs/en/developer/assemblyscript-api/).
83+
84+
```tsx
85+
class Block {
86+
header: Header
87+
evidence: EvidenceList
88+
resultBeginBlock: ResponseBeginBlock
89+
resultEndBlock: ResponseEndBlock
90+
transactions: Array<TxResult>
91+
validatorUpdates: Array<Validator>
92+
}
93+
94+
class EventData {
95+
event: Event
96+
block: HeaderOnlyBlock
97+
}
98+
99+
class TransactionData {
100+
tx: TxResult
101+
block: HeaderOnlyBlock
102+
}
103+
104+
class HeaderOnlyBlock {
105+
header: Header
106+
}
107+
108+
class Header {
109+
version: Consensus
110+
chainId: string
111+
height: u64
112+
time: Timestamp
113+
lastBlockId: BlockID
114+
lastCommitHash: Bytes
115+
dataHash: Bytes
116+
validatorsHash: Bytes
117+
nextValidatorsHash: Bytes
118+
consensusHash: Bytes
119+
appHash: Bytes
120+
lastResultsHash: Bytes
121+
evidenceHash: Bytes
122+
proposerAddress: Bytes
123+
hash: Bytes
124+
}
125+
126+
class TxResult {
127+
height: u64
128+
index: u32
129+
tx: Bytes
130+
result: ResponseDeliverTx
131+
hash: Bytes
132+
}
133+
134+
class Event {
135+
eventType: string
136+
attributes: Array<EventAttribute>
137+
}
138+
```
139+
140+
The types above are just the general ones that mappings use. You can find the full list of types for the Cosmos integration [here](https://github.com/graphprotocol/graph-ts/blob/4c064a8118dff43b110de22c7756e5d47fcbc8df/chain/cosmos.ts).
141+
142+
Each type of handler will receive a different type based on the relevant data. For both event and transaction handlers, a reference to the block they are contained in is passed as well. These are the exact types that are passed as a parameter to each mapping function:
143+
144+
`Block` is passed to the blockHandler.
145+
146+
`EventData` is passed to the eventHandler.
147+
148+
`TransactionData` is passed to the transactionHandler.
149+
150+
## Creating and building a Cosmos subgraph
151+
152+
The first step before starting to write the subgraph mappings is to generate the type bindings based on the entities that have been defined in the subgraph schema file (`schema.graphql`). This will allow the mapping functions to create new objects of those types and save them to the store. This is done by using the `codegen` CLI command:
153+
154+
```bash
155+
$ graph codegen
156+
```
157+
158+
Once the mappings are ready, the subgraph needs to be built. This step will highlight any errors the manifest or the mappings might have. A subgraph needs to build successfully in order to be deployed to the Graph Node. It can be done using the `build` CLI command:
159+
160+
```bash
161+
$ graph build
162+
```
163+
164+
## Deploying a Cosmos subgraph
165+
166+
When the subgraph builds successfully, it is time to deploy it to a Graph Node instance for indexing. Cosmos subgraphs can be deployed to any Graph Node on version `>=v0.26.0`.
167+
168+
The first thing to do is create the subgraph in the node, this only has to be done once via the `create` CLI command:
169+
170+
```bash
171+
Local deployment:
172+
$ graph create subgraph-name --node http://localhost:8020
173+
174+
Hosted service deployment:
175+
$ graph create subgraph-name --product hosted-service
176+
```
177+
178+
After the subgraph has been created, it can be deployed by using the graph `deploy` CLI command:
179+
180+
```bash
181+
Local deployment:
182+
$ graph deploy subgraph-name --ipfs http://localhost:5001 --node http://localhost:8020
183+
184+
Hosted service deployment:
185+
$ graph deploy subgraph-name --product hosted-service
186+
```
187+
188+
Once your subgraph has been deployed, it will be indexed by Graph Node. You can check its progress by querying the subgraph itself at the exposed endpoint.
189+
190+
## Querying a Cosmos subgraph
191+
192+
The GraphQL endpoint for Cosmos subgraphs is determined by the schema definition, with the existing API interface. Please visit the [GraphQL API documentation](https://thegraph.com/docs/en/developer/graphql-api/) for more information.
193+
194+
## Supported Cosmos Blockchains
195+
196+
### Cosmos Hub
197+
198+
##### What is Cosmos Hub?
199+
200+
The [Cosmos Hub blockchain](https://hub.cosmos.network/) is the first blockchain in the [Cosmos](https://cosmos.network/) ecosystem. You can visit the [official documentation](https://docs.cosmos.network/) for more information.
201+
202+
##### Subgraph Dependencies
203+
204+
[graph-cli](https://github.com/graphprotocol/graph-cli) is a CLI tool to build and deploy subgraphs, version `>=0.30.0` is required in order to work with Cosmos Hub subgraphs.
205+
206+
[graph-ts](https://github.com/graphprotocol/graph-ts) is a library of subgraph-specific types, version `>=0.27.0` is required in order to work with Cosmos Hub subgraphs.
207+
208+
##### Networks
209+
210+
Cosmos Hub mainnet is `cosmoshub-4`. Cosmos Hub current testnet is `theta-testnet-001`. <br/>Other Cosmos Hub networks, i.e. `cosmoshub-3`, are halted, therefore no data is provided for them.
211+
212+
### Osmosis
213+
214+
> Osmosis support in Graph Node and on the Hosted Service is in beta: please contact the graph team with any questions about building Osmosis subgraphs!
215+
216+
##### What is Osmosis?
217+
218+
[Osmosis](https://osmosis.zone/) is a decentralized, cross-chain automated market maker (AMM) protocol build on top of the Cosmos SDK. It allows users to create custom liquidity pools and trade IBC enabled tokens. You can visit the [official documentation](https://docs.osmosis.zone/) for more information.
219+
220+
##### Subgraph Dependencies
221+
222+
[graph-cli](https://github.com/graphprotocol/graph-cli) is a CLI tool to build and deploy subgraphs, version `>=0.30.0` is required in order to work with Osmosis subgraphs.
223+
224+
[graph-ts](https://github.com/graphprotocol/graph-ts) is a library of subgraph-specific types, version `>=0.27.0` is required in order to work with Osmosis subgraphs.
225+
226+
##### Networks
227+
228+
Osmosis mainnet is `osmosis-1`. Osmosis current testnet is `osmo-test-4`.
229+
230+
## Example Subgraphs
231+
232+
Here are some example subgraphs for reference:
233+
234+
[Block Filtering Example](https://github.com/graphprotocol/example-subgraph/tree/cosmos-block-filtering)
235+
236+
[Validator Rewards Example](https://github.com/graphprotocol/example-subgraph/tree/cosmos-validator-rewards)
237+
238+
[Validator Delegations Example](https://github.com/graphprotocol/example-subgraph/tree/cosmos-validator-delegations)
239+
240+
[Osmosis Token Swaps Example](https://github.com/graphprotocol/example-subgraph/tree/osmosis-token-swaps)

0 commit comments

Comments
 (0)