Aptos Genesis Tool

The aptos-genesis-tool provides a tool for the genesis ceremony of the Aptos blockchain. The functionality of the tool is dictated by the organization of nodes within the system:

• A aptos root account that maintains the set of validator owners, validator operators, and the active validator set.
• The initial set of Move modules published at genesis.
• Validator owners (OW) that have accounts on the blockchain. These accounts contain a validator configuration and specify a validator operator.
• Validator operators (OP) that have accounts on the blockchain. These accounts have the ability to manipulate validator configuration.

Generating Genesis

The process for starting organization of the planned and current functionality includes:

• Initialization ceremony
  • The association sets up a secure-backend for data uploads, shared storage, e.g., GitHub. The association then distributes credentials for each OW and OP.
  • The association generates its aptos root key and shares the public key to the shared storage.
  • The association uploads the initial set of Move modules to shared storage.
  • Each OW will generate a private owner key and share the public key to the shared storage.
  • Each OP will generate a private operator key and share the public key to the shared storage.
• Validator initialization
  • Each OW will select a OP and submit this as a transaction signed by their owner key and uploads it to the shared storage.
  • For each validator supported by a OP, the OP will generate network, execution and consensus keys as well as network addresses for full node and validator endpoints. The OP will generate a transaction containing this data signed by their operator key and uploads it to the shared storage.
• Genesis
  • Each OP will download the accumulated data to produce a genesis.blob
  • The association will download the accumulated data to produce both a genesis.blob and genesis waypoint.
• Starting
  • The association publishes the data associated with genesis, the genesis.blob, and the genesis waypoint.
  • Each OP downloads the genesis waypoint provided by the association and inserts it into their Aptos instance(s).
  • Each OP verifies that the genesis.blob, waypoint, and local configuration are correct and broadcast their results to other OPs and the association.
  • Upon a quorum of validators having correct status, the association instructs the OPs to begin their validators.
  • Upon a quorum of validators coming online, the blockchain will begin processing transactions.

Notes:

• This describes a process for instantiating organization that has yet to be specified but extends from the current state of the Aptos Testnet.
• The implementation as described has yet to be fully implemented in Move, hence, this tool maps to the current state.
• A new OP / OW onboarding to an existing blockchain follow the same process and delegate the initial creation of accounts and setting of configuration to the association.

Requirements

Each individual instance, OW or OP, should have access to a secure storage solution. Those leveraging Aptos Secure Storage can directly use this tool, those that do not will need to provide their own tooling.

The Tools

aptos-genesis-tool offers several facilities:

• Simplified configuration management via a config file that can store frequently reused paramters including validator and shared storage.
• Retrieving and submitting OW, OP, and validator configuration -- this is from a local secure storage to a remote secure storage -- leveraging the identity tool.
• Converting a genesis configuration and a secure storage into a genesis.blob / genesis waypoint.

The Process

The end-to-end process assumes that each participant has their own secure storage solution, e.g., Vault, and a token stored locally on their disk in a file accessible to the management tool.

In addition, the association will provide an entry point into a shared storage, e.g., GitHub repository (and repository owner) along with a distinct namespace for each participant. GitHub namespaces equate to directories within the repository.

Each participant must retrieve an appropriate GitHub token for their account that allows access to the repo scope. This token must be stored locally on their disk in a file accessible to the management tool.

Finally, each participant should initialize their respective key: aptos_root, owner, or operator in a secure storage solution. How this is done is outside the scope of this document.

The remainder of this section specifies distinct behaviors for each role.

Build a Configuration File

While aptos-genesis-tool supports setting the backends on each command, doing so is cumbersome and fraught with error. Instead, all participants, should first construct a configuration file for use in genesis and later use via the operational tool. Below is an example configuration file in yaml format:

# config.yaml

chain_id: "MAINNET"
json_server: "http://127.0.0.1:8080"
shared_backend:
    type: "github"
    repository_owner: "REPOSITORY_OWNER"
    repository: "REPOSITORY"
    namespace: "REPOSITOR_FOLDER"
    token:
        from_config: "test"
validator_backend:
    type: "vault"
    server: "127.0.0.1:8200"
    namespace: "VIRTUAL_NAMESPACE"
    token:
        from_config: "test"

Overview of fields:

• chain_id specifies a distinct chain and is written into genesis, checked during network connections, and part of each transaction. It is provided by the association.
• json_server specifies an Aptos JSON Server. This can be any that connect to your network including your own of one run by the association. It is not used in genesis, so a dummy value is acceptable during initial configuration.
• shared_backend is a pointer to the associaton's shared storage.
• validator_backend is a pointer to the local validator node's secure storage.

The Association

• The association will publish a layout containing the distinct names and roles of the participants to shared storage:

cargo run -p aptos-genesis-tool -- \
    set-layout \
    --config config_file.yaml \
    --path $PATH_TO_LAYOUT

• The association will publish the initial set of Move modules to shared storage:

cargo run -p aptos-genesis-tool -- \
    set-move-modules \
    --config config_file.yaml \
    --dir $MOVE_MODULES_DIR

This should be a directory containing only Move bytecode files (.mv extension).

• The association will publish the the aptos root public key to the shared storage:

cargo run -p aptos-genesis-tool -- \
    aptos-root-key \
    --config config_file.yaml

• Upon both OW and OP completing their portion of this process, the association will build a genesis waypoint:

cargo run -p aptos-genesis-tool -- \
    create-waypoint \
    --config config_file.yaml

The layout is a toml configuration file of the following format:

[operator] = ["alice", "bob"]
[owner] = ["carol", "dave"]
aptos_root = "erin"

where each field maps to a role as described in this document.

Validator Owners

• Each Validator Owner member will upload their key to GitHub:

cargo run -p aptos-genesis-tool -- \
    owner-key \
    --config config_file.yaml

• Each OW will select the OP responsible for operating the validator node. This selection is done by specifying the name of the OP (as registered in the shared Github):

cargo run -p aptos-genesis-tool --
    set-operator \
    --config config_file.yaml \
    --operator-name $OPERATOR_NAME

Validator Operators

• Each Validator Operator member will upload their key to GitHub:

cargo run -p aptos-genesis-tool --
    operator-key \
    --config config_file.yaml

• For each validator managed by an operator, the operator will upload a signed validator-config. The owner corresponds to the name of the OW (as registered in the shared Github). The namespace in GitHub correlates to the operator namespace:

cargo run -p aptos-genesis-tool --
    validator-config \
    --config config_file.yaml \
    --owner-name $OWNER_NAME \
    --validator-address "/dns/$VALIDATOR_DNS/tcp/$VALIDATOR_PORT" \
    --fullnode-address "/dns/$VFN_DNS/tcp/$VFN_PORT" \

• Upon receiving signal from the association, OPs can now build genesis:

cargo run -p aptos-genesis-tool -- \
    genesis \
    --config config_file.yaml \
    --path $PATH_TO_GENESIS \

• Similarly, the association should publish a genesis waypoint, and the OP should insert it into their storage (using the management tool):

cargo run -p aptos-genesis-tool -- \
    insert-waypoint \
    --config config_file.yaml \
    --waypoint $WAYPOINT

• Perform a verify that ensures the local store maps to Genesis and Genesis maps to the waypoint:

cargo run -p aptos-genesis-tool -- \
    verify \
    --config config_file.yaml \
    --genesis_path $PATH_TO_GENESIS

Important Notes

• A namespace in Vault is represented as a subdirectory for secrets and a prefix followed by __ for transit, e.g., namespace__.
• A namespace in GitHub is represented by a subdirectory
• The GitHub repository and repository owner translate into the following url: https://github.org/REPOSITORY_OWNER/REPOSITORY