From 98904d45cfc7b9615e805cf9ec2941c818141f05 Mon Sep 17 00:00:00 2001 From: sontrinh16 Date: Tue, 8 Oct 2024 14:40:27 +0700 Subject: [PATCH 1/6] add tutorial doc --- x/accounts/defaults/lockup/TUTORIAL.md | 246 +++++++++++++++++++++++++ 1 file changed, 246 insertions(+) create mode 100644 x/accounts/defaults/lockup/TUTORIAL.md diff --git a/x/accounts/defaults/lockup/TUTORIAL.md b/x/accounts/defaults/lockup/TUTORIAL.md new file mode 100644 index 000000000000..43cfc39457c2 --- /dev/null +++ b/x/accounts/defaults/lockup/TUTORIAL.md @@ -0,0 +1,246 @@ +# Using lockup account on Cosmos sdk + +* [Setup](#setup) +* [Init](#init) +* [Execution](#execution) + * [Delegate](#delegate) + * [Undelegate](#undelegate) + * [Withdraw reward](#withdraw-reward) + * [Withdraw unlocked token](#withdraw-unlocked-token) + * [Send coins](#send-coins) +* [Query](#query) + * [Query account info](#query-account-info) + * [Query periodic lockup account locking periods](#query-periodic-lockup-account-locking-periods) + +## Setup + +To create a lockup account we need 2 wallets (newly created or use any of the existing wallet that you have) one for the granter and one for the owner of the lockup account. + +```bash +simd keys add granter --keyring-backend test --home ./.testnets/node0/simd/ +simd keys add owner --keyring-backend test --home ./.testnets/node0/simd/ +``` + +## Init + +Normally the granter 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 granter want to grant the fund to. + +Now, the granter can craft the lockup account init messages. This message depend on what type of lockup account the granter want to create. + +
+ +For continous, delayed, permanent locking account: + +```go +{ + "owner": "cosmos1vaqh39cdex9sgr69ef0tdln5cn0hdyd3s0lx45", + "end_time": 1495793860 + "start_time": 1465793854 +} +``` + +:::infor +*note: `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* +::: + +
+ +For periodic locking account: + +```go + { + "owner": "cosmos1vaqh39cdex9sgr69ef0tdln5cn0hdyd3s0lx45", + "locking_periods": [ + { + "length": 84600 + "amount": { + "denom": "stake", + "amount": 2000 + } + }, + { + "length": 84600 + "amount": { + "denom": "stake", + "amount": 1500 + } + } + ] + "start_time": 1465793854 + } +``` + +Periodic locking account locking duration is the combines of all the period length from `locking_periods`. + +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. + +To initialize the account, we have to run the accounts init command passing the account type and the json string for the init message. + +```bash +initcontents=$(cat init.json) +simd tx accounts init $initcontents --fees 5stake --chain-id $CHAINID --keyring-backend test --home ./.testnets/node0/simd/ --from granter +``` + +Whereas the available `lockup_type` options are: + +* continuous-locking-account + +* delayed-locking-account + +* periodic-locking-account + +* permanent-locking-account + +If success, we'll check the tx result for the lockup account address. You can send token to it like a normal account. + +## Execution + +To execute a message, we can use the command below: + +```bash +msgcontents=$(cat msg.json) +simd tx accounts execute $msgcontents --fees 5stake --chain-id $CHAINID --keyring-backend test --home ./.testnets/node0/simd/ --from owner +``` + +Whereas `execute-msg-type-url` and `msgcontents` corresponds to lockup account available executions, which are: + +### Delegate + +The execute message type url for this execution is `cosmos.accounts.defaults.lockup.MsgDelegate`. + +Example of json file: + +```go +{ + "sender": "cosmos1vaqh39cdex9sgr69ef0tdln5cn0hdyd3s0lx45", + "validator_address": "cosmosvaloper1vaqh39cdex9sgr69ef0tdln5cn0hdyd3s0lx45", + "amount": { + "amount": 100 + "denom": "stake" + } +} +``` + +:::warning +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. +::: + +### Undelegate + +The execute message type url for this execution is `cosmos.accounts.defaults.lockup.MsgUndelegate`. + +Example of json file: + +```go +{ + "sender": "cosmos1vaqh39cdex9sgr69ef0tdln5cn0hdyd3s0lx45", + "validator_address": "cosmosvaloper1vaqh39cdex9sgr69ef0tdln5cn0hdyd3s0lx45", + "amount": { + "amount": 100 + "denom": "stake" + } +} +``` + +:::warning +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. +::: + +### Withdraw reward + +The execute message type url for this execution is `cosmos.accounts.defaults.lockup.MsgWithdrawReward`. + +Example of json file: + +```go +{ + "sender": "cosmos1vaqh39cdex9sgr69ef0tdln5cn0hdyd3s0lx45", + "validator_address": "cosmosvaloper1vaqh39cdex9sgr69ef0tdln5cn0hdyd3s0lx45", +} +``` + +:::warning +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. +::: + +### Withdraw unlocked token + +The execute message type url for this execution is `cosmos.accounts.defaults.lockup.MsgWithdraw`. + +Example of json file: + +```go +{ + // lockup account owner address + "withdrawer": "cosmos1vaqh39cdex9sgr69ef0tdln5cn0hdyd3s0lx46", + // withdraw to an account of choice + "to_address": "cosmos1vaqh39cdex9sgr69ef0tdln5cn0hdyd3s0lx47", + "denoms": ["stake"] +} +``` + +:::warning +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. +::: + +### Send coins + +The execute message type url for this execution is `cosmos.accounts.defaults.lockup.MsgSend`. + +Example of json file: + +```go +{ + "sender": "cosmos1vaqh39cdex9sgr69ef0tdln5cn0hdyd3s0lx45", + "to_address": "cosmos1vaqh39cdex9sgr69ef0tdln5cn0hdyd3s0lx46", + "amount": { + "amount": 100 + "denom": "stake" + } +} +``` + +:::warning +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. +::: + +## Query + +To query a lockup account state, we can use the command below: + +```bash +querycontents=$(cat query.json) +simd tx accounts query $querycontents --fees 5stake --chain-id $CHAINID --keyring-backend test --home ./.testnets/node0/simd/ --from owner +``` + +### Query account info + +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. + +Account informations including: + +* original locked amount + +* delegated amount that are locked + +* delegated amount that are free + +* start and end time + +* owner address + +* current locked and unlocked amount + +### Query periodic lockup account locking periods + +:::info +Note, can only be queried from a periodic lockup account +::: + +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. + +Locking periods including: + +* List of period with its duration and amount + + From 3aac6e31c8538ddc8eb1a5c2bc7c4c7e1b77f3c4 Mon Sep 17 00:00:00 2001 From: son trinh Date: Tue, 8 Oct 2024 23:52:18 +0700 Subject: [PATCH 2/6] Update x/accounts/defaults/lockup/TUTORIAL.md Co-authored-by: Marko --- x/accounts/defaults/lockup/TUTORIAL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x/accounts/defaults/lockup/TUTORIAL.md b/x/accounts/defaults/lockup/TUTORIAL.md index 43cfc39457c2..06c0a8f567a7 100644 --- a/x/accounts/defaults/lockup/TUTORIAL.md +++ b/x/accounts/defaults/lockup/TUTORIAL.md @@ -23,7 +23,7 @@ simd keys add owner --keyring-backend test --home ./.testnets/node0/simd/ ## Init -Normally the granter 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 granter want to grant the fund to. +Normally the granter must have enough token to create to the lockup account during the lockup account init process. The owner wallet should be associated with the individual that the granter wants to create the lockup account for. Now, the granter can craft the lockup account init messages. This message depend on what type of lockup account the granter want to create. From 8fb86e4c0242aabe1566de19830d2f26ad7612db Mon Sep 17 00:00:00 2001 From: son trinh Date: Tue, 8 Oct 2024 23:52:58 +0700 Subject: [PATCH 3/6] Update x/accounts/defaults/lockup/TUTORIAL.md Co-authored-by: Julien Robert --- x/accounts/defaults/lockup/TUTORIAL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x/accounts/defaults/lockup/TUTORIAL.md b/x/accounts/defaults/lockup/TUTORIAL.md index 06c0a8f567a7..1cd05e83d93c 100644 --- a/x/accounts/defaults/lockup/TUTORIAL.md +++ b/x/accounts/defaults/lockup/TUTORIAL.md @@ -40,7 +40,7 @@ For continous, delayed, permanent locking account: ``` :::infor -*note: `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* +`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* :::
From 59fa516b18407498daff05afa60093220d7fcb54 Mon Sep 17 00:00:00 2001 From: son trinh Date: Tue, 8 Oct 2024 23:53:07 +0700 Subject: [PATCH 4/6] Update x/accounts/defaults/lockup/TUTORIAL.md Co-authored-by: Julien Robert --- x/accounts/defaults/lockup/TUTORIAL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x/accounts/defaults/lockup/TUTORIAL.md b/x/accounts/defaults/lockup/TUTORIAL.md index 1cd05e83d93c..24789bd21faa 100644 --- a/x/accounts/defaults/lockup/TUTORIAL.md +++ b/x/accounts/defaults/lockup/TUTORIAL.md @@ -39,7 +39,7 @@ For continous, delayed, permanent locking account: } ``` -:::infor +:::info `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* ::: From 668cb5448ce6ee5fe958aad9dbe4e1a5f3c47d0b Mon Sep 17 00:00:00 2001 From: sontrinh16 Date: Wed, 9 Oct 2024 00:18:41 +0700 Subject: [PATCH 5/6] address comments --- x/accounts/defaults/lockup/TUTORIAL.md | 23 ++++++++++------------- 1 file changed, 10 insertions(+), 13 deletions(-) diff --git a/x/accounts/defaults/lockup/TUTORIAL.md b/x/accounts/defaults/lockup/TUTORIAL.md index 43cfc39457c2..0ec8139ed585 100644 --- a/x/accounts/defaults/lockup/TUTORIAL.md +++ b/x/accounts/defaults/lockup/TUTORIAL.md @@ -12,23 +12,22 @@ * [Query account info](#query-account-info) * [Query periodic lockup account locking periods](#query-periodic-lockup-account-locking-periods) +To learn more about lockup account, please also check out [readme](./README.md) + ## Setup -To create a lockup account we need 2 wallets (newly created or use any of the existing wallet that you have) one for the granter and one for the owner of the lockup account. +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. ```bash -simd keys add granter --keyring-backend test --home ./.testnets/node0/simd/ -simd keys add owner --keyring-backend test --home ./.testnets/node0/simd/ +simd keys add creator +simd keys add owner ``` ## Init -Normally the granter 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 granter want to grant the fund to. - -Now, the granter can craft the lockup account init messages. This message depend on what type of lockup account the granter want to create. - -
+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. +Now, the creator can craft the lockup account init messages. This message depend on what type of lockup account the creator want to create. For continous, delayed, permanent locking account: ```go @@ -42,8 +41,6 @@ For continous, delayed, permanent locking account: :::infor *note: `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* ::: - -
For periodic locking account: @@ -78,7 +75,7 @@ To initialize the account, we have to run the accounts init command passing the ```bash initcontents=$(cat init.json) -simd tx accounts init $initcontents --fees 5stake --chain-id $CHAINID --keyring-backend test --home ./.testnets/node0/simd/ --from granter +simd tx accounts init $initcontents --from creator ``` Whereas the available `lockup_type` options are: @@ -99,7 +96,7 @@ To execute a message, we can use the command below: ```bash msgcontents=$(cat msg.json) -simd tx accounts execute $msgcontents --fees 5stake --chain-id $CHAINID --keyring-backend test --home ./.testnets/node0/simd/ --from owner +simd tx accounts execute $msgcontents --from owner ``` Whereas `execute-msg-type-url` and `msgcontents` corresponds to lockup account available executions, which are: @@ -210,7 +207,7 @@ To query a lockup account state, we can use the command below: ```bash querycontents=$(cat query.json) -simd tx accounts query $querycontents --fees 5stake --chain-id $CHAINID --keyring-backend test --home ./.testnets/node0/simd/ --from owner +simd tx accounts query $querycontents --from owner ``` ### Query account info From 2651c8700354d567a5584a7f36f45b873f4d9460 Mon Sep 17 00:00:00 2001 From: son trinh Date: Wed, 9 Oct 2024 09:46:40 +0700 Subject: [PATCH 6/6] address comments Co-authored-by: beep --- x/accounts/defaults/lockup/TUTORIAL.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/x/accounts/defaults/lockup/TUTORIAL.md b/x/accounts/defaults/lockup/TUTORIAL.md index 70d0bf639c8a..1a308cbcea7c 100644 --- a/x/accounts/defaults/lockup/TUTORIAL.md +++ b/x/accounts/defaults/lockup/TUTORIAL.md @@ -30,7 +30,7 @@ Normally the creator must have enough token to grant to the lockup account durin Now, the creator can craft the lockup account init messages. This message depend on what type of lockup account the creator want to create. For continous, delayed, permanent locking account: -```go +```json { "owner": "cosmos1vaqh39cdex9sgr69ef0tdln5cn0hdyd3s0lx45", "end_time": 1495793860 @@ -44,7 +44,7 @@ For continous, delayed, permanent locking account: For periodic locking account: -```go +```json { "owner": "cosmos1vaqh39cdex9sgr69ef0tdln5cn0hdyd3s0lx45", "locking_periods": [ @@ -107,7 +107,7 @@ The execute message type url for this execution is `cosmos.accounts.defaults.loc Example of json file: -```go +```json { "sender": "cosmos1vaqh39cdex9sgr69ef0tdln5cn0hdyd3s0lx45", "validator_address": "cosmosvaloper1vaqh39cdex9sgr69ef0tdln5cn0hdyd3s0lx45", @@ -128,7 +128,7 @@ The execute message type url for this execution is `cosmos.accounts.defaults.loc Example of json file: -```go +```json { "sender": "cosmos1vaqh39cdex9sgr69ef0tdln5cn0hdyd3s0lx45", "validator_address": "cosmosvaloper1vaqh39cdex9sgr69ef0tdln5cn0hdyd3s0lx45", @@ -149,7 +149,7 @@ The execute message type url for this execution is `cosmos.accounts.defaults.loc Example of json file: -```go +```json { "sender": "cosmos1vaqh39cdex9sgr69ef0tdln5cn0hdyd3s0lx45", "validator_address": "cosmosvaloper1vaqh39cdex9sgr69ef0tdln5cn0hdyd3s0lx45", @@ -166,7 +166,7 @@ The execute message type url for this execution is `cosmos.accounts.defaults.loc Example of json file: -```go +```json { // lockup account owner address "withdrawer": "cosmos1vaqh39cdex9sgr69ef0tdln5cn0hdyd3s0lx46", @@ -186,7 +186,7 @@ The execute message type url for this execution is `cosmos.accounts.defaults.loc Example of json file: -```go +```json { "sender": "cosmos1vaqh39cdex9sgr69ef0tdln5cn0hdyd3s0lx45", "to_address": "cosmos1vaqh39cdex9sgr69ef0tdln5cn0hdyd3s0lx46",