-
Notifications
You must be signed in to change notification settings - Fork 9
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Chores grooming #11
Chores grooming #11
Changes from 10 commits
46a4190
8f83e7a
64ee75f
a5b52c5
44e019f
a6d122f
9ddfa77
aa1c0a7
ba097fb
8935dad
ecf4e91
4ad85a0
ac06e54
a71153e
18c0b58
79805c5
1174c1f
aecffb6
211e779
954e17f
5d7d73b
859819e
e02bc02
1aec967
70432af
bf6ce6c
114b3d8
c3748e6
ff259b4
260398a
8808ccd
c00be40
2495c75
9675a4d
4ab3607
d7a439c
7949342
8765162
c3c1dcd
e1caae3
e6fd291
8c9050c
8704e08
2fad7d7
8a21497
28c4c0a
e79c08b
b0a1ae6
f09a35a
62077ed
b623cbc
a2b65cf
695177e
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,77 +1,112 @@ | ||
# ssv-dkg-tool | ||
|
||
## Architecture | ||
### Build | ||
|
||
```sh | ||
make install | ||
``` | ||
|
||
### Operators data | ||
|
||
The data of the operators (ID, IP, Pubkey) can be collected in any way, for example a central server that you can pull the data from, or a preset file where all operators data exist. | ||
|
||
### Build | ||
|
||
```sh | ||
make install | ||
Information about operators can be collected at `json` file and supplied to initiator to use for a key generation. | ||
|
||
Operators info file example (`./examples/operators_integration.json`): | ||
|
||
```json | ||
[ | ||
{ | ||
"id": 1, | ||
"public_key": "LS0tLS1CRUdJTiBSU0....", | ||
"ip": "http://localhost:3030" | ||
}, | ||
{ | ||
"id": 2, | ||
"public_key": "LS0tLS1CRUdJTiB....", | ||
"ip": "http://localhost:3031" | ||
} | ||
] | ||
``` | ||
|
||
### Server | ||
### Operator | ||
|
||
The dkg server is ran by a SSV operator, an Operator RSA private key is a requirement. | ||
The server is able to participate in multiple instances in parallel. | ||
Whenever the server receives a message it directs it to the right instance by the identifier, and respond with an answer. | ||
The dkg-operator is ran by a SSV operator, an Operator RSA private key is a requirement. | ||
The operator is able to participate in multiple DKG ceremonies in parallel. | ||
|
||
Start a DKG server | ||
NOTE: ssv-dkg tool is using an ssv operator private key file. Encrypted and plintext versiaons are supported. If `password` parameter is provided then the dkgcli tool assumes that the operator`s RSA key is encrypted, if not then it assumes that the key is provided as plaintext. | ||
|
||
#### Start a DKG-operator | ||
|
||
```sh | ||
dkgcli start-dkg-server --privKey ./examples/server1/encrypted_private_key.json --port 3030 --password 12345678 --storeShare true | ||
ssv-dkg start-dkg-operator --privKey ./examples/operator1/encrypted_private_key.json --port 3030 --password ./password --storeShare true | ||
|
||
### where | ||
--privKey ./encrypted_private_key.json # path to base 64 encoded RSA private key in PKCS #1, ASN.1 DER form. | ||
--privKey ./encrypted_private_key.json # path to ssv operator`s private key | ||
--port 3030 # port for listening messages | ||
--password: 12345678 # password for encrypted keys | ||
--storeShare # store created bls key share to a file for later reuse | ||
--password: ./password # path to password file to decrypt the key | ||
--storeShare # store created bls key share to a file for later reuse if needed | ||
``` | ||
|
||
Its also possible to use yaml configuration file `./config/operator.yaml` for parameters. `dkgcli` will be looking for this file at `./config/` folder. | ||
Its also possible to use yaml configuration file `./config/operator.yaml` for parameters. `dkgcli` will be looking for the config file at `./config/` folder. | ||
|
||
Example: | ||
|
||
```yaml | ||
privKey: ./encrypted_private_key.json | ||
password: 12345678 | ||
password: ./password | ||
port: 3030 | ||
storeShare: true | ||
``` | ||
|
||
When using configuration file, run: | ||
|
||
```sh | ||
dkgcli start-dkg-server | ||
ssv-dkg start-dkg-operator | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
|
||
``` | ||
|
||
### Initiator of DKG key generation | ||
### Initiator | ||
|
||
The initiator uses `init-dkg` to create the initial details needed to run DKG between all operators. | ||
|
||
Generate initiator identity RSA key pair: | ||
|
||
```sh | ||
dkgcli init-dkg \ | ||
ssv-dkg generate-initiator-keys --password 12345678 | ||
``` | ||
|
||
This will create `encrypted_private_key.json` with encrypted by password RSA key pair | ||
Write down `password` in any text file, for example to `./password` | ||
|
||
Run: | ||
|
||
```sh | ||
ssv-dkg init-dkg \ | ||
--operatorIDs 1,2,3,4 \ | ||
--operatorsInfoPath ./examples/operators_integration.json \ | ||
--operatorsInfoPath ./operators_integration.json \ | ||
--owner 0x81592c3de184a3e2c0dcb5a261bc107bfa91f494 \ | ||
--nonce 4 \ | ||
--withdrawAddress 0000000000000000000000000000000000000009 \ | ||
--fork 00000000 | ||
--fork "mainnet" | ||
--depositResultsPath deposit.json | ||
--ssvPayloadResultsPath payload.json | ||
--initiatorPrivKey ./encrypted_private_key.json | ||
--initiatorPrivKeyPassword ./password | ||
|
||
#### where | ||
--operatorIDs 1,2,3,4 # operator IDs which will be used for a DKG ceremony | ||
--operatorsInfoPath ./examples/operators_integration.json # path to info about operators - ID,base64(RSA pub key), | ||
--operatorsInfoPath ./operators_integration.json # path to operators info ID,base64(RSA pub key), | ||
--owner 0x81592c3de184a3e2c0dcb5a261bc107bfa91f494 # owner address for the SSV contract | ||
--nonce 4 # owner nonce for the SSV contract | ||
--fork "00000000" # fork id bytes in HEX | ||
--depositResultsPath # path to store the result file | ||
--ssvPayloadResultsPath # path to store ssv contract payload file | ||
--withdrawAddress # Reward payments of excess balance over 32 ETH will automatically and regularly be sent to a withdrawal address linked to each validator, once provided by the user. Users can also exit staking entirely, unlocking their full validator balance. | ||
--fork "mainnet" # fork name: mainnet, prater, or now_test_network | ||
--depositResultsPath # path and filename to store the staking deposit file | ||
--ssvPayloadResultsPath # path and filename to store ssv contract payload file | ||
--initiatorPrivKey ./encrypted_private_key.json # path to ssv initiators`s private key | ||
--initiatorPrivKeyPassword: ./password # path to password file to decrypt the key | ||
``` | ||
|
||
Its also possible to use yaml configuration file `./config/initiator.yaml` for parameters. `dkgcli` will be looking for this file at `./config/` folder. | ||
Its also possible to use yaml configuration file `./config/initiator.yaml` for parameters. `dkgcli` will be looking for this file at `./config/` folder at a same root as the binary. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. dkgcli -> ssv-dkg |
||
|
||
Example: | ||
|
||
|
@@ -84,25 +119,31 @@ fork: "00000000" | |
operatorsInfoPath: ./examples/operators_integration.json | ||
depositResultsPath: ./deposit.json | ||
ssvPayloadResultsPath: ./payload.json | ||
privKey: ./encrypted_private_key.json | ||
password: ./password | ||
``` | ||
|
||
When using configuration file, run: | ||
|
||
```sh | ||
dkgcli init-dkg | ||
ssv-dkg init-dkg | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. can be just |
||
``` | ||
|
||
**_NOTE: Threshold is computed automatically using 3f+1 tolerance._** | ||
|
||
### Generate RSA operator key | ||
--- | ||
|
||
```sh | ||
./dkgcli generate-operator-keys --password 12345678 | ||
``` | ||
### Security notes | ||
|
||
--- | ||
Here we explain how we secure the communication between DKG ceremony initiator and operators | ||
|
||
1. Initiator is using RSA key (2048 bits) to sign init message sent to operators. Upon receiving operators verify the sig using pub key at init message. If the sig is valid, operators store this pub key for further verification of messages coming from the initiator(s). | ||
2. Operators are using RSA key (ssv operator key - 2048 bits) to sign every message sent back to initiator. | ||
3. Initiator verifies every message incoming from any operator using ID and Public Key provided by operators info file, then initiator creates a combined message and signs it. | ||
4. Operators verify each of the messages of other operators participating in the ceremony and verifies initiator signature of the message. | ||
5. During the DKG protocol execution, the BLS auth scheme is being used - G2 for its signature space and G1 for its public key | ||
|
||
### Schema | ||
## Architecture | ||
|
||
![flow](./imgs/DKGinit.drawio.png) | ||
|
||
|
@@ -210,7 +251,7 @@ Initial message fields: | |
|
||
### `Switch` instance management | ||
|
||
The DKG server can handle multiple DKG instances, it saves up to MaxInstances(1024) up to `MaxInstanceTime` (5 minutes). If a new Init arrives we try to clean our list from instances older than `MaxInstanceTime` if we find any, we remove them and add the incoming, otherwise we respond with error that the maximum number of instances is already running. | ||
The DKG-operator can handle multiple DKG instances, it saves up to MaxInstances(1024) up to `MaxInstanceTime` (5 minutes). If a new Init arrives we try to clean our list from instances older than `MaxInstanceTime` if we find any, we remove them and add the incoming, otherwise we respond with error that the maximum number of instances is already running. | ||
|
||
### TODO: | ||
|
||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
remove tool
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.