From 72ec82b26c2fe8d268a29d5642c4529ba7ec07bd Mon Sep 17 00:00:00 2001 From: JukLee0ira Date: Wed, 20 Nov 2024 17:10:45 +0800 Subject: [PATCH] struct of subnet doc --- docs/subnet/Installation_guide.md | 322 ++++++++++++++++++ docs/subnet/components.md | 6 + docs/subnet/components/api_library.md | 8 + docs/subnet/components/checkpoint_contract.md | 183 ++++++++++ docs/subnet/components/relayer.md | 37 ++ docs/subnet/components/subnet_chain.md | 35 ++ docs/subnet/components/subswap.md | 186 ++++++++++ docs/subnet/components/xdc_zero.md | 170 +++++++++ docs/subnet/index.md | 17 + .../install_guide/config_explanation.md | 63 ++++ docs/subnet/install_guide/f&q.md | 77 +++++ docs/subnet/install_guide/launch_subnet.md | 74 ++++ docs/subnet/setting_up_your_subnet.md | 7 + docs/subnet/upgrading_subnet.md | 34 ++ docs/subnet/using_subnet.md | 177 ++++++++++ mkdocs.yml | 22 +- 16 files changed, 1413 insertions(+), 5 deletions(-) create mode 100644 docs/subnet/Installation_guide.md create mode 100644 docs/subnet/components.md create mode 100644 docs/subnet/components/api_library.md create mode 100644 docs/subnet/components/checkpoint_contract.md create mode 100644 docs/subnet/components/relayer.md create mode 100644 docs/subnet/components/subnet_chain.md create mode 100644 docs/subnet/components/subswap.md create mode 100644 docs/subnet/components/xdc_zero.md create mode 100644 docs/subnet/install_guide/config_explanation.md create mode 100644 docs/subnet/install_guide/f&q.md create mode 100644 docs/subnet/install_guide/launch_subnet.md create mode 100644 docs/subnet/setting_up_your_subnet.md create mode 100644 docs/subnet/upgrading_subnet.md create mode 100644 docs/subnet/using_subnet.md diff --git a/docs/subnet/Installation_guide.md b/docs/subnet/Installation_guide.md new file mode 100644 index 0000000..1790858 --- /dev/null +++ b/docs/subnet/Installation_guide.md @@ -0,0 +1,322 @@ +--- +title: Installation Guide +--- + + +In the rapidly evolving landscape of blockchain technology, staying ahead of the curve is essential. One of the most intriguing advancements in the world of blockchain is the concept of blockchain subnets. In this comprehensive guide, we will dive deep into what blockchain subnets are, how they work, and why they are becoming a game-changer in the blockchain industry. + +**What Are Blockchain Subnets?** +Blockchain subnets are like specialized branches of a blockchain network. They allow you to create smaller, independent networks within a larger blockchain ecosystem. Think of them as self-contained mini-blockchains, each with its own unique features and functionalities. These subnets operate alongside the main blockchain but offer more flexibility and scalability. + +**How Do Blockchain Subnets Work?** +Blockchain subnets work by segregating the main blockchain into smaller, more manageable parts. This segmentation brings several advantages such as Scalability, Customization, Privacy and Security. + +**Setting Up Your Own Blockchain Subnet** +**[XDC Subnet](https://xinfin.org/xdc-subnet)** is a powerful technology that allows you to create a secure, scalable, and decentralized network within the XDC Ecosystem. It enables various use cases, including creating private subnets, deploying decentralized applications (DApps), and more. In this guide, we’ll walk you through the steps to set up your own XDC Subnet, opening doors to a world of possibilities. + +**Step 1: Uninstall Old Versions** + +Before you dive into setting up XDC Subnet, ensure that you don’t have any conflicting packages from previous installations. Run the following command to uninstall them: + + for pkg in docker.io docker-doc docker-compose podman-docker containerd runc; do sudo apt-get remove $pkg; done + + +Enter fullscreen mode Exit fullscreen mode + +[![Image description](https://www.xdc.dev/images/H8jvK-J9mS3Wc-nv4Tp8Xe_Qw-57izhfPUH2oLYj6Ns/w:880/mb:500000/ar:1/aHR0cHM6Ly93d3cu/eGRjLmRldi91cGxv/YWRzL2FydGljbGVz/L2k0aWNidDBobGty/OWtkZ2xzb3BrLnBu/Zw)](https://www.xdc.dev/images/H8jvK-J9mS3Wc-nv4Tp8Xe_Qw-57izhfPUH2oLYj6Ns/w:880/mb:500000/ar:1/aHR0cHM6Ly93d3cu/eGRjLmRldi91cGxv/YWRzL2FydGljbGVz/L2k0aWNidDBobGty/OWtkZ2xzb3BrLnBu/Zw) + +**Step 2: Set Up the [Docker Repository](https://docs.docker.com/engine/install/ubuntu/#set-up-the-repository)** + +To install Docker Engine, you need to set up the Docker repository. Follow these steps: + +1. Update the apt package index and install required packages: + + $ sudo apt-get update + $ sudo apt-get install ca-certificates curl gnupg + + +Enter fullscreen mode Exit fullscreen mode + +[![Image description](https://www.xdc.dev/images/fpLc5VCUomHHhnJAsSYZuEp5ePWvrSl5zb07ElQ7n90/w:880/mb:500000/ar:1/aHR0cHM6Ly93d3cu/eGRjLmRldi91cGxv/YWRzL2FydGljbGVz/L2lhNmd4YnY5Z2Vp/OTg2bzM5bmVjLnBu/Zw)](https://www.xdc.dev/images/fpLc5VCUomHHhnJAsSYZuEp5ePWvrSl5zb07ElQ7n90/w:880/mb:500000/ar:1/aHR0cHM6Ly93d3cu/eGRjLmRldi91cGxv/YWRzL2FydGljbGVz/L2lhNmd4YnY5Z2Vp/OTg2bzM5bmVjLnBu/Zw) + +[![Image description](https://www.xdc.dev/images/8TaLx5rpT3xt0D8h6yLGX1n60pK1jGAvSTSx1H16h68/w:880/mb:500000/ar:1/aHR0cHM6Ly93d3cu/eGRjLmRldi91cGxv/YWRzL2FydGljbGVz/L2J2NW9nemFiZzdl/OWxxeTV4anFoLnBu/Zw)](https://www.xdc.dev/images/8TaLx5rpT3xt0D8h6yLGX1n60pK1jGAvSTSx1H16h68/w:880/mb:500000/ar:1/aHR0cHM6Ly93d3cu/eGRjLmRldi91cGxv/YWRzL2FydGljbGVz/L2J2NW9nemFiZzdl/OWxxeTV4anFoLnBu/Zw) + +1. Add Docker’s official GPG key: + + $ sudo install -m 0755 -d /etc/apt/keyrings + $ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg - dearmor -o /etc/apt/keyrings/docker.gpg + $ sudo chmod a+r /etc/apt/keyrings/docker.gpg + + +Enter fullscreen mode Exit fullscreen mode + +[![Image description](https://www.xdc.dev/images/4sH-qnrAM_XukxTa8ADsdiN30807wcI-iTUBV9n3QDI/w:880/mb:500000/ar:1/aHR0cHM6Ly93d3cu/eGRjLmRldi91cGxv/YWRzL2FydGljbGVz/L3ByeGNqNnFxaXY2/cXNodHN2YnZzLnBu/Zw)](https://www.xdc.dev/images/4sH-qnrAM_XukxTa8ADsdiN30807wcI-iTUBV9n3QDI/w:880/mb:500000/ar:1/aHR0cHM6Ly93d3cu/eGRjLmRldi91cGxv/YWRzL2FydGljbGVz/L3ByeGNqNnFxaXY2/cXNodHN2YnZzLnBu/Zw) + +1. Use the following command to set up the repository: + + $ echo \ + "deb [arch="$(dpkg - print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ + "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \ + sudo tee /etc/apt/sources.list.d/docker.list > /dev/null + + +Enter fullscreen mode Exit fullscreen mode + +[![Image description](https://www.xdc.dev/images/_wux1WdFNGn3je4-Da-S_gYCk6jMD41gE0zmraUr1P0/w:880/mb:500000/ar:1/aHR0cHM6Ly93d3cu/eGRjLmRldi91cGxv/YWRzL2FydGljbGVz/L2lucXMzdnlnc3Vz/bTdocGdla3BvLnBu/Zw)](https://www.xdc.dev/images/_wux1WdFNGn3je4-Da-S_gYCk6jMD41gE0zmraUr1P0/w:880/mb:500000/ar:1/aHR0cHM6Ly93d3cu/eGRjLmRldi91cGxv/YWRzL2FydGljbGVz/L2lucXMzdnlnc3Vz/bTdocGdla3BvLnBu/Zw) + +1. Update the apt package index again: + + $ sudo apt-get update + + +Enter fullscreen mode Exit fullscreen mode + +[![Image description](https://www.xdc.dev/images/TqvEhelrqKAR8tb0EISe5w0PLld3ueCLyzfTFbxYejI/w:880/mb:500000/ar:1/aHR0cHM6Ly93d3cu/eGRjLmRldi91cGxv/YWRzL2FydGljbGVz/L3oxbDZzNnB3dHRv/NnJmb2kycDYzLnBu/Zw)](https://www.xdc.dev/images/TqvEhelrqKAR8tb0EISe5w0PLld3ueCLyzfTFbxYejI/w:880/mb:500000/ar:1/aHR0cHM6Ly93d3cu/eGRjLmRldi91cGxv/YWRzL2FydGljbGVz/L3oxbDZzNnB3dHRv/NnJmb2kycDYzLnBu/Zw) + +**Step 3: [Install Docker Engine](https://docs.docker.com/engine/install/ubuntu/#install-docker-engine)** + +1. Now, you can install Docker Engine, containerd, and Docker Compose by running the following command: + + sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin + + + +Enter fullscreen mode Exit fullscreen mode + +[![Image description](https://www.xdc.dev/images/j1B8gAvEia9e1X43tbnLvgxUpnWRBGkrOBYo1ZGFfos/w:880/mb:500000/ar:1/aHR0cHM6Ly93d3cu/eGRjLmRldi91cGxv/YWRzL2FydGljbGVz/L2o2MGpzb3RpZzht/cjhueWo4cHVsLnBu/Zw)](https://www.xdc.dev/images/j1B8gAvEia9e1X43tbnLvgxUpnWRBGkrOBYo1ZGFfos/w:880/mb:500000/ar:1/aHR0cHM6Ly93d3cu/eGRjLmRldi91cGxv/YWRzL2FydGljbGVz/L2o2MGpzb3RpZzht/cjhueWo4cHVsLnBu/Zw) + +1. Verify the installation by running: + + $ sudo docker run hello-world + + +Enter fullscreen mode Exit fullscreen mode + +[![Image description](https://www.xdc.dev/images/xQKjZPiTb42VNWH4gJdXT5pZj-ek_k5Wuvkfjx416vg/w:880/mb:500000/ar:1/aHR0cHM6Ly93d3cu/eGRjLmRldi91cGxv/YWRzL2FydGljbGVz/L216OWRteGlic3lu/Z2FlbGdhYnMzLnBu/Zw)](https://www.xdc.dev/images/xQKjZPiTb42VNWH4gJdXT5pZj-ek_k5Wuvkfjx416vg/w:880/mb:500000/ar:1/aHR0cHM6Ly93d3cu/eGRjLmRldi91cGxv/YWRzL2FydGljbGVz/L216OWRteGlic3lu/Z2FlbGdhYnMzLnBu/Zw) + +1. Update the apt package index & Test the installation. + + $ sudo apt-get update + $ docker compose version + + +Enter fullscreen mode Exit fullscreen mode + +[![Image description](https://www.xdc.dev/images/DtwNZAdP_wtEz46Wmei9pelgnMb1Ciqi1UupgMwmvHs/w:880/mb:500000/ar:1/aHR0cHM6Ly93d3cu/eGRjLmRldi91cGxv/YWRzL2FydGljbGVz/L3BvdjRvOTY5eGl1/am9zZ3B3b2FxLnBu/Zw)](https://www.xdc.dev/images/DtwNZAdP_wtEz46Wmei9pelgnMb1Ciqi1UupgMwmvHs/w:880/mb:500000/ar:1/aHR0cHM6Ly93d3cu/eGRjLmRldi91cGxv/YWRzL2FydGljbGVz/L3BvdjRvOTY5eGl1/am9zZ3B3b2FxLnBu/Zw) + +[![Image description](https://www.xdc.dev/images/ISC7QEPDfiYCkQh7-8EZkhgZUpBOzaVymuXHbfk1Rbs/w:880/mb:500000/ar:1/aHR0cHM6Ly93d3cu/eGRjLmRldi91cGxv/YWRzL2FydGljbGVz/L2ZlbWUzNmhraGUw/OXpvYmU5ZmppLnBu/Zw)](https://www.xdc.dev/images/ISC7QEPDfiYCkQh7-8EZkhgZUpBOzaVymuXHbfk1Rbs/w:880/mb:500000/ar:1/aHR0cHM6Ly93d3cu/eGRjLmRldi91cGxv/YWRzL2FydGljbGVz/L2ZlbWUzNmhraGUw/OXpvYmU5ZmppLnBu/Zw) + +Your Docker installation will be successfully completed using these steps! + +[](#with-docker-set-up-lets-move-on-to-setting-up-xdc-subnet)With Docker set up, let’s move on to setting up XDC Subnet. +------------------------------------------------------------------------------------------------------------------------ + +**Step 4: Clone the Subnet Repository** + +Clone the Subnet repository and change the directory: + + git clone https://github.com/XinFinOrg/XinFin-Node.git + cd XinFin-Node/subnet/deployment-generator/ + + +Enter fullscreen mode Exit fullscreen mode + +[![Image description](https://www.xdc.dev/images/ryY1FXqWM1XCnTVBdYTVYljynYRmMjaBaWUrzAzo5nk/w:880/mb:500000/ar:1/aHR0cHM6Ly93d3cu/eGRjLmRldi91cGxv/YWRzL2FydGljbGVz/L2k4MHg0M3Nrc2p2/ZHp1MGFndzIyLnBu/Zw)](https://www.xdc.dev/images/ryY1FXqWM1XCnTVBdYTVYljynYRmMjaBaWUrzAzo5nk/w:880/mb:500000/ar:1/aHR0cHM6Ly93d3cu/eGRjLmRldi91cGxv/YWRzL2FydGljbGVz/L2k4MHg0M3Nrc2p2/ZHp1MGFndzIyLnBu/Zw) + +**Step 5: Create a Docker Environment File** + +Create a docker.env file with parameters similar to docker.env.example, & make necessary configurations by entering below command. + + cp docker.env.example docker.env + + +Enter fullscreen mode Exit fullscreen mode + +[![Image description](https://www.xdc.dev/images/PnkKfk-2H9wWhNMJfT_4_2PptjdMIciq7NIO7g93kaM/w:880/mb:500000/ar:1/aHR0cHM6Ly93d3cu/eGRjLmRldi91cGxv/YWRzL2FydGljbGVz/L2dvaDFoOGVtZXgw/OGxraWkxbXB4LnBu/Zw)](https://www.xdc.dev/images/PnkKfk-2H9wWhNMJfT_4_2PptjdMIciq7NIO7g93kaM/w:880/mb:500000/ar:1/aHR0cHM6Ly93d3cu/eGRjLmRldi91cGxv/YWRzL2FydGljbGVz/L2dvaDFoOGVtZXgw/OGxraWkxbXB4LnBu/Zw) + +Below is an example of the minimum file required for configs generation, **Update the below parameters with your data in the docker.env file.** Refer to check out in detail **[Config Explanation](https://xinfinorg.github.io/xdc-subnet-docs/deployment/configs_explanation/)**. + +* To check out exact config path, enter the following command: + + pwd + + +Enter fullscreen mode Exit fullscreen mode + +* If you don’t have any private key, You can create it using **[XDC Beta Web wallet](https://betawallet.xinfin.network/#/wallet/create/software?type=overview)** or else you can use **[XDCPay](https://chrome.google.com/webstore/detail/xdcpay/bocpokimicclpaiekenaeelehdjllofo)**. + +* For Devnet XDC, you can visit **[XDC Devnet Faucet](https://faucet.blocksscan.io/)**. + + +docekr.env file: + + #deployment config + CONFIG_PATH= /XinFin-Node/subnet/deployment-generator + #subnet config + NETWORK_NAME=testsubnet + NUM_SUBNET=1 + NUM_MACHINE=3 + MAIN_IP=192.168.1.1 + #parentchain config + PARENTCHAIN=devnet + PARENTCHAIN_WALLET=0x0000000000000000000000000000000000000000 + PARENTCHAIN_WALLET_PK=0x0000000000000000000000000000000000000000000000000000000000000000 + + +Enter fullscreen mode Exit fullscreen mode + +**Step 6: Pull the Latest Subnet Generator Image** + +Pull the latest Subnet Generator image with this command: + + sudo docker pull xinfinorg/subnet-generator:latest + + +Enter fullscreen mode Exit fullscreen mode + +[![Image description](https://www.xdc.dev/images/6MfACdY5is861v8Kzx84botu56qaNfFm9T4I5gJVbk8/w:880/mb:500000/ar:1/aHR0cHM6Ly93d3cu/eGRjLmRldi91cGxv/YWRzL2FydGljbGVz/LzZlenB5bTF6bmpk/azBlOWh2Z2wwLnBu/Zw)](https://www.xdc.dev/images/6MfACdY5is861v8Kzx84botu56qaNfFm9T4I5gJVbk8/w:880/mb:500000/ar:1/aHR0cHM6Ly93d3cu/eGRjLmRldi91cGxv/YWRzL2FydGljbGVz/LzZlenB5bTF6bmpk/azBlOWh2Z2wwLnBu/Zw) + +**Step 7: Generate Configurations** + +Generate configurations, this will create a new generated directory. + + docker run --env-file docker.env -v $(pwd)/generated:/app/generated xinfinorg/subnet-generator:latest && cd generated + + + +Enter fullscreen mode Exit fullscreen mode + +[![Image description](https://www.xdc.dev/images/wfVpMMS7nFNmhpJF4GUYiczTXdCbNGzJsH-TKOOuCOU/w:880/mb:500000/ar:1/aHR0cHM6Ly93d3cu/eGRjLmRldi91cGxv/YWRzL2FydGljbGVz/L25xOG8yMmIyazQ4/OXNwMHc5ZmdkLnBu/Zw)](https://www.xdc.dev/images/wfVpMMS7nFNmhpJF4GUYiczTXdCbNGzJsH-TKOOuCOU/w:880/mb:500000/ar:1/aHR0cHM6Ly93d3cu/eGRjLmRldi91cGxv/YWRzL2FydGljbGVz/L25xOG8yMmIyazQ4/OXNwMHc5ZmdkLnBu/Zw) + +Follow the generated instructions in **commands.txt** to start Subnet Nodes and make sure they are mining. + +**Deploy subnet on machine1:** + + docker compose - env-file docker-compose.env - profile machine1 pull + docker compose - env-file docker-compose.env - profile machine1 up -d + + +Enter fullscreen mode Exit fullscreen mode + +[![Image description](https://www.xdc.dev/images/0wjuIrv-4uFG9aiYUoRhM-4LsAoz7QNrNvJDLdz5LLQ/w:880/mb:500000/ar:1/aHR0cHM6Ly93d3cu/eGRjLmRldi91cGxv/YWRzL2FydGljbGVz/L2t5M2FtZHo3d3Jr/OWYwYnVsb2V4LnBu/Zw)](https://www.xdc.dev/images/0wjuIrv-4uFG9aiYUoRhM-4LsAoz7QNrNvJDLdz5LLQ/w:880/mb:500000/ar:1/aHR0cHM6Ly93d3cu/eGRjLmRldi91cGxv/YWRzL2FydGljbGVz/L2t5M2FtZHo3d3Jr/OWYwYnVsb2V4LnBu/Zw) + +[![Image description](https://www.xdc.dev/images/6xVYBT-Vlw0zkeRgdK8Z69PLH4fiSiRa8wv8zFiYVNk/w:880/mb:500000/ar:1/aHR0cHM6Ly93d3cu/eGRjLmRldi91cGxv/YWRzL2FydGljbGVz/LzNlb2IwM2RsejA0/MmVuNnIwdmMxLnBu/Zw)](https://www.xdc.dev/images/6xVYBT-Vlw0zkeRgdK8Z69PLH4fiSiRa8wv8zFiYVNk/w:880/mb:500000/ar:1/aHR0cHM6Ly93d3cu/eGRjLmRldi91cGxv/YWRzL2FydGljbGVz/LzNlb2IwM2RsejA0/MmVuNnIwdmMxLnBu/Zw) + +**Step 8: Deploy the Checkpoint Smart Contract** + +Again, follow the generated instructions in **commands.txt** to **deploy the Checkpoint Smart Contract** to the “deployment-generator” folder. + +Run “cd..” command to get back to the “deployment-generator” folder. + + cd ~/.XinFin-Node/subnet/deployment-generator + docker run --env-file docker.env \ + -v $(pwd)/generated/deployment.json:/app/generated/deployment.json \ + --entrypoint 'bash' xinfinorg/subnet-generator:latest ./deploy_csc.sh + + +Enter fullscreen mode Exit fullscreen mode + +Execute the following command to deploy the **Checkpoint Smart Contract**: + +This will provide you with the Checkpoint Smart Contract address (**checkpoint deployed to:**) + +[![Image description](https://www.xdc.dev/images/Ft2GA7zspLBSaUeY5n7rHYPwCRoPHP9yLBm5TpT37uY/w:880/mb:500000/ar:1/aHR0cHM6Ly93d3cu/eGRjLmRldi91cGxv/YWRzL2FydGljbGVz/LzUzZ3RrMm0wZm8z/ejg2aGMyZDB0LnBu/Zw)](https://www.xdc.dev/images/Ft2GA7zspLBSaUeY5n7rHYPwCRoPHP9yLBm5TpT37uY/w:880/mb:500000/ar:1/aHR0cHM6Ly93d3cu/eGRjLmRldi91cGxv/YWRzL2FydGljbGVz/LzUzZ3RrMm0wZm8z/ejg2aGMyZDB0LnBu/Zw) + +**Step 9: Deploy Subnet Services** + +Follow the instructions in commands.txt to **deploy Subnet Services** (relayer, stats-server, frontend) to the “deployment-generator/generated” folder: + + cd ~/.XinFin-Node/subnet/deployment-generator/generated + docker compose --env-file docker-compose.env --profile services pull + docker compose --env-file docker-compose.env --profile services up -d + + +Enter fullscreen mode Exit fullscreen mode + +[![Image description](https://www.xdc.dev/images/UO8wZWjhkR84uIqmgcjGSC5m4Mw83Dy7uPPIGSuM5wU/w:880/mb:500000/ar:1/aHR0cHM6Ly93d3cu/eGRjLmRldi91cGxv/YWRzL2FydGljbGVz/L2VkMHFyczZ1Nnkw/dmlpN2h1cXFsLnBu/Zw)](https://www.xdc.dev/images/UO8wZWjhkR84uIqmgcjGSC5m4Mw83Dy7uPPIGSuM5wU/w:880/mb:500000/ar:1/aHR0cHM6Ly93d3cu/eGRjLmRldi91cGxv/YWRzL2FydGljbGVz/L2VkMHFyczZ1Nnkw/dmlpN2h1cXFsLnBu/Zw) + +[![Image description](https://www.xdc.dev/images/0qWK0bhXNxgGbo7XCsF8ZdT-fFL42FbOrrUbmRTsVSg/w:880/mb:500000/ar:1/aHR0cHM6Ly93d3cu/eGRjLmRldi91cGxv/YWRzL2FydGljbGVz/L3A4aTUyZ3dzdjZl/bmkxMTJzdjNxLnBu/Zw)](https://www.xdc.dev/images/0qWK0bhXNxgGbo7XCsF8ZdT-fFL42FbOrrUbmRTsVSg/w:880/mb:500000/ar:1/aHR0cHM6Ly93d3cu/eGRjLmRldi91cGxv/YWRzL2FydGljbGVz/L3A4aTUyZ3dzdjZl/bmkxMTJzdjNxLnBu/Zw) + +**Step 10: Check the Status** + + docker ps -a + + +Enter fullscreen mode Exit fullscreen mode + +[![Image description](https://www.xdc.dev/images/DEdUFJbxHFV6l-UhNaO9YExCdK0v0aSmI-46NftJccs/w:880/mb:500000/ar:1/aHR0cHM6Ly93d3cu/eGRjLmRldi91cGxv/YWRzL2FydGljbGVz/LzhqbTc5cXNscGl6/cDF5OWVkb3Q4LnBu/Zw)](https://www.xdc.dev/images/DEdUFJbxHFV6l-UhNaO9YExCdK0v0aSmI-46NftJccs/w:880/mb:500000/ar:1/aHR0cHM6Ly93d3cu/eGRjLmRldi91cGxv/YWRzL2FydGljbGVz/LzhqbTc5cXNscGl6/cDF5OWVkb3Q4LnBu/Zw) + +**Step 11: Explore the Subnet UI** + +Finally, explore the Subnet UI by accessing it at :5000. + +[![Image description](https://www.xdc.dev/images/TkBF3bvcWinGY7WG_Ipa--M-XY14KFoof5Vbr59Bhmw/w:880/mb:500000/ar:1/aHR0cHM6Ly93d3cu/eGRjLmRldi91cGxv/YWRzL2FydGljbGVz/LzhiYnY3enRhZDFo/bnl1a2FhcDJuLnBu/Zw)](https://www.xdc.dev/images/TkBF3bvcWinGY7WG_Ipa--M-XY14KFoof5Vbr59Bhmw/w:880/mb:500000/ar:1/aHR0cHM6Ly93d3cu/eGRjLmRldi91cGxv/YWRzL2FydGljbGVz/LzhiYnY3enRhZDFo/bnl1a2FhcDJuLnBu/Zw) + +Congratulations! You’ve successfully set up your XDC Subnet, enabling you to harness the full potential of XDC Network’s blockchain technology. + +Checkout the guide for **[XDC Subnet user interface.](https://xinfinorg.github.io/xdc-subnet-docs/category/ui-usage-guide)** + +[](#some-common-issues-and-solutions)Some Common Issues and Solutions: +---------------------------------------------------------------------- + +**Issue 1: Finding the System’s IP Address** + +**Question:** If I do not have the private IP, where can I find the IP address of my system? + +**Answer:** To determine your system’s IP address, use the following command: + + ip a + + +Enter fullscreen mode Exit fullscreen mode + +**Issue 2: Locating the Checkpoint Smart Contract Address** + +**Question:** Where can I find the checkpoint smart contract address? + +**Answer:** After executing the command below, you will obtain the “checkpoint smart contract address.” Please consult the “command.txt” file for the necessary commands. + + cd ~/.XinFin-Node/subnet/deployment-generator + docker run - env-file docker.env \ + -v $(pwd)/generated/deployment.json:/app/generated/deployment.json \ + - entrypoint 'bash' xinfinorg/subnet-generator:latest ./deploy_csc.sh + + +Enter fullscreen mode Exit fullscreen mode + +**Issue 3: Resolving “No Such File or Directory” Errors** + +**Question:** What should I do if I encounter the “no such file or directory” error repeatedly? + +**Answer:** To address this, execute the command below to generate new configuration files. This will create a new directory to replace the existing one. Once you have the new directory, follow the subsequent steps as outlined in the “command.txt” file. + + docker run - env-file docker.env -v $(pwd)/generated:/app/generated xinfinorg/subnet-generator:latest && cd generated + + +Enter fullscreen mode Exit fullscreen mode + +**Issue 4: Determining the Exact Config Path for “docker.env”** + +**Question:** How can I find the exact configuration path to update in the “docker.env” file? + +**Answer:** To obtain the precise configuration path, use the “pwd” command, which will provide you with the necessary information. + + pwd + + +Enter fullscreen mode Exit fullscreen mode + +**Issue 5: Troubleshooting 'CSC Deployment Failed' Issue: Checkpoint Smart Contract Deployment** + +**Question:** Encountering a "CSC deployment failed" issue during the deployment of the Checkpoint Smart Contract? + +**Answer:** Please verify that the provided Private Key contains sufficient funds for both the Smart Contract deployment and subsequent transactions. + +* If you don’t have any private key, You can create it using **[XDC Beta Web wallet](https://betawallet.xinfin.network/#/wallet/create/software?type=overview)** or else you can use **[XDCPay](https://chrome.google.com/webstore/detail/xdcpay/bocpokimicclpaiekenaeelehdjllofo)**. + +* For Devnet XDC, you can visit **[XDC Devnet Faucet](https://faucet.blocksscan.io/)**. + + +Blockchain subnets represent a new frontier in blockchain technology. They offer the scalability, customization, and security needed to drive innovation across various industries. As blockchain subnets continue to gain momentum, staying informed about their capabilities and potential applications is crucial for anyone involved in blockchain development or adoption. + +If you have any questions or need assistance, don’t hesitate to reach out to the XDC Network community on **[XDC.Dev](https://xdc.dev/)**. Start your XDC Subnet journey today! \ No newline at end of file diff --git a/docs/subnet/components.md b/docs/subnet/components.md new file mode 100644 index 0000000..fe2f1e3 --- /dev/null +++ b/docs/subnet/components.md @@ -0,0 +1,6 @@ +--- +title: Upgrading the Subnet +# TODO: title +--- +404 +Upgrading the Subnet \ No newline at end of file diff --git a/docs/subnet/components/api_library.md b/docs/subnet/components/api_library.md new file mode 100644 index 0000000..c97238c --- /dev/null +++ b/docs/subnet/components/api_library.md @@ -0,0 +1,8 @@ +--- +title: Upgrading the Subnet +--- +# API Library +This section specifies the API library we develop for the subnet users to confirm subnet transactions. + +## Specifications +TBW \ No newline at end of file diff --git a/docs/subnet/components/checkpoint_contract.md b/docs/subnet/components/checkpoint_contract.md new file mode 100644 index 0000000..e59d4ec --- /dev/null +++ b/docs/subnet/components/checkpoint_contract.md @@ -0,0 +1,183 @@ +--- +title: Upgrading the Subnet +--- +# Checkpoint Smart Contract + +This section specifies the Checkpoint Smart Contract in the parent chain that protects the child chain. + + +## Design + +### Overview +The primary function of the parent chain smart contract is to receive block data from the subnet node, verify it, and store it. + +**Noteworthy aspects:** + + - Every block data received will be verified to ensure the signature is signed by validators and has passed with 2/3 of the votes. + + - In the gap block occurring in the middle of each epoch, a `next` may appear, which will be selected for temporary storage. + + - In each epoch block, a `current` may appear, which will choose the `next` selected during the gap as validators from the current block to the next epoch. + + - Only three consecutive blocks of `roundNumber` can confirm the previous block, and `mainnetNum` will change from -1 to `block.number` once the block is committed. + +![Overview](sc-overview.jpg) + +### Specifics + +#### Checkpoint + +The Checkpoint contract implements a blockchain checkpoint system, which verifies and stores block header information for subnetworks. Here are some key functions and features: + +- The contract defines several data structures, such as `Header`, `HeaderInfo`, `Validators` and `BlockLite`. These structures are used to store block header information, validator information, and more. + +- The contract employs several mappings and other variables to track the current block header tree, committed blocks, validator set, latest block, and so forth. + +- The contract's constructor receives the initial validator set, the genesis block header, the first block header, etc., as parameters and initializes the contract state based on these. + +- The `receiveHeader` function allows users to submit new block headers. This function will verify the meta information of the block header (like block number, parent block hash, etc.), the signature certificate, and update the block's submission status when specific conditions are met. + +- Functions such as `setLookup`, `setCommittedStatus`, `checkUniqueness`, and `checkCommittedStatus` are used to update or check the contract's internal status. + +- Functions like `getHeader`, `getHeaderByNumber`, `getLatestBlocks` and `getCurrentValidators` enable users to query block header information, validator sets, etc. + +- The `splitSignature` and `recoverSigner` functions are used to recover the signer's address from the signature, which is necessary for verifying the block header signature. + +**Logic Flow:** + +1. Checkpoint uses the following parameters for contract construction: + + - `address[] initial_validator_set `: List of initial validator addresses + - `bytes genesis_header`: block0HexRLP + - `bytes block1_header`: block1HexRLP + - `uint64 gap`: GAP block number on public chain + - `uint64 epoch`: EPOCH block number on public chain + +2. Relayers need to fetch every block data from the subnet node. + +3. Users can retrieve the information of each block using methods such as `getHeader`. + +![Checkpoint](sc-checkpoint.jpg) + +#### Lite Checkpoint + +Lite Checkpoint is a lightweight block header checkpoint. It implements several functions, including: + + - Setting the initial validator set and related parameters during contract initialization. + - Checking whether the submitted block header meets the requirements. + - Receiving and processing submitted block headers. + - Submitting the block header and block header by block number. + - Retrieving uncommitted block header information. + - Accessing specific block header information. + - Fetching the current and next round of epoch blocks according to the index. + - Getting the latest block information. + - Accessing the current set of validators. + +**Logic Flow:** + +1. Lite Checkpoint uses the following parameters for contract construction: + + - `address[] initialValidatorSet `: List of initial validator addresses + - `bytes block1`: block1HexRLP + - `uint64 gap`: GAP block number on public chain + - `uint64 epoch`: EPOCH block number on public chain + +2. Relayers only need to fetch gap/epoch block data and fetch the following consecutive `roundNumber` blocks to confirm the signed gap/epoch block from the subnet node. + +3. Users can get gap/epoch block information from methods such as `getHeader`. + +![Lite Checkpoint](sc-litecheckpoint.jpg) + + +#### Upgradeable module + +The Upgradeable module mainly revolves around the concept of transparent proxies and the ability to upgrade the underlying logic contracts without changing the contract's address. + +##### ProxyGateway Smart Contract + +The `ProxyGateway` smart contract plays a central role in this module. It inherits from `ProxyAdmin` and primarily serves the purpose of creating and managing transparent upgradeable proxies (`TransparentUpgradeableProxy`). + +**Key Components and Functionalities**: + +- **cscProxies**: + - A mapping used to store two types of transparent upgradeable proxies. + - `0` represents "full" + - `1` represents "lite" + +- **CreateProxy Event**: + - Emitted whenever a new transparent upgradeable proxy is created. + +- **createProxy Function**: + - Creates a new `TransparentUpgradeableProxy`. + - Emits the `CreateProxy` event upon creation. + +- **createFullProxy Function**: + - Specifically designed for creating a transparent upgradeable proxy of type "full". + - Checks if a "full" type proxy already exists. + - Ensures the provided logic contract has a `MODE` function that returns "full". + +- **createLiteProxy Function**: + - Designed for creating proxies of type "lite". + - Checks if a "lite" type proxy already exists. + - Ensures the provided logic contract has a `MODE` function that returns "lite". + + +![Alt text](sc-upgradeable-overview.png) + +**Logic Flow:** + +1. **Initialization**: + + The process begins with the `ProxyGateway` contract, which serves as a central hub for creating transparent upgradeable proxies. The contract owner has the capability to create either "full" or "lite" proxies. + +2. **Proxy Creation**: + + - The owner calls either the `createFullProxy` or `createLiteProxy` function based on the desired type of proxy. + - The specified logic contract's `MODE` is checked to ensure it matches the desired proxy type. + - A new `TransparentUpgradeableProxy` is created with the specified logic contract, the `ProxyGateway` as the admin, and any necessary initialization data. + - The new proxy's address is stored in the `cscProxies` mapping under its corresponding type. + - The `CreateProxy` event is emitted to log the creation of the new proxy. + +3. **Upgrading the Proxy**: + + When there's a need to upgrade the underlying logic of the proxy (for instance, to introduce new features or fix bugs): + + - A new logic contract version is deployed to the network. + - The owner (or authorized entity) of the `ProxyGateway` contract calls the inherited `upgrade` function from `ProxyAdmin` to point the proxy to the new logic contract. + - The proxy now delegates all calls to the new logic contract, while still retaining all its previous storage and state. + - This enables the system to evolve and implement new functionalities without migrating to a new contract address or affecting the contract's stored data. + +4. **Interacting with the Proxy**: + + Users and other contracts can interact with the proxy just as they would with a regular contract. However, behind the scenes, all function calls and data accesses are delegated to the current logic contract that the proxy points to. + +5. **Querying and Data Access**: + + Users and contracts can still query data, access functions, or invoke transactions on the proxy's address. The proxy transparently delegates these to the underlying logic contract, ensuring continuity of operations. + +6. **Advanced Management**: + + Through the `ProxyAdmin` functionality, the owner can further manage the proxy, such as changing the admin or even downgrading to a previous version of the logic contract if needed. + +![Alt text](sc-upgradeable-upgrade.png) + +## spec + +### APIs +- Functions that have access restriction to authorized client + - `reviseValidatorSet(address[], int, int)`: Update subnet block header signer list at destined height + - `receiveHeader(bytes[])`: Validate and store subnet headers + +- Functions that open for public access + - `getHeader(byte32)`: Return entire block header in RLP encoding format + - `getHeaderByNumber(int)`: Return block hash and number at input height + - `getHeaderConfirmationStatus(byte32)`: Return block committing status + - `getMainnetBlockNumber(byte32)`: Return mainnet block number that processed the subnet block header + - `getLatestBlocks()`: Return latest committed block and submitted block + +### Algorithms and Rules +Block header verification follows two principle rules: +1. Received block should have consistent round number and block number associated with its parent block. +2. Received block should have enough certificates signed by the list of block signers. + +Once a block header is checked and stored, the contract will examine whether there are 3 consecutive blocks that have 3 consetive round number. If that is the case, all of the direct ancestor blocks that are prior to these 3 consecutive blocks will be committed. diff --git a/docs/subnet/components/relayer.md b/docs/subnet/components/relayer.md new file mode 100644 index 0000000..60ad4c0 --- /dev/null +++ b/docs/subnet/components/relayer.md @@ -0,0 +1,37 @@ +--- +title: Upgrading the Subnet +--- +# Relayer + +This section specifies the relayer that checkpoints the subnet chain to the parent chain. + +## Design + +### Background +There is a strong demand from the banking industry to adopt XDC. One of the key requirements to enter the field is the ability to support subnets so that banks are able to keep the sensitive transactions within their own domain (privacy concern) but at the same time, have the ability to continuously audit the result (hash) of the subnet transactions on the XDC mainnet (security concern). + +Since the mainnet and subnets will be running as two independent node cluster, we will need to figure out a method to bridge them together to perform the auditing feature mentioned above. This is where “relayer” is coming into play. + +### High-level architectural diagram +At high level, the relayer is able to: +1. Pull necessary data from both subnet and mainnet +2. Process and submit subnet block data as smart contract transactions into mainnet +3. When subnet masternodes list changes, report the new list and change height to the mainnet using grand-master account. + +![architectural-diagram](relayer-diagram.jpg) + + +## Relayer Mode + +There are 2 relayer modes 'Full' and 'Lite' where the default mode is 'Full'. In the full mode, all subnet block headers are checkpointed to the parent chain. In the lite mode, only the Epoch and Epoch gap subnet block headers are checkpointed in the parent chain (blocks 451,900,1351,1800, and so on). The Epoch and Epoch gap blocks stores important information regarding subnet validators selection. For further reading please check [Checkpoint Smart Contract](../checkpoint_smart_contract/design.md). + +### Choosing Full or Lite Relayer + +The Full mode has the advantage of being more 'complete' and more 'current' as blocks are getting confirmed in the parent chain almost immediately. The Lite mode has the advantage of using lower parent chain gas fee as the Relayer is only submitting to once every 450 blocks. + +### Deployment + +In the deployment `RELAYER_MODE` config is only relevant for Checkpoint Smart Contract (CSC) deployment. The relayer itself is able to detect the CSC type automatically and push block headers accordingly. + + + diff --git a/docs/subnet/components/subnet_chain.md b/docs/subnet/components/subnet_chain.md new file mode 100644 index 0000000..50d285e --- /dev/null +++ b/docs/subnet/components/subnet_chain.md @@ -0,0 +1,35 @@ +--- +title: Upgrading the Subnet +# TODO: title +--- + +# Subnet Chain +This section specifies the subnet itself, a sovereign, permissioned, and high-performing blockchain. + +## Design + +XDC subnet is a blockchain network tailored for private and consortium use cases. It is powered by XDC2.0, which is the core engine of XDC network and enables state-of-the-art security against Byzantine attacks with forensics, fast transaction confirmation, and low energy consumption. It is also designed to enable secure checkpointing to XDC mainnet, so that it can harness the security, finality, and accountability of mainnet. + +### XDC2.0 Protocol +As the core engine of both XDC mainnet and subnet, XDC2.0 maintains the consistency of the blockchain with strong security and performance guarantees. The Delegated Proof-of-Stake subprotocol elects a committee of masternodes. The masternodes run the state-of-the-art HotStuff consensus subprotocol to settle block generation and verification and confirm transactions. Besides, XDC2.0 protocol enables its unique feature, namely forensic monitoring. When the adversary corrupts more than 1/3 masternodes and violates safety, forensic monitoring can detect those actions and report irrefutable evidence of the culprits. + +The distinction between XDC2.0 for subnet and mainnet is that for subnet the masternodes are permissioned whereas for mainnet they are permissionless. + +### Your Own Blockchain Network +XDC subnet is completely owned by you. You, the owner of the subnet, are capable of controlling several aspects of the subnet. + +First, the owner regulates the master node list. More specifically, the join/retire of mater nodes is done by smart contract calls that only the owner has access to. Also, underperforming or misbehaving masternodes could be expelled by the owner. This is in contrast with XDC mainnet, where masternodes join or leave willingly as long as they follow the rule enforced by the protocol. + +Second, the blockchain genesis can be configured by the owner. The owner is able to distribute initial tokens and create accounts, as well as deploy system-level smart contracts on the blockchain. + +Last, the owner can customize blockchain parameters, such as epoch length, max masternode number, the quorum certificate threshold, the reward per epoch, etc. + +### Integrating with XDC mainnet +Integrating with XDC mainnet will enable subnet to harness the security, finality, and accountability of XDC mainnet. This requires the subnet owner to deploy a smart contract (XDC will provide) to XDC mainnet and report block headers and masternode changes to the smart contract. + +As long as the mainnet is secure, the block header information of the subnet is securely stored on the mainnet. Users can also query the mainnet for finality to enhance the confidence that the subnet transaction is indeed finalized. The subnet can also report the culprits to the forensic server of XDC mainnet when its forensic monitor module detects safety violations. When the culprit report is validated, necessary measurements should be taken by the owner to reestablish the security of the subnet. + +It is worth noting that the subnet can be deployed as a standalone, independent blockchain network without integrating with XDC mainnet. The choice is up to the owner whether to harness the advantages of XDC mainnet. + +## API +Subnet-specific APIs \ No newline at end of file diff --git a/docs/subnet/components/subswap.md b/docs/subnet/components/subswap.md new file mode 100644 index 0000000..aae2ff9 --- /dev/null +++ b/docs/subnet/components/subswap.md @@ -0,0 +1,186 @@ +--- +title: Upgrading the Subnet +--- +# Subswap + +## Design +#### Subswap Documentation + +**Topic**: **Design of Subswap Cross-Chain Transfer System on XDC Zero** + +--- + +##### **Overview** + +Subswap is cross-chain application built on XDC Zero to provide seamless cross-chain transfer capabilities. It is structured in a multi-layered architecture, with each layer handling distinct functions to ensure smooth, secure, and efficient transactions across blockchain networks. This document provides a design overview of each layer, illustrating the components and their roles within the Subswap system. + +--- + +##### **System Architecture** + +Subswap is organized into three layers: + +1. **Layer 0 - XDC Zero (Core Infrastructure)** + - **Relayer**: Manages the transfer of data and assets between blockchains by relaying transaction information across chains. + - **Oracle**: Provides reliable and up-to-date data for cross-chain operations, ensuring that the transfer protocols operate with accurate information. + - **Endpoint**: Serves as the core communication channel within XDC Zero, connecting the layers and ensuring transactions flow smoothly. + - **Front-End Management**: Handles the user interface and manages interactions with the underlying protocols, offering a streamlined experience for users initiating cross-chain transfers. + +2. **Layer 1 - Treasury** + - **Cross-Chain Transfer Frontend**: User-facing interface for initiating and tracking cross-chain transactions. This frontend simplifies the user experience, making it easier for users to start transfers between different blockchains. + - **Mint/Burn Contract**: Manages asset issuance and burning on different chains. This contract mints new assets on the target chain while burning them on the source chain, maintaining asset consistency across networks. + - **Lock/Unlock Contract**: Locks assets on the source chain and unlocks them on the target chain, ensuring that the asset's total supply remains consistent and secure across chains. + +3. **Layer 2 - Swap Protocol** + - **Swap Frontend**: Provides a user-friendly interface for initiating swaps between different assets on the Subswap platform. + - **Swap Contract**: Executes the swap logic, managing the conversion of assets based on the predefined terms and rates, ensuring that users receive the correct assets after a swap. + +--- + +##### **Design Considerations** + +- **Security**: The use of locking and minting mechanisms prevents double-spending and ensures the security of cross-chain assets. +- **User Experience**: Frontends are designed to be intuitive, making it easy for users to interact with complex cross-chain protocols. +- **Reliability**: Oracles and relayers provide real-time data and reliable transaction relay, reducing the chance of errors in cross-chain transfers. + +##### **Conclusion** + +Subswap leverages XDC Zero's powerful infrastructure to deliver an efficient cross-chain transfer service. By layering its architecture, Subswap can maintain security, scalability, and ease of use, meeting the needs of users looking for seamless asset transfers across multiple blockchain networks. + +### Construction(if you want to make a cross chain transfer) +![Alt text](image2.png) + + +![Alt text](image1.png) + +## Spec +### Subswap API Documentation +--- +This document provides an API reference for the Subswap contracts, specifically for the `ParentnetTreasury` and `SubnetTreasury` contracts. These contracts facilitate cross-chain asset transfers by minting, burning, locking, and unlocking tokens between chains. + +--- + +### **Restricted Access Functions** + +#### **ParentnetTreasury** + +1. **`changeEndpoint(address endpoint) -> void`** + - **Description**: Allows the contract owner to set a new endpoint address. + - **Parameters**: + - `endpoint`: The address of the new endpoint. + - **Access**: `onlyOwner` + +2. **`setEndpoint(address endpoint) -> void`** + - **Description**: Sets a new endpoint address, restricted to calls from the current endpoint. + - **Parameters**: + - `endpoint`: The address of the new endpoint. + - **Access**: `onlyEndpoint` + +3. **`mint(...) -> void`** + - **Description**: Mints tokens on the `SubnetTreasury` chain in response to a cross-chain transfer. + - **Parameters**: + - `originalToken`: Address of the original token. + - `name`: Name of the token. + - `symbol`: Symbol of the token. + - `account`: Address of the account receiving the minted tokens. + - `amount`: Number of tokens to mint. + - `sid`: Source chain ID. + - **Access**: `onlyEndpoint` + +#### **SubnetTreasury** + +1. **`changeEndpoint(address endpoint) -> void`** + - **Description**: Allows the contract owner to set a new endpoint address. + - **Parameters**: + - `endpoint`: The address of the new endpoint. + - **Access**: `onlyOwner` + +2. **`setEndpoint(address endpoint) -> void`** + - **Description**: Sets a new endpoint address, restricted to calls from the current endpoint. + - **Parameters**: + - `endpoint`: The address of the new endpoint. + - **Access**: `onlyEndpoint` + +3. **`unlock(address token, uint256 amount, address recv) -> void`** + - **Description**: Unlocks tokens on the current chain, sending them to the specified address. + - **Parameters**: + - `token`: Address of the token to unlock. + - `amount`: Amount of tokens to unlock. + - `recv`: Address of the recipient. + - **Access**: `onlyEndpoint` + +--- + +### **Public Functions** + +#### **ParentnetTreasury** + +1. **`burn(...) -> void`** + - **Description**: Burns tokens on the `ParentnetTreasury` side to initiate a cross-chain transfer, sending a message to `SubnetTreasury` to mint tokens. + - **Parameters**: + - `rid`: Destination chain ID. + - `rua`: Receiver’s address on the destination chain. + - `originalToken`: Address of the original token on the source chain. + - `token`: Address of the Treasury token to burn. + - `amount`: Number of tokens to burn. + - `recv`: Address to receive tokens on the destination chain. + - **Events**: + - Emits a `Burn` event with details of the burned amount and target chain. + +2. **`test(uint256 rid, address rua, bytes memory data) -> void`** + - **Description**: Sends arbitrary data to the specified chain via the endpoint, for testing purposes. + - **Parameters**: + - `rid`: Destination chain ID. + - `rua`: Receiver’s address on the destination chain. + - `data`: Encoded data to send. + +3. **`getEndpoint() -> address`** + - **Description**: Returns the current endpoint address. + +#### **SubnetTreasury** + +1. **`lock(...) -> void`** + - **Description**: Locks tokens on the `SubnetTreasury` side to initiate a cross-chain transfer, sending a message to `ParentnetTreasury` to mint tokens. + - **Parameters**: + - `rid`: Destination chain ID. + - `rua`: Receiver’s address on the destination chain. + - `token`: Address of the token to lock. + - `amount`: Amount of tokens to lock. + - `recv`: Address to receive tokens on the destination chain. + - **Events**: + - Emits a `Lock` event with details of the locked amount and target chain. + +2. **`getChainId() -> uint256`** + - **Description**: Returns the chain ID of the current chain. + +3. **`getEndpoint() -> address`** + - **Description**: Returns the current endpoint address. + +--- + +### **Algorithms and Rules** + +#### **Minting and Burning** + +- **Minting (ParentnetTreasury)** + - When `SubnetTreasury` locks tokens on its chain, it sends a message to `ParentnetTreasury` to mint an equivalent amount on the destination chain. + - If a Treasury token contract does not exist for the original token, a new one is created and mapped to the original token in `treasuryMapping`. + +- **Burning (ParentnetTreasury)** + - To initiate a cross-chain transfer back to the original chain, the `burn` function is called to destroy tokens on `ParentnetTreasury`. + - After burning, a message is sent to `SubnetTreasury` to unlock an equivalent amount on the destination chain. + +#### **Locking and Unlocking** + +- **Locking (SubnetTreasury)** + - Tokens are locked on `SubnetTreasury` by transferring them from the caller’s address to the contract. + - The contract then sends a cross-chain message to `ParentnetTreasury` to mint equivalent tokens on the destination chain. + +- **Unlocking (SubnetTreasury)** + - In response to a burn action on `ParentnetTreasury`, the `SubnetTreasury` unlocks tokens on its chain and sends them to the specified recipient. + +#### **Endpoint and Cross-Chain Communication** + +- All cross-chain messages are handled through the `IEndpoint` interface, which abstracts the low-level cross-chain communication. +- Each function that initiates cross-chain actions (mint, burn, lock, unlock) encodes data using `abi.encodeWithSelector` to create a message payload, ensuring proper handling of contract-specific calls on the destination chain. + diff --git a/docs/subnet/components/xdc_zero.md b/docs/subnet/components/xdc_zero.md new file mode 100644 index 0000000..ab9c6a7 --- /dev/null +++ b/docs/subnet/components/xdc_zero.md @@ -0,0 +1,170 @@ +--- +title: Upgrading the Subnet +--- +# XDCZero +default + + +## Design + +XDC-Zero is a cross-chain framework that allows interoperability between XDC-Subnet and the XDC network. It ensures frictionless data transmission and rigorous validation across the Subnet and the Parentchain. + +### Key Components + +#### Oracle + +Acting as the architectural keystone, the Oracle ensures the safe transfer of pivotal data, notably block headers, bridging source and target blockchains. Utilizing CSC contracts, the system guarantees not just steadfast data transfer but also the safeguarding of crucial block header details on the destination blockchain. Such functionalities affirm the data's integrity and coherence throughout chains. + +#### Relayer + +The Relayer functions as the essential conduit for transactional precision. Its core duty is to extract payload data from the source chain's Endpoint contract and channel it to the counterpart on the target chain. With this mechanism in place, XDC ZERO promises the exact and secure relay of transaction data, fostering efficient cross-chain synergies. + +#### Endpoint + +The XDC Zero Endpoint stands as the nexus for cross-chain communication, adeptly receiving and dispatching data packets across disparate blockchain networks. It offers indispensable services for the fluid operation of the cross-chain paradigm: + +- **Data Reception & Dispatch**: The Endpoint ensures data packets, once received from a chain, are aptly relayed to another, directing data unerringly to its designated recipient. +- **Chain Integration**: The Endpoint facilitates the seamless onboarding of new blockchains into the system. By denoting unique identifiers and related contracts, it amalgamates new chains into the existing cross-chain communication matrix. +- **Transaction Authentication**: With the Endpoint's prowess, transactions undergo rigorous validation, certifying their authenticity before processing, thus bolstering system security against potential threats. +- **Payload Access**: The Endpoint offers a user-friendly interface for applications and entities to pull cross-chain payload data, an essential feature for apps dependent on inter-chain data streams. + +At its core, the Endpoint functions as the orchestrator for all cross-chain data activities, ensuring data is meticulously received, processed, and channeled to its rightful destination. + +#### Frontend + +Experience a user-centric interface to manage the endpoint contracts spanning different chains. View the chain entities already synchronized with the current endpoint contract and effortlessly onboard new chain entities as per requirements. + +![System Architecture](image1.png) + +### Endpoint workflow + +![System Architecture](image2.png) + +### Workflow + +![System Architecture](image.png) + + +## API Documentation +// TODO:Spec? + +### Restricted Access Functions + +Functions accessible only by the contract owner or authorized clients. + +1. **send(uint256 rid, address rua, bytes data)** + + - **Description:** Sends a packet to the designated receive chain. + - **Parameters:** + - `rid`: ID of the receive chain. + - `rua`: Address of the receive application. + - `data`: Data payload for the packet. + +2. **validateTransactionProof(uint256 csid, bytes key, bytes[] calldata receiptProof, bytes[] calldata transactionProof, bytes32 blockHash)** + + - **Description:** Validates transaction and receipt proofs, ensuring secure cross-chain communication. + - **Parameters:** + - `csid`: ID of the send chain. + - `key`: RLP key. + - `receiptProof`: Proof data for the transaction receipt. + - `transactionProof`: Proof data for the transaction. + - `blockHash`: Hash of the relevant block. + +3. **registerChain(uint256 chainId, IFullCheckpoint csc, Endpoint endpoint)** + + - **Description:** Registers a new chain for packet reception. + - **Parameters:** + - `chainId`: ID of the chain being registered. + - `csc`: Checkpoint contract for the receive chain. + - `endpoint`: Endpoint contract for the send chain. + +4. **approveApplication(uint256 rid, address rua, address sua)** + + - **Description:** Approves both a receive and send application for cross-chain interaction. + - **Parameters:** + - `rid`: ID of the receive chain. + - `rua`: Address of the receive application. + - `sua`: Address of the send application. + +5. **approveRua(uint256 rid, address rua)** + + - **Description:** Approves a receive application (rua) for a specific chain. + - **Parameters:** + - `rid`: ID of the receive chain. + - `rua`: Address of the receive application. + +6. **approveSua(address sua)** + + - **Description:** Approves a send application (sua) for packet sending. + - **Parameters:** + - `sua`: Address of the send application. + +7. **revokeApplication(uint256 rid, address rua, address sua)** + + - **Description:** Revokes approval for both a receive and send application. + - **Parameters:** + - `rid`: ID of the receive chain. + - `rua`: Address of the receive application. + - `sua`: Address of the send application. + +8. **revokeRua(uint256 rid, address rua)** + + - **Description:** Revokes approval for a specific receive application. + - **Parameters:** + - `rid`: ID of the receive chain. + - `rua`: Address of the receive application. + +9. **revokeSua(address sua)** + - **Description:** Revokes approval for a send application. + - **Parameters:** + - `sua`: Address of the send application. + +--- + +### Public Functions + +Functions accessible by any user or contract on the blockchain. + +1. **packetHash() returns (bytes32)** + + - **Description:** Retrieves the hash for the Packet event. + +2. **getRlp(bytes memory key, bytes[] calldata proof, bytes32 root) returns (bytes memory)** + + - **Description:** Retrieves RLP data based on a Merkle Patricia proof. + +3. **getFailureDataLength(uint256 rid) returns (uint256)** + + - **Description:** Retrieves the count of failed data entries for a specified receive chain. + +4. **getReceiveChainLastIndex(uint256 chainId) returns (uint256)** + + - **Description:** Retrieves the last index for a specified receive chain. + +5. **getSendChain(uint256 chainId) returns (Chain memory)** + + - **Description:** Retrieves details of a send chain based on its ID. + +6. **getSendChainIds() returns (uint256[] memory)** + + - **Description:** Returns an array of all registered send chain IDs. + +7. **allowanceRua(uint256 rid, address rua) returns (bool)** + + - **Description:** Checks if a receive application is approved for a specific chain. + - **Parameters:** + - `rid`: ID of the receive chain. + - `rua`: Address of the receive application. + +8. **allowanceSua(address sua) returns (bool)** + - **Description:** Checks if a send application is approved. + - **Parameters:** + - `sua`: Address of the send application. + +--- + +### Algorithms and Rules + +- **Packet Validation:** Ensures that only approved applications on registered chains can send packets. The contract validates each transaction’s authenticity by verifying proofs of transaction and receipt. +- **Failure Data Handling:** If a packet transmission fails, the contract records it, allowing for potential retries or analysis. +- **Chain Registration:** Only authorized users (contract owner) can register new chains, safeguarding against unauthorized cross-chain communication. diff --git a/docs/subnet/index.md b/docs/subnet/index.md index 3cdfb36..a347b7b 100644 --- a/docs/subnet/index.md +++ b/docs/subnet/index.md @@ -10,6 +10,23 @@ XDC Subnet is a technology that allows you to create a secure, scalable, and dec Are you ready to embark on a journey into the world of secure, scalable, and decentralized networks? Look no further than XDC Subnet, the cutting-edge technology that empowers you to create a digital realm tailored to your needs within the thriving XDC Ecosystem. +## Motivation & Design Rationale + +As a leading Layer-1 (L1) public blockchain, XDC network has attrated many enterprise and institutional customers. Besides the high performance and high security that XDC already offers, these customers also demand privacy, meaning that their transactions and ledger should not be disclosed to the public. This requirement prohibits them from directly submitting transactions to XDC. Instead, they should only checkpoint snapshots of their ledger to XDC in order to extract XDC's security. + +From a system perspective, "security via checkpointing" is achieved via Layer-2 (L2) techniques, such as rollups and subnets. The most popular rollup technique, namely optimistic rollup, is not suitable for our use case. This is because while transaction execution is offloaded to L2, all these L2 transactions are still submitted to L1 as a record. Another popular rollup called zero-knowledge (ZK) rollup solves this problem. But ZK computation is slow, and the type of use cases it can currently support is very limited (such as token transfers), which cannot fulfill the diverse business needs of XDC's enterprise and institutional customers. + +On the other hand, subnet is a perfect solution. By subnet, the customer runs a blockchain and checkpoints its critical consensus data to the parent chain. This way, not only is privacy preserved, the subnet can have its own security and resiliency besides those provided by the parent chain. This is particularly useful to enterprise and institutional customers who may collaborate with untrusted partners. A common criticism against subnet solutions is the high entry bar and operational cost of running a blockchain. However, in XDC's case, this is indeed welcomed becomes enterprise and institutional customers prefer owning the infrastructure in a private and isolated domain. + + +Motivated by this opportunity, XDC's core protocol team has tailor-designed a subnet solution for XDC's enterprise and institutional customers. It has the following main features: +1. the subnet will be a sovereign, permissioned, and high-performing blockchain wholly owned by the customer. +2. the subnet will be driven by XDC2.0, the most advanced and secure consensus engine originally-built for XDC in-house, and will be deployed to the XDC mainnet, too. +3. a security level equivalent to the sum security of the subnet AND XDC mainnet. +4. native EVM smart contract support. +5. total privacy (i.e., no visibility) of the subset transactions on the XDC mainnet. +6. full access and compatibility to XDC's abundant SDK and tools, such as the explorer and forensic monitoring system. + ## Architecture The architecture consists of the following key components owned by the customer: diff --git a/docs/subnet/install_guide/config_explanation.md b/docs/subnet/install_guide/config_explanation.md new file mode 100644 index 0000000..350552c --- /dev/null +++ b/docs/subnet/install_guide/config_explanation.md @@ -0,0 +1,63 @@ +--- +title: Upgrading the Subnet +# TODO: title +--- + +# Configs Explanation + +## Files under 'generated' directory +After the generator has succesfully run, all generated files will be under 'generated' directory. These files can be edited if you would like to further customize your subnet. Below is a description of each generated file and how it is used. + +- commands.txt - The generated instructions to launch the subnet. +- common.env - The config parameters for Subnet services. +- contract_deploy.env - The config file used for CSC deployment. +- subnet*.env - The config parameters for each Subnet node. +- genesis.json - The 'block 0' of the Subnet. Initializes the blockchain for subnet nodes. +- genesis_input.yml - An intermediate file used in config generation. +- keys.json - Generated keypairs or custom keypairs by user input. Please be mindful to keep the credentials secure. +- docker-compose.yml - The main deployment file. Includes docker images versions, startup commands, network configurations. +- docker-compose.env - The config injection path that docker uses to point to other *.env files. + +### common.env +- PARENTNET_URL - RPC of the parentnet +- SUBNET_URL - RPC of the Subnet +- PARENTNET_WALLET - Public key of the Relayer wallet +- PARENTNET_WALLET_PK - Private key of the Relayer wallet +- VITE_SUBNET_URL - URL of stats server backend that is passed to your local browser +- VITE_SUBNET_RPC - URL of the Subnet RPC that is passed to your local browser +- CHECKPOINT_CONTRACT - Checkpoint Smart Contract address +- STATS_SECRET - Secret used by stats server backend +- EXTIP - Configured IP of bootnode +- BOOTNODE_PORT - Configured port of bootnode + +### subnet*.env +- INSTANCE_NAME - Subnet node name +- PRIVATE_KEY - Subnet node private key +- BOOTNODES - Subnet bootnode to connect and discover other Subnet nodes +- NETWORK_ID - Subnet network ID +- SYNC_MODE - Node operation mode (full or archive) +- RPC_API - enabled api's scheme such as eth, xdpos, debug, net +- STATS_SERVICE_ADDRESS - Stats server backend URL +- STATS_SECRET - Secret to authenticate with Stats server +- PORT - Subnet node port for communication with other Subnet nodes +- RPCPORT - Subnet node port for accepting RPC calls +- WSPORT - Subnet node port for accepting Websocket connections +- LOG_LEVEL - Desired logging level. 2=Warn, 3=Info, 4=Debug. + + + +## Subnet Ports +1. Subnet Nodes - 3 ports are used per each subnet, RPC port, WS port, and Peering port. The port number is incremented by 1 for the next subnet node. For example subnet1's RPC is 8545, subnet2's RPC will be 8546 and so on. + - RPC PORT - 8545, 8546, 8547, ... This is the API port, for outside chain communication to issue transaction or query chaindata. + - WS PORT - 9555, 9556, 9557, ... This is not used currently. + - Peering port - 20303, 20304, 20305, ... This is used for subnet nodes and bootnode peering and communication. + - Subnet ports config can be changed in `subnetX.env` for each individual subnet. +2. Bootnode - port 20301 + - Bootnode port can be changed at `BOOTNODE_PORT` under `common.env`. Also in each `subnetX.env`, `BOOTNODES` port has to be changed. +3. Stats Server (UI backend) - port 5213. +4. UI Frontend - port 5214. +5. Relayer UI - port 5215. +6. Faucet Server - port 5211 +7. Generator UI - port 5210. + + diff --git a/docs/subnet/install_guide/f&q.md b/docs/subnet/install_guide/f&q.md new file mode 100644 index 0000000..070177d --- /dev/null +++ b/docs/subnet/install_guide/f&q.md @@ -0,0 +1,77 @@ +--- +title: Upgrading the Subnet +# TODO: title +--- + +# Common Issues and Troubleshooting + +## Common Issues + - Subnet blocks are not being mined. + 1. First confirm that the Subnet nodes are able to communicate with each other through the network layer. Run the check peer script `generated/scripts/check-peers.sh` the number of peers should be one less than number of subnet nodes. For example, if there are 3 Subnet nodes in total, each node should have 2 peers. + + 2. If the nodes are peering but still not mining, it could be a low memory issue. In Docker configs you can try to increase memory or swap. Then, in case of fresh Subnet, [delete data and start the nodes again](./1_launch_subnet.md/#deleting-subnet). ![Docker Memory Config](./img/docker_mem.png) + + 3. Docker engine in Mac OS can be inconsistent after long-running or high-load. It could help to restart the machine and [hard reset the subnet](./1_launch_subnet.md#deleting-subnet ) to get it running. + + - Subnet node does not boot with error log `Fatal: Error starting protocol stack: listen unix /work/xdcchain/XDC.ipc: bind: invalid argument` + + This is due to the volume mount path being too long. The mounth path is your current directory (also can check with `pwd` command). Please move the `generated` folder to a shorter path and try again. + + - Docker image startup fails with `SIGKILL` or `Error code: 137` found in logs. (Issue found in Frontend image) + + This error occurs because Docker ran Out Of Memory (OOM). You can increase the memory limit in [Docker settings](https://docs.docker.com/desktop/settings/mac/#:~:text=lower%20the%20number.-,Memory,-.%20By%20default%2C%20Docker) + + + + +## Troubleshooting Scripts + - `generated/scripts/check-mining.sh` + + This will check your current block in Subnet + + - `generated/scripts/check-peers.sh` + + This will check the number of peers of your Subnet node + + +## Telegram Troubleshooting Support Group + https://t.me/+jvkX6LaLEEthZWM1 + + +## Frequently Asked Questions + + - How many Subnet nodes should I have? + + Even one node is enough to start the Subnet blockchain! However, for better decantralized security, 3+ nodes is recommended. At least 2/3 of all nodes must be online and honest to mine blocks. + + - For testing, should I checkpoint the Subnet to devnet or testnet? + + Testnet, devnet will be less stable due to frequent development changes. + + - Where are all the Subnet tokens, how do I use the Subnet? + + In XDC-Subnet all initial tokens are assigned to the Grandmaster wallet (check keys.json). You can transfer them to any wallet address. Check [Faucet](../usage/2_faucet.md). + +- How can I manage Subnet tokens? + + 1. Check [here](../usage/2_faucet.md) for how you can use the Subnet Faucet to easily transfer Subnet tokens to your users. + 2. You can use any web3 wallet and connect to the Subnet RPC as a custom network, then transfer to other addresses. + + - How can I easily give out Subnet tokens to my users? + + We have provided a Faucet server for you to deploy under `generated/scripts/faucet-server.sh`. Anyone with access to the faucet page can request for tokens. + Please check (faucet page) + + - Which files contain sensitive data and private keys? + + common.env, contract_deploy.env, keys.json, and subnet*.env. Please make sure these files are kept securely. + +- This function didn't work/I have encoutered an unexpected bug + + For troubleshooting we can help you at [Telegram Support Group](./3_troubleshooting.md#telegram-troubleshooting-support-group) and we will check as soon as possible. + + Other channels for suggestions/requests include [XDC Forum](https://forum.xinfin.org/) and [GitHub Issues](https://github.com/XinFinOrg/XDC-Subnet/issues) + +- How do I change the Relayer Wallet/Parentchain Wallet? + + You can [update services configs](./2_configs_explanation.md#updating-services-configs) in common.env to change the Relayer key diff --git a/docs/subnet/install_guide/launch_subnet.md b/docs/subnet/install_guide/launch_subnet.md new file mode 100644 index 0000000..36b9fa7 --- /dev/null +++ b/docs/subnet/install_guide/launch_subnet.md @@ -0,0 +1,74 @@ +--- +title: Upgrading the Subnet +# TODO: title +--- + +# Launch a Subnet + +## Requirements + - OS: Linux. Only Linux is supported for full deployment. + + - OS: Mac is only supported for single machine testing environment. + + - docker, docker compose V2. For manual installation of docker compose V2 please refer to: https://docs.docker.com/compose/install/linux/ + + - Recommended Hardware (per single Subnet node): + - CPU: 2 Core + - Memory: 4 GB + + - Web3 wallet with funds. For testing we have faucets provided: + - https://faucet.apothem.network/ + - https://faucet.blocksscan.io/ + +## Video Walkthrough + + +## Generate Subnet Configs With UI + + 1. Pull `generator.sh` script from the generator Github repo + ``` + curl -O https://raw.githubusercontent.com/XinFinOrg/XinFin-Node/master/subnet/deployment-generator/scripts/generate.sh + ``` + + 2. Run the configuration generator, this will start a local webserver + ``` + chmod +x generate.sh + ./generate.sh + cd generated + ``` + + 3. Go to [http://localhost:5210/](http://localhost:5210) in your browser. +
+ If you are running this on a remote server. +

+ first use ssh tunnel: ssh -N -L localhost:5210:localhost:5210 USERNAME@IP_ADDRESS -i SERVER_KEY_FILE +

+
+ + + 4. Config the Subnet options per your requirement. + ![UI](./img/ui.png) + + 5. follow the generated instructions in `commands.txt`. In general, the steps are: + - start Subnet Nodes + - deploy CSC + - deploy XDC-Zero (optional) + - start Subnet Services (relayer, stats-server, frontend) + + 6. Once successfully deployed, you can check out [UI usage guide](../usage/ui/1_homepage.md) + +## Removing Subnet + + ### Shutdown Subnet + Under `generated` directory + ``` + docker compose --env-file docker-compose.env --profile services down + docker compose --env-file docker-compose.env --profile machine1 down + ``` + + ### Deleting Subnet + Remove `xdcchain*`, `bootnodes`, and `stats-service` directories + Warning: this cannot be undone + ``` + rm -rf xdcchain* bootnodes stats-service + ``` diff --git a/docs/subnet/setting_up_your_subnet.md b/docs/subnet/setting_up_your_subnet.md new file mode 100644 index 0000000..14a42f1 --- /dev/null +++ b/docs/subnet/setting_up_your_subnet.md @@ -0,0 +1,7 @@ +--- +title: Setting Up Your Own XDC-Subnet Tutorial +--- + +Setting Up Your Own XDC-Subnet Tutorial + + \ No newline at end of file diff --git a/docs/subnet/upgrading_subnet.md b/docs/subnet/upgrading_subnet.md new file mode 100644 index 0000000..b1c4369 --- /dev/null +++ b/docs/subnet/upgrading_subnet.md @@ -0,0 +1,34 @@ +--- +title: Upgrading the Subnet +--- +# Upgrading the Subnet +## Updating Configs +### Upgrading Subnet Deployment +#### Create a Subnet backup +1. [Shutdown the subnet](./1_launch_subnet.md#shutdown-subnet ) + +2. Make a copy of `xdcchain` directory + +#### Update Subnet Versions +1. Go to `docker-compose.yml` under `generated` directory. +2. Change the docker image tag of your desired component(s). +3. Run: +``` + docker compose --env-file docker-compose.env --profile machine1 up -d + docker compose --env-file docker-compose.env --profile services up -d +``` + +Using `latest` tag is not recommended since not all components version are not guaranteed to be compatible. + +### Updating Services Configs +1. Shut down subnet services +``` +docker compose --env-file docker-compose.env --profile services down +``` +2. Update configuration (usually ENVs inside common.env file) + +3. Start subnet services +``` +docker compose --env-file docker-compose.env --profile services up -d +``` + diff --git a/docs/subnet/using_subnet.md b/docs/subnet/using_subnet.md new file mode 100644 index 0000000..ca9cfbe --- /dev/null +++ b/docs/subnet/using_subnet.md @@ -0,0 +1,177 @@ +--- +title: UI Usage Guide +--- +# UI Usage Guide +The guide for XDC Subnet user interface +## Homepage + +Once subnet is successfully deployed. The homepage will show the following. + +![Homepage 1](./img/homepage_1.png) + +1. The Subnet blockchain state. You can see the current 'Not Confirmed' and 'Confirmed' blocks. 'Confirmed' or 'committed' blocks should be 3 blocks behind latest blocks. +2. The Subnet blockchain AS KNOWN by the Parentchain. The Relayer periodically calls the Checkpoint Smart Contract to update the Subnet status (default every 2 minutes). +3. The Network Info card shows the Subnet throughput state, by default Blocktime should be every 2 seconds. It also indicates the Parentchain network +4. The Relayer Info card shows the Relayer status. Which Checkpoint Smart Contract (CSC) it calls, Subnet blocks in the backlog, and the remaining wallet funds. +5. The Masternodes Info card shows the Subnet nodes status. By default, all Subnet nodes are Masternodes and all should be active. + + + + + +In the lower half of the homepage there are more information as shown. + +![Homepage 2](./img/homepage_2.png) + + + +1. This card shows further details of subnet blocks, including their height, hash, proposer, and confirmation status. The left side of 'confirmation status' shows the block being committed in the Subnet chain and the right side shows the block hash being recorded in the Parent chain. + +2. This card shows a detailed view of the subnet nodes including their address. The status also differrentiates inactive nodes to 'penalty' or 'standby' + +3. Additionally, you can select the UI theme (light or dark) by toggling this button. + + +## Confirmation Checker + +After navigating with the left menu bar to the Confirmation Checker of the Subnet, this will be shown. + +![Confirmation Checker 1](./img/confirm_1.png) + +The input box accepts Block height, Block hash, and even TX hash. + +After your input, the search engine will traverse the chain and display the info accodingly. Below is an example of Block height search. + +![Confirmation Checker 2](./img/confirm_2.png) + +1. Confirmation status of the block (or the block that TX belongs to) +2. The block detailed information +3. The Parentchain block where the Subnet block was recorded + + +Next is another example of a Block hash search. + +![Confirmation Checker 3](./img/confirm_3.png) + +1. Confirmation status of the block (or the block that TX belongs to) +2. The block detailed information +3. As the Subnet block has not been checkpointed in the Parentchain, the UI is displaying height 0. + + +## Subnet Management + +Subnet management is used for adding and removing Masternodes in the Subnet. To manage the subnet, you need to use the Grandmaster Account, as only the Grandmaster has the right to manage the Subnet. + +You can find the Grandmaster Key in the `keys.json` file. + +After making a modification with Subnet management, the change will take effect in the next epoch (900 blocks). + +When adding a Masternode address in the management, the new Masternode server should also be started up and added to the network. + +### 1. Log in to the Wallet and Connect to the Subnet + +To manage the subnet, you need to use your **Grandmaster Account**. Find the **Grandmaster Key** in the `keys.json` file and import this account into your wallet. + +![import_account](img/import_account.png) + +1. Go to the correct tab and switch to the **Grandmaster Account**. +2. Click the `Connect Wallet` button. + ![connect_wallet](img/connect_wallet.png) + +3. Choose your wallet and allow the subnet network to be added. The wallet will automatically switch to this network, as shown below: + ![switch_to_subnet](img/switch_subnet.png) + + If the wallet doesn’t switch to the subnet automatically, follow the instructions on the page to fill in the network details manually and connect to the subnet. + +4. Connect the account and network. + ![account_connection](img/account_connect.png) + +You will see a confirmation page like this: + +![successful_connection_confirmation](img/successful_connection_confirmation.png) + +### 2. Node Operations + +#### 2.1 Add candidate + +1. Switch to the **Master List** Tab +2. Click the `Add a new master candidate` button to add the node as a master node. **Delegation amount** must be at least `10,000,000` Subnet tokens. + ![add_master_node_candidate](img/add_master_node_candidate.png) + +#### 2.2 Change node delegation + +- In the list, select the node you want to change the delegation for, then click the `Promote` / `Demote` button and enter the new delegation amount. + + - If increasing the delegation, ensure the total delegation amount is over `10,000,000` Subnet tokens; otherwise, the transaction will fail.There is no extra benefit in delegating more than 10,000,000 tokens to an address + - If decreasing the delegation, ensure the remaining amount is still at least `10,000,000` Subnet tokens; otherwise, the transaction will fail. + + ![promote_node_delegate](img/promote_node_delegate.png) + +#### 2.3 Remove a node + +1. In the **Master List** Tab, select the node you want to remove, and click the `Remove` button. +2. After removal, the node’s delegated XDC will be reset to zero, and the node information will be removed from the list after one epoch. + ![remove_master_node](img/remove_master_node.png) + + + +## Faucet + +In Subnets, all native tokens are initially assigned to the Grandmaster Wallet. To allow users to use the Subnet, we have to distribute the tokens out of the Grandmaster. We have provided convenient scripts for you to easily share Subnet tokens to your users. + +### One-time Transfer + +Under `generated` directory run the Faucet script. + +``` +./scripts/faucet.sh +``` + +The script will ask for your source wallet private key. You can use the Grandmaster Wallet(check `keys.json` file for the private key). +Then input the destination wallet and the transfer amount. + +![Example](./img/faucet.png) + +### Faucet Server + +Under `generated` directory run the Faucet server script. + +``` +./scripts/faucet-server.sh +``` + +The script will ask for your source wallet private key. you can use the Grandmaster Wallet(check `keys.json` for the private key). +By default, the server is hosted on port `5211` of your machine. Then, on your browser, visit the url: `http://127.0.0.1:5211` + +![Example](./img/faucet-server1.png) + +Input your destination wallet or feel free to generate a random wallet via Address Generator. + +![Example](./img/faucet-server2.png) + +Submit and wait for confirmation. + +![Example](./img/faucet-server3.png) + +You can host this on any server and allow users to make token requests by themselves. + +### Transfer Subnet Funds Without Faucet + +The Faucet is not neccessary needed for funds transfer, most Ethereum compatible web3 wallet will also work. + +First import a new wallet with the Grandmaster private key. Then add a custom network pointing to your Subnet RPC URL. Finally, use the web3 wallet for tokens transfer. + + +### Faucet Source Code + +Please feel free to check the below repositories for the Subnet Faucet source code. + +https://github.com/XinFinOrg/XinFin-Node/tree/master/subnet/deployment-generator/scripts + +https://github.com/XinFinOrg/XinFin-Node/tree/master/subnet/deployment-generator/src/faucet.js + + + +## Blockchain Explorer + +You may optionally use an external blocks explorer if you require verbose browsing such as block detail, accounts browsing, contracts browsing. We can recommend [Chainlens-free](https://github.com/web3labs/chainlens-free/tree/master/docker-compose) as one of the solution. Please follow the instructions as the previous link. You only need to pass one of the Subnet's RPC as a variable in the `docker-compose` command, which will most likely be `NODE_ENDPOINT=http://localhost:8545` or `NODE_ENDPOINT=http://:8545`. diff --git a/mkdocs.yml b/mkdocs.yml index 479b6f7..35e9942 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -112,11 +112,23 @@ nav: - XDC Subnet: - XDC Subnet: ./subnet/index.md - User Guide: - - XDC Subnet Official Documentation: https://xinfinorg.github.io/xdc-subnet-docs/category/deployment-guide - - Upgrading the Subnet: https://xinfinorg.github.io/xdc-subnet-docs/deployment/upgrading_the_subnet - - UI Usage Guide: https://xinfinorg.github.io/xdc-subnet-docs/category/ui-usage-guide - - Installation Guide: https://www.xdc.dev/vinn_9686/xdc-subnet-installation-guide-building-a-secure-and-scalable-network-4hb3 - - Setting Up Your Own XDC-Subnet Tutorial: https://youtu.be/VwfI4VTMUnY?si=K9Yv3MdxjKryaDfm + - Installation Guide: + - Launch a Subnet: ./subnet/install_guide/launch_subnet.md + - Configs Explanation: ./subnet/install_guide/config_explanation.md + - Common Issues and Troubleshooting: ./subnet/install_guide/f&q.md + # - Subnet Deployment Generator Changelog + - Components: + - Subnet Chain: ./subnet/components/subnet_chain.md + - Checkpoint Smart Contract: ./subnet/components/checkpoint_contract.md + - Relayer: ./subnet/components/relayer.md + - API Library: ./subnet/components/api_library.md + - XDCZero: ./subnet/components/xdc_zero.md + - Subswap: ./subnet/components/subswap.md + # - XDC Subnet Official Documentation: ./subnet/Installation_guide.md + # - Setting Up Your Own XDC-Subnet Tutorial: ./subnet/setting_up_your_subnet.md + - Using the Subnet: ./subnet/using_subnet.md + - Upgrading the Subnet: ./subnet/upgrading_subnet.md + - Announcements: - Announcements: ./announce/index.md - Upcoming: