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 2 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
27 changes: 26 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,30 @@ 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:

Spendable amount are calculated as
`spendableAmount` = `balance` - `notBondedLockedAmout`
Whereas `notBondedLockedAmout` = `lockedAmount` - `Min(LockedAmount, DelegatedLockedAmount)`

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

1. Case 1: where 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

In the 3 cases, case 1 and case 2 seen the `notBondedLockedAmout` decrease when not applying the slash, make the `spendableAmount` higher.

Due to the natural of x/accounts, as other modules cannot assume certain account types exist so the handling of slashing event would have to be done internally inside x/accounts's accounts which in the case of lockup account would make the logic over complicated. As the above effects are only an edge case that affect a small amount of users, so here we would accept the trade off for a simpler design. The same design intention is also present in the legacy vesting 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 and fix grammatical issues in the slashing documentation

The technical content is accurate, but the section needs improvements in clarity and grammar:

Apply these changes:

-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 base lockup stores `DelegatedLocking` by amount. When a validator that the lockup account is delegated to gets slashed, affecting the actual delegation amount, the `DelegatedLocking` will have an excess amount even if the user undelegates all delegated amounts. This excess amount affects the spendable amount as detailed below:

-Spendable amount are calculated as
-`spendableAmount` = `balance` - `notBondedLockedAmout` 
-Whereas `notBondedLockedAmout`  = `lockedAmount` - `Min(LockedAmount, DelegatedLockedAmount)`
+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`
-if the `notBondedLockedAmout` is positive then `spendableAmount` is less than the actual balance. Let call `NewDelegatedLockedAmount` is the `delegatedLockedAmount` when applying N slash
+As seen in the formula, `notBondedLockedAmount` can only be 0 or a positive value when `delegatedLockedAmount` < `lockedAmount`.
+If `notBondedLockedAmount` is positive, then `spendableAmount` is less than the actual balance. Let's define `newDelegatedLockedAmount` as the `delegatedLockedAmount` after applying N slashes.

-1. Case 1: where 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
+1. Case 1: Originally `delegatedLockedAmount` > `lockedAmount`, but after slashing, `newDelegatedLockedAmount` < `lockedAmount`:
+    * Before slashing: `notBondedLockedAmount = 0`
+    * After slashing: `notBondedLockedAmount = 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 
+2. Case 2: Originally `delegatedLockedAmount` < `lockedAmount`, and after slashing, `newDelegatedLockedAmount` < `lockedAmount`:
+    * Before slashing: `notBondedLockedAmount = lockedAmount - delegatedLockedAmount`
+    * After slashing: `notBondedLockedAmount = 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
+3. Case 3: Originally `delegatedLockedAmount` > `lockedAmount`, and after slashing, `newDelegatedLockedAmount` > `lockedAmount`:
+    * Both before and after slashing: `notBondedLockedAmount = 0`

-In the 3 cases, case 1 and case 2 seen the `notBondedLockedAmout` decrease when not applying the slash, make the `spendableAmount` higher.  
+In cases 1 and 2, `notBondedLockedAmount` decreases when not applying the slash, resulting in a higher `spendableAmount`.

-Due to the natural of x/accounts, as other modules cannot assume certain account types exist so the handling of slashing event would have to be done internally inside x/accounts's accounts which in the case of lockup account would make the logic over complicated. As the above effects are only an edge case that affect a small amount of users, so here we would accept the trade off for a simpler design. The same design intention is also present in the legacy vesting account.
+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
## 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:
Spendable amount are calculated as
`spendableAmount` = `balance` - `notBondedLockedAmout`
Whereas `notBondedLockedAmout` = `lockedAmount` - `Min(LockedAmount, DelegatedLockedAmount)`
As seen in the formula `notBondedLockedAmout` can only be 0 or a positive value when `DelegatedLockedAmount` < `LockedAmount`
if the `notBondedLockedAmout` is positive then `spendableAmount` is less than the actual balance. Let call `NewDelegatedLockedAmount` is the `delegatedLockedAmount` when applying N slash
1. Case 1: where 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
In the 3 cases, case 1 and case 2 seen the `notBondedLockedAmout` decrease when not applying the slash, make the `spendableAmount` higher.
Due to the natural of x/accounts, as other modules cannot assume certain account types exist so the handling of slashing event would have to be done internally inside x/accounts's accounts which in the case of lockup account would make the logic over complicated. As the above effects are only an edge case that affect a small amount of users, so here we would accept the trade off for a simpler design. The same design intention is also present in the legacy vesting account.
## In An Event Of Slashing
The base lockup stores `DelegatedLocking` by amount. When a validator that the lockup account is delegated to gets slashed, affecting the actual delegation amount, the `DelegatedLocking` will have an excess amount even if the user undelegates all delegated amounts. This excess amount affects the spendable amount as detailed below:
The spendable amount is calculated as:
🧰 Tools
🪛 LanguageTool

[grammar] ~114-~114: Consider using either the past participle “slashed” or the present participle “slashing” here.
Context: ... that the lockup account delegate to is slash which affect the actual delegation amou...

(BEEN_PART_AGREEMENT)

[style] ~114-~114: Consider removing “of” to be more concise
Context: ...n excess amount even if user undelegate all of the account delegated amount. This excess ...

(ALL_OF_THE)

[uncategorized] ~134-~134: 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 would ha...

(COMMA_COMPOUND_SENTENCE_2)

[grammar] ~134-~134: This is normally spelled as one word.
Context: ... of lockup account would make the logic over complicated. As the above effects are only an edge ...

(OVER_COMPOUNDS)

[uncategorized] ~134-~134: ‘Amount of’ should usually only be used with uncountable or mass nouns. Consider using “number” if this is not the case.
Context: ...e only an edge case that affect a small amount of users, so here we would accept the t...

(AMOUNTOF_TO_NUMBEROF)

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

(VERB_NOUN_CONFUSION)

sontrinh16 marked this conversation as resolved.
Show resolved Hide resolved

## Examples

### Simple
Expand Down Expand Up @@ -206,7 +231,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