diff --git a/docs/components/API_library/_category_.json b/docs/components/API_library/_category_.json deleted file mode 100644 index f60a32c..0000000 --- a/docs/components/API_library/_category_.json +++ /dev/null @@ -1,11 +0,0 @@ -{ - "label": "API Library", - "position": 5, - "link": { - "type": "generated-index", - "description": "This section specifies the API library we develop for the subnet users to confirm subnet transactions." - } -} - - - diff --git a/docs/components/API_library/api.md b/docs/components/API_library/api.md deleted file mode 100644 index c2e6a97..0000000 --- a/docs/components/API_library/api.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -sidebar_label: Specs -sidebar_position: 1 ---- - -# Specifications - -TBW diff --git a/docs/components/_category_.json b/docs/components/_category_.json deleted file mode 100644 index 5d11bc5..0000000 --- a/docs/components/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Components", - "position": 3, - "link": { - "type": "generated-index", - "description": "This section specifies the four components of XDC subnet." - } -} \ No newline at end of file diff --git a/docs/components/checkpoint_smart_contract/_category_.json b/docs/components/checkpoint_smart_contract/_category_.json deleted file mode 100644 index 8ca6301..0000000 --- a/docs/components/checkpoint_smart_contract/_category_.json +++ /dev/null @@ -1,11 +0,0 @@ -{ - "label": "Checkpoint Smart Contract", - "position": 3, - "link": { - "type": "generated-index", - "description": "This section specifies the Checkpoint Smart Contract in the parent chain that protects the child chain." - } -} - - - diff --git a/docs/components/checkpoint_smart_contract/design.md b/docs/components/checkpoint_smart_contract/design.md deleted file mode 100644 index 868d216..0000000 --- a/docs/components/checkpoint_smart_contract/design.md +++ /dev/null @@ -1,158 +0,0 @@ ---- -sidebar_position: 1 ---- - -# 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) \ No newline at end of file diff --git a/docs/components/checkpoint_smart_contract/sc-checkpoint.jpg b/docs/components/checkpoint_smart_contract/sc-checkpoint.jpg deleted file mode 100644 index d7f6f11..0000000 Binary files a/docs/components/checkpoint_smart_contract/sc-checkpoint.jpg and /dev/null differ diff --git a/docs/components/checkpoint_smart_contract/sc-litecheckpoint.jpg b/docs/components/checkpoint_smart_contract/sc-litecheckpoint.jpg deleted file mode 100644 index af3c859..0000000 Binary files a/docs/components/checkpoint_smart_contract/sc-litecheckpoint.jpg and /dev/null differ diff --git a/docs/components/checkpoint_smart_contract/sc-overview.jpg b/docs/components/checkpoint_smart_contract/sc-overview.jpg deleted file mode 100644 index cd09e19..0000000 Binary files a/docs/components/checkpoint_smart_contract/sc-overview.jpg and /dev/null differ diff --git a/docs/components/checkpoint_smart_contract/sc-upgradeable-overview.png b/docs/components/checkpoint_smart_contract/sc-upgradeable-overview.png deleted file mode 100644 index 6ca8368..0000000 Binary files a/docs/components/checkpoint_smart_contract/sc-upgradeable-overview.png and /dev/null differ diff --git a/docs/components/checkpoint_smart_contract/sc-upgradeable-upgrade.png b/docs/components/checkpoint_smart_contract/sc-upgradeable-upgrade.png deleted file mode 100644 index 3a8bce6..0000000 Binary files a/docs/components/checkpoint_smart_contract/sc-upgradeable-upgrade.png and /dev/null differ diff --git a/docs/components/checkpoint_smart_contract/spec.md b/docs/components/checkpoint_smart_contract/spec.md deleted file mode 100644 index fd18cfe..0000000 --- a/docs/components/checkpoint_smart_contract/spec.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -sidebar_label: Specs -sidebar_position: 2 ---- - -## 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/components/relayer/_category_.json b/docs/components/relayer/_category_.json deleted file mode 100644 index ca32975..0000000 --- a/docs/components/relayer/_category_.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "label": "Relayer", - "position": 4, - "link": { - "type": "generated-index", - "description": "This section specifies the relayer that checkpoints the subnet chain to the parent chain." - } -} - diff --git a/docs/components/relayer/design.md b/docs/components/relayer/design.md deleted file mode 100644 index f567f96..0000000 --- a/docs/components/relayer/design.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -sidebar_position: 1 ---- - -# 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) \ No newline at end of file diff --git a/docs/components/relayer/relayer-diagram.jpg b/docs/components/relayer/relayer-diagram.jpg deleted file mode 100644 index 2e3d31d..0000000 Binary files a/docs/components/relayer/relayer-diagram.jpg and /dev/null differ diff --git a/docs/components/relayer/relayer_mode.md b/docs/components/relayer/relayer_mode.md deleted file mode 100644 index b8edf9c..0000000 --- a/docs/components/relayer/relayer_mode.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -sidebar_position: 2 -sidebar_label: "Relayer Mode" ---- - -# 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/components/subnet/_category_.json b/docs/components/subnet/_category_.json deleted file mode 100644 index 68937a8..0000000 --- a/docs/components/subnet/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Subnet Chain", - "position": 2, - "link": { - "type": "generated-index", - "description": "This section specifies the subnet itself, a sovereign, permissioned, and high-performing blockchain." - } -} diff --git a/docs/components/subnet/api.md b/docs/components/subnet/api.md deleted file mode 100644 index 5123598..0000000 --- a/docs/components/subnet/api.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -sidebar_position: 3 ---- - -# API - -Subnet-specific APIs \ No newline at end of file diff --git a/docs/components/subnet/design.md b/docs/components/subnet/design.md deleted file mode 100644 index 5e94af2..0000000 --- a/docs/components/subnet/design.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -sidebar_position: 1 ---- - -# 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. diff --git a/docs/components/subswap/_category_.json b/docs/components/subswap/_category_.json deleted file mode 100644 index 0407e4e..0000000 --- a/docs/components/subswap/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Subswap", - "position": 6, - "link": { - "type": "generated-index", - "description": "default" - } -} diff --git a/docs/components/subswap/design.md b/docs/components/subswap/design.md deleted file mode 100644 index cdcee2f..0000000 --- a/docs/components/subswap/design.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -sidebar_position: 1 ---- - -# 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) \ No newline at end of file diff --git a/docs/components/subswap/image1.png b/docs/components/subswap/image1.png deleted file mode 100644 index bbda6ba..0000000 Binary files a/docs/components/subswap/image1.png and /dev/null differ diff --git a/docs/components/subswap/image2.png b/docs/components/subswap/image2.png deleted file mode 100644 index 1b8b5ae..0000000 Binary files a/docs/components/subswap/image2.png and /dev/null differ diff --git a/docs/components/subswap/spec.md b/docs/components/subswap/spec.md deleted file mode 100644 index e7358af..0000000 --- a/docs/components/subswap/spec.md +++ /dev/null @@ -1,136 +0,0 @@ ---- -sidebar_label: Specs -sidebar_position: 3 ---- -### 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/components/xdczero/_category_.json b/docs/components/xdczero/_category_.json deleted file mode 100644 index 3759a7b..0000000 --- a/docs/components/xdczero/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "XDCZero", - "position": 5, - "link": { - "type": "generated-index", - "description": "default" - } -} diff --git a/docs/components/xdczero/design.md b/docs/components/xdczero/design.md deleted file mode 100644 index 18ff497..0000000 --- a/docs/components/xdczero/design.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -sidebar_position: 1 ---- - -# 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) - diff --git a/docs/components/xdczero/image.png b/docs/components/xdczero/image.png deleted file mode 100644 index 51cbf2a..0000000 Binary files a/docs/components/xdczero/image.png and /dev/null differ diff --git a/docs/components/xdczero/image1.png b/docs/components/xdczero/image1.png deleted file mode 100644 index 08e5c6c..0000000 Binary files a/docs/components/xdczero/image1.png and /dev/null differ diff --git a/docs/components/xdczero/image2.png b/docs/components/xdczero/image2.png deleted file mode 100644 index eace179..0000000 Binary files a/docs/components/xdczero/image2.png and /dev/null differ diff --git a/docs/components/xdczero/spec.md b/docs/components/xdczero/spec.md deleted file mode 100644 index f3e9070..0000000 --- a/docs/components/xdczero/spec.md +++ /dev/null @@ -1,126 +0,0 @@ ---- -sidebar_label: Specs -sidebar_position: 3 ---- -# API Documentation - -## 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/contact.md b/docs/contact.md index 5109ef9..9e699c3 100644 --- a/docs/contact.md +++ b/docs/contact.md @@ -8,4 +8,4 @@ sidebar_position: 7 For feedback, bug report, request, or general Subnet discussion please feel free to make a post on [XDC Forum](https://forum.xinfin.org/) or [GitHub Issues](https://github.com/XinFinOrg/XDC-Subnet/issues) -For troubleshooting, you can talk to us at [Telegram Support Group](./deployment/3_troubleshooting.md#telegram-troubleshooting-support-group) and we will check as soon as possible. \ No newline at end of file +For troubleshooting, you can talk to us at [Telegram Support Group](https://t.me/+jvkX6LaLEEthZWM1) and we will check as soon as possible. \ No newline at end of file diff --git a/docs/deployment/1_launch_subnet.md b/docs/deployment/1_launch_subnet.md deleted file mode 100644 index 88c346c..0000000 --- a/docs/deployment/1_launch_subnet.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -sidebar_label: "1. Launch a Subnet" -sidebar_position: 1 ---- - -# 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/deployment/2_configs_explanation.md b/docs/deployment/2_configs_explanation.md deleted file mode 100644 index b9dd9c6..0000000 --- a/docs/deployment/2_configs_explanation.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -sidebar_label: "2. Configs Explanation" -sidebar_position: 2 ---- - -# 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. - - - -## 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/deployment/3_troubleshooting.md b/docs/deployment/3_troubleshooting.md deleted file mode 100644 index 503a9dd..0000000 --- a/docs/deployment/3_troubleshooting.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -sidebar_label: "3. Common Issues and Troubleshooting" -sidebar_position: 3 ---- - -# 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 \ No newline at end of file diff --git a/docs/deployment/5_faq.md b/docs/deployment/5_faq.md deleted file mode 100644 index 796adfb..0000000 --- a/docs/deployment/5_faq.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -sidebar_label: "4. FAQ" -sidebar_position: 4 ---- - -# Frequently Asked Questions - -## 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?** - - 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](../usage/2_faucet.md) documentation. - -- **How can I manage Subnet tokens?** - - 1. Use the [Subnet Faucet](../usage/2_faucet.md) 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. - -- **How can I easily give out Subnet tokens to my users?** - - 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](../usage/2_faucet.md) for more details. - -## Security and Sensitive Files - -- **Which files contain sensitive data and private keys?** - - The following files contain sensitive information and should be stored securely: - - - `common.env` - - `contract_deploy.env` - - `keys.json` - - `subnet*.env` - -## Configuration Changes - -- **How do I change the Relayer Wallet/Parentchain Wallet?** - - You can update the `common.env` file to change the Relayer key. Refer to the [service configuration documentation](./2_configs_explanation.md#updating-services-configs) for more details. - -## Troubleshooting - -- **What should I do if a function didn’t work or I encountered an unexpected bug?** - - For troubleshooting support, join our [Telegram Support Group](./3_troubleshooting.md#telegram-troubleshooting-support-group). - For suggestions or requests, you can also reach out via: - - - [XDC Forum](https://forum.xinfin.org/) - - [GitHub Issues](https://github.com/XinFinOrg/XDC-Subnet/issues) diff --git a/docs/deployment/6_subnet_deployment_generator_changelog.md b/docs/deployment/6_subnet_deployment_generator_changelog.md deleted file mode 100644 index 178389f..0000000 --- a/docs/deployment/6_subnet_deployment_generator_changelog.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -sidebar_label: "Subnet Deployment Generator Changelog" -sidebar_position: 5 ---- - -# Subnet Deployment Generator Changelog - -### v1.0.0 - 2024/10/03 - - Added Configuration Generator UI - - Added XDC-Zero configuration generation - - Added Faucet and Faucet Server - - Added helper scripts - - Changed default ports of components to prevent clashing - - Stats Server - port 5213 - - Frontend - port 5214 - - Relayer - port 5215 - - Faucet Server - port 5211 - - Generator UI - port 5210 - - Documentation update - - added Subnet setup video walkthrough - - added FAQ section - - added Contact section - - Minor bug fixes - - -### v0.3.2 - 2024/08/15 - - Changed frontend default due to clashing from 5000 to 5555 - -### v0.3.1 - 2024/07/24 - - Use testnet by default - - Remove admin api by default - - Added PUBLIC_IP optional config in deployment-generator - - Bump component versions - -### v0.2.1 - 2024/01/09 - - New generation style, pulls script from github to run multiple docker images instead of generating from single image. - - New Checkpoint Smart Contract (CSC) deployment image - - Supports upgradable CSC - - Bump components versions - - Fix bugs - - Code refactor, optimization -### v0.1.6 - - Bump relayer version to support gas fee changes -### v0.1.5 - - Added OS=mac option in 'docker.env'. This option is intended for single machine testing environment only. -### v0.1.4 - - Added custom keys functionality - 'docker.env' now accepts GRANDMASTER_PK and SUBNETS_PK. Where SUBNETS_PK can have multiple keys separated by a comma ','. Number of subnet keys must equal NUM_SUBNET. Keys are randomized if not provided. - - Added RELAYER_MODE in 'docker.env', CSC deployment will select from 'full' or 'lite' smart contract, default 'full'. - - Automate CHECKPOINT_CONTRACT copy-paste step (manual action no longer required). - - PARENTCHAIN_WALLET is no longer required in 'docker.env', the address will be derived from PARENTCHAIN_WALLET_PK. - - Disabled parentchain observer in docker-compose.yml, unused for now (due to long startup time). - - Bump default subnet components stable versions diff --git a/docs/deployment/_category_.json b/docs/deployment/_category_.json deleted file mode 100644 index f1b5807..0000000 --- a/docs/deployment/_category_.json +++ /dev/null @@ -1,11 +0,0 @@ -{ - "label": "Deployment Guide", - "position": 3, - "link": { - "type": "generated-index", - "description": "Step-by-step guide to deploy your own XDC subnet and get it secured by XDC" - } -} - - - diff --git a/docs/deployment/img/docker_mem.png b/docs/deployment/img/docker_mem.png deleted file mode 100644 index dd79007..0000000 Binary files a/docs/deployment/img/docker_mem.png and /dev/null differ diff --git a/docs/deployment/img/ui.png b/docs/deployment/img/ui.png deleted file mode 100644 index b1ea249..0000000 Binary files a/docs/deployment/img/ui.png and /dev/null differ diff --git a/docs/intro.md b/docs/intro.md index 9733299..680e821 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -4,4 +4,4 @@ sidebar_position: 1 --- # Welcome -Welcome to the technical documentation site of XDC enterprise private subnet! We are continuously adding materials to it. +This site has been deprecated. We have migrated XDC-Subnet documentation to the official XDC documentation site https://docs.xdc.network/subnet/ \ No newline at end of file diff --git a/docs/introduction/_category_.json b/docs/introduction/_category_.json deleted file mode 100644 index a082441..0000000 --- a/docs/introduction/_category_.json +++ /dev/null @@ -1,11 +0,0 @@ -{ - "label": "Introduction", - "position": 1, - "link": { - "type": "generated-index", - "description": "High-level Overview of XDC Subnet." - } -} - - - diff --git a/docs/introduction/architecture.md b/docs/introduction/architecture.md deleted file mode 100644 index 13a8899..0000000 --- a/docs/introduction/architecture.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -sidebar_position: 2 ---- - -# Architecture - - -The architecture consists of the following four main components owned by the customer: -1. a subnet driven by the XDC2.0 consensus engine, with configurable parameters -2. a relayer program that checkpoints subnet block headers to the XDC mainnet -3. a smart contract in the XDC mainnet that verifies and records the checkpoints and maintain the subnet header chain -4. an API library for the wallet, which enables additional protection of subnet transactions through extra confirmation in the XDC mainnet - -![Docs Version Dropdown](./img/architecture.svg) \ No newline at end of file diff --git a/docs/introduction/img/architecture.svg b/docs/introduction/img/architecture.svg deleted file mode 100644 index db1471a..0000000 --- a/docs/introduction/img/architecture.svg +++ /dev/null @@ -1 +0,0 @@ -XDC MainnetThe SubnetRelayer •Checkpointprivacy-preserving consensus data to the XDC mainnet•Pay XDC transaction feeCheckpointing smart contractThe subnet•Sovereign blockchain ownedbyyou, independent of the XDC mainnet•State-of-the-art XDC2.0 consensus engine with the highest BFT security•Native EVM smart contract support so that you have an ocean of DApps to choose from or build your own•High transaction capacity of 2000+ TPS•Direct access to all the tools developed by the XDC community, such as wallets, explorers, forensics monitors, etcWallet Plus•Submit and confirm subnet transactions normally•Can interact with the XDC mainnet to further finalize subnet transactions, providing extra securityAPIAPI•All green components will be developed & customized by XDC core technical team for you•You will own and operate all of them•XDC core technical team will provide support \ No newline at end of file diff --git a/docs/introduction/intro.md b/docs/introduction/intro.md deleted file mode 100644 index a515fdf..0000000 --- a/docs/introduction/intro.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -sidebar_label: "Motivation & Design Rationale" -sidebar_position: 1 ---- - - -# 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. diff --git a/docs/usage/.DS_Store b/docs/usage/.DS_Store deleted file mode 100644 index f10092a..0000000 Binary files a/docs/usage/.DS_Store and /dev/null differ diff --git a/docs/usage/2_faucet.md b/docs/usage/2_faucet.md deleted file mode 100644 index 4210534..0000000 --- a/docs/usage/2_faucet.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -sidebar_label: "Faucet" -sidebar_position: 2 ---- -# 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 \ No newline at end of file diff --git a/docs/usage/3_explorer.md b/docs/usage/3_explorer.md deleted file mode 100644 index fa83a90..0000000 --- a/docs/usage/3_explorer.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -sidebar_label: "Blockchain Explorer" -sidebar_position: 3 ---- - -# 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/docs/usage/_category_.json b/docs/usage/_category_.json deleted file mode 100644 index 6583c0a..0000000 --- a/docs/usage/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Using the Subnet", - "position": 5, - "link": { - "type": "generated-index", - "description": "The guide to using XDC-Subnet" - } -} \ No newline at end of file diff --git a/docs/usage/img/faucet-server1.png b/docs/usage/img/faucet-server1.png deleted file mode 100644 index bbd74b6..0000000 Binary files a/docs/usage/img/faucet-server1.png and /dev/null differ diff --git a/docs/usage/img/faucet-server2.png b/docs/usage/img/faucet-server2.png deleted file mode 100644 index 723368b..0000000 Binary files a/docs/usage/img/faucet-server2.png and /dev/null differ diff --git a/docs/usage/img/faucet-server3.png b/docs/usage/img/faucet-server3.png deleted file mode 100644 index 2e9f0e2..0000000 Binary files a/docs/usage/img/faucet-server3.png and /dev/null differ diff --git a/docs/usage/img/faucet.png b/docs/usage/img/faucet.png deleted file mode 100644 index 3260e89..0000000 Binary files a/docs/usage/img/faucet.png and /dev/null differ diff --git a/docs/usage/ui/1_homepage.md b/docs/usage/ui/1_homepage.md deleted file mode 100644 index 380aa51..0000000 --- a/docs/usage/ui/1_homepage.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -sidebar_label: "Homepage" -sidebar_position: 1 ---- - - -# 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. \ No newline at end of file diff --git a/docs/usage/ui/2_confirmation_checker.md b/docs/usage/ui/2_confirmation_checker.md deleted file mode 100644 index 4def732..0000000 --- a/docs/usage/ui/2_confirmation_checker.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -sidebar_label: "Confirmation Checker" -sidebar_position: 2 ---- - -# 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. \ No newline at end of file diff --git a/docs/usage/ui/3_management.md b/docs/usage/ui/3_management.md deleted file mode 100644 index f844b09..0000000 --- a/docs/usage/ui/3_management.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -sidebar_label: "Subnet Management" -sidebar_position: 3 ---- - -# 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) diff --git a/docs/usage/ui/_category_.json b/docs/usage/ui/_category_.json deleted file mode 100644 index 25620dc..0000000 --- a/docs/usage/ui/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "UI Usage Guide", - "position": 1, - "link": { - "type": "generated-index", - "description": "The guide for XDC Subnet user interface" - } -} \ No newline at end of file diff --git a/docs/usage/ui/img/account_connect.png b/docs/usage/ui/img/account_connect.png deleted file mode 100644 index c7eb77d..0000000 Binary files a/docs/usage/ui/img/account_connect.png and /dev/null differ diff --git a/docs/usage/ui/img/add_master_node_candidate.png b/docs/usage/ui/img/add_master_node_candidate.png deleted file mode 100644 index 006f869..0000000 Binary files a/docs/usage/ui/img/add_master_node_candidate.png and /dev/null differ diff --git a/docs/usage/ui/img/confirm_1.png b/docs/usage/ui/img/confirm_1.png deleted file mode 100644 index d7242a9..0000000 Binary files a/docs/usage/ui/img/confirm_1.png and /dev/null differ diff --git a/docs/usage/ui/img/confirm_2.png b/docs/usage/ui/img/confirm_2.png deleted file mode 100644 index a1a573b..0000000 Binary files a/docs/usage/ui/img/confirm_2.png and /dev/null differ diff --git a/docs/usage/ui/img/confirm_3.png b/docs/usage/ui/img/confirm_3.png deleted file mode 100644 index 0196c6d..0000000 Binary files a/docs/usage/ui/img/confirm_3.png and /dev/null differ diff --git a/docs/usage/ui/img/connect_wallet.png b/docs/usage/ui/img/connect_wallet.png deleted file mode 100644 index 175f11c..0000000 Binary files a/docs/usage/ui/img/connect_wallet.png and /dev/null differ diff --git a/docs/usage/ui/img/homepage_1.png b/docs/usage/ui/img/homepage_1.png deleted file mode 100644 index d1e886d..0000000 Binary files a/docs/usage/ui/img/homepage_1.png and /dev/null differ diff --git a/docs/usage/ui/img/homepage_2.png b/docs/usage/ui/img/homepage_2.png deleted file mode 100644 index 30b24ad..0000000 Binary files a/docs/usage/ui/img/homepage_2.png and /dev/null differ diff --git a/docs/usage/ui/img/import_account.png b/docs/usage/ui/img/import_account.png deleted file mode 100644 index 3803d4a..0000000 Binary files a/docs/usage/ui/img/import_account.png and /dev/null differ diff --git a/docs/usage/ui/img/promote_node_delegate.png b/docs/usage/ui/img/promote_node_delegate.png deleted file mode 100644 index a555300..0000000 Binary files a/docs/usage/ui/img/promote_node_delegate.png and /dev/null differ diff --git a/docs/usage/ui/img/remove_master_node.png b/docs/usage/ui/img/remove_master_node.png deleted file mode 100644 index 5e8879f..0000000 Binary files a/docs/usage/ui/img/remove_master_node.png and /dev/null differ diff --git a/docs/usage/ui/img/successful_connection_confirmation.png b/docs/usage/ui/img/successful_connection_confirmation.png deleted file mode 100644 index e71e1e8..0000000 Binary files a/docs/usage/ui/img/successful_connection_confirmation.png and /dev/null differ diff --git a/docs/usage/ui/img/switch_subnet.png b/docs/usage/ui/img/switch_subnet.png deleted file mode 100644 index 9545328..0000000 Binary files a/docs/usage/ui/img/switch_subnet.png and /dev/null differ