Overview

The ZChains has two types of private keys that it directly manages:

• Private key used for the consensus mechanism

• Private key used for networking by libp2p

Currently, the ZChains doesn't offer support for direct account management.

Based on the directory structure outlined in the Backup & Restore guide, the ZChains stores these mentioned key files in two distinct directories - consensus and keystore.

Key format

The private keys are stored in simple Base64 format, so they can be human-readable and portable.

# Example private key
0802122068a1bdb1c8af5333e58fe586bc0e9fc7aff882da82affb678aef5d9a2b9100c0

:::info Key Type All private key files generated and used inside the ZChains are relying on ECDSA with the curve secp256k1.

As the curve is non-standard, it cannot be encoded and stored in any standardized PEM format. Importing keys that don't conform to this key type is not supported. :::

Consensus Private Key

The private key file mentioned as the consensus private key is also referred to as the validator private key. This private key is used when the node is acting as a validator in the network and needs to sign new data.

The private key file is located in consensus/validator.key, and adheres to the key format mentioned.

Networking Private Key

The private key file mentioned for networking is used by libp2p to generate the corresponding PeerID, and allow the node to participate in the network.

It is located in keystore/libp2p.key, and adheres to the key format mentioned.

Import / Export

As the key files are stored in simple Base64 on disk, they can be easily backed up or imported.

:::caution Changing the key files Any kind of change made to the key files on an already set up / running network can lead to serious network/consensus disruption, since the consensus and peer discovery mechanisms store the data derived from these keys in node-specific storage, and rely on this data to initiate connections and perform consensus logic :::

Overview

Currently, the ZChains is concerned with keeping 2 major runtime secrets:

• The validator private key used by the node, if the node is a validator

• The networking private key used by libp2p, for participating and communicating with other peers

For additional information, please read through the Managing Private Keys Guide

The modules of the ZChains should not need to know how to keep secrets. Ultimately, a module should not care if a secret is stored on a far-away server or locally on the node's disk.

Everything a module needs to know about secret-keeping is knowing to use the secret, knowing which secrets to get or save. The finer implementation details of these operations are delegated away to the SecretsManager, which of course is an abstraction.

The node operator that's starting the ZChains can now specify which secrets manager they want to use, and as soon as the correct secrets manager is instantiated, the modules deal with the secrets through the mentioned interface - without caring if the secrets are stored on a disk or on a server.

This article details the necessary steps to get the ZChains up and running with a Hashicorp Vault server.

:::info previous guides It is highly recommended that before going through this article, articles on Local Setup and Cloud Setup are read. :::

Prerequisites

This article assumes that a functioning instance of the Hashicorp Vault server is already set up.

Additionally, it is required that the Hashicorp Vault server being used for the ZChains should have enabled KV storage.

Required information before continuing:

• The server URL (the API URL of the Hashicorp Vault server)

• Token (access token used for access to the KV storage engine)

Step 1 - Generate the secrets manager configuration

In order for the ZChains to be able to seamlessly communicate with the Vault server, it needs to parse an already generated config file, which contains all the necessary information for secret storage on Vault.

To generate the configuration, run the following command:

polygon-edge secrets generate --dir <PATH> --token <TOKEN> --server-url <SERVER_URL> --name <NODE_NAME>

Parameters present:

• PATH is the path to which the configuration file should be exported to. Default ./secretsManagerConfig.json

• TOKEN is the access token previously mentioned in the prerequisites section

• SERVER_URL is the URL of the API for the Vault server, also mentioned in the prerequisites section

• NODE_NAME is the name of the current node for which the Vault configuration is being set up as. It can be an arbitrary value. Default polygon-edge-node

:::caution Node names Be careful when specifying node names.

The ZChains uses the specified node name to keep track of the secrets it generates and uses on the Vault instance. Specifying an existing node name can have consequences of data being overwritten on the Vault server.

Secrets are stored on the following base path: secrets/node_name :::

Step 2 - Initialize secret keys using the configuration

Now that the configuration file is present, we can initialize the required secret keys with the configuration file set up in step 1, using the --config:

polygon-edge secrets init --config <PATH>

The PATH param is the location of the previously generated secrets manager param from step 1.

Step 3 - Generate the genesis file

The genesis file should be generated in a similar manner to the Local Setup and Cloud Setup guides, with minor changes.

Since Hashicorp Vault is being used instead of the local file system, validator addresses should be added through the --ibft-validator flag:

polygon-edge genesis --ibft-validator <VALIDATOR_ADDRESS> ...

Step 4 - Start the Polygon Edge client

Now that the keys are set up, and the genesis file is generated, the final step to this process would be starting the Polygon Edge with the server command.

The server command is used in the same manner as in the previously mentioned guides, with a minor addition - the --secrets-config flag:

polygon-edge server --secrets-config <PATH> ...

The PATH param is the location of the previously generated secrets manager param from step 1.

Overview

Currently, the ZChains is concerned with keeping 2 major runtime secrets:

• The validator private key used by the node, if the node is a validator

• The networking private key used by libp2p, for participating and communicating with other peers

For additional information, please read through the Managing Private Keys Guide

The modules of the ZChains should not need to know how to keep secrets. Ultimately, a module should not care if a secret is stored on a far-away server or locally on the node's disk.

Everything a module needs to know about secret-keeping is knowing to use the secret, knowing which secrets to get or save. The finer implementation details of these operations are delegated away to the SecretsManager, which of course is an abstraction.

The node operator that's starting the ZChains can now specify which secrets manager they want to use, and as soon as the correct secrets manager is instantiated, the modules deal with the secrets through the mentioned interface - without caring if the secrets are stored on a disk or on a server.

This article details the necessary steps to get the ZChains up and running with AWS Systems Manager Parameter Store.

:::info previous guides It is highly recommended that before going through this article, articles on Local Setup and Cloud Setup are read. :::

Prerequisites

IAM Policy

User needs to create an IAM Policy that allows read/write operations for AWS Systems Manager Parameter Store. After successfully creating IAM Policy, the user needs to attach it to the EC2 instance that is running the ZChains server. The IAM Policy should look something like this:

{
  "Version": "2012-10-17",
  "Statement" : [
    {
      "Effect" : "Allow",
      "Action" : [
        "ssm:PutParameter",
        "ssm:DeleteParameter",
        "ssm:GetParameter"
      ],
      "Resource" : [
        "arn:aws:ssm:<aws_region>:<aws_account_id>:parameter<ssm-parameter-path>*"
      ]
    }
  ]
}

More information on AWS SSM IAM Roles you can find in the AWS docs.

Required information before continuing:

• Region (the region in which Systems Manager and nodes reside)

• Parameter Path (arbitrary path that the secret will be placed in, for example /polygon-edge/nodes)

Step 1 - Generate the secrets manager configuration

In order for the ZChains to be able to seamlessly communicate with the AWS SSM, it needs to parse an already generated config file, which contains all the necessary information for secret storage on AWS SSM.

To generate the configuration, run the following command:

polygon-edge secrets generate --type aws-ssm --dir <PATH> --name <NODE_NAME> --extra region=<REGION>,ssm-parameter-path=<SSM_PARAM_PATH>

Parameters present:

• PATH is the path to which the configuration file should be exported to. Default ./secretsManagerConfig.json

• NODE_NAME is the name of the current node for which the AWS SSM configuration is being set up as. It can be an arbitrary value. Default polygon-edge-node

• REGION is the region in which the AWS SSM resides. This has to be the same region as the node utilizing AWS SSM.

• SSM_PARAM_PATH is the name of the path that the secret will be stored in. For example if --name node1 and ssm-parameter-path=/polygon-edge/nodes are specified, the secret will be stored as /polygon-edge/nodes/node1/<secret_name>

:::caution Node names Be careful when specifying node names.

The Polygon Edge uses the specified node name to keep track of the secrets it generates and uses on the AWS SSM. Specifying an existing node name can have consequences of failing to write secret to AWS SSM.

Secrets are stored on the following base path: SSM_PARAM_PATH/NODE_NAME :::

Step 2 - Initialize secret keys using the configuration

Now that the configuration file is present, we can initialize the required secret keys with the configuration file set up in step 1, using the --config:

polygon-edge secrets init --config <PATH>

The PATH param is the location of the previously generated secrets manager param from step 1.

:::info IAM Policy This step will fail if IAM Policy that allows read/write operations is not configured correctly and/or not attached to the EC2 instance running this command. :::

Step 3 - Generate the genesis file

The genesis file should be generated in a similar manner to the Local Setup and Cloud Setup guides, with minor changes.

Since AWS SSM is being used instead of the local file system, validator addresses should be added through the --ibft-validator flag:

polygon-edge genesis --ibft-validator <VALIDATOR_ADDRESS> ...

Step 4 - Start the Polygon Edge client

Now that the keys are set up, and the genesis file is generated, the final step to this process would be starting the Polygon Edge with the server command.

The server command is used in the same manner as in the previously mentioned guides, with a minor addition - the --secrets-config flag:

polygon-edge server --secrets-config <PATH> ...

The PATH param is the location of the previously generated secrets manager param from step 1.

Starting the server with various configuration options can be done using a configuration file instead of using just flags. The command used to start the server with a config file: polygon-edge server --config <config_file_name>

Export config file with default configuration

The configuration with default settings for the ZChains server can be exported into a config file in either yaml or json file format. This file can be used as a template for running the server using a configuration file.

YAML

To generate the config file in yaml format:

polygon-edge server export --type yaml

or just

polygon-edge server export

the config file named default-config.yaml will be created in the same directory that this command has been run from.

File example:

chain_config: ./genesis.json
secrets_config: ""
data_dir: ""
block_gas_target: "0x0"
grpc_addr: ""
jsonrpc_addr: ""
telemetry:
  prometheus_addr: ""
network:
  no_discover: false
  libp2p_addr: 127.0.0.1:1478
  nat_addr: ""
  dns_addr: ""
  max_peers: -1
  max_outbound_peers: -1
  max_inbound_peers: -1
seal: true
tx_pool:
  price_limit: 0
  max_slots: 4096
log_level: INFO
restore_file: ""
block_time_s: 2
headers:
  access_control_allow_origins:
    - '*'
log_to: ""

JSON

To generate the config file in json format:

polygon-edge server export --type json

the config file named default-config.json will be created in the same directory that this command has been run from.

File example:

{
  "chain_config": "./genesis.json",
  "secrets_config": "",
  "data_dir": "",
  "block_gas_target": "0x0",
  "grpc_addr": "",
  "jsonrpc_addr": "",
  "telemetry": {
    "prometheus_addr": ""
  },
  "network": {
    "no_discover": false,
    "libp2p_addr": "127.0.0.1:1478",
    "nat_addr": "",
    "dns_addr": "",
    "max_peers": -1,
    "max_outbound_peers": -1,
    "max_inbound_peers": -1
  },
  "seal": true,
  "tx_pool": {
    "price_limit": 0,
    "max_slots": 4096
  },
  "log_level": "INFO",
  "restore_file": "",
  "block_time_s": 2,
  "headers": {
    "access_control_allow_origins": [
      "*"
    ]
  },
  "log_to": ""
}

Checkout CLI Commands section to get information on how to use these parameters.

Typescript schema

The following is the sample format for the configuration file. It's written in TypeScript to express the properties types (string, number, boolean), from it you could derive your configuration. It's worth mentioning that the PartialDeep type from type-fest is used to express that all properties are optional.

import { PartialDeep } from 'type-fest';

type ServerConfig = PartialDeep<{
  chain_config: string; // <genesis_file_path>
  secrets_config: string; // <secrets_file_path>
  data_dir: string; // <data_directory_path>
  block_gas_target: string; // <block_gas_limit>
  grpc_addr: string; // <grpc_listener_address>
  jsonrpc_addr: string; // <json_rpc_listener_address>
  telemetry: {
    prometheus_addr: string; // <prometheus_listener_address>
  };
  network: {
    no_discover: boolean; // <enable/disable_discovery>,
    libp2p_addr: string; // <libp2p_server_address>,
    nat_addr: string; // <nat_address>,
    dns_addr: string; // <dns_address>,
    max_peers: number; // <maximum_allowded_peers>,
    max_inbound_peers: number; // <maximum_allowded_inbound_peers>,
    max_outbound_peers: number; // <maximum_allowded_outbound_peers>
  };
  seal: boolean; // <enable/disable_block_sealing>
  txpool: {
    price_limit: number; // <minimum_gas_price_limit>
    max_slots: number; // <maximum_txpool_slots>
  };
  log_level: 'DEBUG' | 'INFO' | 'WARN' | 'ERROR' | 'DPANIC' | 'PANIC' | 'FATAL'; // <log_level>
  restore_file: string; // <restore_file_path>
  block_time_s: number; // <block_time_seconds>
  headers: Record<string, any>;
  log_to: string; // <log_to>
}>

Overview

Currently, the ZChains is concerned with keeping 2 major runtime secrets:

• The validator private key used by the node, if the node is a validator

• The networking private key used by libp2p, for participating and communicating with other peers

For additional information, please read through the Managing Private Keys Guide

The modules of the ZChains should not need to know how to keep secrets. Ultimately, a module should not care if a secret is stored on a far-away server or locally on the node's disk.

Everything a module needs to know about secret-keeping is knowing to use the secret, knowing which secrets to get or save. The finer implementation details of these operations are delegated away to the SecretsManager, which of course is an abstraction.

The node operator that's starting the ZChains can now specify which secrets manager they want to use, and as soon as the correct secrets manager is instantiated, the modules deal with the secrets through the mentioned interface - without caring if the secrets are stored on a disk or on a server.

This article details the necessary steps to get the ZChains up and running with GCP Secret Manager.

:::info previous guides It is highly recommended that before going through this article, articles on Local Setup and Cloud Setup are read. :::

Prerequisites

GCP Billing Account

In order to utilize GCP Secrets Manager, the user has to have Billing Account enabled on the GCP portal. New Google accounts on GCP platform are provided with some funds to get started, as a king of free trial. More info GCP docs

Secrets Manager API

The user will need to enable the GCP Secrets Manager API, before he can use it. This can be done via Secrets Manager API portal. More info: Configuring Secret Manger

GCP Credentials

Finally, the user needs to generate new credentials that will be used for authentication. This can be done by following the instructions posted here. The generated json file containing credentials, should be transferred to each node that needs to utilize GCP Secrets Manager.

Required information before continuing:

• Project ID (the project id defined on GCP platform)

• Credentials File Location (the path to the json file containing the credentials)

Step 1 - Generate the secrets manager configuration

In order for the ZChains to be able to seamlessly communicate with the GCP SM, it needs to parse an already generated config file, which contains all the necessary information for secret storage on GCP SM.

To generate the configuration, run the following command:

polygon-edge secrets generate --type gcp-ssm --dir <PATH> --name <NODE_NAME> --extra project-id=<PROJECT_ID>,gcp-ssm-cred=<GCP_CREDS_FILE>

Parameters present:

• PATH is the path to which the configuration file should be exported to. Default ./secretsManagerConfig.json

• NODE_NAME is the name of the current node for which the GCP SM configuration is being set up as. It can be an arbitrary value. Default polygon-edge-node

• PROJECT_ID is the ID of the project the user has defined in GCP console during account setup and Secrets Manager API activation.

• GCP_CREDS_FILE is the path to the json file containing credentials which will allow read/write access to the Secrets Manager.

:::caution Node names Be careful when specifying node names.

The ZChains uses the specified node name to keep track of the secrets it generates and uses on the GCP SM. Specifying an existing node name can have consequences of failing to write secret to GCP SM.

Secrets are stored on the following base path: projects/PROJECT_ID/NODE_NAME :::

Step 2 - Initialize secret keys using the configuration

Now that the configuration file is present, we can initialize the required secret keys with the configuration file set up in step 1, using the --config:

polygon-edge secrets init --config <PATH>

The PATH param is the location of the previously generated secrets manager param from step 1.

Step 3 - Generate the genesis file

The genesis file should be generated in a similar manner to the Local Setup and Cloud Setup guides, with minor changes.

Since GCP SM is being used instead of the local file system, validator addresses should be added through the --ibft-validator flag:

polygon-edge genesis --ibft-validator <VALIDATOR_ADDRESS> ...

Step 4 - Start the Polygon Edge client

Now that the keys are set up, and the genesis file is generated, the final step to this process would be starting the Polygon Edge with the server command.

The server command is used in the same manner as in the previously mentioned guides, with a minor addition - the --secrets-config flag:

polygon-edge server --secrets-config <PATH> ...

The PATH param is the location of the previously generated secrets manager param from step 1.