TwitterLinkedInMedium

Node Provisioning APIs

Provisioning APIs for Ethereum nodes creation and staking delegation

What are the Node Provisioning APIs?

  1. Provision Request API: The client calls this API to initiate a request which creates the transaction objects that the client needs to sign.

  2. Get Validator Objects API: The client calls this API to retrieve the transaction objects used to stake with the Beacon deposit contract.

  3. Get Deposit Details API:

    The client invokes this API to fetch deposit data, which can subsequently be utilized for staking with the Beacon deposit contract.

  4. Get Validator and Provision API:

    The client calls this API to receive the validator objects which were created along with their respective provision IDs.

  5. Get Validator Count API:

    The client invokes this API to get the number of validators by their validator status.

In essence, the Node Provisioning APIs allow clients to spin up new Ethereum nodes via REST APIs. These APIs can be used to generate and receive the transaction objects which must be signed using the Beacon deposit contract. A detailed account of the APIs involved is provided in the following section.

API Reference

Supported Environments

Luganodes supports the following environments on ETH, as defined below

Provisioning Request

POST /api/provision

Submits a provision request to our secure node systems to generate the required files based on the withdrawal address and the number of validators sent in the request.

The response will contain a UUID which can be used to track the provision request.

Headers

Request Body

{
    "result": {
        "created": "2024-02-15T05:19:18.942Z",
        "status": "CREATED",
        "provisionId": "f1575191-0b13-4c6c-ae7b-61adfbea0d98",
        "validatorsCount": 3,
        "withdrawalAddress": "0xa08c6C9e3d0E28E0E9Ef17cE67899e8E06501dD2",
        "controllerAddress": "0x918D92fc2cA24379ba1EEa1dd1CA385Fc5C8df7c", //or null
        "feeRecipient": "0x2A0e48522876DbD8B414E938cbE4e05FD6A23811" //or null
    }
}

A maximum of 100 validators can be requested in a single provision request. To provision more nodes, a new provision request must be sent.

Sample Request

curl --location '{{url}}/api/provision' \
--header 'api-key: ee908371-d13b-43dd-ae33-b854dade5e9d' \
--data '{
    "attributes": {
        "withdrawalAddress": "0xa08c6C9e3d0E28E0E9Ef17cE67899e8E06501dD2",
        "controllerAddress": "0x918D92fc2cA24379ba1EEa1dd1CA385Fc5C8df7c", //optional
        "feeRecipient": "0x2A0e48522876DbD8B414E938cbE4e05FD6A23811", //optional
        "validatorsCount": 3,
        "batch":true
    }
}'

Types

Attributes Object

Provision Response Object

If user is unable to sign exit transactions with their withdrawal address, we have added provisions to give signing privileges to controller address

Get Validator Objects

GET /api/validators

Retrieve the transaction objects that require signing by sending the UUID received in the Provisioning Request API.

Query Parameters

Headers

{
  "batch": true,
  "depositInput": "0xc82655b70000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000001400000000000000000000000000000000000000000000000000000000000000220000000000000000000000000000000000000000000000000000000000000006083651cfd972c2170c85754cdcbf5b0ffe31ad96a37835a695d533b951cf2189aa86e4d8b3b4c84e59d0376570e41d31baa3ae8f0d1716cd13ef9874633b42157a43d95fb661457c7b85ba344709458e020491d852264e65c23f39d6d0374057e0000000000000000000000000000000000000000000000000000000000000020010000000000000000000000f345a81af5b23ae1fd0d08f97af1ac05ffad825c00000000000000000000000000000000000000000000000000000000000000c08bd5db0506969f1040e1f0bd0609eaf2d927a500cddf2298cfe8bb56112bd46bcf525f24fe9523fc99e0695f3076a40e01f3f95b6af3c3da0971b68cf3083a204819f55d803fa751d3c1e7c7cf220af12afda0f8bcc138c2dad69eee3ec2885c93bb41fc4e793ea1acb34034181d473c6f48c0591955fbf8d178701469b5f1b543c29a5a5eb4b58470ff44822a977a46010730e3869215ae7ddcb1b0efa4f6cc94705b24cd4c44932c92cd689a310bcd28c131704e98c9ded92bd5d02101ea870000000000000000000000000000000000000000000000000000000000000002e238a9ddbe247c643233a004fb0eae0d9682ee367580549ea0912880201c13f2c30fef3c554b82e5399bff17b31104e60be991af835b236a41c949d436d6c69e",
  "withdrawalAddress": "0xF345A81Af5b23Ae1fD0D08f97AF1aC05fFAd825c",
  "withdrawal_credentials": "0x010000000000000000000000a08c6c9e3d0e28e0e9ef17ce67899e8e06501dd2",
  "validatorsCount": 2,
  "clientId": "0c14fc15-9562-4fbe-bf02-f86e56a57d83",
  "provisionId": "321e7857-f81c-4d0c-9750-17a84d631aed",
  "provisionStatus": "CREATED",
  "results": [
    {
      "validatorIndex": null,
      "validatorAddress": "0x83651cfd972c2170c85754cdcbf5b0ffe31ad96a37835a695d533b951cf2189aa86e4d8b3b4c84e59d0376570e41d31b",
      "amount": 32000000000,
      "created": "2024-01-24T11:37:40.202Z",
      "status": "CREATED",
      "depositInput": null
    },
    {
      "validatorIndex": null,
      "validatorAddress": "0xaa3ae8f0d1716cd13ef9874633b42157a43d95fb661457c7b85ba344709458e020491d852264e65c23f39d6d0374057e",
      "amount": 32000000000,
      "created": "2024-01-24T11:37:40.202Z",
      "status": "CREATED",
      "depositInput": null
    }
  ],
  "page": null,
  "per_page": null,
  "total": 2,
  "pages": null
}

Validators are provisioned asynchronously, and the automation script processes provision requests, generating the required files. Therefore, an empty array response is received until the script execution is completed.

Sample Request

curl --location '{{url}}/api/validators?per_page=10&page=1&provisionId=cd127302-570d-4b38-ba19-26ccf3a5dd2e' \
--header 'api-key: rNmE773fXgApKKAw$2btnNC9p5BdILMsDxxodrepgoU='

Types

Paginated Response Object

Validator Result Object

Validator Status Enum

Provision Status Enum

Get Deposit Details

GET /api/deposit-details

Retrieve the deposit data details that are required to staking in the Ethereum staking contract by sending the UUID received in the Provisioning Request API.

Query Parameters

Headers

{
  "batch": false,
  "withdrawal_credentials": "0x010000000000000000000000a08c6c9e3d0e28e0e9ef17ce67899e8e06501dd2",
  "controllerAddress": "0x918D92fc2cA24379ba1EEa1dd1CA385Fc5C8df7c",
  "feeRecipient": "0x2A0e48522876DbD8B414E938cbE4e05FD6A23811",
  "validatorsCount": 2,
  "clientId": "1e40716f-b684-4dc7-a5a3-ba573a2a05de",
  "provisionId": "566afafa-4154-436e-a0aa-941de7e9bc53",
  "results": [
    {
      "validatorIndex": null,
      "validatorAddress": "0xb032c4194075e73126626e4d6a24a2f01db41f7cfc45e34a48a3f4dc38c52db790ef8818ea5b227277fa3747d312694e",
      "amount": 32000000000,
      "created": "2024-02-15T10:13:24.110Z",
      "status": "CREATED",
      "signature": "0x8fb4ce023e81d1113ee8f5cc962b248352c3ef9be0768e1262b5d0ec5c6d10ed59de826777cba411a2956c083885b05c18f574959c18f3b3ba7c1ca78420f1ee2f81195ff2441a517c36eedff25af86088e65057c57a91a0b4fbe51a8f448bbe",
      "deposit_data_root": "0x2bb2748126b0545b98001e36336952710a792a07fcd99f2462cf3c5c946394f4",
      "deposit_message_root": "0xaa28abd59101232a2eec07c97dfd38b7a0166f767202e56dc45dd99591388610",
      "fork_version": "0x00001020"
    },
    {
      "validatorIndex": null,
      "validatorAddress": "0x99f5759a47651b49b4a3ac6e718ba5e08a01d48c1ff6419bf561659e76c481f9fe93fb4b48dcad13a8ed21058c3d8a33",
      "amount": 32000000000,
      "created": "2024-02-15T10:13:24.110Z",
      "status": "CREATED",
      "signature": "0xafe703147da666044cc276e1cbae2543cf83578e814e692e7aab2cb9ed58679005c31fd7330a7bd8bf379d8ae326467b18f2515f053cc77cb3cbecc479c1cd00ad23054c71a1a40b4e7e2e555c7249628909176b2219bd5bf26aab70c948e490",
      "deposit_data_root": "0x123a26e89fcae9286fedd4ffe0caba245cfbe4f4a98a70c7016919bc77a76495",
      "deposit_message_root": "0x1f563a358f970e2d182d25f1b94f182b97b20cb912d457120ef06eb60a9f6f5b",
      "fork_version": "0x00001020"
    }
  ],
  "page": 1,
  "per_page": 10,
  "total": 2,
  "pages": 1
}

The validator index will be set to null until the validator gets activated on the Ethereum network.

Sample Request

curl --location '{{url}}/api/deposit-details?page=1&per_page=10&provisionId=cd127302-570d-4b38-ba19-26ccf3a5dd2e' \
--header 'api-key: moSAd1Rk/dVJSjm/baRSq7RIfZW5c1PS0PngJL04nHs='

Types

Paginated Response Object

Deposit Details Object

Get Validator and Provision IDs

GET /api/users

Fetch the provision IDs of validators associated with a client API key.

Query Parameters

Headers

{
  "clientId": "5eccab77-2e4a-4b93-98d7-f179567bcd7e",
  "result": [
    {
      "validatorAddress": "0xb3db9b4688155a52d752ff58d97a80b860e56136d94b97c5e088561085f55cb1c389eb46b5eb2d42c873d608441f561f",
      "provisionId": "a4be819b-5035-4219-b4b7-838c972bc753",
      "withdrawalAddress": "0xa08c6C9e3d0E28E0E9Ef17cE67899e8E06501dD2",
      "withdrawal_credentials": "0x010000000000000000000000a08c6c9e3d0e28e0e9ef17ce67899e8e06501dd2",
      "controllerAddress": "0x918D92fc2cA24379ba1EEa1dd1CA385Fc5C8df7c",
      "feeRecipient": "0x2A0e48522876DbD8B414E938cbE4e05FD6A23811",
      "status": "CREATED",
      "createdAt": "2024-02-15T10:28:59.551Z",
      "validatorIndex": 0
    },
    {
      "validatorAddress": "0xadf01960b6accc2367f7532ec74719028907208c916e7be22b0bb0fe755df4a0e7e247969b964c4f7e5bd23a895c02e3",
      "provisionId": "a4be819b-5035-4219-b4b7-838c972bc753",
      "withdrawalAddress": "0xa08c6C9e3d0E28E0E9Ef17cE67899e8E06501dD2",
      "withdrawal_credentials": "0x010000000000000000000000a08c6c9e3d0e28e0e9ef17ce67899e8e06501dd2",
      "controllerAddress": "0x918D92fc2cA24379ba1EEa1dd1CA385Fc5C8df7c",
      "feeRecipient": "0x2A0e48522876DbD8B414E938cbE4e05FD6A23811",
      "status": "CREATED",
      "createdAt": "2024-02-15T10:28:59.551Z",
      "validatorIndex": 0
    }
  ]
}

Sample Request

curl --location --globoff '{{url}}/api/users?page=1&per_page=10' \
--header 'api-key: ee908371-d13b-43dd-ae33-b854dade5e9d'

Types

Paginated Response Object

Validator Result Object

Get Validator Count

GET /api/validators/count

Returns the number of validators by their status.

Query Parameters

Headers

Response

{
  "result": {
      "total": 100,
      "by_status": {
        "pending_initialized": 1,
        "pending_queued": 1,
        "active_ongoing": 0,
        "active_slashed": 0,
        "exited_unslashed": 0,
        "exited_slashed": 0,
        "withdrawal_possible": 94,
        "withdrawal_done": 1,
    }
  }
}

Sample Request

curl --location --globoff '{{url}}/api/validators/count' \
--header 'api-key: ee908371-d13b-43dd-ae33-b854dade5e9d'

Types

Result Object

Status Object

PreviousAuthenticationNextExits

Last updated