From 4319c2236e9a53b72b92d98e14e46849bc301878 Mon Sep 17 00:00:00 2001 From: riyasng12 Date: Mon, 22 Jan 2024 18:28:44 +0530 Subject: [PATCH] docs: update README.md --- LICENSE | 190 +++++++ README.md | 695 ++++++++++++++++++++------ cli/cmd/bridge/utils/types.go | 8 +- cli/cmd/chains/kusama/run.go | 8 +- cli/cmd/chains/polkadot/run.go | 8 +- cli/cmd/chains/utils/types.go | 36 +- cli/sample-jsons/polkadot_config.json | 8 +- 7 files changed, 762 insertions(+), 191 deletions(-) create mode 100644 LICENSE diff --git a/LICENSE b/LICENSE new file mode 100644 index 00000000..e91ee1e2 --- /dev/null +++ b/LICENSE @@ -0,0 +1,190 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + Copyright [2023] [HugoByte AI Labs Pvt Ltd] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. \ No newline at end of file diff --git a/README.md b/README.md index 17e98b85..560c8fd9 100644 --- a/README.md +++ b/README.md @@ -1,34 +1,67 @@ ![DIVE](img/DIVE.png) +**Dive deeply into the world of Blockchain and Web 3.0 using **D.I.V.E.** (Deployable Infrastructure for Virtually Effortless blockchain integration)** + +[![Discord](https://img.shields.io/badge/Discord-hugobyte-00FF00?style=flat&logo=discord&logoColor=00FF00&labelColor=black)](https://discord.gg/GyRQSBN3Cu) + # D.I.V.E. [![run smoke testcases](https://github.com/HugoByte/DIVE/actions/workflows/smoke-test.yaml/badge.svg)](https://github.com/HugoByte/DIVE/actions/workflows/smoke-test.yaml) +# Table of Contents +- [Introduction](#introduction) + - [About](#about) + - [Prerequisites](#prerequisites) +- [Installing Dive CLI](#installing-dive-cli) +- [Commands](#commands) + - [Available Flags](#available-flags) +- [Usage](#usage) + - [Setting up a Node](#setting-up-a-node) + - [Setting Up Bridge Between Two Chains Which Are Already Running](#setting-up-bridge-between-two-chains-which-are-already-running) + - [Setting Up Bridge Between Two Chains](#setting-up-bridge-between-two-chains) + - [Setting Up Relay and Para Chains](#setting-up-relay-and-para-chains) +- [Configuration File Guidelines](#configuration-file-guidelines) + - [Configuration Fields](#configuration-fields) + - [Config Templates](#config-templates) +- [Service Details](#service-details) + - [Chain Command](#chain-command) + - [Bridge Command](#bridge-command) + - [Relay and Para Chains](#relay-and-para-chains) +- [Logs](#logs) +- [Version](#version) +- [Cleaning](#cleaning) +- [Enclaves](#enclaves) +- [Socials](#socials) +- [Testing](#testing) +- [Known Issues](#known-issues) +- [Troubleshooting](#troubleshooting) +- [Contributing](#contributing) +- [License](#license) +- [Feedback](#feedback) + +# Introduction + +

+DIVE CLI – a powerful tool designed to streamline the entire process of node setup, network configuration, and bridge creation. +With DIVE CLI, developers can easily connect and interact with various blockchain networks, paving the way for seamless cross-chain communication and smart contract deployment. +Serving as an all-in-one solution, DIVE CLI eliminates the hassle of manually configuring nodes, allowing developers to effortlessly set up nodes for the bridge networks with just a few simple commands. The tool provides a user-friendly interface that makes the process accessible even to those new to blockchain development. +

+ ## About -Dive deeply into the world of Blockchain and Web 3.0 using **D.I.V.E.** (Deployable Infrastructure for Virtually Effortless blockchain integration),The Dive package aim to implement its services and API for ICON Blockchain. The kurtosis services and API are designed to simplify the process of deploying various nodes and services for development and testing and enhance the overall user experience. Implementing kurtosis for the ICON blockchain can help ease the developers in the ecosystem to focus more on building the business logic without worrying about the setup which consumes a significant amount of time. +The Dive CLI aim to implement its services and API for various Blockchains. The kurtosis services and API are designed to simplify the process of deploying various nodes and services for development and testing and enhance the overall user experience. Implementing kurtosis for the ICON blockchain can help ease the developers in the ecosystem to focus more on building the business logic without worrying about the setup which consumes a significant amount of time. The vision is to making ICON the interoperable hub by easing the setup of BTP and IBC for ICON and the connecting chains. -This repository uses [kurtosis package](https://docs.kurtosis.com/concepts-reference/packages) - -## Setup and requirements +## Prerequisites -Before proceeding make sure to have +Ensure the following prerequisites are met before using the Dive-package: +- [Docker](https://www.docker.com/): Make sure Docker is installed on your machine. You can [install it here](https://www.docker.com/). -- [Docker installed and running](https://docs.kurtosis.com/install#i-install--start-docker) +- [Kurtosis](https://www.kurtosis.com/): Ensure Kurtosis is installed on your machine. You can [install it here](https://www.kurtosis.com/). -- [Kurtosis installed and running ](https://docs.kurtosis.com/install#ii-install-the-cli) or [(upgrading to the latest)](https://docs.kurtosis.com/upgrade) -## DIVE CLI - -

-DIVE CLI – a powerful tool designed to streamline the entire process of node setup, network configuration, and BTP bridge creation. -With DIVE CLI, developers can easily connect and interact with various blockchain networks, paving the way for seamless cross-chain communication and smart contract deployment. -Serving as an all-in-one solution, DIVE CLI eliminates the hassle of manually configuring nodes, allowing developers to effortlessly set up nodes for the BTP network with just a few simple commands. The tool provides a user-friendly interface that makes the process accessible even to those new to blockchain development. -

- -## Installing Dive CLI +# Installing Dive CLI - Install on **`MacOS`** ``` @@ -63,37 +96,86 @@ Serving as an all-in-one solution, DIVE CLI eliminates the hassle of manually co dive.exe ``` -## Commands +# Commands + +- **bridge:** For setting up communication between two different chains.This will setup the relayer to connect two different chains and pass messages between them. + + **Subcommand:** + + - **btp:** Starts connection between specified chains using [BTP](https://icon.community/assets/btp-litepaper.pdf). + - **ibc:** Starts connection between specified chains using [IBC](https://www.ibcprotocol.dev/). + +- **chain:** For initialising and starting a specified blockchain node. By executing this command the node will be launched by enabling the network participation and ledger maintenance within the specified blockchain ecosystem. + + **Subcommand:** + + - **archway:** Build, initialise and start a archway node. + - **eth:** Build, initialise and start a eth node. + - **hardhat:** Build, initialise and start a hardhat node. + - **icon:** Build, initialise and start a icon node. + - **kusama:** Build, initialize and start a Kusama node + - **neutron:** Build, initialise and start a neutron node. + - **polkadot:** Build, initialize and start a Polkadot node + +- **clean:** Destroys and removes any running encalves. +- **discord:** Redirect to the DIVE discord channel. +- **enclaves:** Prints info about kurtosis enclaves. +- **tutorial:** Redirects to the Dive tutorials playlist. +- **twitter:** Opens official HugoByte twitter home page. +- **version:** Returns the current version of the CLI. + +## Available Flags -- **bridge** : For setting up communication between two different chains.This will setup the relayer to connect two different chains and pass messages between them. +**Global Flags** - **Subcommand**: +- **enclaveName (string):** Provide an enclave name to run services inside. Default enclave name is `dive` +- **verbose (bool):** Print out logs to Stdout. +- **h or help (bool):** Help. - - **btp** : Starts connection between specified chains using [BTP](https://icon.community/assets/btp-litepaper.pdf) +**Flags for Bridges** -- **chain**: For initialising and starting a specified blockchain node. By executing this command the node will be launched by enabling the network participation and ledger maintenance within the specified blockchain ecosystem +- **b or bmvbridge (bool):** Whether to use BMV bridge or not. (Only for BTP bridge) +- **chainA (string):** Name of the source chain. +- **chainAServiceName (string):** Service Name of the source chain from the service details file. +- **chainB (string):** Name of the destination chain. +- **chainBServiceName (string):** Service Name of the destination chain from the service details file. - **Subcommand**: +**Flags for Chains** - - **eth** : Build, initialise and start a eth node. +For archway/neutron: + +- **c or config (string):** Path to custom config json file. - - **hardhat** : Build, initialise and start a hardhat node. +For Icon: - - **icon** : Build, initialise and start a icon node. +- **c or config (string):** Path to custom config json file. +- **d or decentralization (bool):** Decentralize Icon Node. +- **g or genesis (string):** Path to custom genesis file. -- **clean**: Cleans the Enclave stared by Dive CLI -- **discord**: Redirect to the DIVE discord channel -- **tutorial**: Takes you to Dive tutorials -- **version**: Returns the current version of the CLI +For Kusama/Polkadot: -## Usage +- **c or config (string):** Path to custom config json file to start kusama relaychain and parachain nodes. +- **explorer (bool):** Specify the bool flag if you want to start polkadot js explorer service +- **metrics (bool):** Specify the bool flag if you want to start prometheus and grafana metrics service +- **n or network (string):** Specify the network to run (localnet/testnet/mainnet). Default will be localnet. +- **no-relay (bool):** Specify the bool flag to run parachain only (only for testnet and mainnet) +- **p or parachain (strings):** Specify the list of parachains to spawn parachain node + +**Flags for Clean** + +- **a (bool):** Clean all running enclaves. + + +# Usage > 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` -### Setting up an Node +## Setting up a Node -``` -dive chain icon +To set up an individual node, simply pass the name of the chain to the dive chain command: + +```bash +dive chain archway ``` After running the command, **DIVE CLI** will automatically start the ICON node and handle the necessary initialization processes. Please wait for the ICON node to fully initialize, which may take a few moments. @@ -101,87 +183,72 @@ After running the command, **DIVE CLI** will automatically start the ICON node a Once the initialization is complete, you can interact with the local ICON chain as needed.**DIVE CLI** sets up the ICON node on your local environment, enabling you to deploy and test smart contracts, explore transactions, and experiment with various ICON blockchain features > Detailed output during execution can be enabled via Verbose flag. -> example: `dive chain icon --verbose` -> Anyhow each Dive cli execution will be logged into log files under log folder in current working directory -After successful execution one can find service details in `services.json` created in current working directory. +> example: `dive chain archway --verbose` + +> Each Dive cli execution will be logged into log files under log folder in current working directory. + +After successful execution one can find service details in `services.json` created in output folder in current working directory. Example `services.json`: -```javascript +```json { -"icon-node-0xacbc4e": { # this key sepcifies service name - "block_number": "206", - "endpoint": "http://172.16.0.2:9080/api/v3/icon_dex", - "endpoint_public": "http://127.0.0.1:8090/api/v3/icon_dex", - "keypassword": "gochain", - "keystore_path": "keystores/keystore.json", - "network": "0x3.icon", - "networkId": "0x1", - "networkTypeId": "0x1", - "network_name": "icon-0xacbc4e", - "nid": "0x3", - "service_name": "icon-node-0xacbc4e" - } + "node-service-constantine-3": { + "service_name": "node-service-constantine-3", + "endpoint_public": "http://127.0.0.1:9431", + "endpoint": "http://172.16.4.5:26657", + "chain_id": "constantine-3", + "chain_key": "constantine-3-key" + } } ``` -### Setting Up Bridge Between Two Chains Which Is Already Running +You can also pass your custom config using the `-c` flag: -- Starting ICON +```bash +dive chain icon -c path/to/config/file +``` - ```bash - dive chain icon -d #This spins up icon and decentralise for btp - ``` +For detailed instructions on writing the configuration file, refer to the [Configuration File Guidelines](#configuration-file-guidelines) -- Starting ETH +## Setting Up Bridge Between Two Chains Which Are Already Running - ```bash - dive chain eth --verbose=true #This spins up Eth - ``` +To set up a bridge between two chains which are already running, you must have the service names of both the chains. - > `--verbose=true` can be used to see details execution logs - - Once chains are running you can find a services.json file in current working directory. Example services.json can be found below. - - ```javascript - { - - "icon-node-0xacbc4e": { - "block_number": "206", - "endpoint": "http://172.16.0.2:9080/api/v3/icon_dex", - "endpoint_public": "http://127.0.0.1:8090/api/v3/icon_dex", - "keypassword": "gochain", - "keystore_path": "keystores/keystore.json", - "network": "0x3.icon", - "networkId": "0x1", - "networkTypeId": "0x1", - "network_name": "icon-0xacbc4e", - "nid": "0x3", - "service_name": "icon-node-0xacbc4e" - }, - "el-1-geth-lighthouse": { - "block_number": "24", - "endpoint": "http://172.16.0.7:8545", - "endpoint_public": "http://", - "keypassword": "password", - "keystore_path": "keystores/eth_keystore.json", - "network": "0x301824.eth", - "network_name": "eth", - "nid": "0x301824", - "service_name": "el-1-geth-lighthouse" - } - } - ``` +For ex: To start an ibc bridge between icon and archway, we need to have service details of icon and archway as follows: - Now you can start bridge just by running +```json +{ + "icon-node-0xacbc4e": { + "service_name": "icon-node-0xacbc4e", + "endpoint_public": "http://127.0.0.1:44444/api/v3/icon_dex", + "endpoint": "http://172.16.4.6:9080/api/v3/icon_dex", + "keypassword": "gochain", + "keystore_path": "keystores/keystore.json", + "network": "0x3.icon", + "network_name": "icon-0xacbc4e", + "nid": "0x3" + }, + "node-service-constantine-3": { + "service_name": "node-service-constantine-3", + "endpoint_public": "http://127.0.0.1:9431", + "endpoint": "http://172.16.4.5:26657", + "chain_id": "constantine-3", + "chain_key": "constantine-3-key" + } +} +``` - ```bash - dive bridge btp --chainA icon --chainB eth --chainAServiceName icon-node-0xacbc4e --chainBServiceName el-1-geth-lighthouse - ``` +Run this command to start a bridge between the two nodes: -### Setting Bridge Between Two Chains +```bash +dive bridge ibc --chainA icon --chainB archway --chainAServiceName icon-node-0xacbc4e --chainBServiceName node-service-constantine-3 +``` +> Note: You can also pass a single running chain instead of passing both. In such case, you can only pass either one of the service name flags that corresponds to the chain. + +## Setting Up Bridge Between Two Chains -Run below command to start btp connection between any supported chain +To set up a bridge between two chains, run this command: ```bash dive bridge btp --chainA icon --chainB eth -b @@ -189,87 +256,396 @@ dive bridge btp --chainA icon --chainB eth -b > `-b` flag is used to specify the type of bmv contract to be deployed for btp setup. -This command sets up btp bridge between icon and eth . After running this command **DIVE CLI** will automatically starts the ICON & ETH node , Deploys contract which is used for BTP and starts the realay to constanly exchange message between established connection. -After successful bridge setup all the neccessary details with respect to bridge will be added to `dive.json` file that will be present in current working directory. -Example `dive.json`: +This command sets up btp bridge between icon and eth . After running this command **DIVE CLI** will automatically starts the ICON & ETH node, deploy contracts which is used for BTP and starts the relay to constantly exchange messages between the established connection. + +After successful bridge setup all the neccessary details with respect to bridge will be added to `dive.json` file that will be present in the output folder in current working directory. + +> Checkout More details on how to setup [BTP](https://www.xcall.dev/quickstart/setting-up-a-local-environment-with-dive-cli) bridge + +## Setting Up Relay and Para Chains + +To set up a relay chain, run this command: + +```bash +dive chain kusama +``` + +To set up a parachain in polkadot along with the relay chain, run this command: + +```bash +dive chain polkadot -p frequency +``` + +To set up only the parachain in kusama, run this command: + +```bash +dive chain kusama -p encointer -n testnet --no-relay +``` + +To set up explorer, pass this flag: + +```bash +dive chain kusama -p encointer --explorer +``` + +To set up metrics, pass this flag: + +```bash +dive chain polkadot -p frequency --metrics +``` + +To specify the network, use the `n` flag: + +```bash +dive chain polkadot -n mainnet +``` + +To pass a custom config, use the `c` flag: + +```bash +dive chain kusama -c path/to/config/file +``` + +For detailed instructions on writing the configuration file, refer to the [Configuration File Guidelines](#configuration-file-guidelines) + +> Note: You can run a parachain without a relay chain only in testnet and mainnet networks. + +> Note: The default network type is localnet. + +# Configuration File Guidelines + +You can also pass custom config using the -c flag for chains that support custom config. + +For **cosmos chain (Archway/Neutron)**, the config file is as follows: + +```json +{ + "chain_id": "archway-node-0", + "key": "archway-node-0-key", + "password": "password" +} +``` + +For **Icon chain**, the config file is as follows: + +```json +{ + "p2p_listen_address": "7080", + "p2p_address": "8080", + "cid": "0xacbc4e" +} +``` + +For **Polkadot/Kusama**, the config file is as follows: + +```json +{ + "chain_type": "localnet", + "relaychain": { + "name": "rococo-local", + "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 + +For **cosmos chain (Archway/Neutron):** + +- **chain_id:** The Chain ID of the chain. +- **key:** The Key to use to spawn the node. +- **password:** The pPassword to use to spawn the node. + +For **Icon chain:** + +- **p2p_listen_address:** The p2p listen address. +- **p2p_address:** The p2p address. +- **cid:** The CID (Chain ID) of the node. + +For **Polkadot/Kusama:** + +- **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). + +> Note: The polkadot/kusama command start two nodes in relay chain and one node in parachain by default in localnet. In testnet and mainnet, only one node is started for both by default. -```javascript +## Config Templates + +Feel free to modify this example configuration file based on your specific network requirements. [Here](./cli/sample-jsons) is a link to the official templates that you can edit and use. + +# Service Details + +The service details are all stored in the output folder in the current working directory. The output is further divided into sub-folders named after the enclave. The sample service details for various commands are given below. + +## Chain Command +The service details returned after running a chain command is as follows: + +```json +{ + "icon-node-0xacbc4e": { + "service_name": "icon-node-0xacbc4e", + "endpoint_public": "http://127.0.0.1:44444/api/v3/icon_dex", + "endpoint": "http://172.16.4.6:9080/api/v3/icon_dex", + "keypassword": "gochain", + "keystore_path": "keystores/keystore.json", + "network": "0x3.icon", + "network_name": "icon-0xacbc4e", + "nid": "0x3" + } +} +``` + +## Bridge Command + +The service details returned after running a bridge command is as follows: + +```json { - "bridge": "true", - "chains": { - "el-1-geth-lighthouse": { - "block_number": "24", - "endpoint": "http://172.16.0.7:8545", - "endpoint_public": "http://", - "keypassword": "password", - "keystore_path": "keystores/eth_keystore.json", - "network": "0x301824.eth", - "network_name": "eth", - "nid": "0x301824", - "service_name": "el-1-geth-lighthouse" - }, - "icon-node-0xacbc4e": { - "block_number": "206", - "endpoint": "http://172.16.0.2:9080/api/v3/icon_dex", - "endpoint_public": "http://127.0.0.1:8090/api/v3/icon_dex", - "keypassword": "gochain", - "keystore_path": "keystores/keystore.json", - "network": "0x3.icon", - "networkId": "0x1", - "networkTypeId": "0x1", - "network_name": "icon-0xacbc4e", - "nid": "0x3", - "service_name": "icon-node-0xacbc4e" - } - }, - "contracts": { - "el-1-geth-lighthouse": { - "bmc": "0xB9D7a3554F221B34f49d7d3C61375E603aFb699e", - "bmcm": "0xAb2A01BC351770D09611Ac80f1DE076D56E0487d", - "bmcs": "0xBFF5cD0aA560e1d1C6B1E2C347860aDAe1bd8235", - "bmv": "0x765E6b67C589A4b40184AEd9D9ae7ba40E32F8d4", - "dapp": "0x9bE03fF3E1888A216f9e48c68B587A89c5b94CD6", - "xcall": "0x5911A6541729C227fAda7D5187ee7518B47fB237" - }, - "icon-node-0xacbc4e": { - "bmc": "cx3f9b7aa2a7fa0334a0068a324c9020b9138363f1", - "bmv": "cxe308f1f14febfff0f906df89d4bd191ba11b4689", - "dapp": "cxfe3cdbe04e78ff3747b076cb7122c4f7ba58cf49", - "xcall": "cx4b33b94cb04bf2c179cda1af81c1d1eb639c5e98" - } - }, - "links": { - "dst": "el-1-geth-lighthouse", # service name for eth chain - "src": "icon-node-0xacbc4e" # Service name for ICON chain - } + "ibc-bridge-icon-archway": { + "chains": { + "icon-node-0xacbc4e": { + "endpoint": "http://172.16.4.6:9080/api/v3/icon_dex", + "endpoint_public": "http://127.0.0.1:44444/api/v3/icon_dex", + "keypassword": "gochain", + "keystore_path": "keystores/keystore.json", + "network": "0x3.icon", + "network_name": "icon-0xacbc4e", + "nid": "0x3", + "service_name": "icon-node-0xacbc4e" + }, + "node-service-constantine-3": { + "chain_id": "constantine-3", + "chain_key": "constantine-3-key", + "endpoint": "http://172.16.4.5:26657", + "endpoint_public": "http://127.0.0.1:9431", + "service_name": "node-service-constantine-3" + } + }, + "contracts": { + "icon-node-0xacbc4e": { + "dapp": "cxdc423964a82cb08ce561b35162b1206ade3199b9", + "ibc_core": "cxf60b8dfcf5745df1ca81832bbd0281fb1c961413", + "light_client": "cx22edaace91d092b3bd62008a57cef77fb8cc458c", + "xcall": "cxc34f0537d11e3c26ee4bbcb6c181daba3a84d0cd", + "xcall_connection": "cx13c69e008ae87e5d0c90ea72f3aa3202e068fe3b" + }, + "node-service-constantine-3": { + "dapp": "archway1eyfccmjm6732k7wp4p6gdjwhxjwsvje44j0hfx8nkgrm8fs7vqfshgatxw", + "ibc_core": "archway14hj2tavq8fpesdwxxcu44rty3hh90vhujrvcmstl4zr3txmfvw9sy85n2u", + "light_client": "archway1nc5tatafv6eyq7llkr2gv50ff9e22mnf70qgjlv737ktmt4eswrqgj33g6", + "xcall": "archway17p9rzwnnfxcjp32un9ug7yhhzgtkhvl9jfksztgw5uh69wac2pgssf05p7", + "xcall_connection": "archway1ghd753shjuwexxywmgs4xz7x2q732vcnkm6h2pyv9s6ah3hylvrqvlzdpl" + } + }, + "links": { + "dst": "node-service-constantine-3", + "src": "icon-node-0xacbc4e" + } + } } ``` +## Relay and Para Chains + +The service details returned after running a relay chain/para chain is as follows: + +```json +{ + "frequency-alice-localnet": { + "service_name": "frequency-alice-localnet", + "endpoint_public": "ws://127.0.0.1:31584", + "endpoint": "ws://172.16.0.10:9946", + "endpoint_prometheus": "tcp://127.0.0.1:13713", + "prometheus": true, + "ip_address": "172.16.0.10", + "prometheus_port": 9615, + "prometheus_public_port": 13713 + }, + "grafana": { + "service_name": "grafana", + "endpoint_public": "http://127.0.0.1:64304", + "endpoint": "http://172.16.0.13:3000" + }, + "polkadot-js-explorer": { + "service_name": "polkadot-js-explorer", + "endpoint_public": "http://127.0.0.1:80", + "endpoint": "http://172.16.0.14:80" + }, + "prometheus": { + "service_name": "prometheus", + "endpoint_public": "http://127.0.0.1:25553", + "endpoint": "http://172.16.0.12:9090" + }, + "rococo-local-alice": { + "service_name": "rococo-local-alice", + "endpoint_public": "ws://127.0.0.1:54384", + "endpoint": "ws://172.16.0.5:9944", + "endpoint_prometheus": "tcp://127.0.0.1:60957", + "prometheus": true, + "ip_address": "172.16.0.5", + "prometheus_port": 9615, + "prometheus_public_port": 60957 + }, + "rococo-local-bob": { + "service_name": "rococo-local-bob", + "endpoint_public": "ws://127.0.0.1:21996", + "endpoint": "ws://172.16.0.4:9944", + "endpoint_prometheus": "tcp://127.0.0.1:9351", + "prometheus": true, + "ip_address": "172.16.0.4", + "prometheus_port": 9615, + "prometheus_public_port": 9351 + } +} +``` + +> Note: The service files are name as `services.json` and `dive.json` for chain and bridge commands respectively. + +> Note: The file names for both chain and bridge commands contain the name of the enclave and the short UUID of the enclave. + +# Logs + +The logs are located within the 'logs' folder, further organized into individual folders named after each enclave. + +You can find the 'logs' folder in the current working directory. -### Version +Each folder named after the enclave, has two files: + - **dive.log** : It is created when the execution of a command starts. It contains the execution logs. + - **error.log** : It is created when an error occurs during the execution of the command. It contains the error logs. + +The file names also contain the timestamp which can be helpful to find a particular log file. + +> Note: The logs folder is not deleted when dive clean is run. + +# Version + +To check the current version of **DIVE CLI**, run this command: ```bash dive version ``` -Prints out the current version of **DIVE CLI** +# Cleaning -### Cleaning +To clean a specific enclave, use: ```bash -dive clean +dive clean --enclaveName 'enclave' ``` -Command cleans up the artifacts , services created on the Enclave during **DIVE** package execution +To clean all running enclaves, use: -> Checkout More details on how to setup [BTP](https://www.xcall.dev/quickstart/setting-up-a-local-environment-with-dive-cli) bridge +```bash +dive clean -a +``` + +> Note: Using the clean command will remove the service files in the output folder. Using `-a` flag removes the output folder. + +# Enclaves + +To get the details of all the running enclaves, use: + +```bash +dive enclaves +``` + +# Socials + +To access any of HugoByte's official social media, run: + +```bash +dive discord +``` + +```bash +dive tutorial +``` + +# Testing + +For guidelines on testing, please refer [here](test/README.md). + +## Known Issues + +[Here](https://github.com/HugoByte/DIVE/issues) 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 Dive-packages, refer to the following troubleshooting tips to resolve common problems: + +- Clean kurtosis engine using: +```bash +kurtosis clean -a +``` + +- Restart kurtosis engine using: +```bash +kurtosis engine restart +``` + +- Check if your docker is installed and accessible: +```bash +docker --version +``` + +- Check if your DIVE-CLI is installed and accessible: +```bash +dive version +``` + +- Upgrade or Re-install your DIVE-CLI: + +Refer [here](#installing-dive-cli) to upgrade or re-install your cli. -## Testing +If you still experience issues after following these troubleshooting tips, please [open an issue](https://github.com/HugoByte/DIVE/issues) to get further assistance. -- Follow the instruction in [Test Folder](test/README.md#steps-to-run-the-script) ## Contributing -Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**. +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 DIVE. 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. @@ -285,7 +661,8 @@ If you have a suggestion that would make this better, please fork the repo and c ## References -Special thanks to [Kurtosis-Tech](https://github.com/kurtosis-tech). +- This repository uses [dive-packages](https://github.com/HugoByte/dive-packages) +- This repository uses [polkadot-kurtosis-packages](https://github.com/HugoByte/polkadot-kurtosis-package) ## License diff --git a/cli/cmd/bridge/utils/types.go b/cli/cmd/bridge/utils/types.go index 06089cd3..a5e9f8f9 100644 --- a/cli/cmd/bridge/utils/types.go +++ b/cli/cmd/bridge/utils/types.go @@ -96,20 +96,20 @@ func (chains *Chains) GetServicesResponse(cli *common.Cli) (string, string, erro func (chains *Chains) CheckForBtpSupportedChains() error { if !slices.Contains(supportedChainsForBtp, chains.ChainA) { - return fmt.Errorf("invalid Chain: %s", chains.ChainA) + return fmt.Errorf("invalid chain: %s", chains.ChainA) } if !slices.Contains(supportedChainsForBtp, chains.ChainB) { - return fmt.Errorf("invalid Chain: %s", chains.ChainB) + return fmt.Errorf("invalid chain: %s", chains.ChainB) } return nil } func (chains *Chains) CheckForIbcSupportedChains() error { if !slices.Contains(supportedChainsForIbc, chains.ChainA) { - return fmt.Errorf("invalid Chain: %s", chains.ChainA) + return fmt.Errorf("invalid chain: %s", chains.ChainA) } if !slices.Contains(supportedChainsForIbc, chains.ChainB) { - return fmt.Errorf("invalid Chain: %s", chains.ChainB) + return fmt.Errorf("invalid chain: %s", chains.ChainB) } return nil } diff --git a/cli/cmd/chains/kusama/run.go b/cli/cmd/chains/kusama/run.go index 2f383d87..eb49660b 100644 --- a/cli/cmd/chains/kusama/run.go +++ b/cli/cmd/chains/kusama/run.go @@ -13,7 +13,7 @@ import ( ) const ( - localChain = "local" + localChain = "localnet" polkadotJUrl = "http://127.0.0.1/?rpc=ws://%s:%s#/explorer" PolkadotJsServiceName = "polkadot-js-explorer" ) @@ -257,9 +257,9 @@ func configureService(serviceConfig *utils.PolkadotServiceConfig) error { } } - if noRelay && serviceConfig.ChainType == "local" { - return common.WrapMessageToError(common.ErrInvalidFlag, "The '--no-relay' flag cannot be used with a 'local' network. This flag is only applicable for 'testnet' and 'mainnet' networks.") - } else if noRelay && serviceConfig.ChainType != "local" { + if noRelay && serviceConfig.ChainType == localChain { + return common.WrapMessageToError(common.ErrInvalidFlag, "The '--no-relay' flag cannot be used with a 'localnet' network. This flag is only applicable for 'testnet' and 'mainnet' networks.") + } else if noRelay && serviceConfig.ChainType != localChain { serviceConfig.RelayChain = utils.RelayChainConfig{} } diff --git a/cli/cmd/chains/polkadot/run.go b/cli/cmd/chains/polkadot/run.go index 677a860e..cdc3421a 100644 --- a/cli/cmd/chains/polkadot/run.go +++ b/cli/cmd/chains/polkadot/run.go @@ -13,7 +13,7 @@ import ( ) const ( - localChain = "local" + localChain = "localnet" polkadotJUrl = "http://127.0.0.1/?rpc=ws://%s:%s#/explorer" PolkadotJsServiceName = "polkadot-js-explorer" ) @@ -257,9 +257,9 @@ func configureService(serviceConfig *utils.PolkadotServiceConfig) error { } } - if noRelay && serviceConfig.ChainType == "local" { - return common.WrapMessageToError(common.ErrInvalidFlag, "The '--no-relay' flag cannot be used with a 'local' network. This flag is only applicable for 'testnet' and 'mainnet' networks.") - } else if noRelay && serviceConfig.ChainType != "local" { + if noRelay && serviceConfig.ChainType == localChain { + return common.WrapMessageToError(common.ErrInvalidFlag, "The '--no-relay' flag cannot be used with a 'localnet' network. This flag is only applicable for 'testnet' and 'mainnet' networks.") + } else if noRelay && serviceConfig.ChainType != localChain { serviceConfig.RelayChain = utils.RelayChainConfig{} } diff --git a/cli/cmd/chains/utils/types.go b/cli/cmd/chains/utils/types.go index c2502561..dd2fc62d 100644 --- a/cli/cmd/chains/utils/types.go +++ b/cli/cmd/chains/utils/types.go @@ -38,13 +38,13 @@ func (cs *CosmosServiceConfig) LoadDefaultConfig() error { publicRPC, err := common.GetAvailablePort() if err != nil { - return common.WrapMessageToError(err, "error getting available Rpc port") + return common.WrapMessageToError(err, "error getting available RPC port") } cs.PublicRPC = &publicRPC publicTCP, err := common.GetAvailablePort() if err != nil { - return common.WrapMessageToError(err, "error getting available Tcp port") + return common.WrapMessageToError(err, "error getting available TCP port") } cs.PublicTCP = &publicTCP @@ -87,13 +87,13 @@ func (cs *CosmosServiceConfig) LoadConfigFromFile(cliContext *common.Cli, filePa publicRPC, err := common.GetAvailablePort() if err != nil { - return common.WrapMessageToError(err, "error getting available Rpc port") + return common.WrapMessageToError(err, "error getting available RPC port") } cs.PublicRPC = &publicRPC publicTCP, err := common.GetAvailablePort() if err != nil { - return common.WrapMessageToError(err, "error getting available Tcp port") + return common.WrapMessageToError(err, "error getting available TCP port") } cs.PublicTCP = &publicTCP @@ -286,7 +286,7 @@ func (sc *PolkadotServiceConfig) LoadConfigFromFile(cliContext *common.Cli, file } func (sc *PolkadotServiceConfig) LoadDefaultConfig() error { - sc.ChainType = "local" + sc.ChainType = "localnet" sc.Explorer = false sc.RelayChain.Name = "rococo-local" sc.RelayChain.Nodes = []NodeConfig{ @@ -417,7 +417,7 @@ func (sc *PolkadotServiceConfig) HasPrometheus() bool { } func (sc *PolkadotServiceConfig) ValidateConfig() error { - var validChainTypes = []string{"local", "testnet", "mainnet"} + var validChainTypes = []string{"localnet", "testnet", "mainnet"} var validRelayNodeType = []string{"validator", "full"} var validParaNodeType = []string{"collator", "full"} var invalidTestNetParaChains = []string{"parallel", "subzero"} @@ -426,39 +426,39 @@ func (sc *PolkadotServiceConfig) ValidateConfig() error { return fmt.Errorf("invalid Chain Type: %s", sc.ChainType) } - if sc.ChainType == "local" { + if sc.ChainType == "localnet" { if sc.RelayChain.Name != "rococo-local" { - return fmt.Errorf("invalid Chain Name for local: %s", sc.RelayChain.Name) + return fmt.Errorf("invalid chain name for localnet: %s", sc.RelayChain.Name) } if len(sc.RelayChain.Nodes) < 2 { - return fmt.Errorf("atleast two nodes required for Relay Chain Local") + return fmt.Errorf("atleast two nodes required for relaychain local") } for _, node := range sc.RelayChain.Nodes { if node.NodeType != "validator" { - return fmt.Errorf("invalid Node Type for Relay Chain Local: %s", node.NodeType) + return fmt.Errorf("invalid node type for relaychain local: %s", node.NodeType) } } } else { for _, node := range sc.RelayChain.Nodes { if !slices.Contains(validRelayNodeType, node.NodeType) { - return fmt.Errorf("invalid Node Type for Relay Chain: %s", node.NodeType) + return fmt.Errorf("invalid node type for relaychain: %s", node.NodeType) } } } if sc.RelayChain.Name != "" { if sc.ChainType == "testnet" && !(sc.RelayChain.Name == "rococo" || sc.RelayChain.Name == "westend") { - return fmt.Errorf("invalid Chain Name for testnet: %s", sc.RelayChain.Name) + return fmt.Errorf("invalid chain name for testnet: %s", sc.RelayChain.Name) } if sc.ChainType == "mainnet" && !(sc.RelayChain.Name == "kusama" || sc.RelayChain.Name == "polkadot") { - return fmt.Errorf("invalid Chain Name for mainnet: %s", sc.RelayChain.Name) + return fmt.Errorf("invalid chain name for mainnet: %s", sc.RelayChain.Name) } } if sc.ChainType == "testnet" { for _, paraChain := range sc.Para { if slices.Contains(invalidTestNetParaChains, paraChain.Name) { - return fmt.Errorf("no Testnet for Parachain: %s", paraChain.Name) + return fmt.Errorf("no testnet for parachain: %s", paraChain.Name) } } } @@ -466,7 +466,11 @@ func (sc *PolkadotServiceConfig) ValidateConfig() error { for _, paraChain := range sc.Para { for _, node := range paraChain.Nodes { if !slices.Contains(validParaNodeType, node.NodeType) { - return fmt.Errorf("invalid Node Type for Parachain: %s", node.NodeType) + return fmt.Errorf("invalid node type for parachain: %s", node.NodeType) + } + + if paraChain.Name == "clover" && node.NodeType == "collator" { + return fmt.Errorf("invalid node type for clover parachain: %s", node.NodeType) } } } @@ -480,7 +484,7 @@ func (sc *PolkadotServiceConfig) GetParamsForRelay() (string, error) { return "", common.WrapMessageToError(common.ErrDataMarshall, err.Error()) } - if sc.ChainType == "local" { + if sc.ChainType == "localnet" { return fmt.Sprintf(`{"relaychain": %s}`, relay_nodes), nil } else { return fmt.Sprintf(`{"chain_type": "%s", "relaychain": %s}`, sc.ChainType, relay_nodes), nil diff --git a/cli/sample-jsons/polkadot_config.json b/cli/sample-jsons/polkadot_config.json index 117b7efd..c1f0ce29 100644 --- a/cli/sample-jsons/polkadot_config.json +++ b/cli/sample-jsons/polkadot_config.json @@ -1,5 +1,5 @@ { - "chain_type": "local", + "chain_type": "localnet", "relaychain": { "name": "rococo-local", "nodes": [ @@ -11,7 +11,7 @@ { "name": "bob", "node_type": "validator", - "prometheus": true + "prometheus": false } ] @@ -30,10 +30,10 @@ { "name": "bob", "node_type": "full", - "prometheus": true + "prometheus": false } ] } ], - "explorer": true + "explorer": false } \ No newline at end of file