Developers Docs
Search…
Subgraph Development Documentation
Start Subgraph Development
There are 3 main components of a subgraph:
- GraphQL schema
- subgraph manifest
- mappings
GraphQL schema
In schema we will define our data model - set of entities which give a shape to the data we want to collect. As a first thing, we'll add entities from SimpleFi's common subgraph schema. Common schema enables us to use abstraction model which can be applied to any DeFi protocol and thus makes it easier to compare protocols, calculate user's ROIs and do other analytics. However it is not trivial to map features of each protocol to a common model. To make it easier, we most often define additional protocol specific entities which enable us to capture all the data we're interested in and then transform it into common shape. So, in case of MasterChef we will first add representation of a farm:
1
type SushiFarm @entity {
2
" masterchef-farmPid "
3
id: ID!
4
​
5
" pid of the farm/pool assigned by the masterChef "
6
farmPid: BigInt!
7
​
8
" masterchef contract address "
9
masterChef: MasterChef!
10
​
11
" sushi LP token which is farm's input token "
12
lpToken: Token!
13
​
14
" contract which tracks and distributes extra reward tokens "
15
rewarder: Rewarder
16
​
17
" amount of sushi to distribute per block. "
18
allocPoint: BigInt!
19
​
20
" total amount of LP tokens provided to farm "
21
totalSupply: BigInt!
22
​
23
" last block number where sushi distribution occurs. "
24
lastRewardBlock: BigInt!
25
​
26
" accumulated amount of sushi per share"
27
accSushiPerShare: BigInt!
28
​
29
" creation timestamp "
30
created: BigInt!
31
​
32
" creation block number "
33
createdAtBlock: BigInt!
34
​
35
" creation transaction "
36
createdAtTransaction: Bytes!
37
}
Copied!
As you can see we store all the relevant info - LP token of the farm and its supply, reward related variables and info related to creation of farm. User's position in particular farm needs to be represented as well:
1
type UserInfo @entity {
2
" usersAddress-farmPID"
3
id: ID!
4
​
5
" user taking positions in farm "
6
user: Account!
7
​
8
" farm to which user position belongs to "
9
farm: SushiFarm!
10
​
11
" LP token amount the user has provided "
12
amount: BigInt!
13
​
14
" amount of SUSHI entitled to the user "
15
rewardDebt: BigInt!
16
}
Copied!
Both farm and
userInfo are based on the structs used within the smart contract. That way it is straight-forward to keep track of all the contract interactions. There is one more important entity - MasterChef itself. Currently there are 2 versions of MasterChef deployed in production, and in future there might be more. This is the entity:1
type MasterChef @entity {
2
" contract address "
3
id: ID!
4
​
5
" masterchef contract version "
6
version: BigInt!
7
​
8
" address of sushi token"
9
sushi: Token!
10
​
11
" total number of farms/pools this masterChef is tracking "
12
numberOfFarms: BigInt!
13
​
14
" sum of all allocation points in all farms "
15
totalAllocPoint: BigInt!
16
​
17
" sushi tokens created per block "
18
sushiPerBlock: BigInt!
19
​
20
" block number when bonus Sushi period ends "
21
bonusEndBlock: BigInt
22
​
23
" bonus muliplier for early sushi makers "
24
bonusMultiplier: BigInt
25
}
Copied!
Now we have basic entities defined (there are some more in the actual subgraph implementation, mostly related to MasterChef V2 which we don't cover here). Let's continue with next step.
Subgraph manifest
Subgraph manifest is yaml file where we specify which smart contracts we're interested in, what are the events we subscribe to and where are the mappings which handle the events. Since MasterChef is implemented as a single smart contract, manifest will be short and concise. We define a
dataSource:1
dataSources:
2
# Controls pools (farms) and SUSHI issuance - V1 version
3
- name: MasterChef
4
kind: ethereum/contract
5
network: mainnet
6
source:
7
abi: MasterChef
8
address: "0xc2edad668740f1aa35e4d8f227fb8e17dca888cd"
9
startBlock: 10736242
10
mapping:
11
kind: ethereum/events
12
apiVersion: 0.0.4
13
language: wasm/assemblyscript
14
file: ./src/mappings/masterChef.ts
15
abis:
16
- name: MasterChef
17
file: ./abis/MasterChef.json
18
- name: IERC20
19
file: ./abis/IERC20.json
20
entities:
21
- MasterChef
22
- Block
23
- Account
24
- Token
25
- Market
26
- Transaction
27
- Transfer
28
- Position
29
- PositionSnapshot
30
eventHandlers:
31
- event: Deposit(indexed address,indexed uint256,uint256)
32
handler: handleDeposit
33
- event: Withdraw(indexed address,indexed uint256,uint256)
34
handler: handleWithdraw
35
- event: EmergencyWithdraw(indexed address,indexed uint256,uint256)
36
handler: handleEmergencyWithdraw
37
callHandlers:
38
- function: add(uint256,address,bool)
39
handler: handleAdd
40
- function: updatePool(uint256)
41
handler: handleUpdatePool
42
- function: set(uint256,uint256,bool)
43
handler: handleSet
44
- function: migrate(uint256)
45
handler: handleMigrate
46
- function: massUpdatePools()
47
handler: handleMassUpdatePools
Copied!
In addition to event handlers we have call handlers defined as well - remember, not every state transition is covered by event, that's why we need to subscribe to event-less function calls. Defining the
startBlock will save indexing time, because not all the Ethereum block will have to be digested, only the ones where our contract is live. You can find start block by looking at contract creation info in Etherscan. ABI files can be downloaded from there and stored into appropriate directory. In general, you will spend big chunk of time going through Etherscan while developing and troubleshooting subgraphs so make sure to become familiar with it. Now that we have schema and manifest in place, let's get onto the real stuff - implementing the mapping code! Last modified 7mo ago
Copy link