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

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

List Validators

iota genesis-ceremony list-validators

Toggle output

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

Commands​

Examples​

Initialize the Genesis Builder​

Add Validators​

List Validators​

Initialize the Token Distribution Schedule​

Validate the Genesis State​

Build the Unsigned Checkpoint​

Examine the Genesis Checkpoint​

Verify and Sign the Checkpoint​

Finalize the Genesis blob​