Skip to content

Commit 3220aab

Browse files
sontrinh16tac0turtlejulienrbrtbeepdeepor
authored
docs(x/accounts/defaults/lockup): Add tutorial document (#22168)
Co-authored-by: Marko <marko@baricevic.me> Co-authored-by: Julien Robert <julien@rbrt.fr> Co-authored-by: beep <beepdeepor@gmail.com>
1 parent f48fac3 commit 3220aab

File tree

1 file changed

+243
-0
lines changed

1 file changed

+243
-0
lines changed

‎x/accounts/defaults/lockup/TUTORIAL.md‎

Lines changed: 243 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,243 @@
1+
# Using lockup account on Cosmos sdk
2+
3+
* [Setup](#setup)
4+
* [Init](#init)
5+
* [Execution](#execution)
6+
* [Delegate](#delegate)
7+
* [Undelegate](#undelegate)
8+
* [Withdraw reward](#withdraw-reward)
9+
* [Withdraw unlocked token](#withdraw-unlocked-token)
10+
* [Send coins](#send-coins)
11+
* [Query](#query)
12+
* [Query account info](#query-account-info)
13+
* [Query periodic lockup account locking periods](#query-periodic-lockup-account-locking-periods)
14+
15+
To learn more about lockup account, please also check out [readme](./README.md)
16+
17+
## Setup
18+
19+
To create a lockup account we need 2 wallets (newly created or use any of the existing wallet that you have) one for the creator and one for the owner of the lockup account.
20+
21+
```bash
22+
simd keys add creator
23+
simd keys add owner
24+
```
25+
26+
## Init
27+
28+
Normally the creator must have enough token to grant to the lockup account during the lockup account init process. The owner wallet should be associated with the individual that the creator want to grant the fund to.
29+
30+
Now, the creator can craft the lockup account init messages. This message depend on what type of lockup account the creator want to create.
31+
For continous, delayed, permanent locking account:
32+
33+
```json
34+
{
35+
"owner": "cosmos1vaqh39cdex9sgr69ef0tdln5cn0hdyd3s0lx45",
36+
"end_time": 1495793860
37+
"start_time": 1465793854
38+
}
39+
```
40+
41+
:::info
42+
`start_time` is only needed for continous locking account init process. For the other two, you dont have to set it in. Error will returned if `start_time` is not provided when creating continous locking account*
43+
:::
44+
45+
For periodic locking account:
46+
47+
```json
48+
{
49+
"owner": "cosmos1vaqh39cdex9sgr69ef0tdln5cn0hdyd3s0lx45",
50+
"locking_periods": [
51+
{
52+
"length": 84600
53+
"amount": {
54+
"denom": "stake",
55+
"amount": 2000
56+
}
57+
},
58+
{
59+
"length": 84600
60+
"amount": {
61+
"denom": "stake",
62+
"amount": 1500
63+
}
64+
}
65+
]
66+
"start_time": 1465793854
67+
}
68+
```
69+
70+
Periodic locking account locking duration is the combines of all the period length from `locking_periods`.
71+
72+
The `owner` field takes a string while `start_time` and `end_time` takes a timestamp as value. `locking_periods` are an array of `period`s which consist of 2 field: `length` for the duration of that period and the `amount` that will be release after such duration.
73+
74+
To initialize the account, we have to run the accounts init command passing the account type and the json string for the init message.
75+
76+
```bash
77+
initcontents=$(cat init.json)
78+
simd tx accounts init <lockup_type> $initcontents --from creator
79+
```
80+
81+
Whereas the available `lockup_type` options are:
82+
83+
* continuous-locking-account
84+
85+
* delayed-locking-account
86+
87+
* periodic-locking-account
88+
89+
* permanent-locking-account
90+
91+
If success, we'll check the tx result for the lockup account address. You can send token to it like a normal account.
92+
93+
## Execution
94+
95+
To execute a message, we can use the command below:
96+
97+
```bash
98+
msgcontents=$(cat msg.json)
99+
simd tx accounts execute <account_address> <execute-msg-type-url> $msgcontents --from owner
100+
```
101+
102+
Whereas `execute-msg-type-url` and `msgcontents` corresponds to lockup account available executions, which are:
103+
104+
### Delegate
105+
106+
The execute message type url for this execution is `cosmos.accounts.defaults.lockup.MsgDelegate`.
107+
108+
Example of json file:
109+
110+
```json
111+
{
112+
"sender": "cosmos1vaqh39cdex9sgr69ef0tdln5cn0hdyd3s0lx45",
113+
"validator_address": "cosmosvaloper1vaqh39cdex9sgr69ef0tdln5cn0hdyd3s0lx45",
114+
"amount": {
115+
"amount": 100
116+
"denom": "stake"
117+
}
118+
}
119+
```
120+
121+
:::warning
122+
The `sender` field are the address of the owner of the lockup account. If the sender is not the owner an error will be returned.
123+
:::
124+
125+
### Undelegate
126+
127+
The execute message type url for this execution is `cosmos.accounts.defaults.lockup.MsgUndelegate`.
128+
129+
Example of json file:
130+
131+
```json
132+
{
133+
"sender": "cosmos1vaqh39cdex9sgr69ef0tdln5cn0hdyd3s0lx45",
134+
"validator_address": "cosmosvaloper1vaqh39cdex9sgr69ef0tdln5cn0hdyd3s0lx45",
135+
"amount": {
136+
"amount": 100
137+
"denom": "stake"
138+
}
139+
}
140+
```
141+
142+
:::warning
143+
The `sender` field are the address of the owner of the lockup account. If the sender is not the owner an error will be returned.
144+
:::
145+
146+
### Withdraw reward
147+
148+
The execute message type url for this execution is `cosmos.accounts.defaults.lockup.MsgWithdrawReward`.
149+
150+
Example of json file:
151+
152+
```json
153+
{
154+
"sender": "cosmos1vaqh39cdex9sgr69ef0tdln5cn0hdyd3s0lx45",
155+
"validator_address": "cosmosvaloper1vaqh39cdex9sgr69ef0tdln5cn0hdyd3s0lx45",
156+
}
157+
```
158+
159+
:::warning
160+
The `sender` field are the address of the owner of the lockup account. If the sender is not the owner an error will be returned.
161+
:::
162+
163+
### Withdraw unlocked token
164+
165+
The execute message type url for this execution is `cosmos.accounts.defaults.lockup.MsgWithdraw`.
166+
167+
Example of json file:
168+
169+
```json
170+
{
171+
// lockup account owner address
172+
"withdrawer": "cosmos1vaqh39cdex9sgr69ef0tdln5cn0hdyd3s0lx46",
173+
// withdraw to an account of choice
174+
"to_address": "cosmos1vaqh39cdex9sgr69ef0tdln5cn0hdyd3s0lx47",
175+
"denoms": ["stake"]
176+
}
177+
```
178+
179+
:::warning
180+
The `withdrawer` field are the address of the owner of the lockup account. If the sender is not the owner an error will be returned.
181+
:::
182+
183+
### Send coins
184+
185+
The execute message type url for this execution is `cosmos.accounts.defaults.lockup.MsgSend`.
186+
187+
Example of json file:
188+
189+
```json
190+
{
191+
"sender": "cosmos1vaqh39cdex9sgr69ef0tdln5cn0hdyd3s0lx45",
192+
"to_address": "cosmos1vaqh39cdex9sgr69ef0tdln5cn0hdyd3s0lx46",
193+
"amount": {
194+
"amount": 100
195+
"denom": "stake"
196+
}
197+
}
198+
```
199+
200+
:::warning
201+
The `sender` field are the address of the owner of the lockup account. If the sender is not the owner an error will be returned.
202+
:::
203+
204+
## Query
205+
206+
To query a lockup account state, we can use the command below:
207+
208+
```bash
209+
querycontents=$(cat query.json)
210+
simd tx accounts query <account_address> <query-request-type-url> $querycontents --from owner
211+
```
212+
213+
### Query account info
214+
215+
The query request type url for this query is `cosmos.accounts.defaults.lockup.QueryLockupAccountInfoRequest`. And query json file can be an empty object since `QueryLockupAccountInfoRequest` does not required an input.
216+
217+
Account informations including:
218+
219+
* original locked amount
220+
221+
* delegated amount that are locked
222+
223+
* delegated amount that are free
224+
225+
* start and end time
226+
227+
* owner address
228+
229+
* current locked and unlocked amount
230+
231+
### Query periodic lockup account locking periods
232+
233+
:::info
234+
Note, can only be queried from a periodic lockup account
235+
:::
236+
237+
The query request type url for this query is `cosmos.accounts.defaults.lockup.QueryLockingPeriodsRequest`. And query json file can be an empty object since `QueryLockingPeriodsRequest` does not required an input.
238+
239+
Locking periods including:
240+
241+
* List of period with its duration and amount
242+
243+

0 commit comments

Comments
 (0)