Skip to content

Commit 65d4e52

Browse files
iulianpascalauiulianpascalau
committed
- added example for the identities of a multikey setup
1 parent 3bca0a1 commit 65d4e52

File tree

1 file changed

+142
-1
lines changed

1 file changed

+142
-1
lines changed

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

Lines changed: 142 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -163,10 +163,151 @@ At the first sight, this can be seen as a security degradation in terms of means
163163

164164
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.
165165
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:
166-
* 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;
166+
* in the `[Preference]` section, the 2 options called `NodeDisplayName` and `Identity` will 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.
167+
The `Identity` can be left empty;
167168
* 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.**
168169

169170
In this way, the operation will be somewhat similar to the *sentinel nodes* seen elsewhere.
170171
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.
171172
The security of our setup (if points 1, 2 and 3 are applied) should be the same with a *sentinel setup*.
172173

174+
### Configuration example
175+
176+
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.
177+
So, for the sake of the example, we generated 5 random BLS keys, the `allValidatorsKeys.pem` should contain something like this:
178+
```
179+
-----BEGIN PRIVATE KEY for 15eb03756fae81d2fbae392a4d7d82abdf7618ce3056b89376c2a46bc6e8403ed3cc84e12bc819c0b088ee46e7c28302d2b666b011714cc8ea2b75488907d07e194a6e83f0f3d15c7699de412de425314be5cc3ce6ab2c594690006f9915dd15-----
180+
NDA5MWVjODMwZjU3MDhkYmQwNzk5ZWEwNjg2MDc0MzUzYmZjNThjM2ZhYzU2Y2I1
181+
ZGRhMjY3YTY1NjhkZjI1YQ==
182+
-----END PRIVATE KEY for 15eb03756fae81d2fbae392a4d7d82abdf7618ce3056b89376c2a46bc6e8403ed3cc84e12bc819c0b088ee46e7c28302d2b666b011714cc8ea2b75488907d07e194a6e83f0f3d15c7699de412de425314be5cc3ce6ab2c594690006f9915dd15-----
183+
-----BEGIN PRIVATE KEY for ff12bc7f471e2e375c6e8b981f13ed823dcca857c41a2ffc3a0956283a8428a95754375dabc0b412df3ec41d2a51ef1490a8d23f4e4f9348787f9615093e0129969085488b59d2ab550467cd0d0fa33df22e2ed2d8c8c0c0f59042dafd0c1098-----
184+
MTcwN2ZlMzFhMzk3Y2VjOWM4ZjdmMWU3Njg4MjY3YTAwOWU5ZjJmMWYxY2Y0ZjFl
185+
MzI2Y2M5NGJiZGFjNGQwZA==
186+
-----END PRIVATE KEY for ff12bc7f471e2e375c6e8b981f13ed823dcca857c41a2ffc3a0956283a8428a95754375dabc0b412df3ec41d2a51ef1490a8d23f4e4f9348787f9615093e0129969085488b59d2ab550467cd0d0fa33df22e2ed2d8c8c0c0f59042dafd0c1098-----
187+
-----BEGIN PRIVATE KEY for 3dec570c02a4444197c1ed53fefd7e57acb9bc99ae47db7661cfbfb47170418702162a46ed40e113e3381d68b713e903e286ffaf9cac77fed8f9c79e83f2abb0ccd690ef4f689607b6414a6f893e0c0ced93d7456240bbccbf223f7603dd8e05-----
188+
ZWMwYWRjYjNiYTQ0YmM4MGM5ZjhmNTlkNTU5YTRlMWJlMTI2ODFmMDlmM2JiNTM4
189+
MmMyYzdlYmNhYjNkNTk2MA==
190+
-----END PRIVATE KEY for 3dec570c02a4444197c1ed53fefd7e57acb9bc99ae47db7661cfbfb47170418702162a46ed40e113e3381d68b713e903e286ffaf9cac77fed8f9c79e83f2abb0ccd690ef4f689607b6414a6f893e0c0ced93d7456240bbccbf223f7603dd8e05-----
191+
-----BEGIN PRIVATE KEY for 38a93e3c00128c31769823710aa7deb145591b99a78c87dbd74c894afd540ade6de3906b45001d3f5a5882db34eaf30e412bef77ed43cf5a394edd0aa70254a74db1c80eef5d41342cae76fbbae596bc811fa491e00f16a7e011a836f7ceaa15-----
192+
YWMzMDk2ZjY3NmExNjhiNTQ5ODQzM2JiM2NiZWFmNzkyYjQyYWZhZjJlZmMwNjNl
193+
YzdhMWI5OGM1ZDdjODg1MQ==
194+
-----END PRIVATE KEY for 38a93e3c00128c31769823710aa7deb145591b99a78c87dbd74c894afd540ade6de3906b45001d3f5a5882db34eaf30e412bef77ed43cf5a394edd0aa70254a74db1c80eef5d41342cae76fbbae596bc811fa491e00f16a7e011a836f7ceaa15-----
195+
-----BEGIN PRIVATE KEY for 1fce426b632e5a5941d9989e4f8bbb93a0a08a0e85dfe16d4d65c08b351dfbff1a1104d5e75e1be7565b4bbc6a583103bfc4b4075727133a54fa421983d894e549576364694b3e8910359b3de5260360bfe9f9bea2fec1cb50c2cf79a3fd590d-----
196+
ZmYzMjM2ODljODQwMDRiMDI1MGU0NjcyMzhjYjJlMDNlNzg0OGI0YzQ1ZTM0ZjQz
197+
YTZkZDVmNTBjYjAwMjAyNg==
198+
-----END PRIVATE KEY for 1fce426b632e5a5941d9989e4f8bbb93a0a08a0e85dfe16d4d65c08b351dfbff1a1104d5e75e1be7565b4bbc6a583103bfc4b4075727133a54fa421983d894e549576364694b3e8910359b3de5260360bfe9f9bea2fec1cb50c2cf79a3fd590d-----
199+
```
200+
201+
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.
202+
The content should resemble the one depicted in this example.
203+
204+
For the `prefs.toml` file, we can have definitions like:
205+
206+
```toml
207+
[Preferences]
208+
# DestinationShardAsObserver represents the desired shard when running as observer
209+
# value will be given as string. For example: "0", "1", "15", "metachain"
210+
# if "disabled" is provided then the node will start in the corresponding shard for its public key or 0 otherwise
211+
DestinationShardAsObserver = "0"
212+
213+
# 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
214+
# In multikey mode, all bls keys not mentioned in NamedIdentity section will use this one as default
215+
NodeDisplayName = "observer"
216+
217+
# Identity represents the keybase/GitHub identity when the node does not run in multikey mode
218+
# In multikey mode, all bls keys not mentioned in NamedIdentity section will use this one as default
219+
Identity = ""
220+
221+
# RedundancyLevel represents the level of redundancy used by the node (-1 = disabled, 0 = main instance (default),
222+
# 1 = first backup, 2 = second backup, etc.)
223+
RedundancyLevel = 0
224+
225+
# FullArchive, if enabled, will make the node able to respond to requests from past, old epochs.
226+
# It is highly recommended to enable this flag on an observer (not on a validator node)
227+
FullArchive = false
228+
229+
# PreferredConnections holds an array containing valid ips or peer ids from nodes to connect with (in top of other connections)
230+
# Example:
231+
# PreferredConnections = [
232+
# "127.0.0.10",
233+
# "16Uiu2HAm6yvbp1oZ6zjnWsn9FdRqBSaQkbhELyaThuq48ybdorrr"
234+
# ]
235+
PreferredConnections = []
236+
237+
# ConnectionWatcherType represents the type of a connection watcher needed.
238+
# possible options:
239+
# - "disabled" - no connection watching should be made
240+
# - "print" - new connection found will be printed in the log file
241+
ConnectionWatcherType = "disabled"
242+
243+
# OverridableConfigTomlValues represents an array of items to be overloaded inside other configuration files, which can be helpful
244+
# so that certain config values need to remain the same during upgrades.
245+
# (for example, an Elasticsearch user wants external.toml->ElasticSearchConnector.Enabled to remain true all the time during upgrades, while the default
246+
# configuration of the node has the false value)
247+
# The Path indicates what value to change, while Value represents the new value in string format. The node operator must make sure
248+
# to follow the same type of the original value (ex: uint32: "37", float32: "37.0", bool: "true")
249+
# File represents the file name that holds the configuration. Currently, the supported files are: config.toml, external.toml, p2p.toml and enableEpochs.toml
250+
# -------------------------------
251+
# Un-comment and update the following section in order to enable config values overloading
252+
# -------------------------------
253+
# OverridableConfigTomlValues = [
254+
# { File = "config.toml", Path = "StoragePruning.NumEpochsToKeep", Value = "4" },
255+
# { File = "config.toml", Path = "MiniBlocksStorage.Cache.Name", Value = "MiniBlocksStorage" },
256+
# { File = "external.toml", Path = "ElasticSearchConnector.Enabled", Value = "true" }
257+
#]
258+
259+
# BlockProcessingCutoff can be used to stop processing blocks at a certain round, nonce or epoch.
260+
# This can be useful for snapshotting different stuff and also for debugging purposes.
261+
[BlockProcessingCutoff]
262+
# If set to true, the node will stop at the given coordinate
263+
Enabled = false
264+
265+
# Mode represents the cutoff mode. possible values: "pause" or "process-error".
266+
# "pause" mode will halt the processing at the block with the given coordinates. Useful for snapshots/analytics
267+
# "process-error" will return an error when processing the block with the given coordinates. Useful for debugging
268+
Mode = "pause"
269+
270+
# CutoffTrigger represents the kind of coordinate to look after when cutting off the processing.
271+
# Possible values: "round", "nonce", or "epoch"
272+
CutoffTrigger = "round"
273+
274+
# 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+
275+
Value = 0
276+
277+
# NamedIdentity represents an identity that runs nodes on the multikey
278+
# There can be multiple identities set on the same node, each one of them having different bls keys, just by duplicating the NamedIdentity
279+
[[NamedIdentity]]
280+
# Identity represents the keybase/GitHub identity for the current NamedIdentity
281+
Identity = "testing-staking-provider"
282+
# NodeName represents the name that will be given to the names of the current identity
283+
NodeName = "tsp"
284+
# BLSKeys represents the BLS keys assigned to the current NamedIdentity
285+
BLSKeys = [
286+
"15eb03756fae81d2fbae392a4d7d82abdf7618ce3056b89376c2a46bc6e8403ed3cc84e12bc819c0b088ee46e7c28302d2b666b011714cc8ea2b75488907d07e194a6e83f0f3d15c7699de412de425314be5cc3ce6ab2c594690006f9915dd15",
287+
"ff12bc7f471e2e375c6e8b981f13ed823dcca857c41a2ffc3a0956283a8428a95754375dabc0b412df3ec41d2a51ef1490a8d23f4e4f9348787f9615093e0129969085488b59d2ab550467cd0d0fa33df22e2ed2d8c8c0c0f59042dafd0c1098",
288+
"3dec570c02a4444197c1ed53fefd7e57acb9bc99ae47db7661cfbfb47170418702162a46ed40e113e3381d68b713e903e286ffaf9cac77fed8f9c79e83f2abb0ccd690ef4f689607b6414a6f893e0c0ced93d7456240bbccbf223f7603dd8e05",
289+
"38a93e3c00128c31769823710aa7deb145591b99a78c87dbd74c894afd540ade6de3906b45001d3f5a5882db34eaf30e412bef77ed43cf5a394edd0aa70254a74db1c80eef5d41342cae76fbbae596bc811fa491e00f16a7e011a836f7ceaa15",
290+
"1fce426b632e5a5941d9989e4f8bbb93a0a08a0e85dfe16d4d65c08b351dfbff1a1104d5e75e1be7565b4bbc6a583103bfc4b4075727133a54fa421983d894e549576364694b3e8910359b3de5260360bfe9f9bea2fec1cb50c2cf79a3fd590d"
291+
]
292+
```
293+
294+
:::important
295+
These 2 configuration files `allValidatorsKeys.pem` and `prefs.toml` should be copied on all n nodes that assemble the multikey group of nodes.
296+
297+
**Do not forget to change the `DestinationShardAsObserver` accordingly for each node.**
298+
:::
299+
300+
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 `observer`.
301+
The BLS keys' identities, on the other hand will have the following names & identities:
302+
303+
304+
| Key | Name | Identity |
305+
|--------------|--------|--------------------------|
306+
| 15eb03756... | tsp-00 | testing-staking-provider |
307+
| ff12bc7f4... | tsp-01 | testing-staking-provider |
308+
| 3dec570c0... | tsp-02 | testing-staking-provider |
309+
| 38a93e3c0... | tsp-03 | testing-staking-provider |
310+
| 1fce426b6... | tsp-04 | testing-staking-provider |
311+
312+
313+

0 commit comments

Comments
 (0)