Withdraw your validator

After the Agora Withdrawal upgrade (August 23, 2023, 01:05:53 AM (UTC)), you will be able to withdraw your staked BOA on validator nodes in two ways:

1. Partial (earnings) withdrawal: This option lets you withdraw your earnings (that is, all value staked above 40,000 BOA) and continue validating.

2. Full withdrawal: This option lets you liquidate your entire stake and earnings, effectively liquidating your validator node(s) and exiting the network.

In this how-to, you'll learn how to perform both types of withdrawals. Familiarity with Agora wallets, mnemonic phrases, and command lines is expected.

Prerequisites​

1. Your validator mnemonic: You'll use this to authorize your validator withdrawal request(s).

2. Access to a beacon node: You'll need to connect your validator to a beacon node in order to submit your withdrawal request. Visit our quickstart for instructions if you need them.

3. The agora-chain installed: The agora-chain is agora nodes and tool provided by the Agora research team.

4. Time to focus: This is a time-consuming procedure making a mistake can be expensive. Be vigilant against scammers; never share your mnemonic; take your time; ping us on Telegram if you have any questions.

We'll install other dependencies as we go.

Option 1: Partial (earnings) withdrawals

This section walks you through the process of performing a partial validator withdrawal, allowing you to withdraw staked balances above 40,000 BOA for each of your active Agora validators.

Step 1: Prepare your withdrawal credentials​

Retrieve your validator’s withdrawal_credentials from the deposit_data-XXX.json file that was generated when you first used the staking launchpad. The withdrawal_credentials value looks like this:

0x00500b3bf612bed69e888edeb045f590c3f37251e3e049c0732f3adaa57ea3f6

If you don't have the deposit_data-XXX.json file, you can retrieve your withdrawal_credentials by sending a request to your synced beacon node via Agora-cl API and providing your validator index or public key:

curl -X 'GET' \
  'http://YOUR_AGORA_NODE_HOST:3500/eth/v1/beacon/states/head/validators/YOUR_VALIDATOR_INDEX_OR_PUBLIC_KEY' \
  -H 'accept: application/json'

Your withdrawal credentials will be visible in the response to this request - look for withdrawal_credentials.

Example output with placeholder values:

{
  "execution_optimistic": false,
  "data": {
    "index": "1",
    "balance": "1",
    "status": "active_ongoing",
    "validator": {
      "pubkey": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a",
      "withdrawal_credentials": "0x008e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
      "effective_balance": "1",
      "slashed": false,
      "activation_eligibility_epoch": "1",
      "activation_epoch": "1",
      "exit_epoch": "1",
      "withdrawable_epoch": "1"
    }
  }
}

Step 2: run the agora-deposit-cli in an offline environment with your mnemonic to generate the blstoexecutionchange message(s)​

In this step, you submit a signed request to the Agora network using the Agora-chain tool provided by the BOSagora project.

Agora-chain installation instructions

If you already have a node running or installed using Agora-chain, you can skip the instructions below.

• Linux / Mac

mkdir agora-chain
cd agora-chain
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/bosagora/agora-chain/v0.x.x/agora.sh)"

• Windows

mkdir agora-chain
cd agora-chain
curl -S -L -o agora.bat https://raw.githubusercontent.com/bosagora/agora-chain/v0.x.x/agora.bat
call agora.bat

CAUTION

We recommend doing this next step without an Internet connection to be maximally secure. Either turn off the internet before introducing your mnemonic for signing or migrate to an air-gapped environment to continue the following steps.

Now that the Agora-chain's deposit-cli tool is executable, you can then use it to generate your signed BLS to Execution request. You need to use your mnemonic for this step, so doing it offline is key and ensuring you do not paste your mnemonic anywhere else than necessary.

Here’s the command to get started with the process. This command will not submit your signed message to the network yet, and will only generate the data needed for the next steps.

./agora.sh deposit-cli generate-bls-to-execution-change <folder>

'folder' is where the SignedBLSToExecutionChange data is stored. The default folder is ./bls_to_execution_changes

By calling the command above, you should go through an interactive process that will ask you for the following information:

1. Your language. You can see the different options available, where English is one of the options, among others.

2. The network you wish to perform this operation for. example: mainnet,testnet or devnet.

3. Enter your mnemonic next

4. Next, you will be asked for the starting index you used to create your validators (read more about hd wallets here). For most users, this will be 0 unless you created validators from a non default index.

INFO

Inside the original deposit.json file used for staking you can count each validator's public key in sequential order starting from 0. The validator starting index is the index of the first validator key you would like to withdraw (i.e. validator key 1 has an index of 0, validator key 2 has an index of 1 etc.). For most stakers, the validator starting index should be set to 0 for withdrawing all their validator keys, however the validator starting index will be different if you choose to skip withdrawing some validators. There are other niche cases where the mnemonic is used for deposit generation multiple times, resulting in a different validator starting index. Validators spanning across different mnemonics will need to be counted separately with starting index as 0 on each of them.

5. You will then be asked the validator indices for the validators you wish to generate the message for. You can find your validator indices on block explorers such as https://www.agorascan.io/ or in your Agora-cl validator client logs. For example, the validator with public key 0x800b1496d4532bbf3404de63619b779bad95dba69396e5d5c4eb64c7aa4a9a1a77229ec8783ad114a14d2eda2a3483ca on https://www.agorascan.io/ has validator index 20, which you can verify by navigating to its page.

INFO

Validator indices need to be provided sequentially without skipped indices in the order of original creation. You can typically find the order in your original deposit.json file. The generate-bls-to-execution-change command needs to be repeated in cases where multiple validator keys that are not in sequential order need to be withdrawn, and will require either merging of the output files or multiple blstoexecutionchange submissions. In the case of validators requiring different withdrawal addresses you will need to also repeat this process using the validator start index of the validator that the different withdrawal address.

6. Next you will be asked for your withdrawal credentials, which you should now have if you followed this guide

7. Next you will be asked for the BOA address you wish to use to receive your withdrawn funds. This needs to be checksummed, and you can get it from your wallet or a block explorer. You cannot change this once it is set on-chain, so triple check it before proceeding.

Below is an example of running through the interactive process explained above:

Please choose the (mainnet or testnet) network/chain name ['mainnet', 'testnet', 'devnet']:  [mainnet]: devnet

Please enter your mnemonic separated by spaces (" "). Note: you only need to enter the first 4 letters of each word if you'd prefer.: board fire prize defy limb arm diet fee usage settle rigid sunny duty squirrel cheap history session same tilt candy loan culture pretty anchor
Please enter the index position for the keys to start generating withdrawal credentials in ERC-2334 format. [0]: 39
Please enter a list of the validator index number(s) of your validator(s) as identified on the beacon chain. Split multiple items with whitespaces or commas.: 39
Please enter a list of the old BLS withdrawal credentials of your validator(s). Split multiple items with whitespaces or commas. The withdrawal credentials are in hexadecimal encoded form.: 0x0072b98f706baf445239abb7b3cbf7a070f9bf34cf016a2c093a9034f364045d
Please enter the 20-byte execution address for the new withdrawal credentials. Note that you CANNOT change it once you have set it on chain.: 0xc304A2aBCb9f14677cE1BA9242637A3a053b2e3a

**[Warning] you are setting an BOA address as your withdrawal address. Please ensure that you have control over this address.**

Repeat your execution address for confirmation.: 0xc304A2aBCb9f14677cE1BA9242637A3a053b2e3a

**[Warning] you are setting an BOA address as your withdrawal address. Please ensure that you have control over this address.**


Success!
Your SignedBLSToExecutionChange JSON file can be found at: /agora-chain/bls_to_execution_changes/bls_to_execution_changes

Step 3: verify the blstoexecutionchange message(s) that the corresponding validator will set to the chosen BOA address​

Once you complete the above, you’ll have a file contained in the bls_to_execution_changes/ folder of your agora-deposit-cli. It will represent a list of BLS to execution messages that have been signed with your private keys and are ready to submit to Agora. Here’s what a sample file of these looks like. Example output with placeholder values:

[
    {
    "message": {
      "validator_index": "838",
      "from_bls_pubkey": "0xb89bebc655569726a318c8e9971bd3144497c61aea4a6578a7a4f94b547dcba5bac16a89108b6b6a1fe3695d1a874a0b",
      "to_execution_address": "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0a"
    },
    "signature": "0xa42103e15d3dbdaa75fb15cea782e4a11329eea77d155864ec682d7907b3b70c7771960bef7be1b1c4e08fe735888b950c1a22053f6049b35736f48e6dd018392efa3896c9e427ea4e100e86e9131b5ea2673388a4bf188407a630ba405b7dc5"
  },
    {
    "message": {
      "validator_index": "20303",
      "from_bls_pubkey": "0xb89bebc699769726a502c8e9971bd3172227c61aea4a6578a7a4f94b547dcba5bac16a89108b6b6a1fe3695d1a874a0b",
      "to_execution_address": "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b"
    },
    "signature": "0xa86103e15d3dbdaa75fb15cea782e4a11329eea77d155864ec682d7907b3b70c7771960bef7be1b1c4e08fe735888b950c1a22053f6049b35736f48e6dd018392efa3896c9e427ea4e100e86e9131b5ea2673388a4bf188407a630ba405b7dc5"
  }
]

The above demonstrates two different validators withdrawing - one with validator index 838, the other with validator index 20303.

CAUTION

Make sure the validator_index corresponds to the correct chosen to_execution_address. Once this message is accepted on submission you will not be able to change it again!

Move the generated bls_to_execution_changes-*.json file to an online environment that has access to a synced beacon node for the next step.

Step 4: submit your signed blstoexecutionchange message(s) to the Agora network using Agora-chain​

This step requires access to a synchronized Agora-cl node.

You can use the ./agora.sh validator withdraw command, which will ask for terms of service acceptance and confirmation of command by providing additional flags, and also a path to the bls_to_execution_changes file from the previous step.

INFO

default Agora node REST <node-url> is http://localhost:3500 aka http://127.0.0.1:3500

Open a terminal in the location where you installed the agora-chain. Some users will need to give permissions to be executable. Linux users can do this by right clicking the file, going to permissions, and clicking the Allow executing file as program checkmark. This may be different for each operating system.

• Linux / Mac

./agora.sh validator withdraw <folder>

• Windows

agora.bat validator withdraw <folder>

'folder' is where the SignedBLSToExecutionChange data is stored. The default folder is ./bls_to_execution_changes

This will extract data from the bls_to_execution_changes-*.json call the Beacon API endpoint on the synced Beacon Node and validate if the request was included.

Step 5: Confirm submission​

On successful submission, the SignedBLStoExecutionChange messages are included in the pool waiting to be included in a block.

agora.sh version 2.0.0
The selected network is 'devnet'
Default data folder is bls_to_execution_changes
INFO[0000] found JSON files for setting withdrawals: [/agora-chain/bls_to_execution_changes/bls_to_execution_changes/bls_to_execution_change-1687424246.json] 
SETTING VALIDATOR INDEX 39 TO WITHDRAWAL ADDRESS 0xc304a2abcb9f14677ce1ba9242637a3a053b2e3a
INFO[0000] Successfully published messages to update 1 withdrawal addresses. 
INFO[0000] Verifying requested withdrawal messages known to node... 
INFO[0000] There are a total of 1 messages known to the node's pool. 
INFO[0000] All (total:1) signed withdrawal messages were found in the pool. 

The withdrawal will be initiated by using the execution address you provided, and your validators’ withdrawal credentials will change to look something like this:

*0x010000000000000000000000a94f5374fce5edbc8e2a8697c15331677e6ebf0b* 

where the BOA address of your choosing will be found within.

Step 6: Confirm your withdrawal​

You can track your withdrawal on an Agora Proof of Stake Block Scanner. Some examples listed below and will be based on network.

• agorascan.io: mainnet, testnet

you can also confirm the withdrawal_credentials updated by querying your local Agora-cl node.

curl -X 'GET' \
  'http://YOUR_PRYSM_NODE_HOST:3500/eth/v1/beacon/states/head/validators/YOUR_VALIDATOR_INDEX' \
  -H 'accept: application/json'

and you should see a response that contains withdrawal credentials that should have changed to the 0x01 format which includes your BOSagora execution address.

Done: Receiving partial withdrawals after withdrawal_credentials are updated is automatic, but will take time.​

Once your withdrawal_credentials field on the validator is updated to the 0x01 prefix all withdrawal actions are complete. Withdrawals of earnings over 40,000 BOA will be automatically sent to the chosen BOSagora address when a block proposer includes your validator in its block. Note that a maximum of 16 validators can have their balances withdrawn per block so delay times may vary before seeing the values appear in the BOA address.

Option 2: Full withdrawals​

To fully withdraw a validator and its earnings, your validator needs to also be exited in addition to having its withdrawal credentials changed.

Please follow our exiting-a-validator how-to.

Refer to the above option 1: partial withdrawal guidance to change your validator's withdrawal credentials.

CAUTION

Instructions for setting your withdrawal address do not need to be repeated if withdrawal_credentials are updated to the 0x01 prefix.

Done: Receiving full withdrawals after withdrawal_credentials are updated and the validator is fully exited is automatic, but will take time.​

Once the validator is both exited as well as having its withdrawal_credentials changed to the 0x01 prefix, the validator will automatically have its full balance withdrawn into the chosen Agora BOA address when a block proposer includes your validator in its block. Note that a maximum of 16 validators can have their balances withdrawn per block so delay times may vary before seeing the values appear in the BOA address.

CAUTION

Slashed or involuntarily exited validators will still need to go through the process of updating withdrawal_credentials to fully withdraw its remaining balance.