Polygon <> Ethereum State Transfer
This document describes the architecture of how arbitrary messages can be passed between Ethereum and Polygon. For a more detailed explanation from the Polygon official docs site, go here.
Two-way bridge between Root on Ethereum and Child on Polygon
At a high level we are deploying "Root" and "Child" bridge contracts on both networks that communicate only with each other and the native state sync infrastructure that Polygon uses to pass data between the Ethereum and Polygon EVM's. Polygon uses "tunnel" to describe what other relayer systems call "bridges".
Diagram of oracle tunnel system: 
.
Root Tunnel Contract
This contract is deployed on Ethereum and inherits from the official tunnel implementation called the "FxBaseRootTunnel" which implements _processMessageFromChild(bytes memory data) to receive messages from Polygon and enforces that the message originated from a Polygon transaction that has been provably checkpointed to Ethereum. Notably, the root tunnel can only communicate with one child tunnel on Polygon, and the child tunnel address cannot be overwritten after being set.
In order to send messages to Polygon, the tunnel contract must be initialized to point to a "FxRoot" contract that is already deployed to Ethereum. The tunnel contract can send messages to Polygon via the "FxRoot" which has special permission to call syncState(address receiver, bytes calldata data) on the "StateSender" contract.
To receive messages from Polygon, the tunnel contract is similarly initialized to point to a "CheckpointManager" deployed on Ethereum. Checkpoints are snapshots of the Polygon chain state that are first validated by the Polygon validator set before being submitted to the "CheckpointManager" on Ethereum. Once a Polygon transaction is checkpointed to Ethereum, its arbitrary message can be used to trigger a function call on the Root Tunnel following an inclusion proof. This line in FxBaseRootTunnel implements the inclusion proof verification, and the _validateAndExtractMessage internal method must pass before the Root Tunnel can submit a price request to the DVM.
Child Tunnel Contract
This contract is deployed on Polygon and inherits from the official tunnel implementation called the "FxBaseChildTunnel" which implements _processMessageFromRoot(bytes memory data) to receive messages from Ethereum. Like the root tunnel, the child tunnel can only communicate with one root tunnel whose address cannot be overwritten after being set.
To send messages to Ethereum, the tunnel contract emits a MessageSent(bytes message) event containing the message that can be passed to the Root tunnel contract after the transaction that originally emitted the MessageSent event has been included in a Checkpoint.
To receive messages from Ethereum, Polygon validators will automatically detect and submit StateSynced(uint256 id, address contractAddress, bytes data) to Polygon's "FxChild" contract and execute onStateReceive(uint256 stateId, bytes _data), which will pass the message on to the Child tunnel contract. The Child tunnel must be initialized by pointing to the "FxChild" contract deployed on Polygon which can only be called by the System Superuser address on Polygon.
Types of messages that can be relayed
Any message can be relayed between Polygon and Ethereum provided that they are sent by contracts that implement the Polygon tunnel interface correctly (i.e. they can make calls to FxChild and FxRoot and they implement _processMessage... correctly). Each contract that wants to transfer state between Polygon and Ethereum must set up its own tunnel, so the relationship between Child and Root tunnels is 1-to-1. For example, UMA requires at least two tunnels to be set up:
- Oracle Tunnel: Submitting price requests from Polygon to Ethereum and resolving prices from Ethereum to Polygon
- Governor Tunnel: Sending governance actions from Ethereum to Polygon that can be executed on Polygon
Special Permissions that Tunnel contracts need within UMA system
- Oracle Tunnel: The Root tunnel must be able to submit price requests to the DVM and therefore must be registered with the
Registry.
Security Considerations
This system relies on the Polygon consensus mechanism secured by validators in a Proof of Stake system. The validator set enforces the integrity of data passed between networks (i.e. downstream users need to trust that the validators are not modifying the arbitrary messages that are being sent between networks).
Moreover, downstream users also rely on off-chain actors to relay messages in a timely fashion. Historically messages are sent once per hour.