Skip to main content
Version: 1.5.2

Key Generation in Cluster Mode

When running keygen many times between the same group of Vertex instances (i.e. a Cluster), exchanging the keygen_id parameter between them for every keygen event is both cumbersome and can potentially decrease security.
Therefore, in those cases, a Cluster can be set up.
A Cluster is simply a defined group of Vertex servers that mutually know the domains and keygen_ids of each other.
This makes the keygen process much smoother, as well as increases security by only requiring that keygen_ids be exchanged securely one time during the Cluster setup.
Below, the flow of setting up and using a Cluster for key generation is shown.

Setting Up a Cluster​

Step 1: Gather Persistent Keygen IDs​

First, gather the persistent keygen IDs of all parties involved. This can be done using the persistent-keygen-id endpoint:

curl -L -X GET "https://<YOUR_VERTEX>/cluster/persistent-keygen-id" \
-H "Content-Type: application/json" \
-H "Authorization: <USER_API_KEY>"

Step 2: Register the Other Vertex Servers on the Vertex​

For each Vertex in the cluster, register the domain and persistent_keygen_id of all other Vertices.
This can be done using the insert-vertex endpoint:

curl -L -X POST "https://<YOUR_VERTEX_1>/admin/cluster/insert-vertex" \
-H 'Content-Type: application/json' \
-H "Authorization: <USER_API_KEY>"
--data-raw '{
  "domain": "https://vertex2.domain",
  "persistent_keygen_id": "<PERSISTENT_KEYGEN_ID_OF_VERTEX_2>"
}'

curl -L -X POST "https://<YOUR_VERTEX_1>/admin/cluster/insert-vertex" \
-H 'Content-Type: application/json' \
-H "Authorization: <USER_API_KEY>"
--data-raw '{
  "domain": "https://vertex3.domain",
  "persistent_keygen_id": "<PERSISTENT_KEYGEN_ID_OF_VERTEX_3>"
}'

Step 3: Create a Cluster​

Next, a SystemAdmin needs to create a cluster using the gathered persistent_keygen_ids. This can be done using the create-cluster endpoint:

curl -L -X POST "https://<YOUR_VERTEX_1>/admin/cluster/create-cluster" \
-H "Content-Type: application/json" \
-H "Authorization: <ADMIN_API_KEY>" \
--data-raw '{
    "name": "my_cluster",
    "vertices_domains": [
        "https://vertex2.domain",
        "https://vertex3.domain"
    ]
}'

Perform Key Generation Using the Cluster​

Once the cluster is created, each Vertex instance that is part of the cluster can perform an MPC key generation using the cluster name.
Users can simply reference the Cluster in their operations.

Use the relevant keygen endpoints for your chosen algorithm:

Example request for Ed25519:

curl -L -X POST "https://<YOUR_VERTEX>/cluster/ed25519/keygen" \
-H "Content-Type: application/json" \
-H "Authorization: <USER_API_KEY>" \
--data-raw '{
  "cluster_name": "my_cluster",
  "num_parties": 3,
  "threshold": 2
}'