Empower your Polkadot development with the Polkadot-kurtosis-package, an all-in-one solution for effortlessly spawning relay chains and parachains. Dive into a world of efficiency, reliability, and innovation, all meant to enhance your Polkadot experience. Welcome to the future of decentralized possibilities! Remember, the key to our existence is to distribute, decentralize, and democratize.

Introduction
- About
  - Polkadot
  - Kusama
  - Parachains
  - Explorer
- Prerequisites
Integrated Parachains Within the Polkadot-kurtosis-package
Configuration File Guidelines
Usage
Service Details
Using Explorer with Service Details
Using Grafana with Service Details
Chopstick Compatibility
Dive CLI Integration
Known Issues
Troubleshooting
Contributing
License
Feedback

Introduction

Polkadot-kurtosis-package is a tool built leveraging the power of Kurtosis, a developer platform for packaging and launching environments. This tool simplifies the process of setting up various localnet, testnet, and mainnet network configurations and scenarios for Polkadot and Kusama parachains.

Polkadot-kurtosis-package made easy with DIVE CLI! Click here to know more.

About

The primary goal of this project is to streamline the setup of Polkadot and Kusama parachain environments using the Kurtosis platform. With just a few one-liners, developers can package and launch environments tailored to their needs.

Polkadot:

Polkadot is a blockchain platform that aims to connect different blockchains together, allowing them to communicate and share data. Imagine it as a web of interconnected blockchains, with each blockchain being an island and Polkadot being the bridges that connect them. This allows for a more seamless and efficient transfer of data and value between different blockchain networks.

You can read more about polkadot here.

Kusama:

Kusama serves as a real-world testing environment for Polkadot, a top blockchain platform designed for interoperability and scalability. Developers initially deploy and experiment with new features and upgrades on Kusama, allowing possible issues to be identified and resolved before they are implemented on the main Polkadot network. This iterative process promotes resilience and stability in the final product.

You can read more about kusama here.

Parachains:

In the context of Polkadot and Kusama, a parachain is a specialized, independent blockchain that connects to the main network (also known as the Relay Chain). Each parachain is tailor-made for a specific purpose, catering to diverse applications like DeFi, gaming, or asset management. They have their own governance, consensus mechanisms, and tokens.

You can read more about parachains here. You can also see list of all the parachains on polkadot and kusama here.

Explorer:

The Polkadot JS Explorer is a web-based application that serves as a comprehensive gateway to interact with and explore the Polkadot and Kusama blockchain networks. It provides a user-friendly interface for a variety of functions.

You can access the explorer here.

Prerequisites

Ensure the following prerequisites are met before using the Polkadot-kurtosis-package:

Docker: Make sure Docker is installed on your machine. You can install it here.
Kurtosis: Ensure Kurtosis is installed on your machine. You can install it here.

Integrated Parachains Within the Polkadot-kurtosis-package

A list of all the parachains supported by the package and the environments they are available in.

Overall List of Integrated Parachains

For Polkadot: acala, ajuna, bifrost, centrifuge, clover, frequency, kilt, kylin, litentry, manta, moonbeam, moonsama, nodle, parallel, pendulum, phala, polkadex, subsocial, zeitgeist
For Kusama: altair, bajun, bifrost, calamari, encointer, karura, khala, integritee, litmus, mangata, moonriver, robonomics, subzero, turing

Parachains Supported in Localnet:

For Polkadot: acala, ajuna, bifrost, centrifuge, clover, frequency, kilt, kylin, litentry, manta, moonbeam, moonsama, nodle, parallel, pendulum, phala, polkadex, subsocial, zeitgeist
For Kusama: altair, bajun, bifrost, calamari, encointer, karura, khala, integritee, litmus, mangata, moonriver, robonomics, subzero, turing

Parachains Supported in Testnet (Beta):

For Polkadot: ajuna, bifrost, frequency, kilt, litentry, moonbeam, nodle, pendulum, phala, zeitgeist
For Kusama: bajun, bifrost, encointer, integritee, mangata, moonriver, turing
Inactive Testnet: karura, khala, robonomics, altair, litmus, calamari, subsocial, moonsama, manta, kylin, centrifuge, acala, polkadex, clover
No Testnet available: parallel, subzero

Parachains Supported in Mainnet (Beta):

For Polkadot: acala, ajuna, bifrost, centrifuge, clover, frequency, kilt, kylin, litentry, manta, moonbeam, moonsama, nodle, parallel, pendulum, phala, polkadex, subsocial, zeitgeist
For Kusama: altair, bajun, bifrost, calamari, encointer, karura, khala, integritee, litmus, mangata, moonriver, robonomics, subzero, turing

Configuration File Guidelines

To use the Polkadot-kurtosis-package, you need to create a configuration file specifying the desired network setup. Below is an example configuration file along with explanations for each field:

{
  "chain_type": "testnet",
  "relaychain": {
    "name": "rococo",
    "nodes": [
      {
        "name": "alice",
        "node_type": "validator",
        "prometheus": false
      },
      {
        "name": "bob",
        "node_type": "validator",
        "prometheus": true

      }
    ]
  },

  "parachains": [
    {
      "name":"acala",
      "nodes": [
        {
          "name": "alice",
          "node_type": "collator",
          "prometheus": false

        },
        {
          "name": "bob",
          "node_type": "full",
          "prometheus": true
        }
      ]
    }
  ],
  "explorer": true
}

Configuration Fields:

chain_type: Specifies the type of the network (e.g., "localnet","testnet", "mainnet").
relaychain: Configuration for the relay chain. (When chain_type is "testnet" or "mainenet", the "relaychain" can be an empty dictonary).
- name: Name of the relay chain (e.g., "rococo-local", "rococo", "polkadot" or "kusama").
- nodes: List of nodes on the relay chain, each with:
  - name: Node name (e.g., "alice").
  - node_type: Node type, can be "validator" or "full".
  - prometheus: Whether Prometheus monitoring is enabled (true/false).
parachains: List of parachains, each with:
- name: Parachain name (e.g., "kilt").
- nodes: List of nodes on the parachain, similar to relay chain nodes.
  - name: Node name (e.g., "alice").
  - node_type: Node type, can be "collator" or "full".
  - prometheus: Whether Prometheus monitoring is enabled (true/false).
explorer: Whether Polkadot js explorer is enabled (true/false).

Feel free to modify this example configuration file based on your specific network requirements. Here is a link to the official template that you can edit and use.

Possible Values for Configuration Fields:

chain_type: localnet, mainnet, testnet
relaychain name:
- for localnet: rococo-local
- for testnet: rococo, westend
- for mainnet: polkadot, kusama
node_type:
- for relaychain: validator, full, archive
- for parachain: collator, full
parachain name:
- for polkadot: any valid parachain for polkadot from this list
- for kusama: any valid parachain for kusama from this list
prometheus: true or false
explorer: true or false
node-name: any

Note: You can pass relaychain as an empty dictionary {} when chain_type is 'testnet' or 'mainnet'. This will only spawn the parachain.

Example Configurations:

Here are some example configurations you can pass to the package.

Passing mutiple parachains without relay chain in testnet:

{
  "chain_type": "testnet",
  "relaychain": {
  },

  "parachains": [
    {
      "name":"mangata",
      "nodes": [
        {
          "name": "alice",
          "node_type": "collator",
          "prometheus": true

        },
        {
          "name": "bob",
          "node_type": "full",
          "prometheus": true
        }
      ]
    },
    {
      "name":"acala",
      "nodes": [
        {
          "name": "alice",
          "node_type": "collator",
          "prometheus": true

        },
        {
          "name": "bob",
          "node_type": "full",
          "prometheus": false
        }
      ]
    }
  ],
  "explorer": false
}

Passing relay chain without parachain in mainnet:

{
  "chain_type": "mainnet",
  "relaychain": {
    "name": "rococo",
    "nodes": [
      {
        "name": "alice",
        "node_type": "validator",
        "prometheus": true
      },
      {
        "name": "bob",
        "node_type": "full",
        "prometheus": true

      }
    ]
  },

  "parachains": [
  ],
  "explorer": false
}

Usage

To use the package, run the following command:

Before proceeding, make sure the Kurtosis Engine is running in the background. If it's not already running, start it by executing the following command: kurtosis engine start

kurtosis run github.com/hugobyte/polkadot-kurtosis-package --enclave 'enclavename' --args-file=path/to/config/file

For detailed instructions on writing the configuration file, refer to the Configuration File Guidelines.

Service Details

Consider this sample config file:

{
  "chain_type": "localnet",
  "relaychain": {
    "name": "rococo-local",
    "nodes": [
      {
        "name": "alice",
        "node_type": "validator",
        "prometheus": false
      },
      {
        "name": "bob",
        "node_type": "full",
        "prometheus": true

      }
    ]
  },

  "parachains": [
    {
      "name":"frequency",
      "nodes": [
        {
          "name": "alice",
          "node_type": "validator",
          "prometheus": false

        }
      ]
    }
  ],
  "explorer": true
}

The service details receieved after running the package with this config should be as follows:

You should also get the user services from kurtosis as follows:

The service name 'frequency-alice-localnet' contains the details of the 'frequency' parachain node and the service names 'rococo-local-alice' and 'rococo-local-bob' contain the details of the relay chain nodes. Each node has its own service name and service details.

The 'polkadot-js-explorer' service contains the details of the explorer.

The 'prometheus' and 'grafana' services contain the details of required metrics.

Using Explorer with Service Details

To use the explorer with the service details, open the given endpoint for 'polkadot-js-explorer' in the user services. In this case, it would be: 'http://127.0.0.1:80'

A page like this should open:

Click on the orange icon next to unknown. This should open a side-menu. Click on Development and replace the custom endpoint port with the port of the node for which you would like to view the explorer details.

You can find the node in the user services. For example, consider port 33131. After passing the port in custom endpoint, your page should look like this:

Using Grafana with Service Details

Grafana is automatically enabled when prometheus for any node is given as true. To use the grafana with the service details, open the given endpoint for 'grafana' in the user services. In this case, it would be: 'http://127.0.0.1:33136'

A page like this should open:

Click on Data Sources, select Prometheus. In Connection field, enter the endpoint given in 'prometheus' service in service details. In this case it would be 'http://172.16.0.12:9090'. Scroll down and click on save and test.

Now, open the side menu and click on Dashboards. Click on Create Dashboard and then import dashboard. Type 13759 in the Find and import dashboards for common applications field and click on Load. You can also use your custom dashboards here.

After loading, select prometheus from the drop down menu in the Substrate Node field and click on Import. You should now be able to see the metrics. It should look something like this:

Chopstick Compatibility

The package also supports Chopsticks, a tool offering a user-friendly approach to locally branching existing Substrate-based chains. It enables block replay, multi-block forking, and more.

Parachains Compatible with Chopsticks

astar
basilisk
acala
centrifuge
composable-polkadot
hydradx
imbu
interlay
karura
mandala
mangata
moonbase
moonbeam
moonriver
nodle-eden
picasso-kusama
picasso-rococo
polkadex
shibuya
shiden
statemine
statemint
ß tinkernet

You can read more about Chopsticks here.

Configuration for Chopsticks

{
    "parachain": "acala",
    "xcm": {
        "relaychain": "polkadot",
        "parachains": [
            "acala",
            "moonbeam"
        ]
    }
}

chain: Name of the chain to run fork of.
xcm: A dict containing the following details to set up XCM multichain:
- relaychain: Name of relay chain.
- parachains: List of parachains.

Feel free to modify this example configuration file based on your specific network requirements. Here is a link to the official template that you can edit and use.

Using Chopsticks

kurtosis run github.com/hugobyte/polkadot-kurtosis-package/chopsticks --enclave 'enclavename' --args-file=path/to/config/file

Service Details for Chopstikcs

The service details after running chopsticks should be similar to this:

Dive CLI Integration

We recommend using the Dive CLI developed by our company for enhanced capabilities and a seamless experience with this package. Dive CLI provides additional features that complement the functionality of this package.

To get started with Dive CLI:

Download Dive CLI
Install and configure Dive CLI following the documentation.

Feel free to explore the powerful features of Dive CLI alongside our package for an optimized development workflow.

Known Issues

Here is a list of known issues and their status that our team is currently working to resolve.

Troubleshooting

If you encounter issues while using the Polkadot-kurtosis-package, refer to the following troubleshooting tips to resolve common problems:

Clean kurtosis engine using:

kurtosis clean -a

Restart kurtosis engine using:

kurtosis engine restart

Check if your docker is installed:

docker --version

If you still experience issues after following these troubleshooting tips, please open an issue to get further assistance.

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. We welcome contributions to enhance and expand the functionality of the Polkadot-kurtosis-package. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request.

Fork the Project.
Create your Feature Branch (git checkout -b feature/AmazingFeature)
Commit your Changes (git commit -m 'feature message')
Push to the Branch (git push origin feature/AmazingFeature)
Open a Pull Request.

License

Distributed under the Apache 2.0 License. See LICENSE for more information.

Feedback

We would happy to hear your thoughts on our project. Your feedback helps us improve and make it better for everyone. Please submit your valuable feedback here

HugoByte/polkadot-kurtosis-package

Table of Contents