Skip to content

Commit

Permalink
docs(staking): add cancel-unbond delegations spec (#11473)
Browse files Browse the repository at this point in the history
## Description

Closes: #XXXX

related to #10885 



---

### Author Checklist

*All items are required. Please add a note to the item if the item is not applicable and
please add links to any relevant follow up issues.*

I have...

- [ ] included the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title
- [ ] added `!` to the type prefix if API or client breaking change
- [ ] targeted the correct branch (see [PR Targeting](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#pr-targeting))
- [ ] provided a link to the relevant issue or specification
- [ ] followed the guidelines for [building modules](https://github.com/cosmos/cosmos-sdk/blob/master/docs/building-modules)
- [ ] included the necessary unit and integration [tests](https://github.com/cosmos/cosmos-sdk/blob/master/CONTRIBUTING.md#testing)
- [ ] added a changelog entry to `CHANGELOG.md`
- [ ] included comments for [documenting Go code](https://blog.golang.org/godoc)
- [ ] updated the relevant documentation or specification
- [ ] reviewed "Files changed" and left comments if necessary
- [ ] confirmed all CI checks have passed

### Reviewers Checklist

*All items are required. Please add a note if the item is not applicable and please add
your handle next to the items reviewed if you only reviewed selected items.*

I have...

- [ ] confirmed the correct [type prefix](https://github.com/commitizen/conventional-commit-types/blob/v3.0.0/index.json) in the PR title
- [ ] confirmed `!` in the type prefix if API or client breaking change
- [ ] confirmed all author checklist items have been addressed 
- [ ] reviewed state machine logic
- [ ] reviewed API design and naming
- [ ] reviewed documentation is accurate
- [ ] reviewed tests and test coverage
- [ ] manually tested (if applicable)
  • Loading branch information
gsk967 authored Apr 7, 2022
1 parent 8800d2e commit feb9d93
Show file tree
Hide file tree
Showing 6 changed files with 54 additions and 1 deletion.
2 changes: 1 addition & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -264,7 +264,7 @@ Ref: https://keepachangelog.com/en/1.0.0/
* [\#11011](https://github.com/cosmos/cosmos-sdk/pull/11011) Remove burning of deposits when qourum is not reached on a governance proposal and when the deposit is not fully met.
* [\#11019](https://github.com/cosmos/cosmos-sdk/pull/11019) Add `MsgCreatePermanentLockedAccount` and CLI method for creating permanent locked account
* (x/staking) [\#10885] (https://github.com/cosmos/cosmos-sdk/pull/10885) Add new `CancelUnbondingDelegation`
transaction to `x/staking` module. Delegators can now cancel unbonding delegation entry and re-delegate back to validator.
transaction to `x/staking` module. Delegators can now cancel unbonding delegation entry and delegate back to validator.
* (x/feegrant) [\#10830](https://github.com/cosmos/cosmos-sdk/pull/10830) Expired allowances will be pruned from state.
* (x/authz,x/feegrant) [\#11214](https://github.com/cosmos/cosmos-sdk/pull/11214) Fix Amino JSON encoding of authz and feegrant Msgs to be consistent with other modules.
* (authz)[\#11060](https://github.com/cosmos/cosmos-sdk/pull/11060) Support grant with no expire time.
Expand Down
6 changes: 6 additions & 0 deletions x/staking/spec/02_state_transitions.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,12 @@ Delegation may be called.
shares from the `BondedPool` to the `NotBondedPool` `ModuleAccount`
* remove the validator if it is unbonded and there are no more delegation shares.

### Cancel an `UnbondingDelegation` Entry
When a `cancel unbond delegation` occurs both the `validator`, the `delegation` and an `UnbondingDelegationQueue` state will be updated.
* if cancel unbonding delegation amount equals to the `UnbondingDelegation` entry `balance`, then the `UnbondingDelegation` entry deleted from `UnbondingDelegationQueue`.
* if the `cancel unbonding delegation amount is less than the `UnbondingDelegation` entry balance, then the `UnbondingDelegation` entry will be updated with new balance in the `UnbondingDelegationQueue`.
* cancel `amount` is [Delegated](02_state_transitions.md#delegations) back to the original `validator`.

### Complete Unbonding

For undelegations which do not complete immediately, the following operations
Expand Down
21 changes: 21 additions & 0 deletions x/staking/spec/03_messages.md
Original file line number Diff line number Diff line change
Expand Up @@ -116,6 +116,27 @@ When this message is processed the following actions occur:

![Unbond sequence](../../../docs/uml/svg/unbond_sequence.svg)

## MsgCancelUnbondingDelegation
The `MsgCancelUnbondingDelegation` message allows delegators to cancel the `unbondingDelegation` entry and deleagate back to a previous validator.

+++ https://github.com/cosmos/cosmos-sdk/blob/28243eb41c16ecfc95631ac2bb266dd28ed5c317/proto/cosmos/staking/v1beta1/tx.proto#L36-L38

+++ https://github.com/cosmos/cosmos-sdk/blob/28243eb41c16ecfc95631ac2bb266dd28ed5c317/proto/cosmos/staking/v1beta1/tx.proto#L144-L154

+++ https://github.com/cosmos/cosmos-sdk/blob/28243eb41c16ecfc95631ac2bb266dd28ed5c317/proto/cosmos/staking/v1beta1/tx.proto#L156-L157


This message is expected to fail if:
* the `unbondingDelegation` entry is already processed.
* the `cancel unbonding delegation` amount is greater than the `unbondingDelegation` entry balance.
* the `cancel unbonding delegation` height doesn't exists in the `unbondingDelegationQueue` of the delegator.

When this message is processed the following actions occur:
* if the `unbondingDelegation` Entry balance is zero
* in this condition `unbondingDelegation` entry will be removed from `unbondingDelegationQueue`.
* otherwise `unbondingDelegationQueue` will be updated with new `unbondingDelegation` entry balance and initial balance
* the validator's `DelegatorShares` and the delegation's `Shares` are both increased by the message `Amount`.

## MsgBeginRedelegate

The redelegation command allows delegators to instantly switch validators. Once
Expand Down
12 changes: 12 additions & 0 deletions x/staking/spec/07_events.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,18 @@ The staking module emits the following events:

* [0] Time is formatted in the RFC3339 standard

### MsgCancelUnbondingDelegation

| Type | Attribute Key | Attribute Value |
| ----------------------------- | ------------------ | ------------------------------------|
| cancel_unbonding_delegation | validator | {validatorAddress} |
| cancel_unbonding_delegation | delegator | {delegatorAddress} |
| cancel_unbonding_delegation | amount | {cancelUnbondingDelegationAmount} |
| cancel_unbonding_delegation | creation_height | {unbondingCreationHeight} |
| message | module | staking |
| message | action | cancel_unbond |
| message | sender | {senderAddress} |

### MsgBeginRedelegate

| Type | Attribute Key | Attribute Value |
Expand Down
13 changes: 13 additions & 0 deletions x/staking/spec/09_client.md
Original file line number Diff line number Diff line change
Expand Up @@ -712,6 +712,19 @@ Example:
```bash
simd tx staking unbond cosmosvaloper1gghjut3ccd8ay0zduzj64hwre2fxs9ldmqhffj 100stake --from mykey
```
#### cancel unbond
The command `cancel-unbond` allow users to cancel the unbonding delegation entry and delegate back to the original validator.

Usage:
```bash
simd tx staking cancel-unbond [validator-addr] [amount] [creation-height]
```

Example:
```bash
simd tx staking cancel-unbond cosmosvaloper1gghjut3ccd8ay0zduzj64hwre2fxs9ldmqhffj 100stake 123123 --from mykey
```


## gRPC

Expand Down
1 change: 1 addition & 0 deletions x/staking/spec/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@ network.
* [MsgEditValidator](03_messages.md#msgeditvalidator)
* [MsgDelegate](03_messages.md#msgdelegate)
* [MsgUndelegate](03_messages.md#msgundelegate)
* [MsgCancelUnbondingDelegation](03_messages.md#msgcancelunbondingdelegation)
* [MsgBeginRedelegate](03_messages.md#msgbeginredelegate)
4. **[Begin-Block](04_begin_block.md)**
* [Historical Info Tracking](04_begin_block.md#historical-info-tracking)
Expand Down

0 comments on commit feb9d93

Please sign in to comment.