[Validator only]

Note This Stage is performed days ahead of the actual ceremony.

3. Contribute Validator information

Once the shared workspace has been initialized, each validator can contribute their information.

3.1. Generate Validator Information

Note It is recommended to run these steps in a secure local environment to avoid storing the private key controlling the validator rewards on the node.

How to generate a new set of Validator Information:

3.1.1 Generate a new keypair

iota client new-address

This generates a new keypair and stores the files within the standard working config folder, i.e., ~/.iota/iota_config/ (in unix). You can skip this step if you already have an account configured. If you would like to import an existing keypair see iota keytool import -h.

Executing the above command provides the keypair info as output, e.g.:

╭──────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Created new keypair and saved it to keystore.                                                    │
├────────────────┬─────────────────────────────────────────────────────────────────────────────────┤
│ alias          │ crazy-pearl                                                                     │
│ address        │ 0x1ce209a128ab5185db4cab896bc88b255bce3fbdb1a2b3fa8ef1edf911628e3e              │
│ keyScheme      │ ed25519                                                                         │
│ recoveryPhrase │ limit chest cloth this possible sister kingdom thunder brother lame know orphan │
╰────────────────┴─────────────────────────────────────────────────────────────────────────────────╯
  • alias: a human-readable identifier to use within the CLI scope to refer to a keypair;
  • address: the public address representing the keypair;
  • keyScheme: the cryptographic scheme used to derive the keypair; the ed25519 is the standard scheme, used most of the times; the BLS12381 scheme is used for the so called authority_key;
  • recoveryPhrase: a list of 12 words used by the cryptographic scheme used to derive the keypair; pair.

This keypair will be referred to, from now on, as account-key.

3.1.2 Switch to the validator account key

This makes that keypair active in the CLI.

iota client switch --address <alias>

3.1.3 Generate the validator data

Finally, all validator's remaining keypairs and data can be generated using:

iota validator make-validator-info \
    <name> \
    <description> \
    <image_url> \
    <project_url> \
    <host_name> \
  • name: human-readable validator name, e.g., validator3;
  • description: human-readable validator description, e.g., this is a validator;
  • image_url: validator image url, e.g., https://www.iota.org/favicon.png;
  • project_url: validator project url, e.g., https://www.iota.org;
  • host_name: the host name that is used to generate the validator network_address, p2p-address and primary_address, e.g., localhost;

This command generates a validator.info file and 4 key pair files in the same directory where the command was executed. All keys but the account.key will need to be copied over to the validator node and included in the YAML configuration of the node. See Validator Node Configuration

  • account.key contains an ed25519 private key (keep this one private)
  • network.key contains an ed25519 private key _(copy over to the validator node)
  • authority.key contains a BLS12381 private key (copy over to the validator node)
  • protocol.keycontains an ed25519 private key (copy over to the validator node)
  • validator.info contains the validator information, e.g.:
---
info:
  name: validator1
  account-address: "0x547b20ffca39cf1c9f57e7d1ff946d4720df48bb582e89b763b5d488ec23f5fa"
  authority-key: h93SKC2tFXMDt+lu4SRb3KA668/lJCPREHnzYZelaQ3iAu0RuiHqETBg/1jkV9HFCECvBCrzKjTuVD/bt5yUDon5nPKQmCyYEmx0NRQmxfP7Szpg17YZ388eT+aTnGEK
  protocol-key: Lm1Iy5KDV0qlMcGVnQNatAMLxhg8FOxE2q/QUkgLAYA=
  network-key: ADBhWCBOzqIvsDa9cowpSQ4t1nz+ZQYeRLBGQYe1Dy8=
  gas-price: 1000
  commission-rate: 200
  network-address: /dns/localhost/tcp/8080/http
  p2p-address: /dns/localhost/udp/8084
  primary-address: /dns/localhost/udp/8081
  description: validator-description1
  image-url: "https://www.iota.org/favicon.png"
  project-url: "https://www.iota.org"
proof_of_possession: hpep8yY/JCj/zTEv9Ws7Qow3KO+2jrsX/yAUAykfxzS5vsg7vlwsscJpspf4XF/u

where:

  • name: human-readable validator name, defined above;
  • account-address: address derived from the account key public key;
  • authority-key: public key derived from the authority key private key;
  • protocol-key: public key derived from the protocol key private key;
  • network-key: public key derived from the network key private key;
  • gas-price: a unsigned integer value indicating the gas price proposed for the first epoch. This is unused starting with protocol version v5;
  • commission-rate: the validator commission rate, i.e., the fee charged by the validator for staking services; the default set at 2% (200);
  • network-address: the network address of the validator, defined using the host_name;
  • p2p-address: the address of the validator used for p2p activities such as state sync, defined using the host_name;
  • primary-address: the primary address of the validator used for the consensus, defined using the host_name;
  • description: human-readable validator description, defined above;
  • image-url: validator image url, defined above;
  • project-url: validator project url, defined above;
  • proof_of_possession: a BLS signature created using the authority-key, committed over the following message: intent || pubkey || address || epoch; intent is serialized to [5, 0, 0] representing an intent with scope as "Proof of Possession", version as "V0" and app_id as "Iota"; pubkey is the serialized public key bytes of the authority-key; address is the account-address; epoch is serialized to [0, 0, 0, 0, 0, 0, 0, 0].

3.2. Submit the Validator Info for the Genesis Ceremony

⚠ Warning Validators MUST create new branches and create Pull Requests whenever they want to submit data to the genesis repo.

Each validator participating in the ceremony must first clone the genesis repo:

git clone <url to genesis repo> && cd <genesis repo folder>

3.2.1 Copying and Renaming the Validator Information File

Then the validator can use the information generated before the ceremony for contributing to the genesis:

  • Copy the file generated using the instructions above into the committee folder (found in the root of the genesis directory).

  • Rename this copied file to match the human-readable validator name used during generation, maintaining any uppercase letters and spaces and using no file extension, e.g., IOTA Foundation 1.

3.2.2 Committing the Validator Information

Finally, the validator commits these files to the shared workspace:

git checkout -b <name>-info
git add .
git commit -m "add validator <name>'s information"
git push
# then create a pull request to the main branch

3.3. Extra (can be skipped if the previous steps were followed)

⚠ Warning The environment variable IOTA_PROTOCOL_CONFIG_CHAIN_OVERRIDE=mainnet is required for mainnet configuration. Ensure this is set before running any commands.

If you haven't generated your validator information before, use the following command to create it:

iota genesis-ceremony add-validator \
    --name <human-readable validator name> \
    --authority-key-file <(BLS12381KeyPair) AUTHORITY_KEY_FILE_PATH> \
    --account-key-file <(Ed25519KeyPair) ACCOUNT_KEY_FILE_PATH> \
    --network-key-file <(Ed25519KeyPair) NETWORK_KEY_FILE_PATH> \
    --protocol-key-file <(Ed25519KeyPair) PROTOCOL_KEY_FILE_PATH> \
    --network-address <multiaddr TCP> \
    --p2p-address <multiaddr UDP> \
    --primary-address <multiaddr UDP> \
    --description <human-readable validator description> \
    --image-url <validator image url> \
    --project-url <validator project url>

  • --name: human-readable validator name, e.g., IOTA Foundation 1;

  • --authority-key-file: a path of a file that contains a BLS12381 private key, e.g., ./authority.key;

  • --account-key-file: a path of a file that contains an ed25519 private key, e.g., ./account.key;

  • --network-key-file: a path of a file that contains an ed25519 private key, e.g., ./network.key;

  • --protocol-key-file: a path of a file that contains an ed25519 private key, e.g., ./protocol.key;

  • --network-address: the network address of the validator, a multiaddr TCP, e.g., /dns/localhost/tcp/8080/http;

  • --p2p-address: the address of the validator used for p2p activities such as state sync, a multiaddr UDP, e.g., /dns/localhost/udp/8084;

  • --primary-address: the primary address of the validator used for the consensus, a multiaddr UDP, e.g., /dns/localhost/udp/8081;

  • --description: human-readable validator description, e.g., this is a validator;

  • --image-url: validator image url, e.g., https://www.iota.org/favicon.png;

  • --project-url: validator project url, e.g., https://www.iota.org;

  • commission-rate: the validator commission rate, i.e., the fee charged by the validator for staking services; the default set to 2% (200);

  • proof_of_possession: a BLS signature created using the authority-key, committed over the following message: intent || pubkey || address || epoch; intent is serialized to [5, 0, 0] representing an intent with scope as "Proof of Possession", version as "V0" and app_id as "Iota"; pubkey is the serialized public key bytes of the authority-key; address is the account-address; epoch is serialized to [0, 0, 0, 0, 0, 0, 0, 0].

This command creates a new file within the committee folder. The file name is the same indicated in --name.