xdczero and subswap (#33)

xdczero and subswap

docs/components/subswap/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Subswap",
+  "position": 6,
+  "link": {
+    "type": "generated-index",
+    "description": "default"
+  }
+}

docs/components/subswap/design.md

@@ -0,0 +1,53 @@
+---
+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)

docs/components/subswap/spec.md

@@ -0,0 +1,136 @@
+---
+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.
+

docs/components/xdczero/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "XDCZero",
+  "position": 5,
+  "link": {
+    "type": "generated-index",
+    "description": "default"
+  }
+}

docs/components/xdczero/design.md

@@ -0,0 +1,43 @@
+---
+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)
+

docs/components/xdczero/spec.md

@@ -0,0 +1,126 @@
+---
+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.