From feb9d93d4d607f095ec4494b1e6579ece391f716 Mon Sep 17 00:00:00 2001 From: Sai Kumar <17549398+gsk967@users.noreply.github.com> Date: Thu, 7 Apr 2022 18:09:27 +0530 Subject: [PATCH] docs(staking): add `cancel-unbond` delegations spec (#11473) ## 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) --- CHANGELOG.md | 2 +- x/staking/spec/02_state_transitions.md | 6 ++++++ x/staking/spec/03_messages.md | 21 +++++++++++++++++++++ x/staking/spec/07_events.md | 12 ++++++++++++ x/staking/spec/09_client.md | 13 +++++++++++++ x/staking/spec/README.md | 1 + 6 files changed, 54 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 98eb4007ec..0c52b9013f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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. diff --git a/x/staking/spec/02_state_transitions.md b/x/staking/spec/02_state_transitions.md index 1eda63bc8c..9e9efffaea 100644 --- a/x/staking/spec/02_state_transitions.md +++ b/x/staking/spec/02_state_transitions.md @@ -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 diff --git a/x/staking/spec/03_messages.md b/x/staking/spec/03_messages.md index 27c307b249..a9ef8d05a9 100644 --- a/x/staking/spec/03_messages.md +++ b/x/staking/spec/03_messages.md @@ -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 diff --git a/x/staking/spec/07_events.md b/x/staking/spec/07_events.md index 3f9203033c..eeeb84c4b9 100644 --- a/x/staking/spec/07_events.md +++ b/x/staking/spec/07_events.md @@ -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 | diff --git a/x/staking/spec/09_client.md b/x/staking/spec/09_client.md index 608705352c..0c3383d014 100644 --- a/x/staking/spec/09_client.md +++ b/x/staking/spec/09_client.md @@ -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 diff --git a/x/staking/spec/README.md b/x/staking/spec/README.md index 688fd810af..08c21234e4 100644 --- a/x/staking/spec/README.md +++ b/x/staking/spec/README.md @@ -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)