A Polygon PoS withdrawal is a two-transaction transfer: tokens are burned on Polygon, then released on Ethereum after validators checkpoint the burn block. Your app should show those as separate stages because a successful burn does not mean the Ethereum claim is ready.
The key integration choice is to track proof eligibility separately from claim completion. The route’s burn, checkpoint, and exit steps follow how Polygon Bridge withdrawals settle, but your app still needs to represent each step and recover if a user closes the page. Treat the burn transaction hash as the durable identifier for the withdrawal.
What states should a withdrawal have?
Use states that correspond to observable chain events, not vague labels such as “processing.” A practical sequence is submitted, burn confirmed, waiting for checkpoint, claim ready, and claimed. Keep failed for a reverted transaction, and needs attention for recoverable problems such as a missing Ethereum gas balance.
After the user submits the Polygon transaction, wait for its receipt and check that its status is successful. Then verify that it contains the expected burn event for the intended token and amount. Store the source chain ID, transaction hash, block number, sender, token address, amount, and destination address; do not infer the amount from a button click or the requested transaction data.
For example, if a user burns 100 bridged USDC, show “100 USDC burned; waiting for Ethereum checkpoint,” not “100 USDC sent to Ethereum.” The latter is only accurate after the Ethereum exit transaction succeeds. This distinction prevents support teams and downstream services from treating funds in transit as spendable.
How do you know when the Ethereum claim is ready?
A burn becomes claimable after the Polygon block containing it is included in a checkpoint submitted to Ethereum. Heimdall coordinates Polygon PoS validator activity, while the checkpoint commits a range of Polygon blocks; the bridge then needs an inclusion proof for the specific burn. A Polygon transaction receipt alone cannot establish that the checkpoint has arrived.
Poll a checkpoint or proof service using the burn’s block number, with exponential backoff and a cap so temporary RPC failures do not create a tight request loop. A “not included yet” response means wait and retry; it is not evidence that the burn failed. When inclusion is confirmed, request the exit payload for the burn transaction and pass it to the bridge’s Ethereum exit call.
Checkpoint timing varies with network conditions. In normal operation, developers commonly see a wait measured in tens of minutes, but it can stretch to hours; present an estimate as approximate and avoid promising a fixed completion time. This PoS wait is distinct from the longer challenge window associated with a Plasma withdrawal route.
What should happen when the user must submit the exit?
The exit is a separate Ethereum transaction, signed by the user or by an explicitly authorized relayer. The user needs enough ETH on Ethereum to pay its gas, and the amount can vary with Ethereum base fees and execution conditions. Show the expected transaction and fee before asking for signature; do not silently treat the Polygon burn as authorization for a later Ethereum transaction.
Once the proof is ready, let the user retry proof retrieval or claim submission without repeating the burn. The burn cannot be cancelled to restore the Polygon balance; if the user leaves before claiming, preserve the pending record and let them resume with its transaction hash. Polygon Portal can help users complete a pending withdrawal, but your own status should still be based on chain data.
After submission, wait for the Ethereum receipt and confirm that it succeeded before marking the withdrawal claimed. A wallet rejection leaves the claim ready; a reverted Ethereum transaction leaves it unclaimed and may require a new attempt with corrected gas settings. Save the Ethereum transaction hash separately from the Polygon burn hash.
How should you reconcile status and edge cases?
Reconcile from both chains rather than relying on a browser session or a single indexer. On a page reload, retrieve the Polygon receipt from the stored burn hash, check its checkpoint status, and then inspect Ethereum for a successful exit. Make the update idempotent—processing the same receipt or event twice must not create two withdrawals in your database.
Handle an Ethereum claim submitted twice as a race: only one valid exit can release the bridged funds, while the other attempt may revert because the withdrawal is already complete. Refresh the claim state from Ethereum before offering another submission, and display the final successful transaction. Also validate token mapping and destination address at initiation; a valid proof cannot correct a burn made through an unsupported token path or to an unintended recipient.
For Polygon Bridge integrations, the decisive condition is whether your product can tolerate a user-driven Ethereum claim and a variable checkpoint delay. If your flow requires one-click delivery or a firm settlement deadline, choose a route and relayer model that explicitly meet those requirements, then design status and fee disclosures around that route’s actual guarantees.