Key Assignment Feature

app/consumer-democracy/export.go

@@ -49,7 +49,8 @@ func (app *App) ExportAppStateAndValidators(
 
 // prepare for fresh start at zero height
 // NOTE zero height genesis is a temporary feature which will be deprecated
-//      in favour of export at a block height
+//
+//	in favour of export at a block height
 func (app *App) prepForZeroHeightGenesis(ctx sdk.Context, jailAllowedAddrs []string) {
 	// applyAllowedAddrs := false
 

app/provider/export.go

@@ -50,7 +50,8 @@ func (app *App) ExportAppStateAndValidators(
 
 // prepare for fresh start at zero height
 // NOTE zero height genesis is a temporary feature which will be deprecated
-//      in favour of export at a block height
+//
+//	in favour of export at a block height
 func (app *App) prepForZeroHeightGenesis(ctx sdk.Context, jailAllowedAddrs []string) {
 	applyAllowedAddrs := false
 

docs/key-assignment/api.cfg

@@ -0,0 +1,11 @@
+CONSTANTS
+    STORAGE_CONSTANT = 2
+(*
+Could be improved by using model value symmetries.
+*)
+    PROVIDER_KEYS = {0, 1, 2}
+    CONSUMER_KEYS = {0, 1, 2, 3, 4, 5, 6, 7, 8}
+INIT Init
+NEXT Next
+INVARIANT Invariant
+

docs/key-assignment/api.tla

@@ -0,0 +1,178 @@
+---- MODULE api ----
+
+EXTENDS  Integers, Naturals, FiniteSets, Sequences, TLC
+
+CONSTANTS
+    STORAGE_CONSTANT,
+    PROVIDER_KEYS,
+    CONSUMER_KEYS
+
+VARIABLES
+    assignments,
+    providerValSets,
+    committedProviderVSCID,
+    committedConsumerVSCID,
+    maturedConsumerVSCID
+
+(***************************************************************************)
+(** Model ******************************************************************)
+(***************************************************************************)
+(***************************************************************************)
+
+(***************************************)
+(** State at genesis *******************)
+(***************************************)
+(***************************************)
+
+Init ==
+    \* Store the genesis assignment, and the current assignment
+    /\ assignments = [vscid \in 1..2 |-> [key \in PROVIDER_KEYS |-> key]]
+    \* One valset has been committed (genesis)
+    /\ \E valset \in SUBSET PROVIDER_KEYS: 
+       providerValSets = [vscid \in {1} |-> valset]
+    \* Genesis block is committed
+    /\ committedProviderVSCID = 1
+    \* on consumer too.
+    /\ committedConsumerVSCID = 1
+    \* Nothing has matured yet.
+    /\ maturedConsumerVSCID = 0
+
+(***************************************)
+(** Public transaction (tx) API ********)
+(***************************************)
+(***************************************)
+
+AssignKey == 
+    \E providerKey \in PROVIDER_KEYS, consumerKey \in CONSUMER_KEYS:
+    \* consumerKey is not in use
+    /\ ~(\E i \in DOMAIN assignments: \E k \in DOMAIN assignments[i] : assignments[i][k] = consumerKey)
+    \* Do assignment
+    /\ assignments' = [
+        assignments EXCEPT ![committedProviderVSCID + 1] = 
+        [@ EXCEPT ![providerKey] = consumerKey] ]
+    \* The rest...
+    /\ UNCHANGED << providerValSets, committedProviderVSCID, committedConsumerVSCID, maturedConsumerVSCID >>
+
+(***************************************)
+(** Internal implemenation API *********)
+(***************************************)
+(***************************************)
+
+ProviderEndAndCommitBlock ==
+    \E valset \in SUBSET PROVIDER_KEYS:
+    \* Create a new assignment entry
+    /\ assignments' = assignments @@ [vscid \in {committedProviderVSCID+2} |-> assignments[committedProviderVSCID]]
+    \* Get a new validator set from changes in voting power
+    /\ providerValSets' = providerValSets @@ [vscid \in {committedProviderVSCID+1} |-> valset]
+    \* Increment vscid
+    /\ committedProviderVSCID' = committedProviderVSCID + 1
+    \* The rest...
+    /\ UNCHANGED << committedConsumerVSCID, maturedConsumerVSCID >>
+
+ConsumerDeliverUpdates == 
+    \* Fast forward the consumer
+    \E vscid \in (committedConsumerVSCID + 1)..committedProviderVSCID:
+    committedConsumerVSCID' = vscid
+    \* The rest...
+    /\ UNCHANGED <<committedProviderVSCID, assignments, providerValSets, maturedConsumerVSCID >>
+
+ProviderDeliverMaturities == 
+    \* Fast forward the consumer maturities, and notify provider
+    \E vscid \in (maturedConsumerVSCID + 1)..committedConsumerVSCID:
+    /\ maturedConsumerVSCID' = vscid
+    /\ assignments' = [i \in {
+            j \in DOMAIN assignments : vscid < j \/ committedProviderVSCID <= j
+        } |-> assignments[i]]
+    \* The rest...
+    /\ UNCHANGED <<committedConsumerVSCID, committedProviderVSCID, providerValSets>>
+
+Next ==
+    \/ AssignKey
+    \/ ProviderEndAndCommitBlock
+    \/ ConsumerDeliverUpdates
+    \/ ProviderDeliverMaturities
+
+(***************************************************************************)
+(** Invariants and properties **********************************************)
+(***************************************************************************)
+(***************************************************************************)
+
+(***************************************)
+(** Public query API *******************)
+(***************************************)
+(***************************************)
+
+(*
+The current consumer key assigned to a provider key is defined and
+queryable.
+True by construction: 'how' not explicitly modelled.
+*)
+AssignmentIsDefined == 
+    \A k \in PROVIDER_KEYS:
+    LET ConsumerKey == assignments[committedProviderVSCID + 1][k]
+    IN TRUE
+
+(****************************************)
+(** Internal implementation properties **)
+(****************************************)
+(****************************************)
+
+(*
+The consumer validator set at committedConsumerVSCID
+is defined as the provider validator set at committedConsumerVSCID
+mapped through the assignment at committedConsumerVSCID.
+True by construction: 'how' not explicitly modelled.
+*)
+ConsumerValidatorSetIsDefined == 
+    LET
+    ConsumerValset == {assignments[committedConsumerVSCID][k] : k \in providerValSets[committedConsumerVSCID]}
+    IN TRUE
+
+(*
+For any unmatured consumer valset, it is always possible to retrieve a unique provider key
+for any consumer key in the set.
+*)
+UniqueReverseQueryResultIsDefined == 
+    \A i \in (maturedConsumerVSCID + 1)..committedConsumerVSCID : 
+    LET
+    \* The valset known to the consumer
+    ConsumerValset == {assignments[i][k] : k \in providerValSets[i]}
+    \* All the keys that are assigned to the consumerKey in stored assignments
+    Assigned(consumerKey) == {
+            providerKey \in PROVIDER_KEYS :
+            \E j \in DOMAIN assignments : assignments[j][providerKey] = consumerKey
+        }
+    \* The query for the providerKey is successful and the result is unique.
+    IN \A consumerKey \in ConsumerValset : Cardinality(Assigned(consumerKey)) = 1
+
+(*
+Storage cost grows linearly with committedProviderVSCID - maturedConsumerVSCID
+*)
+StorageIsBounded ==
+    Cardinality(DOMAIN(assignments)) <= STORAGE_CONSTANT * (1 + (committedProviderVSCID - maturedConsumerVSCID))
+
+
+(*Check that the spec is written correctly.*)
+Sanity == LET
+    Sanity0 == committedConsumerVSCID <= committedProviderVSCID
+    Sanity1 == maturedConsumerVSCID <= committedConsumerVSCID
+    Sanity2 == committedProviderVSCID \in DOMAIN assignments
+    Sanity3 == committedProviderVSCID + 1 \in DOMAIN assignments
+    Sanity4 == committedProviderVSCID \in DOMAIN providerValSets
+    IN
+    /\ Sanity0
+    /\ Sanity1
+    /\ Sanity2
+    /\ Sanity3
+    /\ Sanity4
+
+Invariant == 
+    /\ Sanity
+    /\ AssignmentIsDefined
+    /\ ConsumerValidatorSetIsDefined
+    /\ UniqueReverseQueryResultIsDefined
+    /\ StorageIsBounded
+
+(***************************************************************************)
+
+====

docs/key-assignment/design.md

@@ -0,0 +1,86 @@
+# KeyAssignment
+
+KeyAssignment is the name of the feature that allows validator operators to use different consensus keys for each consumer chain validator node that they operate.
+
+Validators can improve their security by using different consensus keys for each chain. That way, different teams in an organization can operate a subset (can be size 1) of the total number of consumer chains associated to a provider chain. If one key leaks the other keys will not be at risk. It is possible to change the keys at any time by submitting a transaction.
+
+## Overview
+
+The KeyAssignment feature is available via a provider chain API (transactions and queries). The provider chain validator operator submits an assignment transaction to the provider chain with a consumer chain ID and desired consensus key as parameters. The over-IBC protocol used by Interchain Security takes care of forwarding the assignment to the specified consumer chain. When the consumer chain receives the key, it will immediately start using it with tendermint.
+
+It is possible to start validating a consumer chain with the same key as used for the provider. This is the default behavior. It is also possible to specify another key to use when joining the validator set. Moreover it is possible to change the used key at any time, any multiple times, with some minor restrictions.
+
+## External API (High Level)
+
+**TXs**
+
+```go
+// Assign a new public consensus key to be used by a validator
+// on the provider when it signs transactions on the consumer chain.
+// The TX must be signed by the private key associated to the provider
+// validator address.
+//
+// The assignment can fail if the consumer consensus key is already
+// in use for the chain, currently, or in the recent past.
+AssignConsensusPublicKeyToConsumerChain(
+	ChainId                  string, // consumer chain
+	ProviderValidatorAddress string, // must sign TX
+	ConsumerConsensusPubKey  *types.Any
+)
+```
+
+**Queries**
+
+```go
+// Returns the last consumer key associated to the provider key and
+// the consumer chain by a call to AssignConsensusPublicKeyToConsumerChain.
+QueryConsumerChainValidatorKeyAssignment (
+	ChainId                  string, // consumer chain
+	ProviderValidatorAddress string, // validator address for the provider chain
+)
+```
+
+## Internal API (High Level)
+
+TODO: write this section
+
+## API (Details)
+
+The external API is specified in [api.tla](./api.tla). An 'internal' API is also specified. The external API supports the TXs and Queries listed above. The internal API documents the API that the implementation of KeyAssignment exposes for integration
+in the implementation of the wider system.
+
+## Implementation
+
+### Algorithm idea
+
+
+### System integration points
+
+
+## External properties
+
+KeyAssignment has some properties relevant to the external user:
+
+
+
+1. Validator Set Replication\
+   When the Interchain Security property [Validator Set Replication](https://github.com/cosmos/ibc/blob/main/spec/app/ics-028-cross-chain-validation/system_model_and_properties.md#system-properties) holds for an implementation without KeyAssignment, then the property holds when KeyAssignment is used.
+2. Slashable Consumer Misbehavior\
+   When the Interchain Security property [Slashable Consumer Misbehavior](https://github.com/cosmos/ibc/blob/main/spec/app/ics-028-cross-chain-validation/system_model_and_properties.md#system-properties) holds for an implementation without KeyAssignment, then the property holds when KeyAssignment is used.
+
+All Interchain Security properties still hold when KeyAssignment is used, the above are just the most relevant.
+
+Additionally
+
+3. When a `AssignConsensusPublicKeyToConsumerChain` operation succeeds for a given `(chainID, ProviderValidatorAddress, ConsumerConsensusPubKey)` tuple at block height `hp0`, and is not followed by a subsquent call for the same tuple before or during a height `hp1` (`hp0 <= hp1`), and at `hp1` a validator set update packet is committed at the provider chain, then at the next earliest height `hc2` on the consumer chain that the packet is received, the `ConsumerConsensusPubKey ` is passed as consensus key to tendermint. Thus tendermint will expect a signature from `ConsumerConsensusPubKey ` from height `hc2 + 1`.
+
+
+## Internal properties
+
+The internal properties section in [api.tla](./api.tla) specifies abstract but precise properties. In particular, at a high level:
+
+1. The consumer validator set is always defined as per the validator set replication property.
+2. It is always possible to lookup the provider consensus address, for a given consumer consensus public key, when the consumer has been sent that public key and that key is still liable for double signing or downtime slashing.
+3. The storage requirements are reasonable.
+
+Please see [api.tla](./api.tla) and [key_assignment_test.go::externalInvariants](../../x/ccv/provider/keeper/key_assignment_test.go) and [key_assignment.go::internalInvariants](../../x/ccv/provider/keeper/key_assignment.go) for precise formulations.

docs/quality_assurance.md

@@ -80,7 +80,7 @@ The main concern addressed in this section is the correctness of the provider ch
 | 4.01 | Liveness of undelegations <br> - unbonding delegation entries are eventually removed from `UnbondingDelegation` | `Scheduled` | `NA` | `Done` <br> [unbonding_test.go](../tests/e2e/unbonding_test.go) | `Done` | `Scheduled` | `NA` |
 | 4.02 | Liveness of redelegations <br> - redelegations entries are eventually removed from `Redelegations` | `Scheduled` | `NA` | `Scheduled` | `Scheduled` | `Scheduled` | `NA` |
 | 4.03 | Liveness of validator unbondings <br> - unbonding validators with no delegations are eventually removed from `Validators` | `Scheduled` | `NA` | `NA` | `Done` | `Scheduled` | `NA` |
-| 4.04 | Unbonding operations (undelegations, redelegations, validator unbondings) should eventually complete even if the CCV channel is never established (due to error) <br> - expected outcome: the channel initialization sub-protocol eventually times out, which leads to the consumer chain removal <br> - requires https://github.com/cosmos/interchain-security/issues/278 | `Scheduled` | `NA` | `Scheduled` | `Future work` | `Scheduled` | `Done` |
+| 4.04 | Unbonding operations (undelegations, redelegations, validator unbondings) should eventually complete even if the CCV channel is never established (due to error) <br> - expected outcome: the channel initialization sub-protocol eventually times out, which leads to the consumer chain removal | `Scheduled` | `NA` | `Done` [TestUndelegationDuringInit](../tests/e2e/unbonding_test.go#145) | `Future work` | `Scheduled` | `Done` |
 | 4.05 | Unbonding operations (undelegations, redelegations, validator unbondings) should eventually complete even if one of the clients expire <br> - expected outcome: the pending VSC packets eventually timeout, which leads to the consumer chain removal <br> - requires https://github.com/cosmos/interchain-security/issues/283 | `Scheduled` | `NA` | `Scheduled` | `Future work` | `Scheduled` | `NA` |
 | 4.06 | A validator cannot get slashed more than once for double signing, regardless of how many times it double signs on different chains (consumers or provider) | `Scheduled` | `NA` |`Done` <br> [TestHandleSlashPacketErrors](../tests/e2e/slashing_test.go#L317) | `Done` | `Scheduled` | `NA` |
 | 4.07 | A validator cannot get slashed multiple times for downtime on the same consumer chain without requesting to `Unjail` itself on the provider chain in between | `Scheduled` | `NA` | `Partial coverage` <br> [TestSendSlashPacket](../tests/e2e/slashing_test.go#L648) | `Partial coverage` | `Scheduled` | `NA` |

go.mod

@@ -4,7 +4,6 @@ go 1.18
 
 require (
 	github.com/cosmos/cosmos-sdk v0.45.2-0.20220901181011-06d4a64bf808
-	github.com/cosmos/ibc-go v1.2.2
 	github.com/cosmos/ibc-go/v3 v3.0.0-alpha1.0.20220210141024-fb2f0416254b
 	github.com/gogo/protobuf v1.3.3
 	github.com/golang/protobuf v1.5.2
@@ -135,4 +134,4 @@ replace (
 	github.com/cosmos/ibc-go/v3 => github.com/informalsystems/ibc-go/v3 v3.0.0-beta1.0.20220816140824-aba9c2f2b943
 	github.com/gogo/protobuf => github.com/regen-network/protobuf v1.3.3-alpha.regen.1
 	google.golang.org/grpc => google.golang.org/grpc v1.33.2
-)
+)

go.sum

@@ -243,7 +243,6 @@ github.com/cosmos/iavl v0.15.3/go.mod h1:OLjQiAQ4fGD2KDZooyJG9yz+p2ao2IAYSbke8mV
 github.com/cosmos/iavl v0.17.1/go.mod h1:7aisPZK8yCpQdy3PMvKeO+bhq1NwDjUwjzxwwROUxFk=
 github.com/cosmos/iavl v0.17.3 h1:s2N819a2olOmiauVa0WAhoIJq9EhSXE9HDBAoR9k+8Y=
 github.com/cosmos/iavl v0.17.3/go.mod h1:prJoErZFABYZGDHka1R6Oay4z9PrNeFFiMKHDAMOi4w=
-github.com/cosmos/ibc-go v1.2.2 h1:bs6TZ8Es1kycIu2AHlRZ9dzJ+mveqlLN/0sjWtRH88o=
 github.com/cosmos/ibc-go v1.2.2/go.mod h1:XmYjsRFOs6Q9Cz+CSsX21icNoH27vQKb3squgnCOCbs=
 github.com/cosmos/keyring v1.1.7-0.20210622111912-ef00f8ac3d76 h1:DdzS1m6o/pCqeZ8VOAit/gyATedRgjvkVI+UCrLpyuU=
 github.com/cosmos/keyring v1.1.7-0.20210622111912-ef00f8ac3d76/go.mod h1:0mkLWIoZuQ7uBoospo5Q9zIpqq6rYCPJDSUdeCJvPM8=

proto/interchain_security/ccv/consumer/v1/consumer.proto

@@ -47,6 +47,11 @@ message Params {
   // This param is a part of the cosmos sdk staking module. In the case of 
   // a ccv enabled consumer chain, the ccv module acts as the staking module.
   int64 historical_entries = 8;
+
+  // Unbonding period for the consumer,
+  // which should be smaller than that of the provider in general.
+  google.protobuf.Duration unbonding_period = 9
+      [(gogoproto.nullable) = false, (gogoproto.stdduration) = true];
 }
 
 // LastTransmissionBlockHeight is the last time validator holding