Integrating the Withdrawal Request Queue

The entry point is the WithdrawalQueueERC721.requestWithdrawals function. Integrators must pass an array of uint256 amounts and a beneficiary address. The contract mints an ERC-721 NFT for each request, representing the claim on the unbonded ETH. Frontends must handle the approval flow if the user is spending stETH or wstETH, and should clearly communicate that the NFT is the critical proof of ownership for the future claim. Ensure your UI parses the Transfer event to capture the minted requestId for status tracking.

After submission, a request transitions through states: Pending, Claimable, and Claimed. Use getWithdrawalStatus to check the current state. The request becomes Claimable when the protocol has allocated ETH to it, which depends on the queue's processing logic and available ETH from validator exits. Your UI must poll this status and provide clear user feedback. Do not assume a fixed processing time; it is a function of the exit queue length and validator withdrawal cadence on the Beacon Chain.

Once Claimable, the NFT holder calls claimWithdrawal with the specific requestId. This burns the NFT and transfers the unbonded ETH to the caller. For a smoother UX, implement the permit-based claiming pattern using claimWithdrawals with EIP-712 signatures, allowing a service to claim on a user's behalf without a separate approval transaction. Ensure your smart contract or backend correctly constructs the permit digest and handles potential signature replay risks.

The withdrawal request is an ERC-721 token, meaning it can be transferred to another address. Your integration must account for this: the final claimant may not be the original requestor. If you are building a custodial or aggregator service, your backend must track the NFT's current owner by monitoring Transfer events. For a non-custodial UI, warn users that transferring the NFT transfers the claim right and that losing the NFT means losing access to the unbonded ETH.

For services managing multiple withdrawals, use the batch variants: requestWithdrawals accepts an array of amounts, and claimWithdrawals accepts an array of requestIds. This significantly reduces gas costs and transaction count. When building the claiming logic, implement a robust off-chain indexer that maps user addresses to their claimable requestIds by filtering WithdrawalRequested and WithdrawalClaimed events, enabling a single 'Claim All' button in your UI.

The withdrawal flow involves complex state transitions and NFT accounting. Common integration pitfalls include misinterpreting the amountOfStETH as the final ETH claim, failing to handle the NFT transfer correctly, or introducing a race condition in the permit-based claim. Chainscore Labs can conduct a targeted review of your withdrawal integration, focusing on state machine correctness, event indexing logic, and the security of your off-chain permit signing infrastructure.

Start with Lido’s WithdrawalQueueERC721 documentation before implementing request submission, status tracking, NFT ownership checks, or claim flows. The withdrawal request is represented as an ERC-721 position, so integrations must treat ownership transfer, approval, and claim authorization as part of the asset lifecycle. Review the documented methods for creating requests, reading request metadata, checking finalization state, and claiming ETH. Frontends should map these states explicitly instead of assuming a fixed withdrawal delay.

Use the official deployed contracts registry to confirm the current WithdrawalQueueERC721 proxy, stETH, wstETH, oracle, and related contract addresses for the target network. Do not hard-code addresses from third-party articles or old integration examples without checking this source. Production systems should pin verified addresses in configuration, monitor for governance-authorized upgrades, and separate mainnet, testnet, and L2 address books to avoid misrouting requests or approvals.

For mainnet integrations, inspect the verified WithdrawalQueueERC721 proxy on Etherscan to confirm ABI behavior, emitted events, proxy implementation history, and live transaction patterns. Teams should still treat Lido’s deployed-contracts page as the canonical address source, but Etherscan is useful for operational debugging: request creation failures, claim transaction reverts, approval issues, NFT transfers, and event-indexer reconciliation. Indexers should validate that their event parsing matches the verified contract ABI.

Withdrawal finalization is not only a user-initiated queue action; it depends on Lido’s oracle reporting and protocol accounting lifecycle. Review the AccountingOracle documentation when designing status polling, claimability checks, notifications, and support tooling. Wallets and custodians should avoid promising deterministic claim times and should explain that a request moves from pending to finalized according to protocol state, available buffered ETH, validator exits, and oracle-reported accounting.

Review the protocol source before building custom integrations, especially if your system batches requests, abstracts NFT ownership, supports delegated claiming, or signs permit-style operations. Source review helps engineers understand edge cases that are easy to miss from ABI calls alone: request amount constraints, share accounting, finalization batches, claim recipient behavior, event ordering, and revert conditions. Security teams should diff deployed implementations against audited or tagged source before approving production rollout.

Monitor Lido governance channels for protocol changes that can affect withdrawal integrations, including contract upgrades, oracle changes, staking router behavior, or withdrawal-related parameter updates. Governance does not replace contract-level verification, but it gives operators lead time to assess migration work, update monitoring, and review user-facing assumptions. Exchanges, custodians, and DeFi protocols should connect governance monitoring to their release-management and incident-response processes.