ICS28: Reflect deferred unbonding completion in spec

spec/app/ics-028-cross-chain-validation/README.md

@@ -6,7 +6,7 @@ category: IBC/APP
 requires: 25, 26, 20
 author: Marius Poke <[email protected]>, Aditya Sripal <[email protected]>, Jovan Komatovic <[email protected]>, Cezara Dragoi <[email protected]>, Josef Widder <[email protected]>
 created: 2022-06-27
-modified: 2022-08-03
+modified: 2022-08-29
 ---
 
 <!-- omit in toc -->
@@ -55,6 +55,8 @@ Jun 27, 2022 - Draft written
 
 Aug 3, 2022 - Revision of *Bond-Based Consumer Voting Power* property
 
+Aug 29, 2022 - Notify Staking module of matured unbondings in `EndBlock()`
+
 ## Copyright
 
 All content herein is licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0).

spec/app/ics-028-cross-chain-validation/data_structures.md

@@ -209,6 +209,8 @@ This section describes the internal state of the CCV module. For simplicity, the
   It enables the provider CCV module to match a `VSCMaturedPacket{vscId}`, received from a consumer chain with `chainId`, with the corresponding unbonding operations. 
   As a result, `chainId` can be removed from the list of consumer chains that are still unbonding these operations. 
   For more details see how received `VSCMaturedPacket`s [are handled](#ccv-pcf-rcvmat1).
+- `maturedUnbondingOps: [uint64]` is a list of IDs of matured unbonding operations (from the perspective of the consumer chains), for which notifications can be sent to the Staking module (see `stakingKeeper.UnbondingCanComplete`). 
+  Note that `maturedUnbondingOps` is emptied at the end of each block.
 - `downtimeSlashRequests: Map<string, [string]>` is a mapping from `chainId`s to lists of validator addresses, 
   i.e., `downtimeSlashRequests[chainId]` contains all the validator addresses for which the provider chain received slash requests for downtime from the consumer chain with `chainId`.
 

spec/app/ics-028-cross-chain-validation/methods.md

@@ -932,8 +932,8 @@ function StopConsumerChain(chainId: string, lockUnbonding: Bool) {
       unbondingOps[id].unbondingChainIds.Remove(chainId)
       // if the unbonding operation has unbonded on all consumer chains
       if unbondingOps[id].unbondingChainIds.IsEmpty() {
-        // notify the Staking module that the unbonding can complete
-        stakingKeeper.UnbondingCanComplete(id)
+        // append the id of the unbonding to maturedUnbondingOps
+        maturedUnbondingOps.Append(id)
         // remove unbonding operation
         unbondingOps.Remove(id)
       }
@@ -966,8 +966,8 @@ function StopConsumerChain(chainId: string, lockUnbonding: Bool) {
     - if `lockUnbonding == false`, then 
       - `chainId` is removed from all outstanding unbonding operations;
       -  if an outstanding unbonding operation has matured on all consumer chains, 
-        - the `UnbondingCanComplete()` method of the Staking module is invoked;
-        - the unbonding operation is removed from `unbondingOps`;
+        - the matured unbonding operation is added to `maturedUnbondingOps`;
+        - the matured unbonding operation is removed from `unbondingOps`;
       - all the entries with `chainId` are removed from the `vscToUnbondingOps` mapping.
 - **Error Condition**
   - None
@@ -1154,11 +1154,17 @@ The *validator set update* sub-protocol enables the provider chain
 ```typescript
 // PCF: Provider Chain Function
 function EndBlockVSU() {
+  // notify the Staking module to complete all matured unbondings
+  for id IN maturedUnbondingOps {
+    stakingKeeper.UnbondingCanComplete(id)
+  }
+  maturedUnbondingOps.RemoveAll()
+
   // get list of validator updates from the provider Staking module
   valUpdates = stakingKeeper.GetValidatorUpdates()
 
   // iterate over all consumer chains registered with this provider chain
-  foreach chainId in chainToClient.Keys() {
+  foreach chainId IN chainToClient.Keys() {
     // check whether there are changes in the validator set;
     // note that this also entails unbonding operations 
     // w/o changes in the voting power of the validators in the validator set
@@ -1207,6 +1213,8 @@ function EndBlockVSU() {
 - **Precondition**
   - True. 
 - **Postcondition**
+  - For every matured unbonding operation in `maturedUnbondingOps`, the Staking module is notified that the unbonding can complete.
+  - All unbonding operation in `maturedUnbondingOps` are removed.
   - A list of validator updates `valUpdates` is obtained from the provider Staking module.
   - For every consumer chain with `chainId`
     - If either `valUpdates` is not empty or there were unbonding operations initiated during this block, then 
@@ -1289,8 +1297,8 @@ function onRecvVSCMaturedPacket(packet: Packet): bytes {
     op.unbondingChainIds.Remove(chainId)
     // if the unbonding operation has unbonded on all consumer chains
     if op.unbondingChainIds.IsEmpty() {
-      // notify the Staking module that the unbonding can complete
-      stakingKeeper.UnbondingCanComplete(op.id)
+      // append the id of the unbonding to maturedUnbondingOps
+      maturedUnbondingOps.Append(op.id)
       // remove unbonding operation
       unbondingOps.Remove(op.id)
     }
@@ -1313,8 +1321,8 @@ function onRecvVSCMaturedPacket(packet: Packet): bytes {
   - For each unbonding operation `op` returned by `GetUnbondingsFromVSC(chainId, packet.data.id)`
     - `chainId` is removed from `op.unbondingChainIds`;
     - if `op.unbondingChainIds` is empty,
-      - the `UnbondingCanComplete()` method of the Staking module is invoked;
-      - the entry `op` is removed from `unbondingOps`.
+      - `op.id` is added to `maturedUnbondingOps`;
+      - `op.id` is removed from `unbondingOps`.
   - `(chainId, vscId)` is removed from `vscToUnbondingOps`.
   - A successful acknowledgment is returned.
 - **Error Condition**