Keyshares file structure

Using Distributed Key Generation, the SSV protocol encrypts and splits a validator key into multiple key shares. The key shares are then distributed to multiple non-trusting nodes run by operators.

The file also includes signed data that helps detect tampering. For example, if someone changed ownerAddress or ownerNonce and tried to submit the modified file to SSV Network, the key shares would be considered invalid and ignored by network participants because the signature would no longer match the contents.

More details about each element of the keyshares structure are below.

An example of keyshares.json structure:

{
  "version": "v1.1.0",
  "createdAt": "2025-05-14T10:23:43.794Z",
  "shares": [
    {
      "data": {
        "ownerNonce": 0,
        "ownerAddress": "OWNER_ADDRESS",
        "publicKey": "VALIDATOR_PUBKEY",
        "operators": [
          {
            "id": 1,
            "operatorKey": "OPERATOR_PUBKEY"
          },
          {...},
          {...},
          {...}
        ]
      },
      "payload": {
        "publicKey": "VALIDATOR_PUBKEY",
        "operatorIds": [1,2,3,4],
        "sharesData": "ENCRYPTED_SHARES_DATA"
      }
    }
  ]
}

Details about the sharesData field

Below is an example of sharesData from a Hoodi validator with 4 operators. Each segment is highlighted with color:

Explanation of each segment

• Signature - The first 192 characters, excluding 0x, are a serialized BLS-signed message (read more about SSZ). The message is ownerAddress:ownerNonce, signed by the validator private key, and can therefore be verified using the validator publicKey.
• Shares' public keys - An array of concatenated BLS public keys. Each element is a public share of the validator key and is 96 characters long. The number of shares depends on the number of selected operators.
• Encrypted shares - An array of concatenated encrypted shares. Each element is a private share of the validator key and is 512 characters long. The number of shares depends on the number of selected operators. Shares are encrypted with each operator’s public key and can only be decrypted with the corresponding private key.

If you want to learn more about keyshare verification, you can review the verify-keyshare repository on GitHub:

• The validateSingleShares function in ssv-keys.ts performs signature verification.
• The buildSharesFromBytes function breaks down each operator’s key share.
• The areKeysharesValid function then checks the signature and operators’ key shares against the validator public key.