From 83cc6bdc5a442767b4b291fefaba4e4652482ae1 Mon Sep 17 00:00:00 2001 From: Aki Wu Date: Wed, 24 Jan 2024 18:20:14 +0800 Subject: [PATCH 1/7] liquidity node v2 polish --- docs/helixbridge/liquidity_node_v2.md | 267 +++++++++++++++++--------- 1 file changed, 177 insertions(+), 90 deletions(-) diff --git a/docs/helixbridge/liquidity_node_v2.md b/docs/helixbridge/liquidity_node_v2.md index d31ea88..69437a3 100644 --- a/docs/helixbridge/liquidity_node_v2.md +++ b/docs/helixbridge/liquidity_node_v2.md @@ -6,162 +6,249 @@ order: 2 title: Liquidity Node(V2) --- -## Overview -The protocol described here is used when tokens are issued on both the source chain and the target chain, and their exchange values are equal. -It establishes a liquidity provider role called "LnProvider" (Liquidity Node Provider). When a user performs a cross-chain transfer, they transfer tokens to the LnProvider account on the source chain, and the LnProvider transfers an equivalent amount of tokens to the user on the target chain. +# Protocol Overview -During this process, the asset token undergoes the following transfer 👇 +**This protocol can only be used when tokens are natively issued on both the source chain and the target chains, and their exchange values are equal.** -- Source Chain: User → LnProvider -- Target Chain: LnProvider → User +## LnProvider -The user incurs a certain fee for executing the cross-chain transfer, and the LnProvider earns a fee for providing liquidity. This process bypasses the need for underlying bridge messages to complete the asset cross-chain transfer if the LnProvider executes according to the agreement. +This protocol establishes a liquidity provider role called the LnProvider (Liquidity Node Provider). When a user transfers tokens between two chains, the LnProvider receives tokens on one chain and transfers an equivalent amount of tokens to the user on the other chain. -According to the protocol, when a market-making role (LnProvider) registers, it must stake a certain amount of collateral as a guarantee to ensure the safety of user assets during the cross-chain process. When a user initiates a cross-chain transfer, the asset is transferred to the LnProvider account, and an equivalent amount of collateral is locked. Once the cross-chain is successful, the user receives the asset on the target chain, and the collateral is released. The locking of collateral occurs on the source chain, while the release happens on the target chain, and both processes produce proofs on their respective chains. Under normal circumstances, bridge messages are not necessary to relate these processes. However, bridge messages are still needed to monitor the execution process. +During the cross-chain transfer process, the asset token goes through the following flow 👇: Snipaste_2024-01-24_17-15-36 -If, for instance, a user initiates a transfer, generating a transfer proof (or collateral lock proof), but the LnProvider fails to transfer tokens to the user on the target chain to complete the cross-chain process, there are two compensation methods: +1. **Source Chain: User → LnProvider** -- Bridge message channel is from the target chain to the source chain, and the collateral is on the source chain: -
The user sends the proof that the LnProvider did not transfer the tokens on the target chain through the bridge message to the source chain. The source chain combines this proof with the transfer proof and extracts collateral from the LnProvider to compensate the user. + On the source chain, the user sends tokens to the LnProvider’s source chain account. -- Bridge message channel is from the source chain to the target chain (preferably): -
The user sends the transfer proof through the bridge message to the target chain. On the target chain, the proof is combined with the evidence that the LnProvider did not transfer the tokens, and the LnProvider's collateral is extracted to compensate the user. +2. **Target Chain: LnProvider → User** -Either of the above methods is used to ensure the security of the user's assets during the process. The choice between them depends on the direction of the bridge message. For regular users, dealing with such exceptional situations may increase complexity and reduce user experience. To address this, another role called "slasher" is introduced to help users complete the above process. + On the target chain, the LnProvider sends an equivalent amount of tokens to the user. -The slasher role monitors the LnProvider's status and, if the LnProvider fails to work, helps the user handle the exception and eventually extracts the collateral and penalty from the LnProvider using the message channel. +The user pays a fee for using the cross-chain transfer service, and the LnProvider earns a fee for providing liquidity. So, a LnProvider is a market-maker of Helix Token Protocol. -This article also provides explanations for various terms and their meanings, as well as details about the message channel processes for both directions (source chain to target chain and target chain to source chain). It also describes the security assumptions and sequencing requirements for the execution of cross-chain transactions. +**When LnProvider acts according to the protocol, there is no need for the underlying cross-chain messaging channel, which simplifies the process of asset cross-chain transfer and reduce the cost.** -## Key terms +## LnProvider’s Collateral -- **LnProvider (Liquidity Node Provider)** -
The entity consists of an account that exists simultaneously on both the source chain and the target chain, along with a client program. On the source chain, this account is used to receive assets from users initiating cross-chain transfers. On the target chain, the same account is responsible for paying out assets to users who have completed cross-chain transfers. Additionally, the account is registered with the asset bridge and pledges a certain amount of collateral. The client program monitors user transfer events and automatically transfers tokens from the account on the target chain to the user's account, completing the cross-chain process. -- **Slasher** -
The role is responsible for monitoring LnProviders and, in case an LnProvider fails to function properly, helping users complete transactions under exceptional circumstances. Eventually, the role utilizes the message channel to extract the LnProvider's pledged collateral and penalties. -- **Pledged Collateral** -
The LnProvider pledges collateral to the protocol, and this collateral remains constant regardless of user transfers. The pledged collateral only changes in two situations: when the slasher handles exceptions or when the LnProvider adds or withdraws collateral. -- **Available Collateral** -
The available collateral is equal to the pledged collateral minus the collateral occupied by pending transactions. This part of the collateral changes as the status of user cross-chain transactions changes. When a user initiates a transaction, a certain amount of collateral is reserved, reducing the available collateral. Once the transaction is confirmed by LnProvider, the available collateral increases. +According to the protocol, when a LnProvider registers, it must stake collateral to ensure the safety of user assets during the cross-chain process. + +1. When a user initiates a cross-chain transfer, the user's assets are transferred to the LnProvider's account. At the same time, an equivalent amount of the LnProvider's collateral is locked. This ensures that the user's assets are protected. +2. When the cross-chain transfer is successful, the user receives the asset on the target chain, and the LnProvider's locked collateral is released on the source chain. + +In normal circumstances, these two processes do not need to work with the messaging channel, but bridge messages are still used to track the execution process. + +> 💡The locking of collateral occurs on the source chain, while the user’s assets receiving happens on the target chain. Both the two processes are auditable and have proofs on their respective chains. + +Snipaste_2024-01-24_17-58-53 + +### Pledged Collateral + +Pledged Collateral is the LnProvider's fixed total collateral and does not fluctuate when user do cross-chain transfers. + +The only way the pledged collateral changes is: + +- when the slasher handles exceptions, or, +- when the LnProvider deposits or withdraws collateral from it. This ensures that the collateral is always sufficient to cover any potential losses or penalties. + +### Available Collateral + +The available collateral is equal to the pledged collateral minus the collateral locked for pending transactions. The available collateral fluctuates as the status of user cross-chain transactions changes. + +When a user initiates a transaction, a certain amount of collateral is locked, reducing the available collateral. Once the transaction is confirmed by LnProvider, the available collateral increases. + +## LnProvider Failure + +LnProvider may fail, but even if it fails, the user's assets are safe. + +If a user initiates a transfer, but the LnProvider fails to transfer tokens to the user on the target chain. + +There are two situations: + +- If the LnProvider fails to transfer tokens to the user, and [the collateral is on the target chain(Default Type)](https://www.notion.so/Helix-Token-Protocol-c12817f371404edc8c381eefd55e7917?pvs=21). + + The user can submit the transfer proof to the target chain through the messaging channel. The target chain combines the proof with evidence that the LnProvider failed to transfer the tokens, and extracts collateral from the LnProvider to compensate the user. + + > 💡This should be the situation users prefer. + +- If the LnProvider fails to transfer tokens to the user, and **[the collateral is on the source chain](https://www.notion.so/Helix-Token-Protocol-c12817f371404edc8c381eefd55e7917?pvs=21)**. + + The user can use the messaging channel to send proof of the failed transfer to the source chain. The source chain can then combine this proof with the original transfer proof to verify the LnProvider's failure. Once the source chain has verified the LnProvider's failure, it can extract collateral from the LnProvider to compensate the user. + +Either of the above methods is used to ensure the security of the user's assets during the process. The choice between them depends on the direction of the bridge message. + +# Key Terms Explaination + +## LnProvider(Liquidity Node Provider) + +A LnProvider has two components: an account and a client program. + +* **LnProvider Account** + + The account exists on both the source chain and the target chain. On the source chain, the account receives assets from users who initiate cross-chain transfers. On the target chain, the account distributes those assets to users who have successfully completed a cross-chain transfer. The account is registered to the asset bridge and has a collateral. + +* **LnProvider Client Program** + + The client program, which is associated with the account, monitors user transfer events and automatically transfers tokens from the account on the target chain to the user's account, completing the cross-chain process. + +## Slasher + +This compensation mechanism ensures the security of users' assets during the process, although they add some complexity for regular users. To address this issue, a separate role called a "slasher" is introduced. + +Slasher is responsible for monitoring the behavior of LnProviders and, in the event of an LnProvider failure, helping users complete transactions through alternative means. When necessary, slasher utilizes the messaging channel to extract the LnProvider's collateral and impose penalties. This ensures that the user's transaction will eventually be completed, even in exceptional circumstances. The slasher helps users complete the process without having to understand the underlying details. This improves the user experience and makes it easier for regular users to take advantage of cross-chain transfers. ## TransferId -- **Definition** - :::info{title=TransferId} - TransferId = Hash(params，lastTransferId) - ::: - The lastTransferId of the first transaction is 0, and for the k-th transaction, the lastTransferId is the transferId of the (k-1)th transaction. - "params" refers to the specific parameters of the cross-chain transfer, including token address, quantity, LnProvider, receiver, etc. + +$$ +TransferId = Hash(params，lastTransferId) +$$ +Where: + +* **params**: + + The params refers to the specific parameters of the cross-chain transfer, including token address, quantity, LnProvider, receiver, etc. + +* **lastTransferId**: + + The lastTransferId of the first transaction is 0. For the k-th transaction, the lastTransferId is the transferId of the (k-1)th transaction. + +### Purpose + +The purpose of this TransferId mechanism are for: + - **Uniqueness** -
The storage will keep the latest TransferId and mark it as lastTransferId. After each transaction is completed, the lastTransferId cursor is updated to the most recent TransferId. This Id will be used as a hash parameter for calculating the TransferId of the next transaction, ensuring that each transaction's TransferId is unique and different from others. + + The system maintains a 'lastTransferId' value, which is updated after each transaction is completed. This current lastTransferId value is used to generate the TransferId for the next transaction, ensuring that no two transactions share the same TransferId. This mechanism prevents data duplication and ensures the integrity of the system. + - **Ordering** -
In each transaction, the Hash parameter includes the TransferId of the previous transaction, ensuring the sequencing of transactions. -## Type1 (Opposite) + In each transaction, the Hash parameter includes the TransferId of the previous transaction, ensuring the sequencing of transactions. -The generical message is also from target chain to source chain. For this scenario we implement the following asset bridge cross-chain protocol. + + +## Type 1(Opposite) - Collateral on Source Chain + +This type need a messaging channel **from Target Chain** to **Source Chain**. + +For this type we implement the following asset bridge cross-chain protocol. ### Safety Assumptions -1. There exists a secure and reliable general-purpose message channel for communication from the target chain to the source chain. This assumption ensures that messages can be reliably transmitted from the target chain to the source chain, and the integrity and confidentiality of the messages are maintained. +1. There should be a secure and reliable general-purpose messaging channel for communication from the source chain to the target chain. This channel must maintain the integrity and confidentiality of messages sent from source chain to target chain. +2. The source chain and the target chain use the same time(the same world clock), allowing for consistent timestamping and handling of time-sensitive events across both chains. -2. The source chain and the target chain's blocks use the same world clock or time synchronization mechanism. This assumption allows for consistent timestamping and handling of time-sensitive events across both chains. +### Interaction Flow - LnProvider Registration -### Interaction Process +LnProvider registration is the process by which a LnProvider becomes part of the cross-chain asset transfer protocol. This process involves a few key steps, during which the LnProvider provides information about itself and commits to certain obligations. Once registered, the LnProvider is responsible for facilitating cross-chain transfers and adhering to the protocol's rules. -- **LnProvider Registration** -
LnProvider registration refers to the process in which a Liquidity Node Provider (LnProvider) registers in the cross-chain asset transfer protocol. During this process, the LnProvider becomes a part of the protocol and assumes a role in facilitating cross-chain transfers. The main steps of LnProvider registration are as follows: +1. Decide the tokens to support -1. Selection of Supported Tokens: The LnProvider needs to choose the tokens supported by the protocol for cross-chain transfers. These tokens should exist in the accounts on both the source and target chains. -2. Pledge of Collateral: The LnProvider needs to register with the asset bridge and pledge a certain amount of tokens in the accounts on the source and target chains as collateral. The collateral serves to ensure the security of user assets during cross-chain transfers and serves as evidence of the LnProvider's commitment to participating in cross-chain transfers. -3. Setting Transaction Fees: The LnProvider needs to set the transaction fees charged during cross-chain transfers. These fees can be used to compensate for the gas fees paid by the LnProvider on the target chain and cover the cost of providing the service. -4. Registration as LnProvider: The LnProvider completes the registration process by calling the interface on the source chain, submitting the pledged collateral, and setting the transaction fees. After successful registration, the LnProvider becomes a part of the protocol and can offer cross-chain asset transfer services. -5. Running Client Program: After registration, the LnProvider runs a client program, which is used to monitor user's cross-chain transfer requests and automatically execute the transfer transactions. + The LnProvider must select which tokens it will support for cross-chain transfers. These tokens must exist on both the source and target chains, so that transfers can be facilitated. -Through the steps mentioned above, the LnProvider completes the registration process in the cross-chain asset transfer protocol, becoming a liquidity provider eligible to participate in asset transfers, and offering cross-chain transfer services to users. Additionally, the collateral pledged by the LnProvider ensures the security of user assets. +2. Decide the pledging collateral -- **Transfer** + In order to participate in the cross-chain asset transfer protocol, the LnProvider must pledge a certain amount of tokens as collateral on source chain. -1. Users select the token they want to transfer cross-chain, specify the quantity, and designate the LnProvider (the LnProvider can be chosen by a third party on behalf of the user). +3. Decide on the fees to charge -2. They fetch the current latest state from the blockchain, based on which they take a snapshot of the state (snapshot). They then check the available collateral amount of the LnProvider. If the collateral is insufficient, the cross-chain transfer operation will not be executed. + The LnProvider must determine the fee charged for cross-chain transfer. The fee are intended to cover the cost of the LnProvider's activities on the target chain, including **1. gas fee**, as well as **2. LnProvider’s profit**. -3. If there is sufficient collateral, they proceed to call the on-chain interface for executing the transfer, while carrying the snapshot parameters. +4. Completing registration by sending a transaction **on source chain** -4. The blockchain verifies the snapshot. If the on-chain state has expired, the transfer fails. Otherwise, the user's assets will be transferred to the LnProvider, and a transfer proof will be generated. + The LnProvider completes the registration process by calling an interface on the source chain, submitting collateral, and setting the fees. -5. The LnProvider monitors the event, and on the target chain, transfers the tokens to the user's account, generates a transfer proof, and completes the transaction. + Once registration is complete, the LnProvider will be recognized by the protocol and can begin offering cross-chain transfer services. -:::warning{title="Exception Monitoring"} -In step 5 of the cross-chain asset transfer process, a timeout period is set, and the LnProvider is required to complete the transfer within this time limit. If the LnProvider fails to do so, the slasher can take the following actions: +5. Running the client program -1. On the target chain, the `Slasher` will transfer tokens from its own account to the user's account to cover the transaction (this is known as "slash and cover"), and generate a transfer proof. + After registration, the LnProvider needs to run a client program that constantly monitors the network for cross-chain transfer requests. When a request is received, the program automatically executes a transaction to complete the transfer. -2. The `Slasher` will then send this transfer proof to the source chain through the underlying bridge messaging system. Upon receiving the message, the source chain will verify the transaction. If the verification is successful, the source chain will extract the `LnProvider's` collateral to compensate the slasher for covering the assets and to impose a penalty on the `LnProvider`. +The registration process described above allows the LnProvider to become a liquidity provider and participate in the cross-chain asset transfer protocol. -3. The determination of whether the transfer is within the timeout period is based on comparing the time when the user sends the transaction (the timestamp of the block on the source chain where the transaction is included) with the current time on the target chain. The synchronization of clocks between the two chains is ensured by the safety assumptions, allowing the timeout time to be effective within a certain error range. +### Interaction Flow - Transfer -4. This mechanism ensures that the `LnProvider` fulfills its responsibility to complete the transfer within the specified time, and in the event of a failure, the slasher steps in to cover the assets and initiate penalties, thus maintaining the security and reliability of the cross-chain asset transfer protocol. - ::: +1. To initiate a cross-chain transfer, a user first selects the token they wish to transfer, specify the amount, and choose an LnProvider to facilitate the transfer. -### Ordering + > 💡An intermediary party can assist the user in selecting an appropriate LnProvider, if necessary. -- Any cross-chain transaction on the target chain must either be successfully executed or be subject to a "slash" operation. +2. The user retrieves the latest state from the blockchain and takes a snapshot of the state. Then, the user check the available collateral amount of the LnProvider to ensure it is sufficient. If not, the cross-chain transfer cannot proceed. -- Before the timeout period expires, the "slash" operation cannot be executed. + > 💡In actual products, this step will be completed by the front-end code of users. -- For any cross-chain transaction executed on the target chain, it must be completed after the execution of the preceding transaction. +3. If the collateral is sufficient, the user then calls the on-chain api with the snapshot, initiating the transfer. -- When validating a "slash" transaction on the source chain, it must be ensured that all preceding transactions have not been subjected to a "slash" operation, or if any "slash" operations were applied, they have all been executed and completed. +4. The blockchain verifies that the snapshot is valid. If the on-chain state has changed since the snapshot was taken, the transfer fails. Otherwise, the user's assets are transferred to the LnProvider’s account on source chain, and a transfer proof is generated. + +5. The LnProvider monitors the event confirming the transfer **on the source chain**. Upon confirmation, LnProvider transfer the tokens to the user's account **on the target chain** and generate a proof of this transaction. + + In this step, **a timeout period is set**, and the LnProvider is required to complete the transfer within this time limit. If the LnProvider fails to do so, the slasher can do slashing operation. + +### Interaction Flow - Slashing -The above content describes how to ensure the execution order in the cross-chain asset transfer protocol, ensuring that before any transaction is completed, all preceding transaction transactions have been completed. This sequencing mechanism effectively prevents malicious withdrawal of the collateral occupied by previous transactions, ensuring that when users send cross-chain transfer transactions, they only need to be concerned about whether LnProvider has sufficient available collateral before the transaction is completed. +1. On the target chain, the `Slasher` will transfer tokens from its own account to the user's account to cover the transaction (this is known as "slash and cover"), and generate a transfer proof. +2. The `Slasher` will then send this transfer proof to the source chain through the underlying bridge messaging system. Upon receiving the message, the source chain will verify the transaction. If the verification is successful, the source chain will extract the `LnProvider's` collateral to compensate the slasher for covering the assets and to impose a penalty on the `LnProvider`. +3. The determination of whether the transfer is within the timeout period is based on comparing the time when the user sends the transaction (the timestamp of the block on the source chain where the transaction is included) with the current time on the target chain. The synchronization of clocks between the two chains is ensured by the safety assumptions, allowing the timeout time to be effective within a certain error range. +4. This mechanism ensures that the `LnProvider` fulfills its responsibility to complete the transfer within the specified time, and in the event of a failure, the slasher steps in to cover the assets and initiate penalties, thus maintaining the security and reliability of the cross-chain asset transfer protocol. -The specific implementation of maintaining the sequence is as follows: +### Ordering Mechanism -1. Set SId(1) to a certain initial value, indicating that there were no slash transactions before the first transaction. +- Every cross-chain transaction on the target chain must be executed or be subject to a 'slash' operation. +- 'Slash' operations cannot be executed before the timeout period has expired. +- For every cross-chain transaction on the target chain, it must follow a preceding transaction that was executed. +- When validating a "slash" transaction on the source chain, it must be ensured that all preceding transactions have not been subjected to a "slash" operation, or if any "slash" operations were applied, they have all been executed and completed. -2. For each transaction (the k-th transaction) on the target chain, check if the previous transaction (the (k-1)-th transaction) has been sent and further determine whether it has been slashed. Based on the status of the previous transaction, determine the closest slash transaction Id (SId(k)) before the k-th transaction. +The above content describes how to ensure the execution order in the cross-chain asset transfer protocol, ensuring that before any transaction is completed, all preceding transactions have been completed.This sequencing mechanism effectively prevents malicious withdrawals of collateral, ensuring that users only need to consider the available collateral when sending a cross-chain transfer. -3. If the previous transaction is a slash transaction, meaning that the (k-1)-th transaction has been subject to a slash operation, then SId(k) = Id(k-1), which means that SId(k) for the k-th transaction is set to the Id(k-1) of the (k-1)-th transaction. +With this mechanism, users can be confident that their transactions will be processed reliably. -4. If the previous transaction is not a slash transaction, meaning that the (k-1)-th transaction was normally executed by LnProvider, then SId(k) = SId(k-1), which means that SId(k) for the k-th transaction is set to the SId(k-1) of the (k-1)-th transaction. +> 💡 The specific implementation of maintaining the sequence is as follows: +> +> 1. Set SId(1) to a certain initial value, indicating that there were no slash transactions before the first transaction. +> 2. For each transaction (the k-th transaction) on the target chain, check if the previous transaction (the (k-1)-th transaction) has been sent and further determine whether it has been slashed. Based on the status of the previous transaction, determine the closest slash transaction Id (SId(k)) before the k-th transaction. +> 3. If the previous transaction is a slash transaction, meaning that the (k-1)-th transaction has been subject to a slash operation, then SId(k) = Id(k-1), which means that SId(k) for the k-th transaction is set to the Id(k-1) of the (k-1)-th transaction. +> 4. If the previous transaction is not a slash transaction, meaning that the (k-1)-th transaction was normally executed by LnProvider, then SId(k) = SId(k-1), which means that SId(k) for the k-th transaction is set to the SId(k-1) of the (k-1)-th transaction. By following this approach, when sending the slash transaction Id(k) from the target chain to the source chain, the information of SId(k) is included. The source chain, when validating the slash transaction, verifies whether SId(k) has been completed, ensuring that the execution process of the k-th transaction is correctly ordered. This sequencing mechanism effectively prevents transactions from being maliciously tampered with or prematurely executed, ensuring the security and reliability of the transactions. -## Type2 (Default) -The generical message is also from source chain to target chain. For this scenario we implement the following asset bridge cross-chain protocol. -### Safety Assumptions +## Type 2(Default) - Collateral on Target Chain + +**This type need a messaging channel from Source Chain** to **Target Chain.** + +For this type we implement the following asset bridge cross-chain protocol. -1. There exists a secure and reliable general-purpose message channel for communication from the source chain to the target chain. This assumption ensures that messages can be reliably transmitted from source chain to target chain, and the integrity and confidentiality of the messages are maintained. +### Safety Assumptions -2. The source chain and the target chain's blocks use the same world clock or time synchronization mechanism. This assumption allows for consistent timestamping and handling of time-sensitive events across both chains. +1. A secure and reliable message channel connects the source chain to the target chain. This channel ensures that messages can be reliably sent from the source chain to the target chain, and the integrity and confidentiality of the messages are maintained. +2. The source chain and the target chain use the same time(the same world clock), allowing for consistent timestamping and handling of time-sensitive events across both chains. -### Interaction Process +### Differences from Type1 The basic interaction process is similar to the message channel from the target chain to the source chain, with the following differences: - LnProvider's collateral is pledged on the target chain. -- When the slasher executes a slash operation, it initiates a transaction from the source chain to the target chain and does not need to advance tokens to the user. -- If the provider delivers after the timeout, a portion of its collateral will be deducted as a penalty, which will be used to compensate the slasher for the cross-chain fees incurred during the slash operation. -- When the slash message arrives at the target chain, it checks whether the transaction needs to be slashed in the following scenarios: -:::info{title="Slash Scenarios"} +- Slashing + + When the slasher executes a slash operation, it sends a transaction to the target chain that does not require to cover the user any tokens. + + If the provider delivers after the timeout period, a portion of its collateral will be deducted as a penalty. This penalty compensates the slasher for the fees incurred during the slash operation. + + When the slashing request arrives at the target chain, it checks whether the transaction needs to be slashed in the following scenarios: -1. If the cross-chain transaction is not timed out, the slash operation is invalid and not executed. -2. If the cross-chain transaction is timed out and has already been slashed, the slash operation is invalid and not executed. -3. If the cross-chain transaction is timed out and has not been delivered, the slash operation is valid. The slasher receives fees and penalty assets, while the user receives transferred assets. -4. If the cross-chain transaction is timed out and LnProvider delivered before the timeout, the slash operation is invalid and not executed. -5. If the cross-chain transaction is timed out and LnProvider delivered after the timeout, the slash operation is partially valid. The slasher can receive a portion of the penalty assets to compensate for gas and bridge fees incurred by the user. - ::: + 1. If the cross-chain transaction is not past the timeout period, the slashing request is considered invalid and will not be executed. + 2. If the cross-chain transaction is already past the timeout period and the LnProvider has been slashed, then the slashing request is considered invalid and will not be executed. + 3. If the cross-chain transaction is past the timeout period and has not yet been delivered, the slashing request will be executed. The user will receive the transferred assets, and the slasher will receives fees and the penalty assets. + 4. If the cross-chain transaction is past the timeout period, but the provider delivered the transaction within the allowed time, then the slash operation is not permitted and will not be executed. + 5. If the cross-chain transaction is past the timeout period and the LnProvider delivered after the timeout, the slash operation is only partially valid. The slasher can receive some of the penalty assets, but not the full amount, to compensate for the gas and bridge fees incurred by the user. -### Ordering +- Ordering -The requirement is that any transaction on the target chain must have its preceding transaction completed before the transaction itself is finalized. Transaction completion can be achieved through LnProvider's normal delivery or the slasher's slash operation. + The ordering requirement states that any transaction on the target chain must have its preceding transaction completed before the current transaction can be finalized. This can be accomplished in two ways: by the LnProvider completing the transaction as normal, or by the slasher executing a slash operation. -This requirement ensures that before a transaction undergoes a slash operation, its observed snapshot of collateral cannot be maliciously extracted by subsequent transactions. + That is, before a transaction is slashed, it's important to make sure that any collateral associated with that transaction cannot be extracted by its subsequent transactions. -Additionally, we demand that LnProvider includes the state of the extraction into the snapshot when withdrawing collateral. At the time of extraction, all transactions prior to that state must have been executed, ensuring that the available collateral does not decrease during the period from the initiation of the cross-chain transaction to its execution on the target chain. + Additionally, we demand that LnProvider includes the state of the extraction into the snapshot when withdrawing collateral. At the time of extraction, all transactions prior to that state must have been completed, ensuring that the available collateral does not decrease during the period from the initiation of the cross-chain transaction to its execution on the target chain. From c844d292577095f2039469c37fe2ee4e6b274de4 Mon Sep 17 00:00:00 2001 From: Aki Wu Date: Wed, 24 Jan 2024 19:27:55 +0800 Subject: [PATCH 2/7] fix math expression --- docs/helixbridge/liquidity_node_v2.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/helixbridge/liquidity_node_v2.md b/docs/helixbridge/liquidity_node_v2.md index 69437a3..f7b6f4d 100644 --- a/docs/helixbridge/liquidity_node_v2.md +++ b/docs/helixbridge/liquidity_node_v2.md @@ -101,9 +101,7 @@ Slasher is responsible for monitoring the behavior of LnProviders and, in the ev ## TransferId -$$ -TransferId = Hash(params，lastTransferId) -$$ +$TransferId = Hash(params，lastTransferId)$ Where: * **params**: From e51a10c3ca452ecad602c8c9b3884e0c4933ee81 Mon Sep 17 00:00:00 2001 From: Aki Wu Date: Fri, 26 Jan 2024 13:49:00 +0800 Subject: [PATCH 3/7] feat: revise v3 --- docs/helixbridge/liquidity_node_v3.md | 52 +++++++++++++++------------ 1 file changed, 30 insertions(+), 22 deletions(-) diff --git a/docs/helixbridge/liquidity_node_v3.md b/docs/helixbridge/liquidity_node_v3.md index 91ae4d1..f5b2ba8 100644 --- a/docs/helixbridge/liquidity_node_v3.md +++ b/docs/helixbridge/liquidity_node_v3.md @@ -8,39 +8,47 @@ title: Liquidity Node(V3) ## Overview -In the v2 version of the Liquidity Node protocol, we introduced a collateral mechanism to safeguard user assets and effectively reduce the number of cross-chain message invocations, thereby lowering cross-chain fees. In this protocol, the collateral staked by the LnProvider determines the transfer limit for a single transaction in that direction. Therefore, to achieve better trading depth, LnProviders need to stake more collateral. However, as collateral cannot be shared across different directions, this results in increased collateral costs. Hence, the v2 protocol version is suitable for frequent small-value transactions. +In the v2 version of the Liquidity Node Protocol, we have implemented a collateral mechanism to protect user assets. In this v2 protocol, the amount of collateral staked by the LnProvider determines the transfer limit for a single transaction in that direction. To enhance trading depth, LnProviders must stake more collateral. However, since collateral cannot be shared across different directions, this leads to increased collateral costs. Consequently, the v2 protocol is more suitable for frequent, small-value transactions. -To address this, we introduce a new protocol version, v3, which eliminates the need for collateral staking. When registering, LnProviders only need to stake a small amount of penalty reserve, ensuring the completion of message delivery by the LnProvider and imposing penalties when expectations are not met. +To address this issue, we are introducing a new protocol version, v3, which eliminates the requirement for collateral staking. When registering, LnProviders will only need to stake a modest penalty reserve amount. This reserve ensures the timely completion of message delivery by the LnProvider and imposes penalties if expectations are not met. ## Security Assumptions -1. We assume the existence of a secure and reliable general-purpose message channel for communication from the target chain to the source chain. This assumption guarantees the reliable transmission of messages from the target chain to the source chain, maintaining the integrity and confidentiality of the messages. -2. The source chain and the target chain's blocks utilize the same world clock or time synchronization mechanism. This assumption enables consistent timestamping and handling of time-sensitive events across both chains. +1. We make the assumption that there exists a secure and reliable general-purpose messaging channel for communication from the target chain to the source chain. This assumption ensures the reliable transmission of messages from the target chain to the source chain. +2. We assume that both the source chain and the target chain's blocks are synchronized with the same world clock. This assumption allows for consistent timestamping and the handling of time-sensitive events across both chains. -## Interaction +## Interactions ### LnProvider Registration -LnProvider stores its configuration information in the source chain and stakes a certain amount of penalty collateral, which can be shared in different path. +The LnProvider stores its configuration information on the source chain and stakes a specific amount of penalty reserve, which can be shared across different paths. -- Choose the supported source chain, target chain, and transfer token; register LnProvider; set transaction fees and transfer limits. -- Deposit penalty collateral on source chain. -- Run the relayer client. +1. Select the supported source chain, target chain, and token. Register the LnProvider and configure transaction fees and transfer limits accordingly. -### Cross-Chain Tranfer +2. Deposit the penalty reserve on the source chain. -- Users select the direction for token cross-chain and specify LnProvider to initiate cross-chain transactions in the source chain. -- Users lock tokens, fees, and a single LnProvider penalty collateral in the source chain. -- LnProvider monitors the transfer event, completes the transaction on the target chain, transfers tokens to the user's specified account, and generates a transfer proof. -- If the third step is not completed, until a timeout, the Slasher on the target chain transfers tokens to the user and sends a reverse message to the source chain, extracting the locked assets from the second step. +3. Run the relayer client. -:::info{title=Slasher} -Slasher does not need to register; any account, including the user themselves, is considered a Slasher as long as it completes the fourth step. -Slasher plays a crucial role throughout the entire cross-chain transaction cycle and assists in concluding transactions when LnProvider is not functioning. -::: +### Cross-Chain Tranfer by Users -### Liquidity Withdraw +1. A user choose the direction for cross-chain token transfer and specify the LnProvider to initiate the transaction on the source chain. -Upon normal transaction completion, liquidity for each transaction is locked in the source chain. -LnProvider needs to send a generic message from the target chain to the source chain to extract liquidity. -LnProvider can choose to extract liquidity from multiple transactions simultaneously to significantly reduce cross-chain message costs. However, accumulating too many transactions may result in high gas fees upon execution and excessive message accumulation, occupying liquidity costs. Therefore, LnProvider needs to appropriately choose the number of transactions to batch extract liquidity. +2. The user lock tokens, fees, and a single LnProvider penalty collateral on the source chain. + +3. The user waits to see the tokens arrive in his/her account on the target chain. + + Once the LnProvider sees the transfer event, it transfers the tokens to the user-specified account on the target chain and generates a transfer proof at the same time. + + If the LnProvider did not complete the transfer within a specified timeout, the Slasher on the target chain transfers tokens to the user and sends a reverse message to the source chain, extracting the locked assets as per the second step. + +> A Slasher does not need to register. Any account including the user themselves is considered a Slasher as long as it completes the this. +> +> Slashers play a crucial role throughout the entire cross-chain transaction cycle and assists in finalizing transactions when LnProvider is not functioning. + +### Liquidity Withdrawal by LnProvider + +After a regular transaction is successfully completed, the liquidity for each transaction remains locked within the source chain. + +To withdraw this liquidity, LnProvider must send a cross-chain message from the target chain to the source chain. LnProvider has the option to withdraw liquidity from multiple transactions simultaneously, which can notably reduce cross-chain messaging gas fees. + +> However, accumulating too many transactions may lead to the liquidity over-occupation, thereby weakening the LnProvider's liquidity capabilities. Therefore, LnProvider must carefully determine the number of transactions to batch withdraw liquidity from. From 5e42b5e8f06521cd64ae77216694c7f286c96dda Mon Sep 17 00:00:00 2001 From: Aki Wu Date: Fri, 26 Jan 2024 15:04:11 +0800 Subject: [PATCH 4/7] feat: fee --- docs/helixbridge/fee.md | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/docs/helixbridge/fee.md b/docs/helixbridge/fee.md index 60ca14e..25042bc 100644 --- a/docs/helixbridge/fee.md +++ b/docs/helixbridge/fee.md @@ -5,23 +5,28 @@ group: order: 2 --- -## Fee for CBA model +# Fee -Under this model, Helix relies on generic messaging to deliver cross-chain information, with the cost of the underlying messaging accounting for most of the transfer costs. Currently, Helix does not charge protocol fees, so for this type of token bridge, the fees that the user needs to pay are limited to the cost of executing the message channel, which is usually paid by native tokens. +## Fee for CBA Model + +Under the CBA model, Helix relies on generic cross-chain messaging channel to transmit cross-chain information, with the cost of the underlying messaging being the primary factor contributing to the transfer expenses. Currently, Helix Bridge does not charge protocol fees. Therefore, in this type of token bridge, the fees incurred by users are limited to the cost associated with executing the messaging channel, typically paid using native tokens. ## Fee for LnBridge -The fee consists of two parts, a base fee to cover the LnProvider's gas fee for executing transactions on the target chain and a liquidity fee to compensate the LnProvider for the loss of liquidity. +For LnBridge, the fee structure consists of two components: a base fee to cover the gas fees incurred by the LnProvider when executing transactions on the target chain and a liquidity fee designed to compensate the LnProvider for the loss of liquidity. + +1. Base Fee + + The base fee is determined and set by the LnProvider, remaining a fixed value until the LnProvider updates it. Users are required to pay this fee to the LnProvider at the time they initiate the transfer. + +2. Liquidity Fee -- Base Fee -
It is configured by LnProvider, and the fee is a fixed value until the LnPriver is updated. This fee needs to be paid to the LnProvider at the moment the user initiates the transfer. -- Liquidity Fee -
Also configured by LnProvider, and this fee is related to the amount of transfer made by the user, and the higher the amount of transfer, the higher the fee charged. + Similar to the base fee, the liquidity fee is also determined by the LnProvider. However, this fee is directly related to the amount of the transfer initiated by the user. As the transfer amount increases, the corresponding fee also increases. -Assuming the user's transfer quantity is `Amount`, the base fee is `BaseFee`, and the liquidity rate is `LiquidityRate` then +Assuming the user's transfer quantity is denoted as "Amount," the base fee as "BaseFee," and the liquidity rate as "LiquidityRate," then the total fee for the transfer can be calculated as follows: ``` TotalFee = BaseFee + Amount * LiquidityRate ``` -Fees are captured outside of the transfer, so users should set aside a portion of the Token to pay for cross-chain fees when transferring across the chain. LnProvider is open for registration and its fee is freely configurable, Helix backend will grab all the LnProvider information and will choose the one that makes sense for the user based on the configuration parameters. For example, an LnProvider with a lower execution fee will have a higher probability of being selected. +It's important to note that these fees are separate from the actual transfer and need to be accounted for by users. Users should set aside a portion of the token to cover the cross-chain fees. LnProvider registration is permission-less, and their fee is freely configurable. Helix's backend system will gather information from various LnProviders and choose the most suitable one for users based on their preferences. For instance, an LnProvider with a lower fee will have a higher chance of being recommended by the system. From 358d5aafeafe61841079588d6e0c2b6f140717d1 Mon Sep 17 00:00:00 2001 From: Aki Wu Date: Fri, 26 Jan 2024 15:38:01 +0800 Subject: [PATCH 5/7] feat: mapping_token --- docs/helixbridge/mapping_token.md | 65 +++++++++++++++++++------------ 1 file changed, 40 insertions(+), 25 deletions(-) diff --git a/docs/helixbridge/mapping_token.md b/docs/helixbridge/mapping_token.md index e2494ef..8fc714d 100644 --- a/docs/helixbridge/mapping_token.md +++ b/docs/helixbridge/mapping_token.md @@ -5,49 +5,64 @@ group: order: 1 --- -## Overview +# xToken -Although the protocol is currently little used, it's an important part of Helix's business is hosting user assets and completing cross-chain asset transfers. It uses an asset registration and cross-chain protocol based on the CBA (Cryptocurrency Backed Asset) model. +xToken plays an essential role in Helix's business by hosting user assets and facilitating cross-chain asset transfers. It operates based on an asset registration and cross-chain protocol rooted from the CBA (Cryptocurrency Backed Asset) model. -## Terminology +## Terms - **Source Chain And Target Chain** -
Rrefer to the source blockchain network and the target blockchain network for cross-chain asset transfer via a bridge, respectively, or the caller and the callee of a remote chain call. Generally, a light client of the source chain needs to be built on the target chain to perform cross-chain verification of messages or events from the source chain. -- **Origin Token And Mapping Token** -
This is a relative term. Original token usually refer to assets that have not been bridged to the target chain., such as BTC on the Bitcoin network, ETH or USDT on the Ethernet network. As opposed to a orgin token, which is located on the source chain end of the bridge, and a mapping token, which is located on the target chain end of the bridge, and is a type of asset created with the backing of the original token. + + Refers to the source blockchain network and the target blockchain network for cross-chain asset transfers via a bridge, respectively. Alternatively, it can denote the caller and the callee of a remote chain call. Generally, a light client of the source chain needs to be established on the target chain to perform cross-chain verification of messages or events from the source chain. + +- **Original Token and Mapping Token** + + This is a pair of relative terms. The original token typically refers to assets that have not been bridged to the target chain, such as BTC on the Bitcoin network, ETH, or USDT on the Ethereum network. On the other hand, the original token is located on the source chain of the bridge, while the mapping token is situated on the target chain of the bridge. The mapping token is a type of asset created with the backing of the original token. + - **Relayer** -
Relayers are a group of competing and supervising entities to maintain and accomplish the bridge's information transfer tasks. Relayers cannot have a substantial impact on the safety of a bridge, but have a direct role in the stability and effectiveness of the bridge. + + Relayers are a group of competing and supervising entities responsible for maintaining and executing the bridge's information relaying tasks. While relayers may not significantly impact the safety of a bridge, they play a direct role in ensuring the liveness and effectiveness of the bridge. ## CBA Model -Build the Backing module on the source chain and the Issuing module on the target chain, and the underlying call to the generic bridge message channel interface to complete the asset registration and issuance process. +The CBA Model involves deploying the Backing module on the source chain and the Issuing module on the target chain. The asset registration and issuance process is completed through underlying calls to the generic cross-chain messaging channel. - **Backing** -
Deployed on source chain. User tokens are locked to the Backing module, Backing generates locking proofs, and the tokens are hosted in Backing as an endorsement for asset issuance mapping on the target chain. Until the user initiates a reverse redemption operation, the tokens are unlocked again to the user's account. + + Deployed on the source chain, the Backing module locks user tokens. Backing generates locking proofs, and the tokens are held in Backing as collateral for asset issuance mapping on the target chain. These tokens remain locked until a user initiates a reverse redemption operation, at which point they are unlocked and returned to the user's account. + - **Issuing** -
Deployed on target chain. Backed by the original token in the locking model, Issuing issues mapping token to the user's account. When a user initiates a redemption operation, Issuing burns the mapping token and generates a proof of destruction for the original token redemption. + + Deployed on the target chain, the Issuing module is backed by the original token in the locking model. Issuing issues mapping tokens to the user's account. When a user initiates a redemption operation, Issuing burns the mapping token and generates a proof of destruction for the original token redemption. ## Protocol -- **Register** -
Token registration is the process of registering the original token to the Backing module on the source chain and mapping it to the mapping token on the target chain. It calls Backing module interface to pass in meta information of the original token, and the message relayer transfers the information to the Issuing module on the target chain to create the corresponding mapping token. -- **Lock And Issue** -
After the asset registration is completed, the user can lock the original token through Backing module, and after Message Relayer synchronizes the locking message to the target chain, Issuing module mint out the same amount of mapping token to the account specified by the user. -- **Swap And Other Applications** -
On the target chain, mapping token have the same token standard as original token, allowing users to execute various types of applications such as swap and transfer. -- **Burn And Redeem** -
Users holding mapping token on the target chain can burn the mapping token by calling the Issuing module interface. Message Relayer will deliver the burning message to the source chain and then the Backing module unlock the original token to the account specified by the user. +- **Asset registration** + + Asset registration is the process of registering the original token with the Backing module on the source chain and mapping it to the corresponding mapping token on the target chain. This involves calling the Backing module to provide meta information about the original token, and the message relayer relays this information to the Issuing module on the target chain to create the corresponding mapping token. + +- **Tokens Locking and Issuance** + + After completing asset registration, users can lock the original tokens through the Backing module. Once the Message Relayer synchronizes the locking message to the target chain, the Issuing module mints the same amount of mapping tokens to the user's specified account. + +- **Operations After Issuance** + + On the target chain, mapping tokens adhere to the same token standard as original tokens, allowing users to execute various types of operations such as swapping and transferring. + +- **Tokens Burning and Redemption** + + Users holding mapping tokens on the target chain can burn them by calling the Issuing module. The Message Relayer delivers the burning message to the source chain, and then the Backing module unlocks the original token, transferring it to the user's specified account. ## Transaction Atomicity -- Token Protocol V1 -
In this version, any cross-chain transfer message will receive a reply from target chain. If the mapping Token is issued successfully at the target chain, the original token will be locked on the source chain, otherwise the source chain will return the original token to users. -
So the transaction integrity of this version is strictly dependent on the transactions of the message bridge, and if the message bridge does not have a response process, the transaction atomicity of the asset bridge cannot be accomplished. -- Token Protocol V2 -
In this version, we have updated the transaction processing flow, if the issue of mapped assets on the target chain is successful, the transaction will end, if the issue fails, the user can get the issue failure proof to redeem the original token and complete the transaction. -
So we no longer rely on the response result from the bridge messaging service and only need to get the message delivery failure proof in case of message delivery failure. This proof usually consists of two parts, a proof of message delivery and a proof of non-existence of message success. -
Compared with V1 version, this version can adapt more bridge messaging services and save more cost on messaging services. However, an additional refund operation is required in the case of failure. +- Protocol V1 + + In this version, any cross-chain transfer message will receive a reply from the target chain. If the mapping token is successfully issued on the target chain, the original token will be locked on the source chain. If the issue fails, the source chain will return the original token to the users. Therefore, the transaction integrity in this version relies heavily on the transactions of the cross-chain messaging service. If the cross-chain messaging service lacks a response process, the transaction atomicity of the asset bridge cannot be ensured. + +- Protocol V2 + + In this version, we have updated the transaction processing flow. If the issuance of mapped tokens on the target chain succeeds, the transaction concludes. However, if the issuance fails, the user can obtain a proof of the failure to redeem the original token and complete the transaction. Consequently, we no longer depend on the response result from the cross-chain messaging service and only require the failure proof in case of message delivery failure. This proof typically comprises two parts: a proof of message delivery and a proof of the absence of message success. Compared to the V1, this version can adapt to more cross-chain messaging services and reduce costs. However, it requires an additional refund operation in case of failure. From dd8986411b6c8303904743ce01032aab46672caf Mon Sep 17 00:00:00 2001 From: Aki Wu Date: Fri, 26 Jan 2024 15:51:47 +0800 Subject: [PATCH 6/7] feat: relayer client --- docs/helixbridge/relayer_client.md | 30 ++++++++++++++++++++---------- 1 file changed, 20 insertions(+), 10 deletions(-) diff --git a/docs/helixbridge/relayer_client.md b/docs/helixbridge/relayer_client.md index 660ecf3..2de430d 100644 --- a/docs/helixbridge/relayer_client.md +++ b/docs/helixbridge/relayer_client.md @@ -6,22 +6,32 @@ order: 2 title: Client --- -Helix has open-sourced a JavaScript client, and you can find more information about it on their [GitHub](https://github.com/helix-bridge/relayer) repository. For specific configuration and deployment instructions, please refer to the README file in the repository. The README typically contains detailed guidelines on how to set up and use the client effectively. +# Helix Relayer Client -Make sure to carefully follow the instructions provided in the README for a successful setup and deployment of the Helix JavaScript client. +This is an open-source JavaScript software, and you can find more information about it on their [GitHub repository](https://github.com/helix-bridge/relayer). Refer to the README file in the repository for detailed guides. -Here's a brief overview of the steps for deploying a Relayer: +Please make sure to carefully follow the instructions provided in the README for a successful setup and deployment of the Helix Relayer Client. -- **Deploy Indexer Service (You can skip this step if using Helix's public service)**: If not using Helix's public service, you need to deploy your own Indexer service. This might involve setting up and configuring an Indexer to index and provide on-chain data. +Here's a brief overview of the steps to deploy a Relayer: -- **Download Relayer Source Code and Compile**: Download the Relayer's source code and compile it following the instructions provided in the project's documentation. Typically, this involves installing build tools, dependencies, and running compilation commands. +- **Indexer Service Preparation (Skip if using Helix's public service)** -- **Configure Bridge Information for Providing Relay Services**: In the Relayer's configuration file, specify information about the bridges you want to interact with. This includes details about the source and target chains, such as chain types, connection details, contract addresses, etc. + If you're not using Helix's public service, you'll need to deploy your own Indexer service. This may involve setting up and configuring an Indexer to index and provide on-chain data. -- **Start the Relayer Client and Keep It Online**: Run the Relayer client and ensure it stays online, ready to handle forwarding transaction requests. Usually, Relayers listen on specific ports, awaiting requests from users. +- **Building from Source** -- **Register the Relayer, Stake a Bond, and Set Fees**: Depending on the bridge's requirements, you may need to register the Relayer's identity on-chain, stake a certain amount as a bond, and set the fee structure. This ensures the credibility and availability of the Relayer. + Download the Relayer's source code and compile it according to the instructions in the project's documentation. Typically, this involves installing build tools, dependencies, and running build commands. -Absolutely, it's crucial to ensure that the Relayer client is running smoothly and remains online before attempting to register as a Relayer. Failing to do so could result in penalties or other consequences, as reliability and uptime are typically important criteria for becoming and remaining a Relayer in most bridge ecosystems. +- **Configuration** -Relayers play a critical role in maintaining the smooth operation of cross-chain transactions, so they are expected to provide a high level of availability and responsiveness. Therefore, it's essential to thoroughly test and monitor your Relayer setup to ensure it meets the required standards before registering and actively participating in the bridge network. + In the Relayer's configuration file, specify information about the bridges you want to interact with. This includes details about the source and target chains, such as chain types, connection details, contract addresses, etc. + +- **Running** + + Run the client and ensure it remains online, ready to handle relaying requests. Relayers usually listen on a specific port, awaiting requests from users. + +- **On-chain Registeration** + + Depending on the bridge's requirements, you may need to register the Relayer's identity on-chain, stake a certain amount as a bond, and establish the fee structure. This ensures the credibility and availability of the Relayer. + +It's crucial to ensure that the Relayer client runs smoothly and remains online before attempting to register as a Relayer. Failing to do so could result in penalties or other consequences, as reliability and uptime are typically essential criteria for becoming and remaining a Relayer in most bridge ecosystems. Therefore, it's essential to thoroughly test and monitor your Relayer setup to meet the required standards before registering and actively participating in the bridge network. From 979939445c560ef01574e3357257085bde157c82 Mon Sep 17 00:00:00 2001 From: Aki Wu Date: Fri, 26 Jan 2024 16:15:26 +0800 Subject: [PATCH 7/7] feat: relayer indexer --- docs/helixbridge/relayer_indexer.md | 69 +++-------------------------- 1 file changed, 5 insertions(+), 64 deletions(-) diff --git a/docs/helixbridge/relayer_indexer.md b/docs/helixbridge/relayer_indexer.md index 8aaa0b9..d6b9a50 100644 --- a/docs/helixbridge/relayer_indexer.md +++ b/docs/helixbridge/relayer_indexer.md @@ -6,11 +6,13 @@ order: 1 title: Indexer --- -Before we can understand and try to run a relay, we should first understand the index of the helix. Because relayer relies heavily on and trusts the indexed data, the index is very important to the proper functioning and security of relayer. +# Helix Data Indexing + +Before attempting to run a relay, it's essential to have a comprehensive understanding of Helix data indexing. The index plays a pivotal role in the proper functioning and security of the relayer, as it heavily relies on and trusts indexed data. ## Structure -Helix indexing consists of a two-tier index structure, the first tier indexes the data directly on the chain, often using mature solutions such as thegraph. the second tier aggregates and correlates the data from the first tier. +Helix indexing employs a two-tier structure. The first tier directly indexes data on the chain, often utilizing established solutions like thegraph. The second tier then aggregates and correlates the data gathered from the first tier. ``` +------------------------------+ +------------------------------+ @@ -36,65 +38,4 @@ Helix indexing consists of a two-tier index structure, the first tier indexes th Each indexer on the first layer is responsible for indexing and storing data from a single chain. The second layer's service is unique; it connects to the first layer's services, requests data from them sequentially, and associates data from different chains while performing global sorting. The Relayer only requests data from the second-layer indexer and trusts the data from that indexer. -## Deploy - -Relayers have the option to deploy their own indexer services. All Helix-related services are already open source on [GitHub](https://github.com/helix-bridge/indexer). Deploying the indexer service is also a two-step process, first deploying the first-layer indexing service, and then deploying the second layer. - -- For the first-layer service, navigate to the "subgraph" directory. Relayers can choose either the "default" or "opposite" subgraph directory based on their specific needs. Taking "arbitrum -> linea" as an example, before deploying, the relayer should first start the "graph-node" service. For detailed instructions, refer to the "graph-node" [documentation](https://thegraph.com/docs/en/deploying/hosted-service/). - -```shell -// deploy subgraph to graph-node ->> cd subgraph/ln-default-bridge ->> yarn build-arbitrum ->> npx graph create --node http://graph-node:8020/ lndefault/arbitrum ->> npx graph deploy --node http://graph-node:8020/ --ipfs http://ipfs:5001 lndefault/arbitrum ->> yarn build-linea ->> npx graph create --node http://graph-node:8020/ lndefault/linea ->> npx graph deploy --node http://graph-node:8020/ --ipfs http://ipfs:5001 lndefault/linea -``` - -- For the second-layer service, go into the "apollo" directory, and modify the .env.test file. Set the URL for "ENDPOINT" to your own deployed subgraph URL. Before starting the Apollo service, you should first launch a PostgreSQL service. You can follow the example below to start it using Docker Compose: - -```yaml -version: '3' - -services: - postgres: - container_name: subql-postgres - ports: - - 5432:5432 - image: postgres:12-alpine - restart: always - volumes: - - ./data:/var/lib/postgresql/data - environment: - POSTGRES_USER: 'admin' - POSTGRES_PASSWORD: 'admin' - POSTGRES_DB: 'apollo_graph' -``` - -Make sure to customize the environment variables (POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD) to suit your needs, and then use docker-compose up to start the PostgreSQL service before launching the Apollo service. -Once you've completed the setup and configuration, you can proceed to compile and start the Apollo service. The default port for the service is 4002. Here are the general steps: - -1. Make sure you are in the "apollo" directory where you have your configuration files, including the modified .env.test file. - -2. Compile the Apollo service if required. Typically, this can be done by running the necessary build or compile commands. - -3. After compiling (if needed), you can start the Apollo service by running a command like `yarn start:test` from the "apollo" directory. you need to initialize the database for the first-time startup using the command `yarn init:db`. - -4. The Apollo service should now be running on port 4002 as the default. You can access it by navigating to http://localhost:4002 in your web browser or by making API requests to that endpoint. - -```bash -// deploy indexer ->> cd apollo -// update ENDPOINT url in the file .env.test -// start a local postgres service (user:admin, password: admin, db: apollo_graph, port: 5432) ->> yarn generate:prisma ->> yarn build:test ->> yarn init:db ->> yarn start:test -``` - -## Helix Indexer Service - -Helix provides a public indexing service at the address https://apollo.helix.app. Relayers have the option to directly connect to this service. However, it's important to note that Helix does not guarantee the security of indexed data. Relayers should be aware that they are responsible for any data-related risks when using this service. +Each first-layer indexer is responsible for indexing and storing data from a single chain. The second-layer indexer connects to the first-layer services, sequentially requests data from them, and performs global sorting to associate data from different chains. The Relayer exclusively relies on data from the second-layer indexer.