Skip to content

Commit

Permalink
Start addings docs
Browse files Browse the repository at this point in the history
  • Loading branch information
Daniel committed Oct 25, 2022
1 parent 22bc310 commit db04c2d
Show file tree
Hide file tree
Showing 3 changed files with 396 additions and 0 deletions.
112 changes: 112 additions & 0 deletions docs/keymap/README.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
# KeyMap

KeyMap 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 KeyMap feature is available via a provider chain API (transactions and queries). The provider chain validator operator submits a mapping transaction to the provider chain with a consumer chain ID and desired consensus key as parameters. The IBC protocol used by Interchain Security takes care of forwarding the mapping 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. 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.

## API (High level)

**Writes**

```go
// Associates a new consumer key as consensus key on the consumer chain
// for the validator on the provider chain associated to the provider key.
SetConsumerKey(providerKey, consumerChainID, consumerKey) {
}
```

**Reads**


```go
// Returns the last consumerKey associated to the provider key and
// the consumer chain by a call to SetConsumerKey.
GetConsumerKey(providerKey, consumerChainID) {
}
```

```go
// Returns the last providerKey associated to consumerKey and the consumer
// chain by a call to SetConsumerKey.
GetProviderKey(consumerKey, consumerChainID) {
}
```

## API (Details)

**Writes**

```go
// Attemps to associate a new consumer key consumerKey on the consumer chain
// specified by consumerChainID to the validator on the provider chain
// specified by providerKey.
// If the attempt succeeds, the consumer chain will start consumerKey as
// consensus key from the earliest block at which it receives the update
// via IBC.
// The attempt can fail if any of the arguments are invalid, if either chain
// or the IBC connection is faulty.
// The attempt can additionally fail if the key consumerKey was already used
// as for a mapping with the KeyMap feature too recently in the past. This is
// to prevent attacks. In particular, once a key is used in a KeyMap association
// that key is no longer useable for another association until the first
// association is cancelled, and an acknowledgement of the cancellation is
// received from the consumer chain and processed on the provider chain.
SetConsumerKey(providerKey, consumerChainID, consumerKey) {
// TODO: signatures, types
}
```

**Reads**


```go
// Returns the last consumerKey associated to the provider key and
// the consumer chain by a call to SetConsumerKey.
// TODO: more detail needed?
GetConsumerKey(providerKey, consumerChainID) {
}
```

```go
// Returns the last providerKey associated to consumerKey and the consumer
// chain by a call to SetConsumerKey.
// TODO: more detail needed?
GetProviderKey(consumerKey, consumerChainID) {
}
```

### External Properties - Interchain Security

KeyMap 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 KeyMap, then the property holds when KeyMap 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 KeyMap, then the property holds when KeyMap is used.

In fact, all Interchain Security properties still hold when KeyMap is used, the above are just the most relevant.

### External Properties - timeliness

When a call to `SetConsumerKey` succeeds for a given `(providerKey, consumerChainID)` 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 `consumerKey` is passed as consensus key to tendermint. Thus tendermint will expect a signature from `consumerKey` from height `hc2 + 1`.

TODO: check, test, correct, guarantee and formalize this.

### Internal properties

The KeyMap implementation satisfies a number of internal properties, which are used to guarantee the external properties. These are only relevant to system internals. They are, briefly:

1. Validator Set Replication\
'All consumer validator sets are some earlier provider validator set'
2. Queries\
'It is always possible to query the provider key for a given consumer key, when the consumer can still make slash requests'
3. Pruning\
'When the pruning method is used correctly, the internal state of the data structure does not grow unboundedly'

Details can be found in x/ccv/provider/keeper/keymap_core_test.go. TODO: link?
284 changes: 284 additions & 0 deletions docs/keymap/diagrams/dummy.excalidraw
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,284 @@
{
"type": "excalidraw",
"version": 2,
"source": "https://excalidraw.com",
"elements": [
{
"id": "jnw1YontONnXqPoVC-D_5",
"type": "rectangle",
"x": -154.92880673737443,
"y": 3528.5756797513577,
"width": 921.0283500395554,
"height": 472.3939033586794,
"angle": 0,
"strokeColor": "#000000",
"backgroundColor": "transparent",
"fillStyle": "solid",
"strokeWidth": 2,
"strokeStyle": "solid",
"roughness": 2,
"opacity": 100,
"groupIds": [],
"strokeSharpness": "sharp",
"seed": 1440774261,
"version": 74,
"versionNonce": 1312719803,
"isDeleted": false,
"boundElements": null,
"updated": 1665008710945,
"link": null,
"locked": false
},
{
"id": "-lLVqybaoV_sFz4FYz-Q1",
"type": "freedraw",
"x": 127.38944319887776,
"y": 3784.339242812418,
"width": 486.37005434562263,
"height": 216.6303402976191,
"angle": 0,
"strokeColor": "#000000",
"backgroundColor": "transparent",
"fillStyle": "solid",
"strokeWidth": 2,
"strokeStyle": "solid",
"roughness": 2,
"opacity": 100,
"groupIds": [],
"strokeSharpness": "round",
"seed": 497609077,
"version": 54,
"versionNonce": 1332451483,
"isDeleted": false,
"boundElements": null,
"updated": 1665008713037,
"link": null,
"locked": false,
"points": [
[
0,
0
],
[
-5.590460394777324,
-1.3976150986945868
],
[
-9.783305690860288,
-4.192845296082851
],
[
-12.578535888248894,
-11.18092078955442
],
[
-12.578535888248894,
-16.771381184331858
],
[
-8.385690592165929,
-26.554686875192147
],
[
-1.3976150986943594,
-39.133222763441154
],
[
8.385690592165815,
-55.90460394777256
],
[
19.566611381720463,
-79.66406062557598
],
[
33.5427623686636,
-106.21874750076813
],
[
51.711758651689706,
-129.97820417857156
],
[
82.4592908229647,
-149.54481556029214
],
[
121.59251358640563,
-155.13527595506912
],
[
156.5328910537636,
-149.54481556029214
],
[
190.0756534224272,
-129.97820417857156
],
[
215.23272519892498,
-99.23067200729656
],
[
225.01603088978504,
-58.699834145161276
],
[
226.4136459884794,
-20.96422648041471
],
[
232.0041063832566,
15.373766085637271
],
[
240.38979697542254,
43.326068059524005
],
[
255.76356306106004,
61.495064342549995
],
[
273.93255934408626,
60.09744924385541
],
[
297.6920160218897,
47.518913355606855
],
[
331.2347783905532,
25.15707177649756
],
[
367.5727709566056,
-6.98807549347157
],
[
405.3083786213522,
-58.699834145161276
],
[
419.2845296082953,
-97.83305690860243
],
[
415.09168431221224,
-125.78535888248871
],
[
394.1274578317975,
-142.55674006682057
],
[
346.6085444761907,
-153.737660856375
],
[
294.89678582450097,
-152.34004575768085
],
[
238.99218187672818,
-129.97820417857156
],
[
183.08757792895562,
-93.64021161251912
],
[
122.99012868509988,
-53.10937375038429
],
[
76.86883042818738,
-27.95230197388628
],
[
16.771381184331744,
-22.361841579109296
],
[
-29.34991707258075,
-40.530837862135286
],
[
-51.71175865168982,
-61.495064342549995
],
[
-64.2902945399386,
-85.25452102035342
],
[
-67.08552473732732,
-113.2068229942397
],
[
-53.109373750384066,
-141.15912496812598
],
[
-15.373766085637499,
-150.94243065898627
],
[
29.349917072580638,
-143.9543551655147
],
[
85.25452102035331,
-117.39966829032255
],
[
134.1710494746544,
-76.86883042818772
],
[
155.13527595506923,
-48.91652845430099
],
[
163.52096654723516,
-18.16899628302599
],
[
160.72573634984644,
-4.192845296082851
],
[
149.5448155602919,
2.795230197388719
],
[
135.56866457334877,
6.98807549347157
],
[
125.7853588824886,
8.385690592165702
],
[
121.59251358640563,
8.385690592165702
],
[
121.59251358640563,
8.385690592165702
]
],
"pressures": [],
"simulatePressure": true,
"lastCommittedPoint": [
121.59251358640563,
8.385690592165702
]
}
],
"appState": {
"gridSize": null,
"viewBackgroundColor": "#ffffff"
},
"files": {}
}
Binary file added docs/keymap/diagrams/dummy.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit db04c2d

Please sign in to comment.