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

docs(x/accounts/defaults/lockup): Add slash document for lockup account #22783

Merged
merged 4 commits into from
Dec 6, 2024
Merged

docs(x/accounts/defaults/lockup): Add slash document for lockup account #22783

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
3661a5c
add docs
sontrinh16 Dec 6, 2024
cdbc212
minor
sontrinh16 Dec 6, 2024
72c34be
minor
sontrinh16 Dec 6, 2024
c7e6918
address suggestion
sontrinh16 Dec 6, 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
26 changes: 25 additions & 1 deletion x/accounts/defaults/lockup/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
* [PeriodicLockup](#periodiclockup)
* [PermanentLocked](#permanentlocked)
* [Genesis Initialization](#genesis-initialization)
* [In An Event Of Slashing](#in-an-event-of-slashing)
* [Examples](#examples)
* [Simple](#simple)
* [Slashing](#slashing)
Expand Down Expand Up @@ -108,6 +109,29 @@ type PermanentLockingAccount struct {

<!-- TODO: once implemented -->

## In An Event Of Slashing

As defined, base lockup store `DelegatedLocking` by amount. In an event of a validator that the lockup account delegate to is slash which affect the actual delegation amount, this will leave the `DelegatedLocking` have an excess amount even if user undelegate all of the
account delegated amount. This excess amount would affect the spendable amount, further details are as below:

The spendable amount is calculated as:
`spendableAmount` = `balance` - `notBondedLockedAmount`
where `notBondedLockedAmount` = `lockedAmount` - `Min(lockedAmount, delegatedLockedAmount)`

As seen in the formula `notBondedLockedAmout` can only be 0 or a positive value when `DelegatedLockedAmount` < `LockedAmount`. Let call `NewDelegatedLockedAmount` is the `delegatedLockedAmount` when applying N slash

1. Case 1: Originally `DelegatedLockedAmount` > `lockedAmount` but when applying the slash amount the `NewDelegatedLockedAmount` < `lockedAmount` then
* When not applying slash `notBondedLockedAmout` will be 0
* When apply slash `notBondedLockedAmout` will be `lockedAmount` - `NewDelegatedLockedAmount` = a positive amount
2. Case 2: where originally `DelegatedLockedAmount` < `lockedAmount` when applying the slash amount the `NewDelegatedLockedAmount` < `lockedAmount` then
* When not applying slash `lockedAmount` - `DelegatedLockedAmount`
* When apply slash `notBondedLockedAmout` will be `lockedAmount` - `NewDelegatedLockedAmount` = `lockedAmount` - `(DelegatedLockedAmount - N)` = `lockedAmount` - `DelegatedLockedAmount` + N
3. Case 3: where originally `DelegatedLockedAmount` > `lockedAmount` when applying the slash amount still the `NewDelegatedLockedAmount` > `lockedAmount` then `notBondedLockedAmout` will be 0 applying slash or not
Comment on lines +121 to +129
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

Fix inconsistencies and improve case descriptions

There are inconsistencies in terminology and formatting of the cases.

Apply these changes:

  1. Fix spelling: notBondedLockedAmout → notBondedLockedAmount
  2. Standardize variable names: DelegatedLockedAmount → delegatedLockedAmount
  3. Improve case formatting for consistency
  4. Add proper code blocks for formulas

Would you like me to provide the complete diff for these changes?


In cases 1 and 2, `notBondedLockedAmount` decreases when not applying the slash, resulting in a higher `spendableAmount`.

Due to the nature of x/accounts, as other modules cannot assume certain account types exist so the handling of slashing event must be done internally within x/accounts's accounts. For lockup accounts, this would make the logic overcomplicated. Since these effects are only an edge case that affect a small number of users, so here we would accept the trade off for a simpler design. This design decision aligns with the legacy vesting account implementation.
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

Fix grammar and hyphenation in the conclusion

The concluding paragraph needs grammatical improvements and proper hyphenation.

Apply this change:

-Due to the nature of x/accounts, as other modules cannot assume certain account types exist so the handling of slashing event must be done internally within x/accounts's accounts. For lockup accounts, this would make the logic overcomplicated. Since these effects are only an edge case that affect a small number of users, so here we would accept the trade off for a simpler design. This design decision aligns with the legacy vesting account implementation.
+Due to the nature of x/accounts, where other modules cannot assume certain account types exist, the handling of slashing events must be done internally within x/accounts. For lockup accounts, this would make the logic overcomplicated. Since these effects only impact a small number of users, we accept the trade-off for a simpler design. This design decision aligns with the legacy vesting account implementation.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
Due to the nature of x/accounts, as other modules cannot assume certain account types exist so the handling of slashing event must be done internally within x/accounts's accounts. For lockup accounts, this would make the logic overcomplicated. Since these effects are only an edge case that affect a small number of users, so here we would accept the trade off for a simpler design. This design decision aligns with the legacy vesting account implementation.
Due to the nature of x/accounts, where other modules cannot assume certain account types exist, the handling of slashing events must be done internally within x/accounts. For lockup accounts, this would make the logic overcomplicated. Since these effects only impact a small number of users, we accept the trade-off for a simpler design. This design decision aligns with the legacy vesting account implementation.
🧰 Tools
🪛 LanguageTool

[uncategorized] ~133-~133: Use a comma before ‘so’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...annot assume certain account types exist so the handling of slashing event must be ...

(COMMA_COMPOUND_SENTENCE_2)

[style] ~133-~133: Specify a number, remove phrase, use “a few”, or use “some”
Context: ...fects are only an edge case that affect a small number of users, so here we would accept the trad...

(SMALL_NUMBER_OF)

[uncategorized] ~133-~133: When ‘trade-off’ is used as a noun or modifier, it needs to be hyphenated.
Context: ...r of users, so here we would accept the trade off for a simpler design. This design decis...

(VERB_NOUN_CONFUSION)


## Examples

### Simple
Expand Down Expand Up @@ -206,7 +230,7 @@ It can still, however, delegate.
BC = 2.5 + 5 = 7.5
```

Notice how we have an excess amount of `DV`.
Notice how we have an excess amount of `DV`. This is explained in [In An Event Of Slashing](#in-an-event-of-slashing)

### Periodic Lockup

Expand Down
Loading