Cosmos-sdk: Add document about how Unbonding works and why its crucial for PoS systems

[jackzampolin]

This is not described anywhere and per @cwgoes is important to understanding the system.

[cwgoes]

Specifically, we should discuss the security/economic model of the unbonding period & slashing (as opposed to the implementation, which is documented in the SDK spec).

[kidinamoto01]

should we put unbonding period in genesis?

[jackzampolin]

@kidinamoto01 That is a great question for the fourm: https://forum.cosmos.network

[ValarDragon]

@kidinamoto01 I believe the plan is to include all parameters that can be set by governance with _Parameter Change Proposals_ in genesis. That will include the unbonding period for example.

[cwgoes]

This should include https://github.com/cosmos/cosmos-sdk/issues/1440#issuecomment-414864544.

[cwgoes]

Addressing this in the upcoming staking/slashing spec/code reconciliation.

[rigelrozanski]

I think this type of documentation doesn't necessarily belong in the _spec_ per say, more in explanatory documentation sections

[cwgoes]

Hmm maybe, I guess it's a question of terminology, I think we should have a "design spec" and a "implementation spec" (mostly at the moment we just have the latter).

[cwgoes]

I am still very interested in doing this and I think we should formalize Cosmos BPoS into a paper.

Let's plan to discuss further post-launch.

[rigelrozanski]

@cwgoes - it's not my preference, but I could see the appeal to having much of our documentation organized in papers... maybe an explicit papers folder could be good. The problem I see with papers is the inability for updating the original work... I see standard documentation as dynamic where as papers static (you can publish addendums of course but it's not the same). Additionally, papers are usually "one-offs" so much of the introduction material for instance would be duplicate across papers, which is annoying for reference documentation, but great for publication purposes

I think that papers should exist in compliment to having a nice clean markdown breakdown of everything. But I don't see the problem of having both!

CC @ValarDragon

[cwgoes]

Closing in favor of https://github.com/cosmos/ics/issues/89, this seems more suited for that repo now.