Polygon validators continuously monitor a contract on Ethereum chain called
StateSender. Each time a registered contract on Ethereum chain calls this contract, it emits an event. Using this event Polygon validators relay the data to another contract on Polygon chain. This State Sync mechanism is used to send data from Ethereum to Polygon.
Additionally, Polygon validators send an Ethereum hash of each transaction on the Polygon chain on a regular basis. You can use this checkpoint to validate any transaction that took place on Polygon. Once a transaction has been verified to have occurred on the Polygon chain, Ethereum can then be used to carry out the appropriate action.
These 2 mechanisms can be used together to enable two-way data (state) transfer between Ethereum and Polygon. To abstract out all these interactions, you can directly inherit our
FxBaseRootTunnel (on Ethereum) and
FxBaseChildTunnel (on Polygon) contracts.
Root Tunnel Contract
FxBaseRootTunnel contract from here. This contract gives access to the following functions:
function _processMessageFromChild(bytes memory data): This is a virtual function that needs to be implemented in the contract which inherits it to handle data being sent from
_sendMessageToChild(bytes memory message): This function can be called internally with any bytes data as a message. This data will be sent as it is to the child tunnel.
receiveMessage(bytes memory inputData): This function needs to be called to receive the message emitted by
ChildTunnel. The proof of transaction needs to be provided as calldata. An example script to generate proof using matic.js is included below.
Child Tunnel Contract
FxBaseChildTunnel contract from here. This contract gives access to following functions:
function _processMessageFromRoot(uint256 stateId, address sender, bytes memory data): This is a virtual function that needs to implement the logic to handle messages sent from the
function _sendMessageToRoot(bytes memory message): This function can be called internally to send any bytes message to the root tunnel.
You need to inherit
FxBaseRootTunnelcontract in your root contract on Ethereum. As an example, you can follow this contract . Similarly, inherit
FxBaseChildTunnelcontract in your child on Polygon. Follow this contract as an example.
While deploying your root contract on
Goerli Testnet, pass the address of
_checkpointManageras 0x2890bA17EfE978480615e330ecB65333b880928e and
_checkpointManageris 0x86e4dc95c7fbdbf52e33d563bbdb00823894c287 and
For deploying the child contract on Mumbai testnet, pass 0xCf73231F28B7331BBe3124B907840A94851f9f11 as
_fxChildin constructor. For Polygon mainnet,
_fxChildwill be 0x8397259c983751DAf40400790063935a11afa28a.
setFxChildTunnelon deployed root tunnel with the address of child tunnel. Example: 0x79cd30ace561a226258918b56ce098a08ce0c70707a80bba91197f127a48b5c2
setFxRootTunnelon deployed child tunnel with address of root tunnel. Example: 0xffd0cda35a8c3fd6d8c1c04cd79a27b7e5e00cfc2ffc4b864d2b45a8bb7e98b8
Example Contracts of State Transfer Bridge
- Contracts: Fx-Portal Github Repository
- Goerli: 0xc4432e7dab6c1b43f4dc38ad2a594ca448aec9af
- Mumbai: 0xa0060Cc969d760c3FA85844676fB654Bba693C22
State Transfer from Ethereum → Polygon
- You need to call
_sendMessageToChild()internally in your root contract and pass the data as an argument to be sent to Polygon. Example: 0x28705fcae757a0c88694bd167cb94a2696a0bc9a645eb4ae20cff960537644c1
- In your child contract, implement
_processMessageFromRoot()virtual function in
FxBaseChildTunnelto retrieve data from Ethereum. The data will be received automatically from the state receiver when the state is synced.
State Transfer from Polygon → Ethereum
_sendMessageToRoot()internally in your child contract with data as a parameter to be sent to Ethereum. Example: 0x3cc9f7e675bb4f6af87ee99947bf24c38cbffa0b933d8c981644a2f2b550e66a
Note the transaction hash as it will be used to generate proof after it has been included as a checkpoint.
Proof Generation to complete the exit on root chain: Generate the proof using the tx hash and MESSAGE_SENT_EVENT_SIG. To generate the proof, you can either use the proof generation API hosted by Polygon or you can also spin up your own proof generation API by following the instructions here.
The proof generation endpoint hosted by Polygon is available here.
burnTxHashis the transaction hash of the
_sendMessageToRoot()transaction you initiated on Polygon.
eventSignatureis the event signature of the event emitted by the
_sendMessageToRoot()function. The event signature for the MESSAGE_SENT_EVENT_SIG is
The proof generation API usage examples for the Mainnet and Testnet are as follows:-
→ Mumbai Testnet Proof generation
_processMessageFromChild()in your root contract.
Use the generated proof as an input to
receiveMessage()to retrieve data sent from child tunnel into your contract. Example: 0x436dcd500659bea715a09d9257295ddc21290769daeea7f0b666166ef75e3515 )