Voluntary Exits

To stop staking, validators need to submit a SignedVoluntaryExit transaction. This is signed with the validator keys that Staked holds. Request a voluntary exit and submit it or hold it offline for submission at a later date.

Voluntary exits are only valid for the chain version/fork for which they were created and the following fork, e.g. an exit signed during Altair is only valid to be submitted during Altair and Bellatrix. Staked signs new exits each fork so if you are holding them offline re-request them after a fork.

To exit validators either submit a signed challenge containing the validators to exit or request the encrypted exits, decrypt them on your end, and then submit.

const challenge = JSON.stringify({
    intentToExit: "I am signing this message and requesting that Staked exit the following validators from the network",
    validatorIndexes: [1234, 1235, 1236], // REQUIRED: list of validator indexes
    date: Date.now().toString(), // optional, timestamp this was signed
    address: withdrawal_address, // REQUIRED: the signing address
}, null, 2)
const signature = await web3.eth.personal.sign(challenge, withdrawal_address);
const packed_challenge = web3.utils.toHex('\u0019Ethereum Signed Message:\n' + challenge.length.toString() + challenge);

Staked supports EOA and EIP-1271 compliant signatures when requesting voluntary exits.

Request Staked to submit exits

POST https://mainnet.staked.cloud/api/delegations/eth2/delegator/:key/exit/submit

Request Staked to exit a set of validators for a given withdrawal address. The list of validators comes from a challenge that must be signed with the withdrawal address. See the above code snippet for constructing the body for this method.

NOTE: If the challenge and signature check out, this submits the voluntary exits and will initiate the process for exiting validators. This method does not return the voluntary exits. If you need the voluntary exits you must request the encrypted exits.

Query Parameters

Name	Type	Description
key*	String	The withdrawal key to exit

Request Body

Name	Type	Description
signature*	String	The signature by the withdrawal key to
challenge*	String	The packed message to be signed (see above). This specifies which validators to exit.

200: OK Success

All exits submitted successfully.

400: Bad Request Some or all failed to submit

Some voluntary exits failed to submit. The error for each failed exit is returned. Ignored exits were successful.

{
    "failures": [
        {
            "validator_index": 1231,
            "message": "invalid signature"
        },
        {
            "validator_index": 1239,
            "message": "invalid signature"
        },
    ]
}

Voluntary exits are encrypted with the validator's withdrawal credential's public key. The public key address must have at least one outgoing transaction to be discoverable for encryption. You also have the option of providing your own ecies pubkey to staked to override this default encryption key. Example of using ecies to create a pubkey is below, please contact our support desk if you need to use this override pubkey.

Exit messages are stored and delivered encrypted so that only the staker can initiate voluntary exits. The voluntary exit for every validator with a shared withdrawal credential public key is encrypted in one batch to reduce the burden of decrypting, however multiple batches may be returned (though n<=5).

import json, base64
from ecies import encrypt, decrypt

# how Staked encrypts
data = base64.b64encode(json.dumps(signed_voluntary_exits_arr).encode())
encrypted_exits = base64.b64encode(encrypt(withdrawal_public_key, data)).decode()

# to decrypt you just invert the process:
decrypted_exits = json.loads(
    base64.b64decode(
        decrypt(
            withdrawal_private_key,
            base64.b64decode(
                encrypted_exits.encode()
            )
        )
    ).decode()
)
# signed_voluntary_exits = [
#     {
#         "message": {
#             "epoch": "1234",
#             "validator_index": "1234"
#         },
#         "signature": "0x1234..."
#     },
#     ... 
# ]
assert(decrypted_exits == encrypted_exits)

# To create new ecies pubkeys to provide as encryption keys:
from ecies.utils import generate_eth_key
eth_k = generate_eth_key()
pubkey_hex = eth_k.public_key.to_hex()
secretkey_hex = eth_k.to_hex()

Request voluntary exits for a type-0x01 withdrawal address

GET https://mainnet.staked.cloud/api/delegations/ETH2/delegator/:withdrawal_address/exit

Returns all SignedVoluntaryExits for validators using the given withdrawal credential.

signed_exits contents are encrypted with the same withdrawal key and will need to be decrypted before submission, but may contain more than one encrypted blob of SignedVoluntaryExits.

NOTE: this does not submit these exits, it just returns the encrypted exits for storage or decryption by the API consumer.

Path Parameters

Name	Type	Description
withdrawal_address*	String	Return exits for the set of validators using this ETH address as the basis for their 0x01 withdrawal credentials

Query Parameters

Name	Type	Description
api_key*	String	Your Staked API key

200: OK Success

{
    "withdrawal_key": "0x123...abc",
    "validator_pubkeys": ["1234...", "1235...", "1236...", ...],
    "signed_exits": ["encrypted_exits", ...]
}

206: Partial Content Success, some exits returned

Not all voluntary exits have been created for every validator using this withdrawal credential, but those that have been are returned.

{
    "withdrawal_key": "0x123...abc",
    "validator_pubkeys": ["1234...", "1235...", "1236...", ...],
    "missing_validators": 10,
    "signed_exits": ["encrypted_exits"]
}

404: Not Found No validators found, or no exits prepared

"No active validators found with given credential" or "Found active validators, but could not find prepared exit txns"

Exiting is separate from withdrawing. After successfully submitting an exit, validators will continue to stake until out of the exit queue and completely exited. Once finalized, the withdrawal process will take additional time to return all funds to the withdrawal address.

NOTE: if an exit is submitted before the validator has a type-0x01 ETH withdrawal credential funds will not be returned until a SignedBLSToExecutionChange has been submitted.

Submit voluntary exits for a type-0x01 withdrawal address

PUT https://mainnet.staked.cloud/api/delegations/ETH2/delegator/:withdrawal_address/exit

Submit a list of (decrypted) SignedVoluntaryExits to submit to the beacon chain.

Path Parameters

Name	Type	Description
withdrawal_address*	String	Return exits for the set of validators using this ETH address as the basis for their 0x01 withdrawal credentials

Query Parameters

Name	Type	Description
api_key*	String	Your Staked API key

Request Body

Name	Type	Description
exits*	Array	List of SignedVoluntaryExits to submit

200: OK Success

All exits submitted successfully.

400: Bad Request Some failures

Some voluntary exits failed to submit. The error for each failed exit is returned. Ignored exits were successful.

{
    "failures": [
        {
            "validator_index": 1231,
            "message": "invalid signature"
        },
        {
            "validator_index": 1239,
            "message": "invalid signature"
        },
    ]
}