Merge pull request #792 from multiversx/development

Development

Author: iulianpascalau

docs/validators/key-management/multikey-nodes.md

@@ -163,10 +163,151 @@ At the first sight, this can be seen as a security degradation in terms of means
 
 Regarding point 3, each managed BLS key will create a virtual p2p identity that no node from the network can connect to since it does not advertise the connection info but is only used to sign p2p messages.
 Associated with a separate named identity, the system will make that BLS key virtually unreachable, and its origin hidden from the multikey nodes. Therefore, the node operators will need to apply the following changes on the `prefs.toml` file:
-* in the `[Preference]` section, the 2 options called `NodeDisplayName` and `Identity` will be changed to something relevant for the nodes that are running the multikey group;
+* in the `[Preference]` section, the 2 options called `NodeDisplayName` and `Identity` should be changed to something different used in the BLS' definitions to prevent easy matching. Generic names like `gateway` or `observer` are suitable for this section. 
+Also, completely random strings can be used as to be easier to identify the nodes in explorer. The `Identity` can be left empty;
 * in the `[[NamedIdentity]]` section, the 2 options called `NodeName` and `Identity` will be changed to the real identities of the BLS keys: such as the staking provider brand names. **They should be different from the ones defined in the `[Preference]` section.**
 
 In this way, the operation will be somewhat similar to the *sentinel nodes* seen elsewhere. 
 The difference in our case is that the setup is greatly simplified as there is no separate network for the protected nodes that will need to be maintained.
 The security of our setup (if points 1, 2 and 3 are applied) should be the same with a *sentinel setup*.
 
+### Configuration example
+
+Let's suppose we have 5 BLS keys that belong to a staking provider called `testing-staking-provider` and we want to apply the security notes described above.
+So, for the sake of the example, we generated 5 random BLS keys, the `allValidatorsKeys.pem` should contain something like this:
+```
+-----BEGIN PRIVATE KEY for 15eb03756fae81d2fbae392a4d7d82abdf7618ce3056b89376c2a46bc6e8403ed3cc84e12bc819c0b088ee46e7c28302d2b666b011714cc8ea2b75488907d07e194a6e83f0f3d15c7699de412de425314be5cc3ce6ab2c594690006f9915dd15-----
+NDA5MWVjODMwZjU3MDhkYmQwNzk5ZWEwNjg2MDc0MzUzYmZjNThjM2ZhYzU2Y2I1
+ZGRhMjY3YTY1NjhkZjI1YQ==
+-----END PRIVATE KEY for 15eb03756fae81d2fbae392a4d7d82abdf7618ce3056b89376c2a46bc6e8403ed3cc84e12bc819c0b088ee46e7c28302d2b666b011714cc8ea2b75488907d07e194a6e83f0f3d15c7699de412de425314be5cc3ce6ab2c594690006f9915dd15-----
+-----BEGIN PRIVATE KEY for ff12bc7f471e2e375c6e8b981f13ed823dcca857c41a2ffc3a0956283a8428a95754375dabc0b412df3ec41d2a51ef1490a8d23f4e4f9348787f9615093e0129969085488b59d2ab550467cd0d0fa33df22e2ed2d8c8c0c0f59042dafd0c1098-----
+MTcwN2ZlMzFhMzk3Y2VjOWM4ZjdmMWU3Njg4MjY3YTAwOWU5ZjJmMWYxY2Y0ZjFl
+MzI2Y2M5NGJiZGFjNGQwZA==
+-----END PRIVATE KEY for ff12bc7f471e2e375c6e8b981f13ed823dcca857c41a2ffc3a0956283a8428a95754375dabc0b412df3ec41d2a51ef1490a8d23f4e4f9348787f9615093e0129969085488b59d2ab550467cd0d0fa33df22e2ed2d8c8c0c0f59042dafd0c1098-----
+-----BEGIN PRIVATE KEY for 3dec570c02a4444197c1ed53fefd7e57acb9bc99ae47db7661cfbfb47170418702162a46ed40e113e3381d68b713e903e286ffaf9cac77fed8f9c79e83f2abb0ccd690ef4f689607b6414a6f893e0c0ced93d7456240bbccbf223f7603dd8e05-----
+ZWMwYWRjYjNiYTQ0YmM4MGM5ZjhmNTlkNTU5YTRlMWJlMTI2ODFmMDlmM2JiNTM4
+MmMyYzdlYmNhYjNkNTk2MA==
+-----END PRIVATE KEY for 3dec570c02a4444197c1ed53fefd7e57acb9bc99ae47db7661cfbfb47170418702162a46ed40e113e3381d68b713e903e286ffaf9cac77fed8f9c79e83f2abb0ccd690ef4f689607b6414a6f893e0c0ced93d7456240bbccbf223f7603dd8e05-----
+-----BEGIN PRIVATE KEY for 38a93e3c00128c31769823710aa7deb145591b99a78c87dbd74c894afd540ade6de3906b45001d3f5a5882db34eaf30e412bef77ed43cf5a394edd0aa70254a74db1c80eef5d41342cae76fbbae596bc811fa491e00f16a7e011a836f7ceaa15-----
+YWMzMDk2ZjY3NmExNjhiNTQ5ODQzM2JiM2NiZWFmNzkyYjQyYWZhZjJlZmMwNjNl
+YzdhMWI5OGM1ZDdjODg1MQ==
+-----END PRIVATE KEY for 38a93e3c00128c31769823710aa7deb145591b99a78c87dbd74c894afd540ade6de3906b45001d3f5a5882db34eaf30e412bef77ed43cf5a394edd0aa70254a74db1c80eef5d41342cae76fbbae596bc811fa491e00f16a7e011a836f7ceaa15-----
+-----BEGIN PRIVATE KEY for 1fce426b632e5a5941d9989e4f8bbb93a0a08a0e85dfe16d4d65c08b351dfbff1a1104d5e75e1be7565b4bbc6a583103bfc4b4075727133a54fa421983d894e549576364694b3e8910359b3de5260360bfe9f9bea2fec1cb50c2cf79a3fd590d-----
+ZmYzMjM2ODljODQwMDRiMDI1MGU0NjcyMzhjYjJlMDNlNzg0OGI0YzQ1ZTM0ZjQz
+YTZkZDVmNTBjYjAwMjAyNg==
+-----END PRIVATE KEY for 1fce426b632e5a5941d9989e4f8bbb93a0a08a0e85dfe16d4d65c08b351dfbff1a1104d5e75e1be7565b4bbc6a583103bfc4b4075727133a54fa421983d894e549576364694b3e8910359b3de5260360bfe9f9bea2fec1cb50c2cf79a3fd590d-----
+```
+
+The staking operators that will create the actual `allValidatorsKeys.pem` file used on the chain should concatenate all keys from their `validatorKey.pem` files with a text editor. 
+The content should resemble the one depicted in this example.   
+
+For the `prefs.toml` file, we can have definitions like:
+
+```toml
+[Preferences]
+   # DestinationShardAsObserver represents the desired shard when running as observer
+   # value will be given as string. For example: "0", "1", "15", "metachain"
+   # if "disabled" is provided then the node will start in the corresponding shard for its public key or 0 otherwise
+   DestinationShardAsObserver = "0"
+
+   # NodeDisplayName represents the friendly name a user can pick for his node in the status monitor when the node does not run in multikey mode
+   # In multikey mode, all bls keys not mentioned in NamedIdentity section will use this one as default
+   NodeDisplayName = "s14"
+
+   # Identity represents the GitHub identity when the node does not run in multikey mode
+   # In multikey mode, all bls keys not mentioned in NamedIdentity section will use this one as default
+   Identity = ""
+
+   # RedundancyLevel represents the level of redundancy used by the node (-1 = disabled, 0 = main instance (default),
+   # 1 = first backup, 2 = second backup, etc.)
+   RedundancyLevel = 0
+
+   # FullArchive, if enabled, will make the node able to respond to requests from past, old epochs.
+   # It is highly recommended to enable this flag on an observer (not on a validator node)
+   FullArchive = false
+
+   # PreferredConnections holds an array containing valid ips or peer ids from nodes to connect with (in top of other connections)
+   # Example:
+   # PreferredConnections = [
+   #    "127.0.0.10",
+   #    "16Uiu2HAm6yvbp1oZ6zjnWsn9FdRqBSaQkbhELyaThuq48ybdorrr"
+   # ]
+   PreferredConnections = []
+
+   # ConnectionWatcherType represents the type of the connection watcher needed.
+   # possible options:
+   #  - "disabled" - no connection watching should be made
+   #  - "print" - new connection found will be printed in the log file
+   ConnectionWatcherType = "disabled"
+
+   # OverridableConfigTomlValues represents an array of items to be overloaded inside other configuration files, which can be helpful
+   # so that certain config values need to remain the same during upgrades.
+   # (for example, an Elasticsearch user wants external.toml->ElasticSearchConnector.Enabled to remain true all the time during upgrades, while the default
+   # configuration of the node has the false value)
+   # The Path indicates what value to change, while Value represents the new value in string format. The node operator must make sure
+   # to follow the same type of the original value (ex: uint32: "37", float32: "37.0", bool: "true")
+   # File represents the file name that holds the configuration. Currently, the supported files are: config.toml, external.toml, p2p.toml and enableEpochs.toml
+   # -------------------------------
+   # Un-comment and update the following section in order to enable config values overloading
+   # -------------------------------
+   # OverridableConfigTomlValues = [
+   #    { File = "config.toml", Path = "StoragePruning.NumEpochsToKeep", Value = "4" },
+   #    { File = "config.toml", Path = "MiniBlocksStorage.Cache.Name", Value = "MiniBlocksStorage" },
+   #    { File = "external.toml", Path = "ElasticSearchConnector.Enabled", Value = "true" }
+   #]
+
+# BlockProcessingCutoff can be used to stop processing blocks at a certain round, nonce or epoch.
+# This can be useful for snapshotting different stuff and also for debugging purposes.
+[BlockProcessingCutoff]
+   # If set to true, the node will stop at the given coordinate
+   Enabled = false
+
+   # Mode represents the cutoff mode. possible values: "pause" or "process-error".
+   # "pause" mode will halt the processing at the block with the given coordinates. Useful for snapshots/analytics
+   # "process-error" will return an error when processing the block with the given coordinates. Useful for debugging
+   Mode = "pause"
+
+   # CutoffTrigger represents the kind of coordinate to look after when cutting off the processing.
+   # Possible values: "round", "nonce", or "epoch"
+   CutoffTrigger = "round"
+
+   # The minimum value of the cutoff. For example, if CutoffType is set to "round", and Value to 20, then the node will stop processing at round 20+
+   Value = 0
+
+# NamedIdentity represents an identity that runs nodes on the multikey
+# There can be multiple identities set on the same node, each one of them having different bls keys, just by duplicating the NamedIdentity
+[[NamedIdentity]]
+   # Identity represents the GitHub identity for the current NamedIdentity
+   Identity = "testing-staking-provider"
+   # NodeName represents the name that will be given to the names of the current identity
+   NodeName = "tsp"
+   # BLSKeys represents the BLS keys assigned to the current NamedIdentity
+   BLSKeys = [
+       "15eb03756fae81d2fbae392a4d7d82abdf7618ce3056b89376c2a46bc6e8403ed3cc84e12bc819c0b088ee46e7c28302d2b666b011714cc8ea2b75488907d07e194a6e83f0f3d15c7699de412de425314be5cc3ce6ab2c594690006f9915dd15",
+       "ff12bc7f471e2e375c6e8b981f13ed823dcca857c41a2ffc3a0956283a8428a95754375dabc0b412df3ec41d2a51ef1490a8d23f4e4f9348787f9615093e0129969085488b59d2ab550467cd0d0fa33df22e2ed2d8c8c0c0f59042dafd0c1098", 
+       "3dec570c02a4444197c1ed53fefd7e57acb9bc99ae47db7661cfbfb47170418702162a46ed40e113e3381d68b713e903e286ffaf9cac77fed8f9c79e83f2abb0ccd690ef4f689607b6414a6f893e0c0ced93d7456240bbccbf223f7603dd8e05",
+       "38a93e3c00128c31769823710aa7deb145591b99a78c87dbd74c894afd540ade6de3906b45001d3f5a5882db34eaf30e412bef77ed43cf5a394edd0aa70254a74db1c80eef5d41342cae76fbbae596bc811fa491e00f16a7e011a836f7ceaa15",
+       "1fce426b632e5a5941d9989e4f8bbb93a0a08a0e85dfe16d4d65c08b351dfbff1a1104d5e75e1be7565b4bbc6a583103bfc4b4075727133a54fa421983d894e549576364694b3e8910359b3de5260360bfe9f9bea2fec1cb50c2cf79a3fd590d"
+   ]
+```
+
+:::important
+These 2 configuration files `allValidatorsKeys.pem` and `prefs.toml` should be copied on all n nodes that assemble the multikey group of nodes.
+
+**Do not forget to change the `DestinationShardAsObserver` accordingly for each node.**
+:::
+
+After starting the multikey nodes, in ~10 minutes, the explorer will reflect the changes. All n nodes that run the multikey group will broadcast their identity as an empty string and their names will be `s14`.
+The BLS keys' identities, on the other hand will have the following names & identities:
+
+
+| Key          | Name   | Identity                 |
+|--------------|--------|--------------------------|
+| 15eb03756... | tsp-00 | testing-staking-provider |
+| ff12bc7f4... | tsp-01 | testing-staking-provider |
+| 3dec570c0... | tsp-02 | testing-staking-provider |
+| 38a93e3c0... | tsp-03 | testing-staking-provider |
+| 1fce426b6... | tsp-04 | testing-staking-provider |
+
+
+