Cosmos-sdk: Distinguish "delegate"/"bond" & "Jail" more clearly in CLI and docs

[rigelrozanski]

Edit:

I think there is good points that we should be using "delegate" and "bond" to distinguish the overloading of language in this original issue as such:

action items

• [ ] change CLI language and command to say "undelegate" to be more correct
• [ ] change the docs to reflect this new distinction in language

CC @faboweb @jbibla @zramsay

---

Just realized that the word bond is overloaded to mean:

1. The tokens are at stake, because they contribute to voting power in tendermint OR are in the unbonding process
2. The tokens are associated with a validator, which may OR may not be a part of the bonded-validator set (could be totally unbonded)

I think we should continue to use the term "unbond" for (1.) but probably come up with some new term to describe (2.)

Thoughts?
"in-trust" - lawyers use "held in trust"
"in-non-trust" lawl
"glued"
"held"

CC: @ValarDragon @alexanderbez @cwgoes

[gamarin2]

Why not "delegated"?

You tokens can be

• Delegated and unbonded
• Delegated and bonded

[alexanderbez]

Would that get confusing as as the "delegated" tokens could also be at stake (bonded-validator set)?

[rigelrozanski]

@gamarin2 oh of course that makes so much sense - obviously the most correct term. This just means that we should be saying undelegate in the CLI instead of unbond - which could mean, in reality that when you undelegate you may also be unbonding but only if your delegation was to a bonded validator.

@alexanderbez I think that it makes sense? as per mentioned delegated tokens which are bonded (aka at stake) is totally intuitive (to me) - To make things simpler - I think that we can just talk about "bonded" or "unbonding" tokens without needing to mention that they're delegated - this is because all bonded/unbonding tokens MUST be delegated per how DPOS is specified (this includes the validators self delegation) -> it's only when the tokens are in the unbonded state which we need to specify further whether or not they're delegated

[jbibla]

i'm having a hard time following this proposal.

@rigelrozanski are you proposing for (verbs):

• delegate as opposed to bond and
• undelegate as opposed to unbond?

and therefore as @gamarin2 has stated (adjectives):

• delegated and unbonded but also
• delegated and bonded

and if so - how does this differ from current usage?

[alexanderbez]

Thanks @rigelrozanski that cleared up things for me.

[gamarin2]

Also with this new terminology, do we still need to use revoked and unrevoke?

• A revoked validator is just unbonding. Then it becomes unbonded.
• Unrevoke is just rebond

Am I missing something @rigelrozanski ?

[rigelrozanski]

@gamarin2

A revoked validator is just unbonding. Then it becomes unbonded.

partially correct, a revoked validator always becomes unbonding then unbonded, however a validator could also begin unbonding without being revoked, this situation arises when a new validator with higher voting power joins the validator set and kicks out a validator, this kicked out validator will begin unbonding

Unrevoke is just rebond

incorrect, unrevoke just means you're now allowed to be bonded, if you're nolonger in the top 100 you will not be bonded, you will remain in your unbonding or unbonded state.

---

@jbibla

are you proposing for (verbs):
delegate as opposed to bond and

no, we already use the word delegate - delegation and bonding are to different things, you delegate to validators which may or may not be bonded. Your tokens enter whichever state that validator is in when you delegate to them

undelegate as opposed to unbond?

YES, unbond is overloaded, a delegator _undelegates_ tokens from the validator, which, depending on the state of the validator, may be moving the tokens from a bonded state to an unbonding state, if the validator is already unbonded, then the tokens which not change state, they will simply be moved from the validator account to the delegators wallet.

Does that clear things up for you?

[gamarin2]

@rigelrozanski

partially correct, a revoked validator always becomes unbonding then unbonded, however a validator could also begin unbonding without being revoked, this situation arises when a new validator with higher voting power joins the validator set and kicks out a validator, this kicked out validator will being to unbond

Sure, but it does not mean we need a different term.

incorrect, unrevoke just means you're now allowed to be bonded, if you're nolonger in the top 100 you will not be bonded, you will remain in your unbonding or unbonded state.

So if we remove revoke, maybe we can rename unrevoke to attempt-rebond ?

[rigelrozanski]

totally disagree, they are two distinct concepts which need to be explained with unique terms. I'm positive we can't remove the concept of revoke based on all the distinctions I just explained.

[cwgoes]

Note that we're renaming the "revoked" state to "jailed" and updating the CLI appropriately - https://github.com/cosmos/cosmos-sdk/issues/1305#issuecomment-411356706.

@gamarin2 Does that help clarify? They are distinct states, logically:

• A validator A is bonded if and only if
  
  
  
  • A is not jailed
  
  
  • A is in the top n (100 for the Cosmos Hub) validators, by delegated Atoms, who are not jailed
  
  

Bonded isn't a state that a validator chooses to enter or leave (directly), it's simply determined each block by the staking logic and often will be updated by other users' transactions (which change how much delegated stake other validators have).

I don't think attempt-rebond is prudent since it confuses the action taking place - either the validator will be bonded upon leaving jail or it won't, there is no "attempt" - trying again won't do anything unless other validators have changed state.

[jackzampolin]

Going to close this issue as mainly addressed. If anyone wants to reopen it please add a list of actionable items.