This is a Kurtosis package developed by LZero that will spin up a private Coreum or Cosmos Hub testnet over Docker or Kubernetes. Kurtosis packages are entirely reproducible and composable, so this will work the same way over Docker or Kubernetes, in the cloud or locally on your machine.
You now have the ability to spin up a private Coreum testnet or public devnet/testnet with a single command. This package is designed to be used for testing, validation, and development, and is not intended for production use.
Specifically, this package will:
- Generate genesis files with prefunded accounts and validators using cored and gaia
- Spin up networks of n size using the genesis data generated above
- Spin up a Grafana and Prometheus instances to observe the network
- Launch a faucet service to create funded accounts or fund existing accounts
- Spin up a Big Dipper block explorer instance
- Launch a transaction spammer if configured
- Possibility to inject latencies between nodes to create more realistic networks
- Launch a hermes IBC relayer to connect testnets
-
Install Docker & start the Docker Daemon if you haven't done so already
-
Install the Kurtosis CLI, or upgrade it to the latest version if it's already installed
-
Run the package with default configurations from the command line:
kurtosis run --enclave my-testnet github.com/LZeroAnalytics/coreum-package
This command will spin up one coreum node, launch prometheus and grafana instances, launch a block explorer, and set up a faucet service.
Kurtosis packages are parameterizable, meaning you can customize your network and its behavior to suit your needs by storing parameters in a file that you can pass in at runtime like so:
kurtosis run --enclave my-testnet github.com/LZeroAnalytics/coreum-package --args-file network_params.yaml
Where network_params.yaml
contains the parameters for your network in your home directory. You can also use the sample configuration file.
Kurtosis packages work the same way over Docker or on Kubernetes. Please visit the Kubernetes docs to learn how to spin up a private testnet on a Kubernetes cluster.
The Kurtosis CLI can be used to inspect and interact with the network.
For example, if you need shell access, simply run:
kurtosis service shell my-testnet $SERVICE_NAME
And if you need the logs for a service, simply run:
kurtosis service logs my-testnet $SERVICE_NAME
To access logs of any blockchain nodes or the transaction spammer, please instead use the previous command to gain
shell access and inspect the log files node.log
and locust.log
for the nodes and the transaction spammer respectively.
To stop a network run:
kurtosis enclave stop $THE_NETWORK_NAME
Before running a new network with the same network name, you should remove all associated resources:
kurtosis enclave rm $THE_NETWORK_NAME
You can also pass the -f
flag to stop a network and remove resources in one command.
An easy way to clean all unused resources and shut down all networks:
kurtosis clean -a
Check out the full list of CLI commands here
To grab any files generated by the package, simply run:
kurtosis files download my-testnet $FILE_NAME $OUTPUT_DIRECTORY
For example, to retrieve the genesis file, run:
kurtosis files download my-testnet genesis-file ~/Downloads
To configure the package behaviour, you can modify your network_params.yaml
file. The full YAML schema that can be passed in is as follows with the defaults provided:
# An array of unlimited number of chains
# All parameters are optional except name and type
chains:
# The name of the chain
# Can be used to create connections between chains
- name: coreum
# Allows values: coreum or gaia
type: coreum
# Chain ID can be coreum-devnet-1 (default), coreum-testnet-1, or coreum-mainnet-1
# If coreum-testnet-1 or coreum-mainnet-1 is used, denom needs to be adapted
# Can be any id for gaia and should be set when creating more than 1 gaia chain
chain_id: coreum-devnet-1
# How long you want the network to wait before starting up in seconds
genesis_delay: 20
# The initial block height of the chain
initial_height: 1
# Parameters about the denomination (denom) used in the chain
# Values should correspond to each other
denom:
# The base denomination name used in the chain
name: udevcore
# The display name of the denomination
display: devcore
# The symbol representing the denomination
symbol: udevcore
# A description of the denomination
description: udevcore coin
# Units of the denomination with different exponents
units:
# The smallest unit of the denomination
- denom: udevcore
exponent: 0
# A larger unit of the denomination
- denom: devcore
exponent: 6
# Faucet related parameters for distributing tokens
faucet:
# The amount that the faucet account should have
faucet_amount: 100000000000000
# How much tokens should be transferred on each API call
# Only supported in Coreum networks
transfer_amount: 100000000
# Consensus parameters that define the blockchain's rules
consensus_params:
# The maximum block size in bytes (default: 21MB)
block_max_bytes: 22020096
# The maximum gas that can be consumed by a block
block_max_gas: 50000000
# The maximum age of evidence in nanoseconds
evidence_max_age_duration: 172800000000000
# The maximum number of blocks for which evidence is valid
evidence_max_age_num_blocks: 100000
# The maximum size of evidence in bytes
evidence_max_bytes: 1048576
# Which public key types are allowed for validators
validator_pub_key_types:
- ed25519
# Modules and their configurations
modules:
auth:
# Maximum number of characters allowed in transaction memo
max_memo_characters: 256
# Cost of verifying a signature using ed25519 algorithm
sig_verify_cost_ed25519: 1000
# Cost of verifying a signature using secp256k1 algorithm
sig_verify_cost_secp256k1: 1000
# Maximum number of signatures allowed per transaction
tx_sig_limit: 7
# Cost per byte of transaction size
tx_size_cost_per_byte: 10
distribution:
# Base reward for proposers
base_proposer_reward: 0.010000000000000000
# Bonus reward for proposers
bonus_proposer_reward: 0.040000000000000000
# Community tax rate
community_tax: 0.050000000000000000
# Whether withdrawal addresses are enabled
withdraw_addr_enabled: true
crisis:
# The constant fee amount for the crisis module
constant_fee_amount: 500000000000
feemodel:
# Minimum gas price
min_gas_price: 0.0625
# Fraction at which gas price escalation starts
escalation_start_fraction: 0.8
# Initial gas price
initial_gas_price: 0.0625
# Length of the long EMA (Exponential Moving Average) block
long_ema_block_length: 1000
# Maximum gas that can be consumed in a block
max_block_gas: 50000000
# Maximum discount allowed on gas price
max_discount: 0.5
# Maximum multiplier for gas price
max_gas_price_multiplier: 1000.0
# Length of the short EMA (Exponential Moving Average) block
short_ema_block_length: 50
slashing:
# Duration for which a validator is jailed for downtime
downtime_jail_duration: 60s
# Minimum fraction of blocks that must be signed within a window
min_signed_per_window: 0.500000000000000000
# Number of blocks in the slashing window
signed_blocks_window: 34000
# Fraction of stake slashed for double signing
slash_fraction_double_sign: 0.050000000000000000
# Fraction of stake slashed for downtime
slash_fraction_downtime: 0.005000000000000000
staking:
# Maximum number of validators
max_validators: 32
# Minimum self-delegation amount
min_self_delegation: 20000000000
mint:
# Annual provisions for the mint module
annual_provisions: 0.000000000000000000
# Inflation rate
inflation: 0.100000000000000000
# Number of blocks per year
blocks_per_year: 17900000
# Goal bonded rate
goal_bonded: 0.670000000000000000
# Maximum inflation rate
inflation_max: 0.200000000000000000
# Minimum inflation rate
inflation_min: 0.000000000000000000
# Rate of change for inflation
inflation_rate_change: 0.130000000000000000
ibc:
# Allowed IBC clients
allowed_clients:
- 06-solomachine
- 07-tendermint
- 09-localhost
# Maximum expected time per block
max_expected_time_per_block: 30000000000
# Configure the url from which grafana is served
# Only relevant for cloud hosted environments
grafana:
server_url: ""
# Array of node templates (participants)
participants:
# Image used for these nodes
- image: tiljordan/coreum-cored:latest
# Account balance for the participant
account_balance: 100000000000
# Staking amount for the participant
staking_amount: 20000000000
# Number of nodes to launch for this template
count: 1
# Whether the participant is a staking validator
staking: true
# Latency in ms between this node and other nodes
latency: 0
# Jitter represents the variance in latency in ms
jitter: 0
# The minimum amout of CPUs the nodes must have, in millicpu/millicore.
# CAUTION: This is only available for Kubernetes, and will be ignored for Docker.
min_cpu: 500
# The minimum amount of memory, in megabytes, the nodes must have.
# CAUTION: This is only available for Kubernetes, and will be ignored for Docker.
min_memory: 512
# Configure the transactions per second (tps) sent
# Only launched when spammer is included in additional_services
# Default: 10
spammer:
tps: 10
# Additional services to be deployed with the chain
# For Coreum, all services except transaction spammer are launched by default
# For Gaia, grafana and prometheus are launched by default
# Gaia only support prometheus, grafana, and transaction spammer currently
additional_services:
- faucet
- bdjuno
- prometheus
- grafana
- spammer
# Connections between different chains
# Each connection requires at least the two chain names as specified above
connections:
- chain_a: chain_name_1
chain_b: chain_name_2
# Currently only supports hermes but can specify custom image
relayer_config:
hermes_image: tiljordan/hermes:latest
The default configurations and all example configurations can be found in the samples folder.
A 2-node bare bones Coreum network without additional services
chains:
- name: coreum-testnet
type: coreum
participants:
- count: 2
additional_services: []
A 3-node Coreum network with block size of 50MB
chains:
- name: coreum-testnet
type: coreum
consensus_parama:
block_max_bytes: 52428800
participants:
- count: 3
A 1-node Coreum and Gaia chain connected using IBC
chains:
- name: coreum
type: coreum
- name: gaia
type: gaia
connections:
- chain_a: coreum
chain_b: gaia
Two gaia chains connected using IBC
chains:
- name: gaia-1
type: gaia
chain_id: gaia-chain-1
- name: gaia-2
type: gaia
chain_id: gaia-chain-2
connections:
- chain_a: gaia-1
chain_b: gaia-2
Two Coreum chains connected using IBC
It is currently not possible to connect two coreum devnets but the configuration below shows how to connect a coreum testnet with a coreum devnet.
chains:
- name: coreum-testnet
type: coreum
chain_id: coreum-testnet-1
denom:
name: utestcore
display: testcore
symbol: utestcore
description: utestcore coin
units:
- denom: utestcore
exponent: 0
- denom: testcore
exponent: 6
additional_services:
- prometheus
- grafana
- name: coreum-devnet
type: coreum
chain_id: coreum-devnet-1
additional_services:
- prometheus
- grafana
connections:
- chain_a: coreum-testnet
chain_b: coreum-devnet
The faucet service is based on this repository.
The faucet service exposes an api that is mapped to a local port on localhost.
The service offers three paths: /api/faucet/v1/status
, /api/faucet/v1/fund
and /api/faucet/v1/gen-funded
.
fund
Send funds to the specified address. Prefunded addresses can be found in the console when running the package.
curl --location 'https://127.0.0.1:60095/api/faucet/v1/fund' \
--header 'Content-Type: application/json' \
--data '{
"address": "devcore19tmtuldmuamlzuv4xx704me7ns7yn07crdc4r3"
}'
{
"txHash":"E3B0C44298FC1C149AFBF4C8996FB92427AE41E4649B934CA495991B7852B855"
}
gen-funded
Generate a new funded account. This request requires to pass in the mnemonic address.
curl --location 'https://localhost:8090/api/faucet/v1/gen-funded' \
--header 'Content-Type: application/json' \
--data '{
"address": "devcore175m7gdsh9m0rm08a0w3eccz9r895t9jex0abcd"
}'
{
"txHash": "D039E2E8F4318A3C03F2B51D74E8E8CA8CFAFBC02B67E0A9716340B874347778",
"mnemonic": "day oyster today mechanic soup happy judge matter output asset tiny bundle galaxy theory witness act adapt company thought shock pole explain orchard surround",
"address": "devcore1lj597uzf689t0tpfxurhra9q9vtkxldezmtvwh"
}
-
Clone this repository to your local machine:
git clone https://github.com/LZeroAnalytics/coreum-package.git cd coreum-package
-
Make your code changes
-
To spin up the network, use the following command:
kurtosis run --enclave my-testnet . --args-file samples/default_config_sample.yml
Replace
samples/default_config_sample.yml
with the path to your custom configuration YAML file if needed.
When you're happy with your changes:
-
Create a PR
-
Add one of the maintainers of the repo as a "Review Request":
tiljrd
(LZero)
-
Once everything works, merge!