Skip to main content

IOTA Genesis Ceremony CLI

The IOTA CLI genesis-ceremony command allows the orchestration of an IOTA Genesis Ceremony, where multiple remote validators can sign a genesis blob. Each step persists in a file structure that can be shared (for instance, via GitHub) with the validators.

Commands​

Typing iota genesis-ceremony --help into your terminal or console displays the following information on available commands.

Create an IOTA Genesis Ceremony with multiple remote validators

Usage: iota genesis-ceremony [OPTIONS] <COMMAND>

Commands:
  init                        Initialize a Genesis builder which can be configured with validators
  validate-state              Validate the current state of the Genesis builder
  add-validator               Add a validator to the Genesis builder
  add-token-allocation        Add token allocation for the given address
  list-validators             List the current validators in the Genesis builder
  build-unsigned-checkpoint   Build the Genesis checkpoint
  examine-genesis-checkpoint  Examine the details of the built Genesis checkpoint
  verify-and-sign             Verify and sign the built Genesis checkpoint
  finalize                    Create the Genesis blob file from the current configuration
  help                        Print this message or the help of the given subcommand(s)

Options:
      --path <PATH>                          The directory where the Genesis builder will be stored. Defaults to the current directory
      --protocol-version <PROTOCOL_VERSION>  The protocol version to use for this snapshot [default: 1]
  -h, --help                                 Print help
  -V, --version                              Print version

Examples​

The following example demonstrates how to build a genesis blob.

Initialize the Genesis Builder​

This command creates a structure in the file system to persist the genesis builder. Afterward, the below commands can be used to set additional configurations.

iota genesis-ceremony init

Toggle created parameters file

chain_start_timestamp_ms: 1724332830839
protocol_version: 1
allow_insertion_of_extra_objects: true
epoch_duration_ms: 86400000

Add Validators​

Each validator is added one at a time, and is persisted in the committee folder.

iota genesis-ceremony add-validator \
    --name validator0 \
    --authority-key-file validator-authority.key \
    --protocol-key-file validator-protocol.key \
    --account-key-file validator-account.key \
    --network-key-file validator-network.key \
    --network-address /ip4/127.0.0.1/tcp/38189/http \
    --p2p-address /ip4/127.0.0.1/udp/34523 \
    --primary-address /ip4/127.0.0.1/udp/38603 \
    --description validator0 \
    --image-url https://www.iota.org/favicon.png \
    --project-url https://www.iota.org

Toggle created committee/validator0 file

info:
  name: validator0
  account-address: "0x3906e94925f3622aaf35a4b7462fa0f22fa6a9c5df160c07e050ca1ff0bf55bb"
  authority-key: tNswfm+q76ecEQwe6OkR/lnBOcQnt4dnlQozhMEhQ+4eQ4+JoDX+3J0RMVUUT1P6AMue5TJApqa0a5TguBAvYrDjdJs8NDaGU2aJsb1/HQ7UKCL5IiEnFSLAOO12HszU
  protocol-key: E7uErkWEg6ac1MWMHHEYmDJ6mTk0Pd2QNV9H0feXSiI=
  network-key: E7uErkWEg6ac1MWMHHEYmDJ6mTk0Pd2QNV9H0feXSiI=
  gas-price: 1000
  commission-rate: 200
  network-address: /ip4/127.0.0.1/tcp/38189/http
  p2p-address: /ip4/127.0.0.1/udp/34523
  primary-address: /ip4/127.0.0.1/udp/38603
  description: validator0
  image-url: "https://www.iota.org/favicon.png"
  project-url: "https://www.iota.org"
proof_of_possession: pk+5HoByE1fuHjkDVHOaKxazKnHLEOYf9IoDP9+C5eeG06Ji30Y9lXCHmB/swVdf

List Validators​

iota genesis-ceremony list-validators

Toggle output

Validator Name Account Address
-------------- ------------------------------------------------------------------
validator0     0x3906e94925f3622aaf35a4b7462fa0f22fa6a9c5df160c07e050ca1ff0bf55bb
validator1     0xba55e3ce221bb7edfbbef4d59b68893f5550b6302a9456b738ad8cf06919be0c

Initialize the Token Distribution Schedule​

Set the initial token distribution schedule through a .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.

The resulting distribution schedule is amended only if any migration sources are passed in the Build the Unsigned Checkpoint step.

$ iota genesis-ceremony init-token-distribution-schedule \
    --token-allocations-path <path-to-token-allocations-csv-file>

Validate the Genesis State​

This command checks the current state of the builder and reports any issues.

iota genesis-ceremony validate-state

Build the Unsigned Checkpoint​

iota genesis-ceremony build-unsigned-checkpoint

Examine the Genesis Checkpoint​

This command opens the Genesis Inspector, a responsive command-line tool which allows viewing various attributes of the current built checkpoint.

iota genesis-ceremony examine-genesis-checkpoint

Verify and Sign the Checkpoint​

Each validator must sign the created checkpoint before finalizing the genesis blob.

iota genesis-ceremony verify-and-sign --key-file authority.key

Finalize the Genesis blob​

Executing this command will generate the genesis.blob file using the configuration that has been persisted by the previous commands.

iota genesis-ceremony finalize