Skip to main content

Ethereum / Unstaking

Withdraw your staked ETH from Ethereum's consensus layer using Figment's Staking API!

To unstake ETH using a pre-signed exit transaction and the Staking API, you will need:

  • validator_index — The validator index that your validator was assigned when it joined the beacon chain.
  • epoch — Epoch when the pre-signed exit transaction was generated by Figment.
  • signature — A BLS signature of the VoluntaryExit message by the validator"s signing key.

Follow the steps in this guide for the details on this process.

Flow Diagram​

Below is a complete diagram for the Ethereum unstaking flow:

Ethereum Unstaking Flow Diagram

Notes​

important
  • During the transition from exiting to unstaked, hourly checks are performed by the Staking API for up to 28 hours. If hourly checks timeout (by exceeding 28 attempts) the flow state becomes failed and a webhook is sent.

For more information on the withdrawal process, refer to Figment's Ethereum Withdrawals: A Comprehensive FAQ.

Actions​

Create New Unstaking Flow

To initiate the unstaking process, create a new flow with a POST request to /api/v1/flows.

URL

https://eth-slate.datahub.figment.io/api/v1/flows

Request

  • flow — object
    • network_code* : string Network this flow operates on (ex. ethereum).
    • chain_code* : string Chain this flow operates on (ex. goerli).
    • operation* : string The operation to perform (ex. unstaking).
    • version : string API version to use (ex. v1).

Response

  • id : string ID of the flow.
  • operation : string The operation being performed by this flow.
  • state : string The current state of the flow.
  • actions : array It includes the name & inputs of all next possible actions.
    • broadcast_unstaking_msg : Use this action to broadcast a transaction to unstake your ETH.
      • validator_index : The validator from which the ETH will be unstaked.
      • epoch : Epoch when the pre-signed exit transaction was generated by Figment.
      • signature : A BLS proof of possession, i.e. a proof that the private key corresponding to the validator_index is known by the signer.
    • unstaking_msg_expired : Use this action to indicate that the unstaking message has expired. This action has no inputs.
  • data : object Flow & transaction data.
Request
Example Response
{
  "id": "96d16e6f-4984-4a8e-9018-9e4a7da54dfe",
  "operation": "unstaking",
  "state": "initialized",
  "actions": [
    {
      "name": "broadcast_unstaking_msg",
      "inputs": [
        {
          "name": "validator_index",
          "display": "Validator Index",
          "description": "",
          "type": "string",
          "validations": [
            {
              "type": "numericality",
              "options": {
                "only_integer": true,
                "greater_than_or_equal_to": 0
              }
            },
            {
              "type": "presence",
              "options": {}
            }
          ],
          "array": false,
          "default_value": null
        },
        {
          "name": "epoch",
          "display": "Epoch",
          "description": "",
          "type": "string",
          "validations": [
            {
              "type": "numericality",
              "options": {
                "only_integer": true,
                "greater_than_or_equal_to": 0
              }
            },
            {
              "type": "presence",
              "options": {}
            }
          ],
          "array": false,
          "default_value": null
        },
        {
          "name": "signature",
          "display": "Signature",
          "description": "",
          "type": "string",
          "validations": [
            {
              "type": "presence",
              "options": {}
            },
            {
              "type": "hex",
              "options": {}
            }
          ],
          "array": false,
          "default_value": null
        }
      ]
    },
    {
      "name": "unstaking_msg_expired",
      "inputs": []
    }
  ],
  "data": {
    "validator_index": null,
    "epoch": null,
    "signature": null,
    "estimated_principal_return_at": null,
    "transactions": []
  },
  "network_code": "ethereum",
  "chain_code": "goerli",
  "created_at": "2023-03-10T15:19:51.359Z",
  "updated_at": "2023-03-10T15:19:51.359Z"
}

Submit Unstaking Data

After collecting the required inputs, PUT /api/v1/flows/[:flow_id]/next to move on to the next step.

URL

https://eth-slate.datahub.figment.io/api/v1/flows/[:flow_id]/next

Request

  • name* : broadcast_unstaking_msg
  • inputs* : object
    • epoch* : string Epoch when the pre-signed exit transaction was generated by Figment.
    • validator_index* : number Index of the validator to exit.
    • signature* : hexadecimal A BLS signature of the VoluntaryExit message by the validator's signing key.

Response

  • id : string ID of the flow.
  • operation : string The Staking API operation being performed by this flow.
  • state : string The current state of the flow.
  • actions : array It includes the name & inputs of all next possible actions.
    • wait : Provides an estimated_state_change_at timestamp. This action has no inputs.
  • data : object Flow & transaction data.
Request
Example Response
{
  "id": "5d3fb8e0-bf2d-4fcc-9ff8-ed9d02d47659",
  "operation": "unstaking",
  "state": "broadcasting",
  "actions": [
    {
      "name": "wait",
      "estimated_state_change_at": "2023-02-24T11:36:45.451Z",
      "inputs": []
    }
  ],
  "data": {
    "validator_index": 398094,
    "epoch": 158149,
    "signature": "0xa5ccd66f59898d3b655affe90ca328849c5993a54e4f63ed5447ce0f3bb6b5918bf72f06cbaec29af169abc433209eb30aa95d7ac1513c79887e2b552590119c32f350924e8f1dda2f2c1a5a68d801f3c150e8234493e0658031abdddcc9b2e3",
    "estimated_principal_return_at": null
  },
  "network_code": "ethereum",
  "chain_code": "goerli",
  "created_at": "2023-02-23T05:16:02.187Z",
  "updated_at": "2023-02-24T11:28:44.565Z"
}

Get Unstaking Flow Status

To get the current state of the existing flow, send a GET request to /api/v1/flows/[:flow_id] using the flow ID from the previous step.

URL

https://eth-slate.datahub.figment.io/api/v1/flows/[:flow_id]

Request

  • None

Response

  • id : string ID of the flow.
  • operation : string The Staking API operation being performed by this flow.
  • state : string The current state of the flow.
    • broadcasting : Transaction is broadcasting and not confirmed yet.
    • exiting : The validator is in the exit queue.
    • withdrawing : The validator has exited the active set and the deposited ETH will be sent to the withdrawal address.
    • unstaked : The validator stake has been sent to the withdrawal address.
    • Refer to the Ethereum Validator Lifecycle guide for more information.
  • actions : array It includes the name & inputs of all next possible actions.
  • data : object Flow & transaction data.
Request
Example Response
{
  "id": "5d3fb8e0-bf2d-4fcc-9ff8-ed9d02d47659",
  "operation": "unstaking",
  "state": "unstaked",
  "actions": [],
  "data": {
    "validator_index": 398094,
    "epoch": 158149,
    "signature": "0xa5ccd66f59898d3b655affe90ca328849c5993a54e4f63ed5447ce0f3bb6b5918bf72f06cbaec29af169abc433209eb30aa95d7ac1513c79887e2b552590119c32f350924e8f1dda2f2c1a5a68d801f3c150e8234493e0658031abdddcc9b2e3",
    "estimated_principal_return_at": "2023-02-25T14:16:36.302Z"
  },
  "network_code": "ethereum",
  "chain_code": "goerli",
  "created_at": "2023-02-23T05:16:02.187Z",
  "updated_at": "2023-02-25T14:18:36.302Z"
}