Coreum Package

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:

1. Generate genesis files with prefunded accounts and validators using cored and gaia
2. Spin up networks of n size using the genesis data generated above
3. Spin up a Grafana and Prometheus instances to observe the network
4. Launch a faucet service to create funded accounts or fund existing accounts
5. Spin up a Big Dipper block explorer instance
6. Launch a transaction spammer if configured
7. Possibility to inject latencies between nodes to create more realistic networks
8. Launch a hermes IBC relayer to connect testnets

Quickstart

1. Install Docker & start the Docker Daemon if you haven't done so already

2. Install the Kurtosis CLI, or upgrade it to the latest version if it's already installed

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

Run with your own configuration

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.

Run on Kubernetes

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.

Management

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

Debugging

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

Configuration

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

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

Example configurations

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

Faucet service

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 'http://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 'http://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"
}

Developing On This Package

1. Clone this repository to your local machine:

   git clone https://github.com/LZeroAnalytics/coreum-package.git
   cd coreum-package

2. Make your code changes

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

1. Create a PR

2. Add one of the maintainers of the repo as a "Review Request":

   • tiljrd (LZero)

3. Once everything works, merge!