diff --git a/docs/subnet/components/checkpoint_contract.md b/docs/subnet/components/checkpoint_contract.md index 1498c05..5edef02 100644 --- a/docs/subnet/components/checkpoint_contract.md +++ b/docs/subnet/components/checkpoint_contract.md @@ -86,7 +86,7 @@ Lite Checkpoint is a lightweight block header checkpoint. It implements several 3. Users can get gap/epoch block information from methods such as `getHeader`. -![Lite Checkpoint](../img/sc-litecheckpoint.jpg) +![Lite Checkpoint](sc-litecheckpoint.jpg) #### Upgradeable module @@ -161,7 +161,7 @@ The `ProxyGateway` smart contract plays a central role in this module. It inheri ![Alt text](../img/sc-upgradeable-upgrade.png) -## spec +## Spec ### APIs - Functions that have access restriction to authorized client diff --git a/docs/subnet/components/relayer.md b/docs/subnet/components/relayer.md index cfba53a..ae441b7 100644 --- a/docs/subnet/components/relayer.md +++ b/docs/subnet/components/relayer.md @@ -22,7 +22,7 @@ At high level, the relayer is able to: ## 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). +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](../components/checkpoint_contract.md). ### Choosing Full or Lite Relayer diff --git a/docs/subnet/components/subswap.md b/docs/subnet/components/subswap.md index 701d9b5..fb76564 100644 --- a/docs/subnet/components/subswap.md +++ b/docs/subnet/components/subswap.md @@ -4,19 +4,17 @@ 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** +### **System Architecture** Subswap is organized into three layers: @@ -37,13 +35,13 @@ Subswap is organized into three layers: --- -##### **Design Considerations** +### **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** +### **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. @@ -55,7 +53,6 @@ Subswap leverages XDC Zero's powerful infrastructure to deliver an efficient cro ## 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. --- diff --git a/docs/subnet/components/xdc_zero.md b/docs/subnet/components/xdc_zero.md index e2db844..b5529c7 100644 --- a/docs/subnet/components/xdc_zero.md +++ b/docs/subnet/components/xdc_zero.md @@ -2,7 +2,6 @@ title: Upgrading the Subnet --- # XDCZero -default ## Design diff --git a/docs/subnet/install_guide/f&q.md b/docs/subnet/install_guide/f&q.md index c794996..0c02198 100644 --- a/docs/subnet/install_guide/f&q.md +++ b/docs/subnet/install_guide/f&q.md @@ -3,28 +3,32 @@ title: Upgrading the Subnet # TODO: title --- -# Common Issues and Troubleshooting - -## Common Issues - - Subnet blocks are not being mined. +# Frequently Asked Questions +## Subnet Launch +### 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. + 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](../install_guide/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](../install_guide/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. +- **Subnet node does not boot with error log `Fatal: Error starting protocol stack: listen unix /work/xdcchain/XDC.ipc: bind: invalid argument`** - - Docker image startup fails with `SIGKILL` or `Error code: 137` found in logs. (Issue found in Frontend image) + 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. - 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) - +- **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 -## Troubleshooting Scripts - `generated/scripts/check-mining.sh` This will check your current block in Subnet @@ -34,44 +38,57 @@ title: Upgrading the Subnet This will check the number of peers of your Subnet node -## Telegram Troubleshooting Support Group - https://t.me/+jvkX6LaLEEthZWM1 +## Subnet Node Requirements + +- **How many Subnet nodes should I have?** + + Even one node is enough to start the Subnet blockchain! However, for better decentralized security, 3+ nodes are recommended. At least 2/3 of all nodes must be online and honest to mine blocks. + +## Development and Testing + +- **For testing, should I checkpoint the Subnet to devnet or testnet?** + + It's recommended to use the testnet, as the devnet will be less stable due to frequent development changes. + +## Managing Subnet Tokens + +- **Where are all the Subnet tokens, and how do I use the Subnet?** -## Frequently Asked Questions + In XDC-Subnet, all initial tokens are assigned to the Grandmaster wallet (check `keys.json`). You can transfer tokens to any wallet address. For easy transfers, refer to the [Faucet](../using_subnet.md/#faucet) documentation. - - How many Subnet nodes should I have? +- **How can I manage Subnet tokens?** - 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. + 1. Use the [Subnet Faucet](../using_subnet.md/#faucet) to easily transfer Subnet tokens to your users. + 2. Use any Web3 wallet (such as Metamask or OKX wallet), add the Subnet RPC as a custom network then connect to the Subnet and transfer tokens to other addresses. - - For testing, should I checkpoint the Subnet to devnet or testnet? - - Testnet, devnet will be less stable due to frequent development changes. +- **How can I easily give out Subnet tokens to my users?** - - Where are all the Subnet tokens, how do I use the Subnet? + A Faucet server script is provided for you to deploy under `generated/scripts/faucet-server.sh`. Anyone with access to the faucet page can request tokens. Please refer to the [faucet page](../using_subnet.md/#faucet) for more details. - 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). +## Security and Sensitive Files -- How can I manage Subnet tokens? +- **Which files contain sensitive data and private keys?** - 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. + The following files contain sensitive information and should be stored securely: - - 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) + - `common.env` + - `contract_deploy.env` + - `keys.json` + - `subnet*.env` - - Which files contain sensitive data and private keys? +## Configuration Changes - common.env, contract_deploy.env, keys.json, and subnet*.env. Please make sure these files are kept securely. +- **How do I change the Relayer Wallet/Parentchain Wallet?** -- This function didn't work/I have encoutered an unexpected bug + You can update the `common.env` file to change the Relayer key. Refer to the [service configuration documentation](../upgrading_subnet.md/#updating-services-configs) for more details. - 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. +## Troubleshooting - Other channels for suggestions/requests include [XDC Forum](https://forum.xinfin.org/) and [GitHub Issues](https://github.com/XinFinOrg/XDC-Subnet/issues) +- **What should I do if a function didn’t work or I encountered an unexpected bug?** -- How do I change the Relayer Wallet/Parentchain Wallet? + For troubleshooting support, join our [Telegram Support Group](https://t.me/+jvkX6LaLEEthZWM1). + For suggestions or requests, you can also reach out via: - You can [update services configs](./2_configs_explanation.md#updating-services-configs) in common.env to change the Relayer key + - [XDC Forum](https://forum.xinfin.org/) + - [GitHub Issues](https://github.com/XinFinOrg/XDC-Subnet/issues) diff --git a/docs/subnet/install_guide/launch_subnet.md b/docs/subnet/install_guide/launch_subnet.md index 31c3853..c29abe8 100644 --- a/docs/subnet/install_guide/launch_subnet.md +++ b/docs/subnet/install_guide/launch_subnet.md @@ -21,7 +21,9 @@ title: Upgrading the Subnet - https://faucet.blocksscan.io/ ## Video Walkthrough - + + + ## Generate Subnet Configs With UI @@ -55,18 +57,19 @@ title: Upgrading the Subnet - 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) + 6. Once successfully deployed, you can check out [UI usage guide](../using_subnet.md) ## Removing Subnet - ### Shutdown 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 +### Deleting Subnet + Remove `xdcchain*`, `bootnodes`, and `stats-service` directories Warning: this cannot be undone ``` diff --git a/docs/subnet/upgrading_subnet.md b/docs/subnet/upgrading_subnet.md index b1c4369..6166618 100644 --- a/docs/subnet/upgrading_subnet.md +++ b/docs/subnet/upgrading_subnet.md @@ -5,7 +5,7 @@ title: Upgrading the Subnet ## Updating Configs ### Upgrading Subnet Deployment #### Create a Subnet backup -1. [Shutdown the subnet](./1_launch_subnet.md#shutdown-subnet ) +1. [Shutdown the subnet](install_guide/launch_subnet.md/#shutdown-subnet) 2. Make a copy of `xdcchain` directory