search

HugoByte / polkadot-kurtosis-package

Polkadot Kurtosis Package
Apache License 2.0
7 stars 3 forks source link

readme

HugoByte

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.

Discord

Table of Contents

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:

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

Parachains Supported in Localnet:

Parachains Supported in Testnet (Beta):

Parachains Supported in Mainnet (Beta):

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:

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:

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:

Service Details

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

User Services

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:

Polkadot js explorer

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:

Explorer

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:

Grafana

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:

Metrics

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

You can read more about Chopsticks here.

Configuration for Chopsticks

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

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:

Chopsticks Service Details

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:

  1. Download Dive CLI
  2. 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:

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.

  1. Fork the Project.

  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)

  3. Commit your Changes (git commit -m 'feature message')

  4. Push to the Branch (git push origin feature/AmazingFeature)

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