Enabling DKG

The ssv-dkg tool enable operators to participate in ceremonies to generate distributed validator keys for Ethereum stakers.

The ssv-dkg tool is separate from the ssv-node, and could be running on a different machine, but the two are heavily correlated, as the keyshare generated by the ssv-dkg tool, will ultimately be used by the Node itself to manage the related validator.

If you wish to take part in DKG ceremonies initiated by stakers and increase your opportunity to run their validators, it is crucial to have your ssv-dkg client online at all times.

Also, in order to access logs it is necessary to utilize permanent storage when running this software.

Prerequisites

In order to successfully participate in DKG ceremonies initiated by stakers, you will need to possess and/or provide this information:

• Operator ID - the ID of your operator within the SSV network.

• Operator Key Pair

  • Public Key - the public key of the operator

  • Private Key - the private key of the operator as an password-encrypted file (if you are in possession of raw text private key, follow this migration guide to encrypt your existing operator keys)

• Machine Endpoint - the endpoint (protocol:ip:port) of the machine intended to run the ssv-dkg client (if you have a domain name, instead of an ip that works as well)

You must use the same key of your SSV operator when running ssv-dkgnode. Using a different key will result in the inability to successfully complete the DKG ceremony.

Start SSV-DKG

It is advised launching the tool as a Docker image as it is the most convenient way and only requires to have Docker installed. The team builds a Docker image with every release of the tool.

Docker and YAML file

All of the necessary configuration information can be provided in a YAML file.

A good way to manage all the necessary files (encrypted_private_key.json, password) is to store them in a single folder (in this case operator-config), together with the operator.yaml configuration file, like so:

ssv@localhost:~/ssv-dkg# tree operator-config
operator-config
├── encrypted_private_key.json
├── operator.yaml
└── password

1 directory, 3 files

With this configuration, a typical configuration file would look like this:

operator.yaml

privKey: /data/encrypted_private_key.json
privKeyPassword: /data/password
operatorID: <YOUR_OPERATOR_ID>
port: 3030
logLevel: info
logFormat: json
logLevelFormat: capitalColor
logFilePath: /data/debug.log
outputPath: /data/output

In the config file above, /data/ represents the container's shared volume created by the docker command itself with the -v option.

Under the assumption that all the necessary files (encrypted_private_key.json, operator.yaml, password) are under the same folder (represented below with <PATH_TO_FOLDER_WITH_CONFIG_FILES>) you can run the tool using the command below:

docker run -u $(id -u):$(id -g) --restart unless-stopped --name ssv_dkg -p 3030:3030 -v "<PATH_TO_FOLDER_WITH_CONFIG_FILE>":/data -it "bloxstaking/ssv-dkg:latest" start-operator --configPath /data/operator.yaml

A quick explanation of the command flags is due:

• -u flag makes sure the container will write any output as the current user

• --restart unless-stopped makes sure that, in case of a crash, the container will automatically restart. It will only stop when manually stopped

• --name provisions the container with the specific name, so it's easier to find, with docker ps

Just make sure to substitute <PATH_TO_FOLDER_WITH_CONFIG_FILES> with the actual folder containing all the files (e.g. /home/my-user/operator-config/).

You can, of course, change the configuration above to one that suits you better, just be mindful about changing the path references in the docker command and in the operator.yaml file as well. The two need to be consistent with each other.

This command will keep the terminal busy, showing the container's logs. It is useful to make sure that the tool start up sequence runs correctly.

You can detach the terminal at any time by hitting Ctrl-c key combination, or closing the terminal itself. The tool will be stopped, but it will restart automatically, thanks to the --restart unless-stopped startup parameter.

If you are sure that the tool works, and don't care about the logs, you can add the -d parameter right after docker run.

docker-compose and YAML file

All of the necessary configuration information can be provided in a YAML file.

A good way to manage all the necessary files (encrypted_private_key.json, password) is to store them in a single folder (in this case operator-config), together with the operator.yaml configuration file, like so:

ssv@localhost:~/ssv-dkg# tree operator-config
operator-config
├── encrypted_private_key.json
├── operator.yaml
└── password

1 directory, 3 files

With this configuration, a typical configuration file would look like this:

operator.yaml

privKey: /data/encrypted_private_key.json
privKeyPassword: /data/password
operatorID: <YOUR_OPERATOR_ID>
port: 3030
logLevel: info
logFormat: json
logLevelFormat: capitalColor
logFilePath: /data/debug.log
outputPath: /data/output

In the config file above, /data/ represents the container's shared volume created by the docker command itself with the -v option.

Under the assumption that all the necessary files (encrypted_private_key.json, operator.yaml, password) are under the same folder (represented below with <PATH_TO_FOLDER_WITH_CONFIG_FILES>), here is an example of a docker-compose file:

docker-compose.yaml

ssv-dkg:
  image: bloxstaking/ssv-dkg:latest
  restart: "unless-stopped"
  container_name: ssv-dkg
  volumes:
    - <PATH_TO_FOLDER_WITH_CONFIG_FILE>:/data
  user: "${UID}:${GID}"
  ports:
    - 3030:3030/tcp
  command: start-operator --configPath /data/operator.yaml

A quick explanation of the command flags is due:

• user flag makes sure the container will write any output as the current user

• restart: "unless-stopped" makes sure that, in case of a crash, the container will automatically restart. It will only stop when manually stopped

• container_name provisions the container with the specific name, so it's easier to find, with docker ps

Just make sure to substitute <PATH_TO_FOLDER_WITH_CONFIG_FILES> with the actual folder containing all the files (e.g. /home/my-user/operator-config/).

You can, of course, change the configuration above to one that suits you better, just be mindful about changing the path references in the docker command and in the operator.yaml file as well. The two need to be consistent with each other.

In order to launch the container, you would need to run this command:

docker compose up

This command will keep the terminal busy, showing the container's logs. It is useful to make sure that the tool start up sequence runs correctly.

You can detach the terminal at any time by hitting Ctrl-c key combination, or closing the terminal itself. The tool will be stopped, but it will restart automatically, thanks to the restart: "unless-stopped" startup parameter.

If you are sure that the tool works, and don't care about the logs, you can add the -d parameter right after docker compose up.

Build from Source

A prerequisite for this is to have go version 1.22 installed on the system, and an optional requirement is to have the make tool installed as well (alternatively you could run the corresponding command defined in the Makefile).

Clone repository

Clone the ssv-dkg repository in your local machine:

git clone [e-mail]:ssvlabs/ssv-dkg.git

Build

From the project's root folder, run the following command:

make install

SSL certificate

Launching the DKG tool as a Docker container has the advantage of automatically creating and managing SSL certificate. If you decide to build it from source, you will have to do this yourself.

But don't worry, the entry-point.sh script in the repository is what is used by the Docker container, you could use that as an example for how to create an SSL certificate for your DKG node. For example:

mkdir -p "/ssl"
openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes -keyout "/ssl/tls.key" -out "/ssl/tls.crt" -subj "/C=CN/ST=GD/L=SZ/O=localhost, Inc./CN=localhost"

Launch with command line parameters

It is advised to store all the necessary files (encrypted_private_key.json, password) in a single folder (in this case operator-config), as shown below:

ssv@localhost:~/ssv-dkg# tree operator-config
operator-config
├── encrypted_private_key.json
└── password

1 directory, 2 files

To run the DKG tool as an operator, you can launch the following command with the appropriate values to each parameter:

ssv-dkg start-operator \
            --privKey ./operator-config/encrypted_private_key.json  \
            --privKeyPassword ./operator-config/password \
            --operatorID <YOUR_OPERATOR_ID> \
            --port 3030 \
            --logLevel info \
            --logFormat json \
            --logLevelFormat capitalColor \
            --logFilePath ./operator-config/debug.log \
            --outputPath /data/output

Here's an explanation of each parameter:

Argument	Type	Description
--privKey	string	Path to private key of ssv operator
--port	int	Port for listening messages (default: 3030)
--privKeyPassword	string	Path to password file to decrypt the key
--operatorID	int	An integer, representing the ID of the operator, registered on the SSV network
--logLevel	debug | info | warning | error | critical	Logger's log level (default: debug)
--logFormat	json | console	Logger's encoding (default: json)
--logLevelFormat	capitalColor | capital | lowercase	Logger's level format (default: capitalColor)
--logFilePath	string	Path to file where logs should be written (default: ./data/debug.log)
--outputPath	string	Path to store results (default ./output)

Launch with YAML config file

It is also possible to use YAML configuration file, just as it was shown in the Docker section above.

Just pay attention to the path of the necessary files, which needs to be changed to reflect the local configuration. If the operator.yaml file is created in the same folder as the other files, and the folder structure looks like this:

ssv@localhost:~/ssv-dkg# tree operator-config
operator-config
├── encrypted_private_key.json
├── config.yaml
└── password

1 directory, 3 files

Then the content of the YAML file should be changed to this:

operator.yaml

privKey: /data/encrypted_private_key.json
privKeyPassword: /data/password
operatorID: <YOUR_OPERATOR_ID>
port: 3030
logLevel: info
logFormat: json
logLevelFormat: capitalColor
logFilePath: /data/debug.log
outputPath: /data/output

Then the tool can be launched from the root folder, by running this command:

ssv-dkg start-operator --configPath ./operator-config/operator.yaml

If the --configPath parameter is not provided, ssv-dkg will be looking for a file named config.yaml in ./config/ folder at the same root as the binary (i.e. ./config/config.yaml)

When you set up your firewall on your DKG node machine, make sure to expose the port you set in the configuration (and Docker container creation command ,if running on Docker). The default is 3030.

Update Operator Metadata

To participate in DKG ceremonies without coordination and to enable others to initiate ceremonies with you via your provided endpoint, it's crucial to update your operator metadata with the correct information.

Once the DKG tool is up and running, please make sure to update your operator metadata, and provide your DKG Operator endpoint, in the form of protocol:ip:port (if you have a domain name, instead of an ip that works as well).

Please head over to the Operator User guide on how to update metadata and follow the instructions

Test the setup

You can test out if your DKG node is correctly setup, with these simple steps:

• fetch operator metadata from SSV-API (e.g. https://api.ssv.network/api/v4/<holesky | mainnet>/operators/<OPERATOR_ID> choosing the right network and substituting your operator ID) and get dkg_address from the output

• run the command:docker run "bloxstaking/ssv-dkg:latest" ping --ip <DKG_ADDRESS> where <DKG_ADDRESS> is the address used in the previous step

It should tell you if the operator is online and is updated to the latest version.