Canonical Bridge Integration Guide

Implement the two-phase commit pattern for PoS bridge deposits. First, call depositEtherFor or depositERC20For on the RootChainManager on Ethereum. Then, monitor for NewDepositBlock events on the ChildChainManager on Polygon PoS to credit users. For zkEVM, use the bridgeAsset function on the L1 PolygonZkEVMBridge contract and watch for BridgeEvent on the L2 bridge. Always verify the depositCount index to prevent replay or double-credit attacks. Wallets should display a 'Deposit Initiated' state until the child chain event is confirmed.

Build a reliable event listener for the StateSynced event emitted by the StateSender contract on Ethereum. On the Polygon PoS side, Bor validators pick up these events and execute onStateReceive on the target child contract. Integrators must handle the 30-minute checkpointing delay and potential reorgs of the Bor chain. Implement a polling or WebSocket subscription against the child contract to detect execution, and maintain a local cursor of processed stateIds to ensure idempotent handling of cross-chain messages from Ethereum.

Withdrawals follow a burn-and-release pattern with a critical 30-minute checkpoint window on PoS. After burning tokens on the child chain, wait for the transaction to be included in a checkpoint submitted to Ethereum. Only then can you call exit on the RootChainManager with a Merkle proof. For zkEVM, the claimAsset function on the L1 bridge requires the globalExitRoot and a Merkle proof verified against the PolygonZkEVM contract. Never credit a user on L1 before the exit transaction confirms.

For arbitrary message passing between zkEVM, PoS, and CDK chains, use the bridgeMessage function on the LxLy bridge. Design your receiving contract to implement a handler that is called by the bridge on the destination chain. Monitor BridgeEvent and ClaimEvent emissions to track message lifecycle. Be aware that message ordering is not guaranteed across different origin networks. For CDK chains, confirm the globalExitRootManager address and the network ID to avoid cross-chain replay attacks.

Build a unified indexing pipeline that consumes bridge events from both L1 and L2. On Ethereum, track NewDepositBlock, StateSynced, and Withdraw events. On Polygon PoS, monitor NewDepositBlock and Withdraw on the child chain. For zkEVM, index BridgeEvent and ClaimEvent on both layers. Use the depositCount and globalIndex as monotonically increasing counters to detect gaps. Implement a reconciliation job that compares L1 and L2 event logs to identify stuck deposits or unclaimed exits.

Bridge integrations introduce trust assumptions around checkpoint submission, sequencer behavior, and proof verification. Chainscore Labs can perform a targeted review of your bridge integration, including event monitoring logic, Merkle proof verification, replay protection, and failure recovery procedures. We assess your system's behavior during checkpoint delays, chain reorgs, and sequencer downtime to ensure asset safety and operational resilience.

Start with Polygon’s official documentation for PoS, zkEVM, bridge, staking, RPC, and network configuration references. Bridge integrators should use the docs to confirm the current canonical bridge flow, supported networks, token mapping process, and operational assumptions before hardcoding addresses or finality windows. Because Polygon has multiple execution environments, teams should distinguish PoS Bridge behavior from zkEVM LxLy bridge behavior and verify whether guidance applies to Ethereum mainnet, Polygon PoS, Polygon zkEVM, Amoy, Cardona, or a CDK chain.

Use the Polygon PoS contracts repository to inspect bridge-related contract source, ABI expectations, and event surfaces instead of relying on copied snippets from third-party guides. Integration teams should map their deposit, withdrawal, token-mapping, and event-indexing logic back to the relevant root-chain and child-chain contract code. This is especially important for custodians and exchanges that need deterministic deposit detection, replay-safe withdrawal handling, and clear separation between ERC-20, ERC-721, ERC-1155, and native asset flows.

For zkEVM bridge integrations, review the official zkEVM contracts repository to understand the bridge, global exit root, rollup manager, and L1 settlement interfaces used by the zkEVM system. Teams integrating LxLy messaging or monitoring withdrawals should confirm ABI compatibility, emitted events, claim mechanics, and proof-related assumptions against the contract source. Do not assume Polygon PoS Bridge semantics carry over to zkEVM; the trust model, finality path, and message-claim lifecycle are different.

Polygon Portal is useful as an operational reference for the current user-facing bridge flow, supported assets, and expected deposit or withdrawal states. Engineering teams should not treat the UI as a protocol specification, but it can help validate whether backend indexing, wallet status messages, and customer-support runbooks match canonical bridge behavior. When debugging user reports, compare internal transaction state with the Portal flow, relevant L1 and L2 transaction hashes, and the bridge contract events.

Use PolygonScan to verify deployed Polygon PoS contracts, inspect event logs, test read-only calls, and cross-check transaction inclusion on the Polygon side of a bridge flow. Indexers and custodians should reconcile their own deposit and withdrawal state machines against explorer-visible events, but should not depend on explorer APIs as the only source of truth. For production systems, pair explorer checks with direct RPC reads, Ethereum-side verification, and alerting for delayed checkpoints, missed events, or inconsistent token mappings.

Polygon bridge flows depend on Ethereum-side contracts for deposits, withdrawals, checkpoints, and zkEVM settlement. Use Etherscan to confirm Ethereum transaction status, contract verification, emitted events, and finality before crediting assets or marking withdrawals complete. Wallets, exchanges, and custodians should correlate Ethereum logs with Polygon-side logs and maintain independent confirmation policies. If contract labels, ABIs, or addresses differ across documentation, repositories, and explorers, pause automation and verify against Polygon’s canonical documentation before processing user funds.