Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: polygon hook doc #31

Merged
merged 4 commits into from
May 11, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 47 additions & 0 deletions docs/reference/hooks/polygon-pos.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
# Polygon PoS Hook

Polygon PoS has their own interface for message passing between Ethereum and Polygon called the [`fx portal`](https://github.com/0xPolygon/fx-portal). Messages passed via this interface benefit from the security of the Polygon [state sync mechanism](https://docs.polygon.technology/pos/architecture/bor/state-sync/).

To provide this security as an option in Hyperlane, we created a Hook and ISM combo that can be transparently configured to reuse the fx-portal interface.

See the [addresses](../contract-addresses.mdx) page for Hook and ISM addresses.

## How It Works

Polygon FX-Portal provide FxChild (FxChild.sol) and FxRoot (FxRoot.sol) as the main contracts on which the bridge works. It calls and passes data to user-defined methods on another chain without needing a mapping.

The FxChild/FxRoot contract are provided and maintained by the polygon team. You can find the address of this contract in Polygon’s [Fx-Portal repo](https://github.com/0xPolygon/fx-portal).
The PolygonPosHook sends payloads with FxRoot. Validators will pick up the message and pass it to the other chain. You can find detailed state sync mechanism in [documentation](https://docs.polygon.technology/pos/how-to/bridging/l1-l2-communication/state-transfer/) `StateReceiver` at `0x0000000000000000000000000000000000001001` is allowed to call `onStateReceive` in FxChild contract. FxChild calls `processMessageFromRoot` in abstract `CrossChainEnabledPolygonChild` on which PolygonPosISM implements. `CrossChainEnabledPolygonChild` is maintained by [OpenZeppelin](https://docs.openzeppelin.com/contracts/4.x/api/crosschain#)

```mermaid
flowchart TB
subgraph Origin Ethereum
Sender
M_O[(Mailbox)]
Hook[PolygonPosHook]
Eth[(FxRoot)]

Sender -- "dispatch(...)" --> M_O
M_O -- "postDispatch(message)" --> Hook
Hook -- "sendMessage(messageId)" --> Eth
end

M_O -. "relay" .-> M_D
Eth -. "validator node" .-> Polygon

subgraph Destination Polygon PoS
Recipient
M_D[(Mailbox)]
ISM{PolygonPosISM}
Polygon[(FxChild)]

M_D -- "verify(..., message)" --> ISM
M_D -- "handle(...)" --> Recipient
ISM -. "interchainSecurityModule()" .- Recipient

Polygon -- "verifyMessageId(messageId)" --> ISM
end

style Eth fill: #ff0402
style Polygon fill: #ff0402
```
5 changes: 5 additions & 0 deletions sidebars.js
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,11 @@ const sidebars = {
id: "reference/hooks/op-stack",
label: "OP Stack",
},
{
type: "doc",
id: "reference/hooks/polygon-pos",
label: "Polygon PoS",
},
],
},
{
Expand Down