State Transfer

Polygon Chain provides several contracts for passing data between Ethereum (L1) and Polygon (L2). They serve different purposes and operate at different levels of abstraction. The right choice depends on what you are transferring and in which direction.

​

Ethereum to Polygon (L1 to L2)

Data flows from Ethereum to Polygon via the state sync mechanism. A contract on Ethereum calls syncState on the StateSender contract, which emits a StateSynced event. Heimdall validators relay this event to Bor, which calls onStateReceive on the target contract on Polygon within a single sprint (approximately 16 blocks, or a few minutes). This mechanism is used internally by both the PoS token bridge and FxPortal. You can also use it directly for arbitrary data, subject to the registration requirement described below. For a step-by-step implementation, see Ethereum to PoS.

​

Registration requirement

Sender/receiver pairs must be registered with StateSender before state sync will relay events between them. This registration authorizes the pair: Heimdall only processes StateSynced events from registered sender contracts targeting registered receiver contracts. Registration is managed by the Polygon team. Contact the team on Discord or via the mapping request form to register a new pair.

​

Security in receiver contracts

The onStateReceive function on Polygon is called by the StateReceiver system contract at address 0x0000000000000000000000000000000000001001. Always verify msg.sender against this address in your receiver implementation. Without this check, any address on Polygon can call onStateReceive directly and inject arbitrary data. See the state sync architecture docs for a full description of how state sync works.

​

Polygon to Ethereum (L2 to L1)

Data flows from Polygon back to Ethereum via the checkpoint and exit mechanism. There is no continuous message relay in this direction. Instead:

1. A transaction on Polygon emits an event containing the data to transfer.
2. The transaction is included in a Polygon checkpoint, which is committed to Ethereum roughly every 30 minutes.
3. After the checkpoint is finalized on Ethereum, anyone can submit an exit proof to RootChainManager on Ethereum to trigger the corresponding state change on the root contract.

This is how the PoS bridge handles withdrawals: tokens are burned on Polygon, and after checkpoint, the lock is released on Ethereum. The same pattern works for arbitrary data. For a step-by-step implementation, see PoS to Ethereum.

​

Choosing the right approach

If you are building fee collection or settlement infrastructure that bridges tokens from Polygon back to Ethereum from a smart contract, use the PoS bridge withdrawal path: call withdraw on the child ERC-20 contract on Polygon to burn tokens, then after checkpoint, call exit on RootChainManager on Ethereum to release the funds to your target address.

​

Contract reference

The following contracts are used for L1-L2 messaging on mainnet. Source addresses are from the canonical network config.

​

State sync

These are the low-level contracts that underpin all L1-to-L2 messaging on Polygon Chain.

​

FxPortal

FxPortal is Polygon’s pre-registered messaging layer built on top of state sync. FxRoot is already registered as a sender in StateSender, and FxChild is its registered receiver on Polygon. You can inherit from FxBaseRootTunnel and FxBaseChildTunnel to build bidirectional messaging without needing custom registration.

​

PoS token bridge

These contracts handle token deposits and withdrawals through the official PoS bridge. Use these when bridging mapped ERC-20, ERC-721, or ERC-1155 tokens rather than arbitrary data.