Skip to content

Commit 72409ea

Browse files
tmigonetmigone
authored
docs: add provision management documentation (#1151)
Signed-off-by: Tomás Migone <[email protected]>
1 parent a2ddbac commit 72409ea

File tree

2 files changed

+137
-0
lines changed

2 files changed

+137
-0
lines changed

‎docs/images/provision.png‎

68.3 KB
Loading

‎docs/provision-management.md‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
2+
# Graph Horizon provision management
3+
4+
## Glossary
5+
6+
- **indexer stake**: all of the tokens that have been staked by the indexer
7+
- **idle stake**: indexer's stake that has not been assigned to a provision and it's not part of legacy allocations
8+
- **provisioned stake**: stake that has been assigned to a provision
9+
- **delegated stake**: stake that has been delegated to a specific (indexer, provision). Pre-horizon delegation is automatically credited to the `SubgraphService` provision.
10+
- **available stake**: stake that is available within the provision to be used, for example for allocations. Note that this will include provisioned tokens plus delegated stake.
11+
12+
![](./images/provision.png)
13+
14+
## Provision creation for the Subgraph Service
15+
`indexer-agent` will perform the initial creation of the provision. This is attempted _only_ when the agent starts up and _only_ if the indexer's idle stake is greater than 100k GRT, that is:
16+
17+
```
18+
idle stake > 100k GRT
19+
indexer stake - legacy allocated stake > 100k GRT
20+
```
21+
22+
For the provision to be created the agent needs to be configured with a max initial provision size, this can be done by:
23+
- setting env var `INDEXER_AGENT_MAX_PROVISION_INITIAL_SIZE=100000`
24+
- via config file:
25+
```
26+
indexerOptions:
27+
maxProvisionInitialSize: 100000
28+
```
29+
30+
## Provision management
31+
32+
There are three basic operations on a provision:
33+
- `provision()/addToProvision()`: adding idle stake to a provision.
34+
- `thaw()`: thawing available stake from a provision.
35+
- `deprovision()`: removing thawed stake from a provision back into the idle stake pool.
36+
37+
These actions can be executed via indexer-cli or Graph Explorer. We recommend using the cli since it's more versatile.
38+
Note that it's still required to `stake()` and `unstake()` to get stake into/out from the protocol.
39+
40+
41+
### Provision management: Graph Explorer
42+
43+
- When staking through Graph Explorer the added stake will automatically be provisioned to the Subgraph Service (if the provision exists).
44+
- When unstaking/withdrawing through Graph Explorer stake will automatically be thawed and deprovisioned from the provision.
45+
46+
### Provision management: indexer-cli
47+
48+
`indexer-cli` provides a much more flexible way to manage your provision:
49+
50+
```jsx
51+
$ graph indexer provision --help
52+
Manage indexer's provision
53+
54+
indexer provision thaw Thaw stake from the indexer's provision
55+
indexer provision remove Remove thawed stake from the indexer's provision
56+
indexer provision list-thaw List thaw requests for the indexer's provision
57+
indexer provision get List indexer provision details
58+
indexer provision add Add stake to the indexer's provision
59+
indexer provision Manage indexer's provision
60+
```
61+
62+
**Get provision details**
63+
64+
```jsx
65+
$ graph indexer --network hardhat provision get
66+
✔ Provisions
67+
┌────────────────────────────────────────────┬─────────────────┬───────────────────┬─────────────────┬───────────────┬────────────────┬───────────────┐
68+
│ dataService │ protocolNetwork │ tokensProvisioned │ tokensAllocated │ tokensThawing │ maxVerifierCut │ thawingPeriod │
69+
├────────────────────────────────────────────┼─────────────────┼───────────────────┼─────────────────┼───────────────┼────────────────┼───────────────┤
70+
│ 0x0a17fabea4633ce714f1fa4a2dca62c3bac4758d │ hardhat │ 100,000.0 │ 0.01 │ 0.0 │ 50.0 │ 7200 │
71+
└────────────────────────────────────────────┴─────────────────┴───────────────────┴─────────────────┴───────────────┴────────────────┴───────────────┘
72+
73+
Indexer's idle stake: 100,000.0 GRT
74+
To add this stake to the Subgraph Service provision, run 'graph indexer provision add <amount>'
75+
```
76+
77+
**Add stake to the provision**
78+
79+
```jsx
80+
$ graph indexer --network hardhat provision add 100000
81+
✔ Stake added to the provision
82+
┌────────────────────────────────────────────┬─────────────────┬───────────────────┐
83+
│ dataService │ protocolNetwork │ tokensProvisioned │
84+
├────────────────────────────────────────────┼─────────────────┼───────────────────┤
85+
│ 0x0a17fabea4633ce714f1fa4a2dca62c3bac4758d │ hardhat │ 200,000.0 │
86+
└────────────────────────────────────────────┴─────────────────┴───────────────────┘
87+
```
88+
89+
**Thaw stake from the provision**
90+
91+
Note that multiple thaws can be going on simultaneously.
92+
93+
```jsx
94+
$ graph indexer --network hardhat provision thaw 50000
95+
✔ Stake thawed from the provision
96+
┌────────────────────────────────────────────┬─────────────────┬───────────────┬───────────────┬────────────────────────┐
97+
│ dataService │ protocolNetwork │ tokensThawing │ thawingPeriod │ thawingUntil │
98+
├────────────────────────────────────────────┼─────────────────┼───────────────┼───────────────┼────────────────────────┤
99+
│ 0x0a17fabea4633ce714f1fa4a2dca62c3bac4758d │ hardhat │ 50,000.0 │ 7200 │ 9/18/2025, 10:08:58 PM │
100+
└────────────────────────────────────────────┴─────────────────┴───────────────┴───────────────┴────────────────────────┘
101+
```
102+
103+
**List ongoing thaw requests**
104+
105+
This will also show any thawings initiated via Graph Explorer
106+
107+
```jsx
108+
$ graph indexer --network hardhat provision list-thaw
109+
✔ Got thaw requests
110+
┌────────────────────────────────────────────────────────────────────┬───────────┬─────────────────┬──────────┬────────────────────────┐
111+
│ id │ fulfilled │ protocolNetwork │ shares │ thawingUntil │
112+
├────────────────────────────────────────────────────────────────────┼───────────┼─────────────────┼──────────┼────────────────────────┤
113+
│ 0x26b448afdeb7b9b7552ec5aa774b692871f808b80616d9d3e150c4576597acff │ false │ hardhat │ 50,000.0 │ 9/18/2025, 10:08:58 PM │
114+
├────────────────────────────────────────────────────────────────────┼───────────┼─────────────────┼──────────┼────────────────────────┤
115+
│ 0x87f978a42c77a4c525d781f00fdef0225507317c7c5a34018ae166a7243ee80b │ false │ hardhat │ 12,345.0 │ 9/18/2025, 10:11:15 PM │
116+
├────────────────────────────────────────────────────────────────────┼───────────┼─────────────────┼──────────┼────────────────────────┤
117+
│ 0x920f5c0eee54e4741f99cabc6f0142a6c3502f62e430d880762c6489c6ac1c23 │ false │ hardhat │ 1,337.0 │ 9/18/2025, 10:12:40 PM │
118+
└────────────────────────────────────────────────────────────────────┴───────────┴─────────────────┴──────────┴────────────────────────┘
119+
120+
Latest block timestamp: 9/18/2025, 8:12:40 PM
121+
```
122+
123+
**Remove thawed stake**
124+
125+
This puts the stake into the indexer’s “idle stake” pool
126+
127+
```jsx
128+
$ graph indexer --network hardhat provision remove
129+
✔ Thawed stake removed from the provision
130+
┌────────────────────────────────────────────┬─────────────────┬───────────────────┬───────────────┐
131+
│ dataService │ protocolNetwork │ tokensProvisioned │ tokensThawing │
132+
├────────────────────────────────────────────┼─────────────────┼───────────────────┼───────────────┤
133+
│ 0x0a17fabea4633ce714f1fa4a2dca62c3bac4758d │ hardhat │ 200,000.0 │ 0.0 │
134+
└────────────────────────────────────────────┴─────────────────┴───────────────────┴───────────────┘
135+
136+
Removed 63,682.0 GRT from the provision
137+
```

0 commit comments

Comments
 (0)