[Utility] Introduce an unbonding period after an actor unstakes

[Olshansk]

Objective

Design & implement a framework of how to handle on-chain Unbonding after an actor submits a valid Unstake transaction.

Origin Documents

• Cosmos SDK documentation on unbonding
• Cosmos explanation of unbonding in the context of validators
• Morse (pocket-core) has a parameter called UnstakingTime which can be found here
• Unstaking has been discussed on the Pocket Forums as can be found here

Goals

• Unbonding definition: a state during which an actor operates normally, after unstaking, before their escrowed stake is returned and they are removed as active actors
• At a minimum, have parity with unbonding periods from Morse
• Evaluate options for how on-chain actor unbonding could be implemented
• Design, document and implement unbonding of Applications, Suppliers & Gateways
• Create a pattern reusable for all actors

Deliverables

IMPORTANT NOTE TO THE OWNER: The deliverables below are not a complete list of everything that needs to be done, but rather a starting point to help. The research, which is part of the deliverables, should drive most of the design decisions.

1. Research
   • [ ] Put together a reference doc with bullet points, links, highlights, learnings capturing the research below(< 1 page total
   • Other Projects
     • [ ] Investigate how actor (e.g. validator) unbonding is designed and implemented in the Cosmos SDK
     • [ ] Investigate how at least one other project does (non-validator) actor unbonding in the Cosmos ecosystem
   • Morse
     • [ ] Investigate how actor unbonding currently works in Morse
2. Before implementation
   • [ ] Prepare a 1-pager “mini spec” notion / docs / markdown and get feedback & review before kicking off the implementation
3. Implementation requirements
   • [ ] Unbonding should finish automatically N blocks from the moment the actor submits the unstaking transaction
   • [ ] N should have a unique governance parameter for every actor: Application, Supplier, Gateway
   • [ ] Escrowed funds are returned to the actor only AFTER the unbonding process is complete
4. During implementation
   • [ ] Separate PRs per actor after the foundation is in place
   • [ ] Add unit / integration tests
   • [ ] Add at least 1 E2E test (per actor)
   • [ ] Make target to trigger the E2E test
5. After implementation
   • [ ] Add a new page in docusaurus that explains how the implemented mechanism works

Estimated Days of Work

5 days

Disclaimer: This is the total projected number of estimated hours to completion & merge. The owner of this tickets is expected to use this GitHub issue to communicate with the core protocol team along the way, with update & feedback for each deliverable throughout the duration of this work._

---

Creator: @olshansk Co-Owners: @moatus

[Olshansk]

@moatus Could you review the requirements for unstaking here. I'm thinking of mounting out the engineering work for it.

[Olshansk]

With some guidance from @facundomedica, here is the way to go

In that case I don't think we have a solution that would work "out of the box". You could achieve something like that with endblock or x/epochs, both solutions being pretty similar, main difference being that with x/epochs you can "schedule" the process to happen every certain amount of time. Most likely you'll have an unbonding queue so on endblock/epochEnd you iterate through them and release any that its unbonding time has expired. You might also want to add some limits to this kind of processing, so you process up to X unbonds per epoch/endblock. Otherwise you might get timeouts.

After looking through [1], this is EXACTLY what we should be using for this.

[1] https://github.com/cosmos/cosmos-sdk/tree/main/x/epochs

[Olshansk]

Please note that the documentation is outdated on their website right now: https://github.com/cosmos/cosmos-sdk/issues/20651

[Olshansk]

@red-0ne Please make sure to take a look at the notes & comments. We should tackle this in the next iteration.

[Olshansk]

Cross-referencing this comment for the most up to date documentation [2]

[1] https://github.com/cosmos/cosmos-sdk/issues/20651#issuecomment-2179515541 [2] https://docs.cosmos.network/main/build/modules/epochs