Introduction

The IOTA Rebased Launch Playbook is a guide for conducting the genesis ceremony procedure for an IOTA Rebased network.

During this genesis ceremony, the IOTA Stardust network is shut down, a snapshot is taken of the network state, and a new network genesis is prepared from the snapshotted data.

The genesis validators of IOTA Rebased must sign off on the new genesis state before the network can be restarted.

This book outlines the steps required to conduct the genesis ceremony, including the tools and commands required to prepare the new genesis state.

License

The IOTA Rebased Launch Playbook source is released under the Apache License v2.0.

Ceremony

The following sections lay out the step-by-step process for orchestrating an IOTA Genesis Ceremony.

Prerequisites for Validators

• IOTA CLI with the latest indicated version. Binaries are found attached to the Github Release page.
• A secure Mac or Linux machine to execute the ceremony steps. Windows is not supported for the ceremony!
• A validator machine with a public domain name that is accessible from the internet.

Process Overview

The diagram below shows the dependencies between ceremony processes and artifacts.

The following steps are performed in the ceremony:

• Step 1: Master of Ceremony creates a shared workspace for the ceremony.
• Step 2: Master of Ceremony initializes the genesis repository.
• Step 3: Validators contribute their information to the genesis repository.
• Step 4: Master of Ceremony prepares an address swap map.
• Step 5: Master of Ceremony prepares a delegator map.
• Step 6: The IOTA Stardust network is shut down. A hornet snapshot is taken by the Master of Ceremony.
• Step 7: The Master of Ceremony generates a Stardust Object Snapshot from the hornet snapshot.
• Step 8: The Master of Ceremony re-initializes the ceremony to update the chain start time.
• Step 9: The Master of Ceremony initializes validator delegations.
• Step 10: The Master of Ceremony builds an unsigned checkpoint.
• Step 11: Validators fetch blobs required for verifying and signing the checkpoint.
• Step 12: Validators verify and sign the checkpoint.
• Step 13: The Master of Ceremony finalizes the genesis state.
• Step 14: Validators start up their nodes with the new genesis state.

[Master of Ceremony only]

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

1. Repository Init

To start the Genesis Ceremony, the creation of a shared workspace where all validators will be able to share their information in time is needed.

For these instructions, it is assumed that such a shared workspace is created and managed using a git repository hosted on a git hosting provider, i.e., the genesis repo.

The following operations are performed by only one entity, i.e., the Master of Ceremony.

The Master of Ceremony creates a new git repository.

• For the actual launch, the following github repository will be used: https://github.com/iotaledger/mainnet-launch-ceremony
• For trial runs however, refer to this repository: https://github.com/iotaledger/dryrun-mainnet-launch-ceremony

[Master of Ceremony only]

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

2. Ceremony Init

The Master of Ceremony initialize the genesis directory:

iota genesis-ceremony init
git add .
git commit -m "init genesis"
git push

This creates a parameter file with the following parameters, that will be used to build the genesis:

• chain_start_timestamp_ms: UNIX time indicating the milliseconds at which the ceremony and the whole chain starts; e.g., 1736335092898 (it will be updated later, at the start of the actual ceremony)
• protocol_version: the version of the protocol to use for executing the genesis build and to run the nodes with after the genesis, e.g. 3
• allow_insertion_of_extra_objects: a flag that indicates if extra objects are allowed to be pushed to the genesis during its building; this does not include migration objects e.g., true
• epoch_duration_ms: the duration of an epoch in the chain in milliseconds, e.g., 86400000

It also creates 2 empty folders:

• committee
• signatures

The committee folder is now ready to be filled by validators in the next step.

[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.

[Master of Ceremony only]

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

4. Generate the Address Swap Map

The Master of Ceremony creates a CSV file containing the Address Swap Map. This is used to swap "origin" addresses present in the Hornet full snapshot with new "destination" addresses during the genesis bulding process. More info here.

The following code contains example values:

touch <address swap map file name>
echo "Origin,Destination" >> <address swap map file name>
echo "iota1qp8h9augeh6tk3uvlxqfapuwv93atv63eqkpru029p6sgvr49eufyz7katr,0x4f72f788cdf4bb478cf9809e878e6163d5b351c82c11f1ea28750430752e7892" >> <address swap map file name>
git add .
git commit -m "commit Address Swap Map"
git push

[Master of Ceremony only]

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

5. Create the Delegator Map

The Master of Ceremony creates a CSV file containing the Delegator Map. This is used to map a delegator address, i.e., an address that owns some assets in the migrated state, to some validator addresses; this mapping can indicate some amounts of IOTA tokens that the delegator stakes and/or transfers to the validator during the genesis building process; the staking can also be of type timelocked staking. More info here.

The following code contains example values:

touch <delegator map file name>
echo "delegator,validator,amount-nanos-to-stake,amount-nanos-to-pay-gas" >> <delegator map file name>
echo "0x4f72f788cdf4bb478cf9809e878e6163d5b351c82c11f1ea28750430752e7892,0xc296f475c7cfc9c0eab8fe5f6a13f3ab91032268194ef0c598830c45c0205b7b,1500000000000000,10000000000" >> <delegator map file name>

[Master of Ceremony only]

6. Commit the Hornet Full Snapshot

The Master of Ceremony creates a Hornet Full Snapshot and pushes it to the genesis repository. This is needed to generate a migrated state, i.e., a state representing the latest stage of the Stardust mainnet ledger. More info here.

[Master of Ceremony only]

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

7. Generate the Stardust Objects Snapshot

The Master of Ceremony creates the Stardust Objects Snapshot based on the Address Swap Map, the Address Swap Split Map and the Hornet full snapshot obtained in the previous steps. The Stardust Objects Snapshot is a BCS-encoded vector of Objects that represent the migrated state. More info here.

iota-genesis-builder iota --address-swap-split-map-path <address swap split map file path> --address-swap-map-path <address swap map file path> --snapshot-path <hornet full snapshot file path> --target-network mainnet
git add .
git commit -m "commit Stardust Objects Snapshot"
git push

[Master of Ceremony only]

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

8. Genesis Ceremony Init

Make sure that the Contribute Validator information step is completed for each validator.

The genesis repository was created and initialized in the previous steps. Since now the ceremony officially starts, the Master of Ceremony must update the chain_start_timestamp_ms with the current timestamp. This is done by executing the ceremony init again.

iota genesis-ceremony init
git add .
git commit -m "init genesis"
git push

[Master of Ceremony only]

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

9. Init Delegations

The Master of Ceremony must init the delegations that will be used to build the genesis by using the Delegator Map.

iota genesis-ceremony init-delegations --delegations-path <delegator map file name>
git add .
git commit -m "commit Delegator Map"
git push

This command creates a delegator-map file containing the delegation information.

[Master of Ceremony only]

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

10. Build the Unsigned Checkpoint

Once all validators have been added and the delegations initiated, then the Master of Ceremony can build the Unsigned Checkpoint:

iota genesis-ceremony build-unsigned-checkpoint --local-migration-snapshots stardust_object_snapshot.bin
git add .
git commit -m "commit Unsigned Checkpoint"
git push

Command flags:

• local-migration-snapshots: the path of the Stardust Object Snapshot;

This command creates:

• unsigned-genesis: a file containing:
  • the genesis Checkpoint summary info
  • the genesis Checkpoint contents (referencing the main genesis transaction and all the transactions in contained in migration.blob by their digest),
  • the main genesis transaction, instantiating the system and framework packages and objects,
  • the effects of such transaction,
  • the events of such transaction,
  • the additional objects (not coming from migration) for the genesis, normally this is empty;
• migration-sources: a file containing the path of the Stardust Object Snapshot;
• migration.blob: a file containing the list of transactions that are used to push migrated objects at genesis time into the node DB once started, plus the list of such objects in a BCS-encoded form; these transactions are part of the genesis Checkpoint.
• token-distribution-schedule: a file used internally to indicate the values of assets to "minted" during the genesis execution; these are assets that are destroyed from the migrated objects and re-created in the form of Coin<IOTA>, TimelockedStakedIota or StakedIota in favor of validators; these assets are owned by the delegators indicated in the Delegator Map.

[Validator only]

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

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

11. Fetch blobs

Before you can verify and sign the genesis, you need to fetch the blobs required for the process. These are:

• latest-full_snapshot.bin - the hornet snapshot
• stardust_object_snapshot.bin - the stardust snapshot generated from the hornet snapshot
• migration.blob - contains migrated ledger state, output of "building the insigned genesis"

The genesis.blob will not be available at this step, as it can only be generated in Step 13 once all validators signed the genesis.

The script also verifies the integrity of the blobs by checking the hash of the files against those committed to the repository.

./fetch_blobs.sh

[Validator only]

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

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

12 Sign the Checkpoint

Once the Unsigned Checkpoint is built and the blobs fetched, each validator will need to verify and sign the checkpoint:

(git checkout main)
git pull
git checkout -b <name>-signature
iota genesis-ceremony verify-and-sign --key-file <(BLS12381KeyPair) AUTHORITY_KEY_FILE_PATH>
git add .
git commit -m "sign Checkpoint"
git push
# then create a pull request to the main branch

Command flags:

• --key-file: the path of the validator's authority private key, e.g., ./authority.key;

This command creates a new file within the signatures folder. The file name is the same indicated in --name for each validator. This file ia a binary file containing the digital signature of the Unsigned Genesis.

[Validator only]

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

13. Finalize Genesis

Once all validators signed the Checkpoint, then all participants can finalize their genesis blob locally:

iota genesis-ceremony finalize

This command creates the genesis.blob file that is generated from unsigned-genesis by aggregating signatures of validators on the checkpoint summary. This, together with the migration.blob file generated in the previous steps, can be used to run the node.

Alternatively, the genesis.blob can be downloaded via the fetch_blobs.sh script once the Master of Ceremony has finalized the genesis and uploaded the genesis.blob to storage.

[Validator only]

14. Run Validator Nodes

There are two files that your validator needs to run the new network:

• migration.blob
• genesis.blob

Both of them can be grabbed by executing the fetch_blobs.sh script of the genesis repository.

First time running the node after genesis ceremony

Option 1: Running with chain override

Since the new genesis has just been generated, your node software doesn't recognize it yet as mainnet. Therefore, you need to override this parameter in the chain configuration.

The following docker-compose snippet shows how to do this:

services:
  iota-node:
    image: iotaledger/iota-node:v0.11.1-alpha
    ports:
      - "8080:8080"
      - "8081:8081"
      - "8084:8084/udp"
      - "9000:9000"
      - "9184:9184"
    volumes:
      - ./key-pairs:/opt/iota/key-pairs/:ro
      - ./validator.yaml:/opt/iota/config/validator.yaml:ro
      - ./genesis.blob:/opt/iota/config/genesis.blob:ro
      - ./migration.blob:/opt/iota/config/migration.blob:ro
      - ./iotadb:/opt/iota/db:rw
    environment:
      - IOTA_PROTOCOL_CONFIG_CHAIN_OVERRIDE=mainnet
    command: [
      "/usr/local/bin/iota-node",
      "--config-path",
      "/opt/iota/config/validator.yaml",
    ]

Option 2: Running with a fresh software release

Once the genesis is finalized, the IOTA Foundation will release a new version of the node software that recognizes the new genesis as the mainnet. Building and releasing this software is a process that takes some time, so you might need to wait a bit before it is available. However, once it is out, you don't need to run your node with the IOTA_PROTOCOL_CONFIG_CHAIN_OVERRIDE environment variable anymore.

Optional Genesis Ceremony Commands

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

Here are some commands that aren’t mandatory for the Genesis Ceremony flow but might still be useful to know about.

Examine Genesis Checkpoint

Examine the details of the Genesis checkpoint.

iota genesis-ceremony examine-genesis-checkpoint

More info here.

Validate State

Validate the current state of the Genesis.

iota genesis-ceremony validate-state

More info here.

Init Token Distribution Schedule

Initialize token distribution schedule.

iota genesis-ceremony init-token-distribution-allocation --token-allocations-path <file_path>

More info here.

List Validators

List the current validators in the Genesis.

iota genesis-ceremony list-validators

Examine Genesis Checkpoint

The examine_genesis_checkpoint command is a diagnostic tool designed to analyze the Genesis checkpoint state.

The command begins by extracting the system object from the genesis checkpoint and converting it to a format suitable for analysis. It prepares detailed mappings and distributions of validators, IOTA allocations, and on-chain objects to facilitate structured examination.

Validation steps:

1. Validator Information Preparation The set of active validators in the genesis checkpoint is analyzed and mapped by name and staking pool ID. This mapping enables quick access to validator metadata and facilitates the verification of validator-specific information, such as their keys, addresses, and staking pools.
2. IOTA Distribution Analysis The distribution of IOTA tokens is compiled into a structured format. The tool aggregates allocations for entities such as the storage fund, validators, and other recipients. It calculates total token supplies and verifies their consistency with the IOTA Treasury Cap, ensuring no discrepancies in token accounting. When a migrated state is present during the genesis ceremony, this analysis must take into account that IOTA Tokens are also stored in Stardust outputs.
3. Object Categorization and Mapping All objects in the genesis checkpoint are categorized and mapped based on their type. Key categories include:
   • Gas Coins: Represent IOTA tokens.
   • Staked IOTA: Tokens allocated to staking pools.
   • Timelocked Staked IOTA: Staked tokens with time-based restrictions.
   • Timelock Balance IOTA: Timelocked IOTA tokens.
   • Basic Output: Stardust output coming from migration.
   • Alias Output: Stardust output coming from migration.
   • Nft Output: Stardust output coming from migration.
   • Packages: Move packages.
   • Coin Metadata: Metadata for tokens.
   • Other Objects: Objects not fitting into the above categories. Each object is associated with its owner.
4. Total Supply Validation The total supply of IOTA tokens, including staked and allocations, is calculated and verified against the genesis TreasuryCap. Any inconsistency triggers an error, ensuring accurate token accounting.
5. Signature and Migration Data Validation Validator signatures associated with the genesis checkpoint are verified for authenticity and correctness.

Validate State

Validate the current state of the Genesis. Contains 3 validation steps:

1. Input validation - the validation begins by evaluating global constraints, such as the allowance for extra objects and the presence of validators. If extra objects are not permitted and any are present, an error is immediately raised to enforce the restriction. This ensures that the input remains consistent with the system's intended configuration.

   Each validator is then individually validated to verify that its metadata is correct and adheres to specific rules. Validator metadata checks to ensure it meets requirements for length, character set, format, and logical correctness. The process involves validating key metadata fields such as names, descriptions, and various network addresses:

   • Name Validation: The name must consist of ASCII characters and must not exceed a predefined maximum length. This ensures compatibility and readability.
   • Description Validation: Descriptions must also be ASCII and within the allowable length, ensuring that metadata remains concise and standardized.
   • URL Validation: URLs for images and projects must not exceed the maximum length. This prevents excessively long or malformed URLs from being accepted.
   • Network Address Validation: Each network address (e.g., network_address, p2p_address, primary_address) must be ASCII-compliant and adhere to the length constraints. Additionally, these addresses must be correctly formatted for their respective types.
   • Address Format Checks: Specific addresses, such as p2p_address and primary_address, must be valid in the anemo protocol context. Any errors in parsing or interpreting these addresses result in immediate validation failure.
   • The validator's authority public key is extracted, and its proof of possession is verified. This cryptographic check ensures that the validator legitimately owns the provided authority key and account address.
   • The commission rate for validators must not exceed 100%, ensuring logical and acceptable fee structures.

   #![allow(unused)]
   fn main() {
   pub name: String,
   pub account_address: IotaAddress,
   pub authority_key: AuthorityPublicKeyBytes,
   pub protocol_key: NetworkPublicKey,
   pub network_key: NetworkPublicKey,
   pub gas_price: u64,
   pub commission_rate: u64,
   pub network_address: Multiaddr,
   pub p2p_address: Multiaddr,
   /// Primary address used for consensus-related inter-node communication.
   pub primary_address: Multiaddr,
   pub description: String,
   pub image_url: String,
   pub project_url: String,
   
   /// GenesisValidatorInfo
   pub proof_of_possession: AuthoritySignature,
   }

2. Token Distribution Schedule Validation - the validation process for the token distribution schedule ensures that the allocation and staking of tokens meet predefined rules and thresholds. The process begins with verifying the token distribution schedule itself, ensuring that all allocations are consistent with predefined rules. If a distribution schedule is provided, it undergoes a thorough validation to confirm that the total amount of tokens allocated does not exceed the pre-minted supply. Each allocation is evaluated for compliance with governance requirements, including verifying that tokens are staked with valid validators.

   Additionally, the process validates that all tokens allocated for staking are associated with valid validators. Each validator referenced in the schedule must exist and be available to participate in the network. The total staked tokens for each validator are aggregated, and their stakes are evaluated against the minimum stake threshold defined in the system's governance rules. This threshold ensures that validators have sufficient tokens staked to actively and effectively contribute to the network's operations. Any validator failing to meet the minimum stake requirement is flagged as non-compliant, with detailed error messages identifying the specific issues.

3. Output Validation - the output validation flow ensures that the generated output—representing the initial chain state—is correct, consistent, and adheres to all predefined system requirements and rules. The validation begins by retrieving the generated genesis checkpoint. If no genesis has been built, the validation process terminates early, as there is no output to validate. We can highlight 7 validation steps:

   1. Genesis System State Validation The genesis system state is verified to ensure it adheres to the expected configuration. For non-testing environments, the genesis state must be of version V1. System components such as the randomness state, authenticator state, bridge object, and coin denylist are validated to confirm their presence or absence based on the protocol configuration.
   2. Validator Metadata and Pool Mapping Active validators in the genesis state are matched against the input validators. The metadata of each validator is validated against its corresponding input definition, including: - IOTA address - Authority and network keys - Gas price and commission rate - Name, description, and associated URLs This step ensures that validators in the genesis state are configured exactly as defined in the input.
   3. System Parameters Validation Chain parameters such as protocol version, epoch duration, validator thresholds, and grace periods are checked to ensure they match the configuration specified in the input. Key values like the storage fund balance and epoch start timestamp are validated to confirm proper initialization.
   4. Token Distribution Validation The token distribution schedule is validated to ensure that all allocations are accurately reflected in the genesis state. The total supply is checked against the sum of the pre-minted supply and all allocations, ensuring no discrepancy.
   5. Signature Validation Validator signatures are checked to ensure that all provided signatures correspond to known validators and are valid against the genesis checkpoint. This step confirms that the initial state is cryptographically authenticated.
   6. Migration Data Validation If migration data is present, it is validated against the unsigned genesis state to detect and prevent corrupted or malicious data. Genesis containing migrations must include valid migration data. The validation is based on cryptographic links (i.e., hash digests) between genesis transactions, transaction effects and events.
   7. Object Accounting All gas and staked objects are accounted for, ensuring no surplus or missing objects unless extra objects are explicitly permitted by the configuration. This prevents unintended discrepancies in the genesis state.

Init Token Distribution Schedule

The InitTokenDistributionSchedule command initializes and configures a token distribution schedule based on input provided in a CSV file.

This operation is crucial ONLY WHEN THE GENESIS IS CREATED WITHOUT MIGRATION, for setting up the distribution of tokens during the network's genesis phase. However, in the case of a migration, this command shall not be used. In that case, init-delegations should be used.

Example of csv file:

recipient-address,amount-nanos,staked-with-validator,staked-with-timelock-expiration
<faucet-address>,1500000000000000,,
<validator-1-address>,1500000000000000,<validator-1-address>,
<validator-2-address>,1500000000000000,<validator-2-address>,

This is useful for allocating funds for a faucet, or for distributing the initial stake to validators.

Tools

The following sections lay out the commands and procedures that can be used in the context of the genesis.

Address Swap Map

Address Swap is a process used during the creation of a Stardust Objects snapshot from a Hornet snapshot. This process ensures that assets (including IOTA tokens) in the Hornet snapshot are reallocated to new addresses specified in a CSV Address Swap Map.

During the migration process, the system checks whether the owner address of each output is present in the Address Swap Map. If it is, the address is replaced with the corresponding destination address specified in the map.

To ensure correctness, the ledger state is verified after the migration. This involves double-checking that all swapped addresses are correctly updated for every output.

The validation process occurs after all outputs have been processed. During this step, the system confirms that every address in the Address Swap Map has been swapped at least once. If any address remains unswapped, an error is returned, ensuring the integrity of the migration process.

Address Swap Map CSV format:

This must be a CSV file with two columns, where an entry contains in the first column an Bech32 format present in the Hornet full-snapshot and in the second column an IotaAddress that will be used for the swap.

• Columns: Origin: The address in the Hornet snapshot from which assets are taken. Type - bech32. Destination: The new address where assets are allocated in the Stardust Object snapshot. Type - IotaAddress.
• Constraints: Origin addresses must exist in the Hornet snapshot. Destination addresses must be valid IOTA addresses.

Origin,Destination
iota1qp8h9augeh6tk3uvlxqfapuwv93atv63eqkpru029p6sgvr49eufyz7katr,0xa12b4d6ec3f9a28437d5c8f3e96ba72d3c4e8f5ac98d17b1a3b8e9f2c71d4a3c
iota1qp7h2lkjhs6tk3uvlxqfjhlfw34atv63eqkpru356p6sgvr76eufyz1opkh,0x42d8c182eb1f3b2366d353eed4eb02a31d1d7982c0fd44683811d7036be3a85e

How to use Address Swap:

1. Prepare Address Swap Map CSV file.
2. Invoke the iota-genesis-builder command: Use the following command to execute the process:

iota-genesis-builder iota --address-swap-map-path address_swap.csv ...

Address Swap Split Map

Address Swap Split is a process used during the creation of a Stardust Objects snapshot from a Hornet snapshot. This process ensures that some assets, i.e., IOTA tokens and timelocked IOTA tokens, in the Hornet snapshot are reallocated to new addresses specified in a CSV Address Swap Split Map.

During the migration process, the system checks whether the address of the Address Unlock Condition of each output is present in the Address Swap Split Map as an Origin Address. If it is, this address is replaced with the corresponding Destination Address specified in the map. However, differently from the Address Swap Map, here possibly not all outputs are swapped. The amount (in nanos) of IOTA tokens and timelocked IOTA tokens to be swapped to is indicated in the Address Swap Split Map as Tokens and TokensTimelocked numerical values. In addition, there may be multiple Destination Addresses associated with the same Origin Address. All of this means that, probably, during this process, some outputs could be split.

To ensure correctness, the ledger state is verified during the migration. This involves double-checking that all the Tokens and TokensTimelocked amount targets have been met after all outputs contained in the Hornet snapshot have been processed. If a target remains unsatisfied, an error is returned, which means that the Address Swap Split Map was constructed with some amount targets that are greater than the value of the assets owned by the Origin Address in the Hornet snapshot.

After that the Address Swap Split operation has been performed, some assets might still be owned by the indicated Origin Addresses. This means that the Address Swap Map can be used to swap these remainder assets to a new Destination Address.

Address Swap Split Map CSV format:

This must be a CSV file with four columns, where an entry contains in the first column an Bech32 format present in the Hornet full-snapshot, in the second column an IotaAddress that will be used for the swap, and in the other columns the tokens target amounts.

• Columns: Origin: The address in the Hornet snapshot from which assets are taken. Type - bech32. Destination: The new address where assets are allocated in the Stardust Object snapshot. Type - IotaAddress. Tokens: The amount of IOTA tokens to swap indicated in NANO. Type - u64. TokensTimelocked: The amount of timelocked IOTA tokens to swap indicated in NANO. Type - u64.
• Constraints: Origin addresses must exist in the Hornet snapshot. Destination addresses must be valid IOTA addresses. The two amounts in nano must represent amounts of assets owned by the Origin addresses in the Hornet snapshot.

Origin,Destination,Tokens,TokensTimelocked
iota1qp8h9augeh6tk3uvlxqfapuwv93atv63eqkpru029p6sgvr49eufyz7katr,0x1336d143de5eb55bcb069f55da5fc9f0c84e368022fd2bbe0125b1093b446313,107667149000,107667149000
iota1qp8h9augeh6tk3uvlxqfapuwv93atv63eqkpru029p6sgvr49eufyz7katr,0x83b5ed87bac715ecb09017a72d531ccc3c43bcb58edeb1ce383f1c46cfd79bec,388647312000,0

How to use Address Swap Split:

1. Prepare Address Swap Split Map CSV file.
2. Invoke the iota-genesis-builder command: Use the following command to execute the process:

iota-genesis-builder iota --address-swap-split-map-path address_swap_split.csv ...

Delegator Map

The concept of a delegator is crucial for establishing the validator set and providing gas tokens when building a genesis with a migrated state, i.e., a state representing the latest stage of the Stardust mainnet ledger. The delegator is an existing address present in the migrated state that holds IOTA Foundation funds. These funds are partially allocated to meet the staking requirements for validators and to supply them gas tokens during the genesis.

The delegations are needed because:

• all validators participating to the genesis ceremony need to have at least a minimum required stake to qualify as validators on the new network;
• validators also require gas tokens to execute transactions during the initial phases of the network.

It is REQUIRED that, given the migrated state, delegators hold at least the amount of IOTA/timelocked IOTA tokens indicated in the Delegator Map. The genesis building process will take care of re-allocating these funds as indicated in the map.

Creating delegations

During a genesis building, a delegator-map.csv file is used to define the relationship between delegators and validators. This file specifies different rows where:

• Delegator Address: The address contributing funds.
• Validator Address: The address receiving funds.
• Staked Amount: The amount of tokens (in nanos) allocated to the validator's stake.
• Gas Token Amount: The amount of tokens (in nanos) allocated for gas.

Example of delegator-map.csv:

delegator,validator,amount-nanos-to-stake,amount-nanos-to-pay-gas
0x4f72f788cdf4bb478cf9809e878e6163d5b351c82c11f1ea28750430752e7892,0xc05734060fc9ced23bc92a0998e86e4edecf051098de432ccc8c73aa87f745da,50000000000000000,10000000000

• Delegator Address: 0x4f72f788cdf4bb478cf9809e878e6163d5b351c82c11f1ea28750430752e7892
• Validator Address: 0xc05734060fc9ced23bc92a0998e86e4edecf051098de432ccc8c73aa87f745da
• Staked Amount: 50,000,000,000,000,000 nanos.
• Gas Tokens: 10,000,000,000 nanos.

This mapping ensures validators receive the necessary resources to join the validator set and participate in the network.

Genesis builder and the Stardust Objects Snapshot

The Stardust Objects Snapshot is a BCS-encoded vector of Objects that represent the migrated state. The migration can happen from a ledger compliant with the Stardust protocol. In particular, in order to create a Stardust Objects Snapshot, a Hornet Full Snapshot is required.

iota-genesis-builder iota --address-swap-split-map-path <address swap split map file path> --address-swap-map-path <address swap map file path> --snapshot-path <hornet full snapshot file path> --target-network <target network name>

Command flags:

• --address-swap-split-map-path: the path of an Address Swap Split Map, e.g., ./address_swap_split.csv
• --address-swap-map-path: the path of an Address Swap Map, e.g., ./address_swap.csv
• --snapshot-path: the path of the Hornet full snapshot e.g., ./full_snapshot_latest.bin
• --target-network: a string that generates the salt used for hashing the genesis transaction and obtaining its transaction id, e.g., mainnet

Additionally:

• --disable_global_snapshot_verification: flag used to disable the verification of a Hornet snapshot, namely, if true, this skips the check that the Hornet snapshot must be a full snapshot; thus, for a correct migration, this flag must be false.

This command generates a file named stardust_object_snapshot.bin.

Hornet Snapshot

The Hornet Snapshot is a snapshot of the Hornet node database. In particular, during the genesis ceremony, a Hornet Full Snapshot is required in order to create a Stardust Objects Snapshot.

The Hornet node needs to be shut down before executing the following command:

hornet tools db-snapshot --sourceDatabasePath <database path> --targetSnapshotPath <target snapshot path> --targetIndex <milestone index> --global

The IOTA Foundation will indicate the target milestone index to use here, stemming from the last confirmed milestone on the Stardut mainnet.

Command flags:

• --sourceDatabasePath: the path to the source database, e.g., ./data
• --targetSnapshotPath: the path to the target snapshot file, e.g., ./16382940_full_snapshot.bin
• --targetIndex: the target milestone index, e.g., 16382940
• --global: a flag to set to create a global snapshot, i.e., SEP equal to milestone parents

Testing the Genesis creation locally

There are two ways to create a genesis:

• Manually via the iota genesis-ceremony commands. In order to launch a live production network this setup is needed, since then one can control several validators joining, allocations, etc. A genesis ceremony is a coordinated process involving multiple participants (nodes, validators, etc) to create and finalize the genesis creation.
• Automatically via the iota genesis command, which outputs a config directory suitable for running a local network. It's useful for local testing, debugging purposes.

All this means that, the genesis created through the iota genesis command can be used just for testing purposes because it doesn't provide ways to configure some parameters like custom validators and their stakes.

Creation Genesis locally flow:

1. The Hornet snapshot is a file containing information about a Stardust ledger which can be used to represent a migrated state. Thus, a genesis can be build without this file, and be considered "without migration", or it can include this file and be used to start a network with some predetermined Objects.

iota-genesis-builder -- --disable-global-snapshot-verification iota --snapshot-path <path_to_hornet_snapshot_file.bin> --target-network <network_name>

For detailed instructions, refer to the Stardust Object Snapshot Generation.

2. Generate a test configuration directory containing all necessary settings for running a local network, including validator information, and local migration snapshots. The number of validators can be customized as required.

iota genesis --working-dir <working_directory> -f --with-faucet --num-validators <number_of_validators> --local-migration-snapshots <path_to_startdust_snapshot_file.bin>

For more information, consult the Test Configuration Generation.

3. Launch the network locally using the generated configuration. This step initializes the network with the specified settings and validators.

iota start --network.config <working_directory>

Additional details are available in the Local Network Run.

Generate Test Configuration

Bootstrap and initialize a new Iota network:

iota genesis --working-dir <working_directory> -f --with-faucet --num-validators <number_of_validators> --local-migration-snapshots <path_to_startdust_snapshot_file.bin>

Command flags:

• (Optional)--from-config: start genesis with a given config file. Read the file that was written by --write-config command.
• (Optional)--write-config: build a genesis config, write it to the specified path, and exit. Example of written config:

---
ssfn_config_info: ~
validator_config_info: ~
parameters:
  chain_start_timestamp_ms: 1737646154723
  protocol_version: 1
  allow_insertion_of_extra_objects: true
  epoch_duration_ms: 86400000
accounts:
  - address: "0x3529ec0ab25aa843942715194dd4eee1fc1d5c83dfef28e839838fa0f0b36aa0"
    gas_amounts:
      - 30000000000000000
      - 30000000000000000
      - 30000000000000000
      - 30000000000000000
      - 30000000000000000
  - address: "0x42d8c182eb1f3b2366d353eed4eb02a31d1d7982c0fd44683811d7036be3a85e"
    gas_amounts:
      - 30000000000000000
      - 30000000000000000
      - 30000000000000000
      - 30000000000000000
      - 30000000000000000
  - gas_amounts:
      - 30000000000000000
      - 30000000000000000
      - 30000000000000000
      - 30000000000000000
      - 30000000000000000
migration_sources:
  - Local: stardust_object_snapshot.bin

• (Optional)--working-dir: path to the directory that contains configurations files.
• (Optional)--force: a flag used to forces overwriting existing configuration. Default value is false.
• (Optional)--epoch-duration-ms: epoch duration in ms to be set in the genesis config, the default is 86400000 (24h).
• (Optional)--benchmark-ips: a list of IP addresses used to generate a genesis configuration optimized for benchmarking. If no persisted configuration file or compatible keystore exists, the provided ips will be used to create a benchmark-specific genesis configuration, including a keystore for gas keys. This enables streamlined bootstrapping of a network for testing purposes. If a configuration already exists, the --force flag is required to regenerate the setup.
• (Optional)--with-faucet: a flag used to creates an extra faucet configuration for iota persisted runs. Default value is false.
• (Optional)--num-validators: set the number of validators in the network; since becoming a validator requires a certain amount of staked coins, this commands makes so that a delegator will stake 1.5 million IOTA for each validator. Default value is 4.
• (Optional)--local-migration-snapshots: path to the local based stardust snapshot.
• (Optional)--remote-migration-snapshots: path to the remote based stardust snapshot. A remote snapshot is one that is downloaded from the specified URL, e.g. https://api.devnet.iota.cafe.
• (Optional)--delegator: the delegator is an existing address in the migrated state that holds IF funds which will be partially used for the genesis distribution of validator stakes and gas tokens on the new network; when building a genesis for a local network, a single delegator is used with default allocations for all validators instead of a Delegator Map.

Run genesis locally

iota start --network.config <working_directory>

Start a local network in two modes: saving state between re-runs and not saving state between re-runs. By default, iota start will start a local network from the genesis blob that exists in the IOTA config default dir or in the config_dir that was passed. If the default directory does not exist and the config_dir is not passed, it will generate a new default directory, generate the genesis blob (without migration), and start the network. Note that if you want to start an indexer, Postgres DB is required.

Command flags:

• (Optional)--config-dir aliased as - network.config: сonfig directory that will be used to store network config, node db, keystore.
• (Optional)--force-regenesis: a flag used to generates new genesis is created each time this flag is set, and state is not persisted between runs. Only use this flag when you want to start the network from scratch every time you run this command. To run with persisted state, do not pass this flag and use the iota genesis command to generate a genesis that can be used to start the network with.
• (Optional)--with-faucet: starts a faucet with default host and port: 0.0.0.0:9123. When providing a specific value, please use the = sign between the flag and value: --with-faucet=6124 or --with-faucet=0.0.0.0, or --with-faucet=0.0.0.0:9123.
• (Optional)--faucet-amount: set the amount of nanos that the faucet will put in an object. 200 IOTA is default value.
• (Optional)--indexer-feature-args: enabling indexer-related features (like the indexer, GraphQL hosts, and PostgreSQL) only works if the indexer feature is enabled.
• (Optional)--fullnode-rpc-port: port to start the Fullnode RPC server on. Default port is 9000.
• (Optional)--epoch-duration-ms: set the epoch duration. Can only be used when --force-regenesis flag is passed or if there's no genesis config and one will be auto-generated. When this flag is not set but --force-regenesis is set, the epoch duration will be set to 60 seconds.
• (Optional)--no-full-node: a flag used to starts the network without a fullnode.
• (Optional)--committee-size: used to set the number of validators in the network. If a genesis was already generated with a specific number of validators, this will not override it; the user should recreate the genesis with the desired number of validators.
• (Optional)--local-migration-snapshots: the path to local migration snapshot files.
• (Optional)--remote-migration-snapshots: the path to remote migration snapshot files. A remote snapshot is one that is downloaded from the specified URL, e.g. https://api.devnet.iota.cafe. Is required to use this flag when you have use a local/remote migration snapshot.
• (Optional)--delegator: the delegator is an existing address on the old network that holds IF funds which will be partially used for the genesis distribution of validator stakes and gas tokens on the new network.

Validator Commands

Validator commands are used to manage, operate, and secure validator nodes. They handle tasks such as node setup, consensus participation, info and key management and governance.

1. Make Validator Info

Generate a validator.info file and 4 key pair files (account, network, authority, protocol). The network, authority and protocol keys will need to be copied over to the validator node and included in the YAML configuration of the node. See Validator Node Configuration

Args:

• name - serves as a human-readable identifier for the validator.
• description - provides additional context, description about the validator.
• image-url - adds a visual identity to the validator, simplify visual regocnition in the explorers.
• project-url - specifies where the validator's node is hosted or can be accessed.
• host-name - specifies where the validator's node is hosted or can be accessed.

Command structure:

iota validator make-validator-info <name> <description> <image-url> <project-url> <host-name>

2. Become Candidate

Submit an on-chain transaction to become a validator candidate. The parameter is the file path to the validator.info generated by MakeValidatorInfo.

Args:

• file - path to the validator.info file.
• (Optional)gas-budget - gas budget for this transaction.

Command structure:

iota validator become-candidate <validator.info file path>

3. Join Validators

Once you collect enough staking amount, run this command to become a pending validator. A pending validator will become active and be eligible join the committee starting from next epoch.

Args:

• (Optional)gas-budget - gas budget for this transaction.

Command structure:

iota validator join-validators

4. Leave Validators

Leave the validators (and potentially the committee) starting with the next epoch.

Args:

• (Optional)gas-budget - gas budget for this transaction.

Command structure:

iota validator leave-validators

5. Display Metadata

Display metadata about the validator.

Args:

• validator-address - address of the validator.
• json - boolean indicating whether to format the metadata in JSON or not.

Command structure:

iota validator display-metadata $VALIDATOR_ADDRESS  --json true

Example of metadata fields with description in JSON format:

{
  "metadata": {
    "iota_address": "String representing the validator's unique address on the IOTA network.",
    "authority_pubkey_bytes": "Base64-encoded public key for authority purposes.",
    "network_pubkey_bytes": "Base64-encoded public key for network communication.",
    "protocol_pubkey_bytes": "Base64-encoded public key for protocol operations.",
    "proof_of_possession_bytes": "Base64-encoded proof that the validator possesses the private key associated with the public key.",
    "name": "Human-readable name of the validator.",
    "description": "Short description about the validator or its organization.",
    "image_url": "URL to the validator's logo or image.",
    "project_url": "URL to the validator's website.",
    "net_address": "Network address of the validator node.",
    "p2p_address": "P2P communication address for the validator.",
    "primary_address": "Primary address used for network operations.",
    "next_epoch": {
      "authority_pubkey_bytes": "Optional Base64-encoded authority public key for the next epoch.",
      "proof_of_possession": "Optional Base64-encoded proof of possession for the next epoch.",
      "network_pubkey_bytes": "Optional Base64-encoded network public key for the next epoch.",
      "protocol_pubkey_bytes": "Optional Base64-encoded protocol public key for the next epoch.",
      "net_address": "Optional network address for the next epoch.",
      "p2p_address": "Optional P2P address for the next epoch.",
      "primary_address": "Optional primary address for the next epoch."
    }
  },
  "voting_and_gas": {
    "voting_power": "Validator's voting power in the network.",
    "operation-cap-id": "Object ID representing the operation capability of the validator.",
    "gas_price": "Gas price set by the validator for the current epoch.",
    "commission_rate": "Commission rate charged by the validator.",
    "next_epoch": {
      "stake": "Stake amount for the next epoch.",
      "gas_price": "Gas price for the next epoch.",
      "commission_rate": "Commission rate for the next epoch."
    }
  },
  "staking_pool": {
    "staking_pool_id": "ID of the staking pool object associated with the validator.",
    "activation_epoch": "Epoch when the staking pool became active.",
    "deactivation_epoch": "Epoch when the staking pool was deactivated, if applicable.",
    "staking_pool_iota_balance": "Total number of IOTA tokens in the staking pool.",
    "rewards_pool": "Total rewards to be distributed at the end of the epoch.",
    "pool_token_balance": "Total number of pool tokens issued.",
    "pending": {
      "stake": "Pending stake amount for the current epoch.",
      "total_iota_withdraw": "Total IOTA withdrawn during the current epoch.",
      "pool_token_withdraw": "Total pool tokens withdrawn during the current epoch."
    },
    "exchange_rates": {
      "exchange_rates_id": "ID of the exchange rate table object.",
      "exchange_rates_size": "Number of exchange rates in the table."
    }
  }
}

6. Update Metadata

Update the validator metadata.

Submit an on-chain transaction to update name, description, image url, project url, netowork address, primary address, p2p address, network public key, protocol public key, authority public key.

Args:

• (Optional)gas-budget - gas budget for this transaction.

Command structure:

iota validator update-metadata <key> <new-value>

7. Report Validator

Report or un-report a validator as bad or non-performant. Validator can be reported because of some malicious behavior or performance issues.

Validator reporting succeeds if all the following are satisfied:

• both the reporter in cap and the input reportee_addr are active validators.
• reporter and reportee not the same address.
• the cap object is still valid. This function is idempotent.

Args:

• operation-cap-id - validator's ID can be found by using the display-metadata subcommand. Optional when sender is reporter validator itself and it holds the Cap object. Required when sender is not the reporter validator itself.
• reportee-address - the Iota Address of the validator is being reported or un-reported/
• (Optional)undo-report - if true, undo an existing report.
• (Optional)gas-budget - gas budget for this transaction.

Command structure:

iota validator report-validator $ADDRESS_OF_NON_PERFORMANT_VALIDATOR

8. Serialize Payload For Pop

Serialize the payload that is used to generate Proof of Possession. Proof of Possession - it's a verification process whereby assurance is obtained that the owner of a key pair actually has the private key associated with the public key. This is allows the signer to take the payload offline for an Authority protocol BLS keypair to sign.

Args:

• account-address - authority account address encoded in hex with 0x prefix.
• authority-public-key - authority public key encoded in hex.

Command structure:

iota validator serialize-payload-pop --account-address $ACCOUNT_ADDRESS --authority-public-key $BLS_PUBKEY

Command result:

Serialized payload: BQAAgAGZ8l72H4AyuRRjZGCYLFzG8TTvHdrnZlfyy/7B6/yNCXN0CA32/PDcuLxLDY4K9dgOu/8rTFmfVPQtYxLfwxQnYHjBzDR+u77FGYviWFE/OGuTDQLCdJqAPiMwlV69GhARERERFQTpNQ5jXWXNOMzSwClDTGo6SA2JR6m6ahWyFQAAAAAAAAAA

9. List

Get a list of the validators in the network. Use the display-metadata command to see the complete data for a validator.

Command structure:

iota validator list

Example of command result:

╭────────────────────────────────────────────────────────────────────┬───────────────────────────────┬──────────────────────┬───────────────╮
│ iota address                                                       │ name                          │ staking pool balance │ pending stake │
├────────────────────────────────────────────────────────────────────┼───────────────────────────────┼──────────────────────┼───────────────┤
│ 0xa276b4c076fff55588255630e9ee35cf0d07e8d80c78991cfd58b43b687b4206 │ IOTA Foundation 2             │ 35656599527382853    │ 0             │
│ 0xc571a9bb5da166b1de54ff90846399ddb63385c769e75cea4dce751e2fd29e55 │ Tangle Ecosystem Association  │ 35659211813708295    │ 10000000000   │
│ 0xb64051fe5048486c0a215ff1ec48dc63214528bcc4d00c27d151404dbd717ba4 │ IOTA Ecosystem DLT Foundation │ 35608690485959502    │ 10000000000   │
│ 0x392316417a23198afeeb80d9fec314c65162ab5ad18f8a4c3375d31deab29670 │ IOTA Foundation 1             │ 35608163183652856    │ 26500000000   │
│ 0x6d6416b3d8978e8821d875ec703daeefe0a2177037b0350bb2f760a426dcae03 │ Validator1                    │ 4356274051328678     │ 25000000000   │
│ 0x2e312d87e22b39d5bc3946060917e8be4a9d2076e7da8da07f016b07ad123d06 │ Validator2                    │ 4304476672123940     │ 25000000000   │
│ 0xdfb52cfe07f7c87f23cc829929797a5509bbc8693e4aa180d0dd8ed034855042 │ Validator3                    │ 3494574866394500     │ 0             │
│ 0xe1a4e6303a75ec1fa70e086368bebc3a615394d83307a056d4eabf729b6f6a5f │ Validator4                    │ 4183319150671519     │ 10000000000   │
╰────────────────────────────────────────────────────────────────────┴───────────────────────────────┴──────────────────────┴───────────────╯