From c19393cc18616ad40c3b240cc746edf6211cbfba Mon Sep 17 00:00:00 2001 From: Krishna Upadhyaya Date: Mon, 16 Oct 2023 21:23:48 +0530 Subject: [PATCH 1/5] Added Bridge README --- bridge/README.md | 77 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) create mode 100644 bridge/README.md diff --git a/bridge/README.md b/bridge/README.md new file mode 100644 index 000000000..6dfda7b8a --- /dev/null +++ b/bridge/README.md @@ -0,0 +1,77 @@ +# Bridge (Setu) + +## Table of Contents + +- [Preliminary Terminology](#preliminary-terminology) +- [Overview](#overview) +- [Listner](#listner) +- [Processor](#processor) +- [How to start bridge](#how-to-start-bridge) + +## Preliminary Terminology + +## Overview + +Bridge module is responsible for listening to multiple chains and processing the events emitted by them, It converts the emitted data into heimdall messages and send them to the heimdall chain. There are `listener` and `processor` components in the bridge module which are responsible for listening and processing the events respectively as per their module, For example `listner/rootchain.go` is responsible for listening to events coming from rootchain OR L1 i.e Ethereum chain in our case and `listner/maticchain.go` is responsible for listening to events coming from maticchain OR L2 i.e Bor chain in our case. + +In order to process the events emitted by the chains, bridge module uses `processor` component, which is responsible for processing the events emitted by the chains. For example `processor/clerk.go` is responsible for processing the events related to clerk module, `processor/staking.go` is responsible for processing the events related to staking module and so on. + +Other components of the bridge module includes `queue` which is used for queuing the messages between listner and processors, `broadcaster` which is responsible for broadcasting the messages to the heimdall chain. + +Polygon PoS bridge provides a bridging mechanism that is near-instant, low-cost, and quite flexible. + +There is no change to the circulating supply of your token when it crosses the bridge: +- Tokens that leave the Ethereum network are locked and the same number of tokens are minted on Polygon PoS as a pegged token (1:1). +- To move the tokens back to the Ethereum network, tokens are burned on Polygon PoS network and unlocked on Ethereum network. + +## Listner + +The bridge module has a `BaseListner` which is extended by `RootChainListener`, `MaticChainListener` and `HeimdallListener`. It has all the methods required to start polling, listen to incoming headers(blocks) and stop the process if required. All the 3 listneres uses these properties with their individual implementations on how to handle the incoming header once received. + +For example in `RootChainListner` the incoming header is used to determine the current height of root chain and calculate the `from` and `to` block numbers using which the events are fetched from the root chain. These events are then sent to `handleLog` where based on their event signature they are added to queue as tasks for further processing by their respective processors. + +## Processor + +There is a `BaseProcessor` which is extended by every processor in the processor package. It has all the methods required to start processing the events, Register for the tasks which are there in the queue and stop the process if required. All the processors uses these properties with their individual implementations on how to handle the incoming events once received. + +Once the event is added to the queue by the `Listner`, The `Processor` takes over and processes the events which are added into the queue based on their event signature. Each processor has `RegisterTasks` method using which they register to process specific tasks added to the queue based on the module they serve, For example `StakingProcessor` registers for `Staking` related tasks, `ClerkProcessor` registers for `Clerk` related tasks and so on. You can look into each processor to check which tasks they are registered for. + +## How to start bridge + +Bridge should used by validator nodes only as they are the only ones who can send txns on heimdall chain, So if a non validator node is running bridge then it's of no use as it won't be able to send txns to heimdall chain. + +To start bridge as a validator you just have to add `--bridge` command to your heimdall node command, You can also control which services you want to run from processor by using `--all` or `--only` flags. + +To run all the service : + +```bash +./heimdalld start --bridge --all +``` + +To use specific services : + +```bash +./heimdalld start --bridge --only=clerk,staking +``` + +## Reset Tasks + +> :warning: Do this only when you are advised so and you understand the impact of this command. + +If you want to reset the bridge server data, you can use the following command: + +```bash +./heimdalld unsafe-reset-all +``` + + + + + + + + + + + + From 55ed069ff27414706a0647bb0247f26122ec899a Mon Sep 17 00:00:00 2001 From: Krishna Upadhyaya Date: Mon, 16 Oct 2023 21:27:15 +0530 Subject: [PATCH 2/5] Update README --- bridge/README.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/bridge/README.md b/bridge/README.md index 6dfda7b8a..68d8c49c8 100644 --- a/bridge/README.md +++ b/bridge/README.md @@ -2,14 +2,11 @@ ## Table of Contents -- [Preliminary Terminology](#preliminary-terminology) - [Overview](#overview) - [Listner](#listner) - [Processor](#processor) - [How to start bridge](#how-to-start-bridge) -## Preliminary Terminology - ## Overview Bridge module is responsible for listening to multiple chains and processing the events emitted by them, It converts the emitted data into heimdall messages and send them to the heimdall chain. There are `listener` and `processor` components in the bridge module which are responsible for listening and processing the events respectively as per their module, For example `listner/rootchain.go` is responsible for listening to events coming from rootchain OR L1 i.e Ethereum chain in our case and `listner/maticchain.go` is responsible for listening to events coming from maticchain OR L2 i.e Bor chain in our case. From a00687e75d8989c965d04fe7804a57773b63c49b Mon Sep 17 00:00:00 2001 From: Krishna Upadhyaya Date: Mon, 16 Oct 2023 23:51:10 +0530 Subject: [PATCH 3/5] Add FAQ --- bridge/README.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/bridge/README.md b/bridge/README.md index 68d8c49c8..3668adb19 100644 --- a/bridge/README.md +++ b/bridge/README.md @@ -6,6 +6,8 @@ - [Listner](#listner) - [Processor](#processor) - [How to start bridge](#how-to-start-bridge) +- [Reset](#reset) +- [Common Issues (FAQ)](#common-issues-faq) ## Overview @@ -51,7 +53,7 @@ To use specific services : ./heimdalld start --bridge --only=clerk,staking ``` -## Reset Tasks +## Reset > :warning: Do this only when you are advised so and you understand the impact of this command. @@ -61,12 +63,7 @@ If you want to reset the bridge server data, you can use the following command: ./heimdalld unsafe-reset-all ``` - - - - - - +## Common Issues (FAQ) From 7f76c43e41e65c0a42c39fec8e648b9ceeac70ba Mon Sep 17 00:00:00 2001 From: Krishna Upadhyaya Date: Thu, 2 Nov 2023 14:16:32 +0530 Subject: [PATCH 4/5] Fix --- bridge/README.md | 37 +++++++++++++++++++++++++++++++------ 1 file changed, 31 insertions(+), 6 deletions(-) diff --git a/bridge/README.md b/bridge/README.md index 3668adb19..ef97efd75 100644 --- a/bridge/README.md +++ b/bridge/README.md @@ -3,7 +3,7 @@ ## Table of Contents - [Overview](#overview) -- [Listner](#listner) +- [Listener](#listener) - [Processor](#processor) - [How to start bridge](#how-to-start-bridge) - [Reset](#reset) @@ -11,7 +11,7 @@ ## Overview -Bridge module is responsible for listening to multiple chains and processing the events emitted by them, It converts the emitted data into heimdall messages and send them to the heimdall chain. There are `listener` and `processor` components in the bridge module which are responsible for listening and processing the events respectively as per their module, For example `listner/rootchain.go` is responsible for listening to events coming from rootchain OR L1 i.e Ethereum chain in our case and `listner/maticchain.go` is responsible for listening to events coming from maticchain OR L2 i.e Bor chain in our case. +Bridge module is responsible for listening to multiple chains and processing the events emitted by them.It converts the emitted data into heimdall messages and send them to the heimdall chain. There are `listener` and `processor` components in the bridge module which are responsible for listening and processing the events respectively as per their module. For example `listner/rootchain.go` is responsible for listening to events coming from rootchain OR L1 i.e Ethereum chain in our case and `listner/maticchain.go` is responsible for listening to events coming from maticchain or L2 i.e Bor chain in our case. In order to process the events emitted by the chains, bridge module uses `processor` component, which is responsible for processing the events emitted by the chains. For example `processor/clerk.go` is responsible for processing the events related to clerk module, `processor/staking.go` is responsible for processing the events related to staking module and so on. @@ -23,17 +23,17 @@ There is no change to the circulating supply of your token when it crosses the b - Tokens that leave the Ethereum network are locked and the same number of tokens are minted on Polygon PoS as a pegged token (1:1). - To move the tokens back to the Ethereum network, tokens are burned on Polygon PoS network and unlocked on Ethereum network. -## Listner +## Listener -The bridge module has a `BaseListner` which is extended by `RootChainListener`, `MaticChainListener` and `HeimdallListener`. It has all the methods required to start polling, listen to incoming headers(blocks) and stop the process if required. All the 3 listneres uses these properties with their individual implementations on how to handle the incoming header once received. +The bridge module has a `BaseListner` which is extended by `RootChainListener`, `MaticChainListener` and `HeimdallListener`. It has all the methods required to start polling, listening to incoming headers(blocks) and stopping the process if required. All the 3 listneres uses these properties with their individual implementations on how to handle the incoming header once received. For example in `RootChainListner` the incoming header is used to determine the current height of root chain and calculate the `from` and `to` block numbers using which the events are fetched from the root chain. These events are then sent to `handleLog` where based on their event signature they are added to queue as tasks for further processing by their respective processors. ## Processor -There is a `BaseProcessor` which is extended by every processor in the processor package. It has all the methods required to start processing the events, Register for the tasks which are there in the queue and stop the process if required. All the processors uses these properties with their individual implementations on how to handle the incoming events once received. +There is a `BaseProcessor` which is extended by every processor in the processor package. It has all the methods required to start processing the events, registering for the tasks which are there in the queue and stopping the process if required. All the processors uses these properties with their individual implementations on how to handle the incoming events once received. -Once the event is added to the queue by the `Listner`, The `Processor` takes over and processes the events which are added into the queue based on their event signature. Each processor has `RegisterTasks` method using which they register to process specific tasks added to the queue based on the module they serve, For example `StakingProcessor` registers for `Staking` related tasks, `ClerkProcessor` registers for `Clerk` related tasks and so on. You can look into each processor to check which tasks they are registered for. +Once the event is added to the queue by the `Listener`, the `Processor` takes over and processes the events which are added into the queue based on their event signature. Each processor has `RegisterTasks` method using which they register to process specific tasks added to the queue based on the module they serve. For example `StakingProcessor` registers for `Staking` related tasks, `ClerkProcessor` registers for `Clerk` related tasks and so on. You can look into each processor to check which tasks they are registered for. ## How to start bridge @@ -65,7 +65,32 @@ If you want to reset the bridge server data, you can use the following command: ## Common Issues (FAQ) +### Connection reset by peer +If the node shows up the logs in below pattern + +``` +panic: Exception (501) Reason: "read tcp 127.0.0.1:35218->127.0.0.1:5672: read: connection reset by peer" +goroutine 1 [running]: +github.com/maticnetwork/heimdall/bridge/setu/queue. NewQueueConnector({0xc0002ccf60,0x22}) +``` +Your Heimdall Bridge has issues please follow the steps below to fix this + +``` +stop rabbitmq-server +rm /var/lib/rabbitmq/mnesia +start rabbitmq-server +``` + +### Validator is unable to propose checkpoints + +Please check the validator heimdall service and ensure the below flag is set and ensure rabbitmq is installed on your validator. + +``` +--bridge --all +``` + +Once done restart the services. From b9ff4dcfc4fa8a10e4daec0c68469759f0364f24 Mon Sep 17 00:00:00 2001 From: Krishna Upadhyaya Date: Thu, 2 Nov 2023 18:58:00 +0530 Subject: [PATCH 5/5] Fix --- bridge/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bridge/README.md b/bridge/README.md index ef97efd75..048b21b71 100644 --- a/bridge/README.md +++ b/bridge/README.md @@ -11,7 +11,7 @@ ## Overview -Bridge module is responsible for listening to multiple chains and processing the events emitted by them.It converts the emitted data into heimdall messages and send them to the heimdall chain. There are `listener` and `processor` components in the bridge module which are responsible for listening and processing the events respectively as per their module. For example `listner/rootchain.go` is responsible for listening to events coming from rootchain OR L1 i.e Ethereum chain in our case and `listner/maticchain.go` is responsible for listening to events coming from maticchain or L2 i.e Bor chain in our case. +Bridge module is responsible for listening to multiple chains and processing the events emitted by them.It converts the emitted data into heimdall messages and send them to the heimdall chain. There are `listener` and `processor` components in the bridge module which are responsible for listening and processing the events respectively as per their module. For example `listener/rootchain.go` is responsible for listening to events coming from rootchain OR L1 i.e Ethereum chain in our case and `listener/maticchain.go` is responsible for listening to events coming from maticchain or L2 i.e Bor chain in our case. In order to process the events emitted by the chains, bridge module uses `processor` component, which is responsible for processing the events emitted by the chains. For example `processor/clerk.go` is responsible for processing the events related to clerk module, `processor/staking.go` is responsible for processing the events related to staking module and so on.