Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs(x/accounts/defaults/lockup): Add tutorial document #22168

Merged
merged 9 commits into from
Oct 9, 2024
Merged

docs(x/accounts/defaults/lockup): Add tutorial document #22168

Changes from 4 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
98904d4
add tutorial doc
sontrinh16 Oct 8, 2024
3aac6e3
Update x/accounts/defaults/lockup/TUTORIAL.md
sontrinh16 Oct 8, 2024
8fb86e4
Update x/accounts/defaults/lockup/TUTORIAL.md
sontrinh16 Oct 8, 2024
59fa516
Update x/accounts/defaults/lockup/TUTORIAL.md
sontrinh16 Oct 8, 2024
668cb54
address comments
sontrinh16 Oct 8, 2024
9866a06
resolve conflict
sontrinh16 Oct 8, 2024
c026d0c
Merge branch 'main' into son/add_lockup_docs
sontrinh16 Oct 8, 2024
2651c87
address comments
sontrinh16 Oct 9, 2024
3bbe7e3
Merge branch 'main' into son/add_lockup_docs
sontrinh16 Oct 9, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
246 changes: 246 additions & 0 deletions x/accounts/defaults/lockup/TUTORIAL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)

sontrinh16 marked this conversation as resolved.
Show resolved Hide resolved
## 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/
sontrinh16 marked this conversation as resolved.
Show resolved Hide resolved
simd keys add owner --keyring-backend test --home ./.testnets/node0/simd/
```

## Init

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.

</br>
sontrinh16 marked this conversation as resolved.
Show resolved Hide resolved

For continous, delayed, permanent locking account:

```go
sontrinh16 marked this conversation as resolved.
Show resolved Hide resolved
{
"owner": "cosmos1vaqh39cdex9sgr69ef0tdln5cn0hdyd3s0lx45",
"end_time": 1495793860
"start_time": 1465793854
}
```

:::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*
:::

</br>
sontrinh16 marked this conversation as resolved.
Show resolved Hide resolved

For periodic locking account:

```go
sontrinh16 marked this conversation as resolved.
Show resolved Hide resolved
{
"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 <lockup_type> $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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Improve clarity, consistency, and formatting in the Init section

  1. Consider replacing "granter" with "creator" or "admin" throughout the document for clarity, as suggested in past comments.

  2. Improve the structure and grammar of the first paragraph:

- 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.
+ The creator must have sufficient tokens to initialize the lockup account. The owner wallet should be associated with the individual for whom the creator is establishing the lockup account.
  1. Use language-specific formatting for JSON code blocks. For example:
- ```go
+ ```json
{
    "owner": "cosmos1vaqh39cdex9sgr69ef0tdln5cn0hdyd3s0lx45",
    "end_time": 1495793860,
    "start_time": 1465793854
}
  1. Improve the explanation of start_time:
- `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 required for continuous locking account initialization. For other account types, it's optional. An error will be returned if `start_time` is not provided when creating a continuous locking account.
  1. Use consistent formatting for command examples:
initcontents=$(cat init.json)
simd tx accounts init <lockup_type> "$initcontents" \
    --fees 5stake \
    --chain-id "$CHAINID" \
    --keyring-backend test \
    --home ./.testnets/node0/simd/ \
    --from creator

These changes will improve the overall clarity and consistency of the Init section.

🧰 Tools
🪛 LanguageTool

[typographical] ~25-~25: Consider adding a comma after ‘Normally’ for more clarity.
Context: ...e ./.testnets/node0/simd/ ``` ## Init Normally the granter must have enough token to c...

(RB_LY_COMMA)

[grammar] ~28-~28: The verb ‘depend’ is plural. Did you mean: “depends”? Did you use a verb instead of a noun?
Context: ...kup account init messages. This message depend on what type of lockup account the gran...

(PLURAL_VERB_AFTER_THIS)

[style] ~28-~28: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...what type of lockup account the granter want to create.
For continous, delayed,...

(REP_WANT_TO_VB)

[grammar] ~43-~43: The modal verb ‘will’ requires the verb’s base form.
Context: ... you dont have to set it in. Error will returned if start_time is not provided when cr...

(MD_BASEFORM)

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 <account_address> <execute-msg-type-url> $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
sontrinh16 marked this conversation as resolved.
Show resolved Hide resolved
{
"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
sontrinh16 marked this conversation as resolved.
Show resolved Hide resolved
{
"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
sontrinh16 marked this conversation as resolved.
Show resolved Hide resolved
{
"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
sontrinh16 marked this conversation as resolved.
Show resolved Hide resolved
{
// 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
sontrinh16 marked this conversation as resolved.
Show resolved Hide resolved
{
"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.
:::
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Improve consistency and conciseness in the Execution section

  1. Remove HTML tags and use Markdown formatting instead. For example, replace <br> with an empty line.

  2. Consolidate the repetitive warnings about the sender field into a single note at the beginning of the Execution section:

> **Note:** For all execution operations, the `sender` field must be the address of the owner of the lockup account. If the sender is not the owner, an error will be returned.
  1. Use consistent and language-specific formatting for JSON code blocks. For example:
- ```go
+ ```json
{
    "sender": "cosmos1vaqh39cdex9sgr69ef0tdln5cn0hdyd3s0lx45",
    "validator_address": "cosmosvaloper1vaqh39cdex9sgr69ef0tdln5cn0hdyd3s0lx45",
    "amount": {
        "amount": 100,
        "denom": "stake"
    }
}
  1. Use consistent formatting for command examples:
msgcontents=$(cat msg.json)
simd tx accounts execute <account_address> <execute-msg-type-url> "$msgcontents" \
    --fees 5stake \
    --chain-id "$CHAINID" \
    --keyring-backend test \
    --home ./.testnets/node0/simd/ \
    --from owner
  1. Consider using a table to summarize the different execution operations, their message type URLs, and any specific requirements. This would make the information more accessible and easier to reference.

These changes will improve the overall consistency and readability of the Execution section.

🧰 Tools
🪛 LanguageTool

[grammar] ~108-~108: The verb ‘execute’ does not usually follow articles like ‘The’. Check that ‘execute’ is spelled correctly; using ‘execute’ as a noun may be non-standard.
Context: ...e executions, which are: ### Delegate The execute message type url for this execution is ...

(A_INFINITIVE)

[grammar] ~129-~129: The verb ‘execute’ does not usually follow articles like ‘The’. Check that ‘execute’ is spelled correctly; using ‘execute’ as a noun may be non-standard.
Context: ... will be returned. ::: ### Undelegate The execute message type url for this execution is ...

(A_INFINITIVE)

[grammar] ~150-~150: The verb ‘execute’ does not usually follow articles like ‘The’. Check that ‘execute’ is spelled correctly; using ‘execute’ as a noun may be non-standard.
Context: ...be returned. ::: ### Withdraw reward The execute message type url for this execution is ...

(A_INFINITIVE)

[grammar] ~167-~167: The verb ‘execute’ does not usually follow articles like ‘The’. Check that ‘execute’ is spelled correctly; using ‘execute’ as a noun may be non-standard.
Context: ...rned. ::: ### Withdraw unlocked token The execute message type url for this execution is ...

(A_INFINITIVE)

[grammar] ~187-~187: The verb ‘execute’ does not usually follow articles like ‘The’. Check that ‘execute’ is spelled correctly; using ‘execute’ as a noun may be non-standard.
Context: ... will be returned. ::: ### Send coins The execute message type url for this execution is ...

(A_INFINITIVE)


## Query

To query a lockup account state, we can use the command below:

```bash
querycontents=$(cat query.json)
simd tx accounts query <account_address> <query-request-type-url> $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


Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Improve clarity and consistency in the Query section

  1. Improve the explanation of the query command:
- To query a lockup account state, we can use the command below:
+ To query a lockup account state, use the following command:

```bash
querycontents=$(cat query.json)
simd tx accounts query <account_address> <query-request-type-url> "$querycontents" \
    --fees 5stake \
    --chain-id "$CHAINID" \
    --keyring-backend test \
    --home ./.testnets/node0/simd/ \
    --from owner
  1. Correct grammatical issues and improve clarity:
- 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.
+ The query request type URL for this query is `cosmos.accounts.defaults.lockup.QueryLockupAccountInfoRequest`. The query JSON file can be an empty object since `QueryLockupAccountInfoRequest` does not require any input.
  1. Use consistent formatting for lists. For example, in the "Account informations including:" section:
Account information includes:

- Original locked amount
- Delegated amount that is locked
- Delegated amount that is free
- Start and end time
- Owner address
- Current locked and unlocked amount
  1. For the "Query periodic lockup account locking periods" section, use consistent formatting and improve clarity:
### Query periodic lockup account locking periods

> **Note:** This query can only be performed on a periodic lockup account.

The query request type URL for this query is `cosmos.accounts.defaults.lockup.QueryLockingPeriodsRequest`. The query JSON file can be an empty object since `QueryLockingPeriodsRequest` does not require any input.

Locking periods information includes:

- List of periods with their duration and amount

These changes will improve the overall clarity, consistency, and readability of the Query section.

🧰 Tools
🪛 LanguageTool

[grammar] ~218-~218: After the auxiliary verb ‘do’, use the base form of a verb. Did you mean “require”?
Context: ...QueryLockupAccountInfoRequest` does not required an input. Account informations includi...

(AUXILIARY_DO_WITH_INCORRECT_VERB_FORM)

[misspelling] ~220-~220: The word ‘informations’ is a legal term. In standard English, the word ‘information’ is a non-count noun.
Context: ...t` does not required an input. Account informations including: * original locked amount *...

(INFORMATIONS)

[grammar] ~240-~240: After the auxiliary verb ‘do’, use the base form of a verb. Did you mean “require”?
Context: ...e QueryLockingPeriodsRequest does not required an input. Locking periods including: ...

(AUXILIARY_DO_WITH_INCORRECT_VERB_FORM)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Overall document improvement suggestions

This tutorial provides valuable information on using lockup accounts in Cosmos SDK. To further enhance its effectiveness, consider the following overall improvements:

  1. Add a brief introduction or abstract at the beginning of the document to provide context.
  2. Consistently use Markdown formatting throughout the document, avoiding HTML tags.
  3. Standardize the formatting of code blocks, using language-specific syntax highlighting where appropriate.
  4. Replace the term "granter" with "creator" or "admin" for clarity.
  5. Consolidate repetitive information, such as warnings about the sender field.
  6. Use tables or other structured formats to present information more concisely where applicable.
  7. Ensure consistent capitalization and punctuation throughout the document.
  8. Review and correct any remaining grammatical issues.

By implementing these suggestions, the tutorial will become more readable, consistent, and user-friendly, making it easier for developers to understand and implement lockup accounts in Cosmos SDK.

🧰 Tools
🪛 LanguageTool

[duplication] ~11-~11: Possible typo: you repeated a word
Context: ...ken) * Send coins * Query * Query account info ...

(ENGLISH_WORD_REPEAT_RULE)

[typographical] ~17-~17: It seems that a comma is missing.
Context: ...periods) ## Setup To create a lockup account we need 2 wallets (newly created or use...

(IN_ORDER_TO_VB_COMMA)

[typographical] ~25-~25: Consider adding a comma after ‘Normally’ for more clarity.
Context: ...e ./.testnets/node0/simd/ ``` ## Init Normally the granter must have enough token to c...

(RB_LY_COMMA)

[grammar] ~28-~28: The verb ‘depend’ is plural. Did you mean: “depends”? Did you use a verb instead of a noun?
Context: ...kup account init messages. This message depend on what type of lockup account the gran...

(PLURAL_VERB_AFTER_THIS)

[style] ~28-~28: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...what type of lockup account the granter want to create.
For continous, delayed,...

(REP_WANT_TO_VB)

[grammar] ~43-~43: The modal verb ‘will’ requires the verb’s base form.
Context: ... you dont have to set it in. Error will returned if start_time is not provided when cr...

(MD_BASEFORM)

[grammar] ~108-~108: The verb ‘execute’ does not usually follow articles like ‘The’. Check that ‘execute’ is spelled correctly; using ‘execute’ as a noun may be non-standard.
Context: ...e executions, which are: ### Delegate The execute message type url for this execution is ...

(A_INFINITIVE)

[grammar] ~129-~129: The verb ‘execute’ does not usually follow articles like ‘The’. Check that ‘execute’ is spelled correctly; using ‘execute’ as a noun may be non-standard.
Context: ... will be returned. ::: ### Undelegate The execute message type url for this execution is ...

(A_INFINITIVE)

[grammar] ~150-~150: The verb ‘execute’ does not usually follow articles like ‘The’. Check that ‘execute’ is spelled correctly; using ‘execute’ as a noun may be non-standard.
Context: ...be returned. ::: ### Withdraw reward The execute message type url for this execution is ...

(A_INFINITIVE)

[grammar] ~167-~167: The verb ‘execute’ does not usually follow articles like ‘The’. Check that ‘execute’ is spelled correctly; using ‘execute’ as a noun may be non-standard.
Context: ...rned. ::: ### Withdraw unlocked token The execute message type url for this execution is ...

(A_INFINITIVE)

[grammar] ~187-~187: The verb ‘execute’ does not usually follow articles like ‘The’. Check that ‘execute’ is spelled correctly; using ‘execute’ as a noun may be non-standard.
Context: ... will be returned. ::: ### Send coins The execute message type url for this execution is ...

(A_INFINITIVE)

[grammar] ~218-~218: After the auxiliary verb ‘do’, use the base form of a verb. Did you mean “require”?
Context: ...QueryLockupAccountInfoRequest` does not required an input. Account informations includi...

(AUXILIARY_DO_WITH_INCORRECT_VERB_FORM)

[misspelling] ~220-~220: The word ‘informations’ is a legal term. In standard English, the word ‘information’ is a non-count noun.
Context: ...t` does not required an input. Account informations including: * original locked amount *...

(INFORMATIONS)

[grammar] ~240-~240: After the auxiliary verb ‘do’, use the base form of a verb. Did you mean “require”?
Context: ...e QueryLockingPeriodsRequest does not required an input. Locking periods including: ...

(AUXILIARY_DO_WITH_INCORRECT_VERB_FORM)

Loading