base-org/withdrawer

Golang utility for proving and finalizing withdrawals from op-stack chains.

withdrawer

Golang utility for proving and finalizing ETH withdrawals from op-stack chains.

Installation

git clone https://github.com/base-org/withdrawer.git
cd withdrawer
go install .

Usage

Caution

Do not send ERC-20 or other tokens to the L2StandardBridge, only native ETH is supported.

Without Fault Proofs

Step 1

Initiate a withdrawal on L2 by sending ETH to the L2StandardBridge contract at 0x4200000000000000000000000000000000000010, and note the tx hash. Example on Base Sepolia: 0x5e47346867cf87d8e8c82cae1d30a94b8d5587dc9d354aef5c5a7b4c84ad9463.

Note

Users are required to wait for a period of seven days when moving assets out of Base mainnet into the Ethereum mainnet. This period of time is called the Challenge Period and serves to help secure the assets stored on Base mainnet.

Step 2

Prove your withdrawal:

withdrawer --network base-mainnet --withdrawal <withdrawal tx hash> --rpc <L1 RPC URL> --private-key <L1 private key>

or use a ledger:

withdrawer --network base-mainnet --withdrawal <withdrawal tx hash> --rpc <L1 RPC URL> --ledger

Example output:

Proved withdrawal for 0xc4055dcb2e4647c37166caba8c7392625c2b62f9117a8bc4d96270da24b38f13: 0x6b6d1cc45b6601a30646847f638847feb629221ee71bbe6a3de7e6d0fbfe8fad
waiting for tx confirmation
0x6b6d1cc45b6601a30646847f638847feb629221ee71bbe6a3de7e6d0fbfe8fad confirmed

Note: this can be called from any L1 address, it does not have to be the same address that initiated the withdrawal on the L2.

Step 3

After the finalization period, finalize your withdrawal (same command as above):

withdrawer --network base-mainnet --withdrawal <withdrawal tx hash> --rpc <L1 RPC URL> --private-key <L1 private key>

Example output:

Completed withdrawal for 0xc4055dcb2e4647c37166caba8c7392625c2b62f9117a8bc4d96270da24b38f13: 0x1c457f1992f48f1f959ceaee5b3c7e699a26f6f05d93997d49dafe703fd66dea
waiting for tx confirmation
0x1c457f1992f48f1f959ceaee5b3c7e699a26f6f05d93997d49dafe703fd66dea confirmed

Note: this can be called from any L1 address, it does not have to be the same address that initiated the withdrawal on the L2.

With Fault Proofs

Note

With the recent fault proofs upgrade for Base on Sepolia testnet, withdrawals are required to wait for a period of seven days. This mirrors the Challenge Period that exists for Base mainnet. Additionally, withdrawals are required to be finalized against dispute games that resolve in favor of the output root claim. If the dispute game is blacklisted, resolves against the output root claim (challenger wins), or the respected game type is changed, then the withdrawal will need to be re-proven.

Step 1

Initiate a withdrawal on L2 by sending ETH to the L2StandardBridge contract at 0x4200000000000000000000000000000000000010, and note the tx hash. Example on Base Sepolia: 0x5e47346867cf87d8e8c82cae1d30a94b8d5587dc9d354aef5c5a7b4c84ad9463.

Step 2

Prove your withdrawal:

withdrawer --network base-mainnet --withdrawal <withdrawal tx hash> --rpc <L1 RPC URL> --private-key <L1 private key> --fault-proofs

or use a ledger:

withdrawer --network base-mainnet --withdrawal <withdrawal tx hash> --rpc <L1 RPC URL> --ledger --fault-proofs

Example output:

Proved withdrawal for 0xc4055dcb2e4647c37166caba8c7392625c2b62f9117a8bc4d96270da24b38f13: 0x6b6d1cc45b6601a30646847f638847feb629221ee71bbe6a3de7e6d0fbfe8fad
waiting for tx confirmation
0x6b6d1cc45b6601a30646847f638847feb629221ee71bbe6a3de7e6d0fbfe8fad confirmed

Note: this can be called from any L1 address, it does not have to be the same address that initiated the withdrawal on the L2.

Step 3

Important

Unlike the non fault proof withdrawal flow, you MUST use the same address that proved the withdrawal to finalize the withdrawal.

After the dispute game has resolved in favor of the root claim AND the finalization period has elapsed, finalize your withdrawal (same command as above):

withdrawer --network base-mainnet --withdrawal <withdrawal tx hash> --rpc <L1 RPC URL> --private-key <L1 private key> --fault-proofs

Example output:

Completed withdrawal for 0xc4055dcb2e4647c37166caba8c7392625c2b62f9117a8bc4d96270da24b38f13: 0x1c457f1992f48f1f959ceaee5b3c7e699a26f6f05d93997d49dafe703fd66dea
waiting for tx confirmation
0x1c457f1992f48f1f959ceaee5b3c7e699a26f6f05d93997d49dafe703fd66dea confirmed

Flags

Usage of withdrawer:
    -rpc string
        Ethereum L1 RPC url
    -network string
        op-stack network to withdraw.go from (one of: base-mainnet, base-sepolia, op-mainnet, op-sepolia) (default "base-mainnet")
    -withdrawal string
        TX hash of the L2 withdrawal transaction
    -fault-proofs
        Use fault proofs withdrawal flow (only for networks that support fault proofs)
    -private-key string
        Private key to use for signing transactions
    -mnemonic string
        Mnemonic to use for signing transactions
    -ledger
        Use ledger device for signing transactions
    -hd-path string
        Hierarchical deterministic derivation path for mnemonic or ledger (default "m/44'/60'/0'/0/0")
    -l2-rpc string
        Custom network L2 RPC url
    -l2oo-address string
        Custom network L2OutputOracle address
    -portal-address string
        Custom network OptimismPortal address
    -dfg-address string
        Custom network DisputeGameFactory address (only for networks that support fault proofs)

withdrawer's Issues

L1 private key

Hello! I wonder whether it is possible to prove and finalize the withdrawal from the other account (not the one that sent the funds to 0x420...010
Please state this in the guide
Thank you

Withdrawal can not be proved Error

The latest L2 output is 2233800 and is not past L2 block 2235640 that includes the withdrawal, no withdrawal can be proved yet.
Please wait for the next proposal submission to 0x56315b90c40730925ec5485cf004d835058518A0, which happens every 30m0s.

Pls what causes this error?

Could it the RPC URL?

Cleanup withdrawer code

As noted in #17 there are some spots where the code can be cleaned up / better optimized. This work should be done as a fast-follow.

Can't prove withdrawal after 14 days.

Hey there,

When trying to prove my withdrawal, I send this command:

withdrawer --network base-mainnet --withdrawal 0xefce5b34d7b6262a277774896cff42ce8f4da6a5049aafd8d38ebfac9368eb66 --rpc https://rpc.flashbots.net/ --private-key

And I am returned the following:

Error completing withdrawal: withdrawal tx 0xefce5b34d7b6262a277774896cff42ce8f4da6a5049aafd8d38ebfac9368eb66 was included in L2 block 2034109 (time 1690857565) but L1 only knows of L2 proposal 2628000 (time 1692045347) at head 604800 (time 17915639) which has not reached output confirmation yet (period is 1692046919).

I think there is a bug somewhere in withdrawer ?

Thank you in advance for your help.

challenge period 168h0m0s problems

i have waited the challenge period plus a couple hours. is the bridge back officially open? is the finalization period longer than 7 days? the code worked on testnet but seem to have problems for mainnet withdrawal.

Add edge case handling for FP withdrawals

As mentioned here, the current FP withdrawal logic doesn't handle edge cases that can occur during proving / finalization with fault proof enabled networks. These should be added to the withdrawer.

Fault Proofs Support

The API for doing a withdrawal is changing with the release of fault proofs. The modifications to the bridge can be found in the specs. This tool will need to be updated to support fault proof style withdrawals if it is used in production.