Node Provisioning APIs

Provisioning APIs for Ethereum nodes creation and staking delegation

What are the Node Provisioning APIs?

Provision Request API: The client calls this API to initiate a request which creates the transaction objects that the client needs to sign.
Get Validator Objects API: The client calls this API to retrieve the transaction objects used to stake with the Beacon deposit contract.
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.
Get Validator and Provision API:
The client calls this API to receive the validator objects which were created along with their respective provision IDs.
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

Holesky Testnet

Ethereum Mainnet

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

Name

Type

Description

api-key*

String

API Key provided by Luganodes

Request Body

Name

Type

Description

attributes*

Object

{
    "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

Property

Description

Type

withdrawalAddress

Ethereum wallet address which will be used to create withdrawal credentials for the validator

String

controllerAddress

Address that can be used to sign the exit message. This field is optional

String

feeRecipient

Fee Recipient address of the validator that receive EL rewards. This field is optional

String

validatorsCount

Number of validators required

Number

batch

true will return transaction objects for a batch deposit of all validators false will return individual transaction objects for each validators

Boolean

Provision Response Object

Property

Description

Type

provisionId

Unique identifier of provisioning request

String

withdrawalAddress

Withdrawal address specified by user

String

status

status = "CREATED" will be sent as an acknowledgement

String

created

Timestamp of the creation of the provision request

String

validatorsCount

Number of validators

Number

controllerAddress

Address that can be used to sign the exit message

String

feeRecipient

Fee Recipient address of the validator that receive EL rewards

String

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

Name

Type

Description

provisionId*

String

provisioning_request_uuid:YOUR UUID

page

Number

page number to be fetched

per_page

Number

Number of results per page

Headers

Name

Type

Description

api-key*

String

API Key provided by Luganodes

{
  "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
}

{
  "batch": false,
  "depositInput": null,
  "withdrawalAddress": "0xF345A81Af5b23Ae1fD0D08f97AF1aC05fFAd825c",
  "withdrawal_credentials": "0x010000000000000000000000a08c6c9e3d0e28e0e9ef17ce67899e8e06501dd2",
  "validatorsCount": 2,
  "clientId": "0c14fc15-9562-4fbe-bf02-f86e56a57d83",
  "provisionId": "b8b3fee5-dcdd-48f9-b706-a5d5a4e8ca87",
  "provisionStatus": "CREATED",
  "results": [
    {
      "validatorIndex": null,
      "validatorAddress": "0xb98a5ce144b937c578c76fd29b6e4cd8931a64409be40d07c2c155ed246d80d7be811c2c2a82f38614939df34bf5e389",
      "amount": 32000000000,
      "created": "2024-01-24T11:47:38.493Z",
      "status": "CREATED",
      "depositInput": "0x22895118000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000e00000000000000000000000000000000000000000000000000000000000000120f26b4af336055faad90f23008dee3762b4c31832f87dc8768911939145554f5e0000000000000000000000000000000000000000000000000000000000000030b98a5ce144b937c578c76fd29b6e4cd8931a64409be40d07c2c155ed246d80d7be811c2c2a82f38614939df34bf5e389000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000020010000000000000000000000f345a81af5b23ae1fd0d08f97af1ac05ffad825c00000000000000000000000000000000000000000000000000000000000000609772ef64086dd85016a0cdb924d7bef185d2b5406d656bfef23def9bf79057b5ba425b0dc662085338d66ff3c485b53f16a670b32a03172754db5c02cf38e2b7b6a713aa9bd02995c6b67f4d50eaf536bac3411ba199343d0d01fc267a5f756b"
    },
    {
      "validatorIndex": null,
      "validatorAddress": "0x8b085da6c957e3494d72f54f593031c8087ec10a2ae969693c1bc18e61d4d2073e54d70ffdec997260998f6359c2cf47",
      "amount": 32000000000,
      "created": "2024-01-24T11:47:38.493Z",
      "status": "CREATED",
      "depositInput": "0x22895118000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000e00000000000000000000000000000000000000000000000000000000000000120147bbc9232026fc3617044feef15f28a499e24aa02f572c00b8ca5b592fc81d800000000000000000000000000000000000000000000000000000000000000308b085da6c957e3494d72f54f593031c8087ec10a2ae969693c1bc18e61d4d2073e54d70ffdec997260998f6359c2cf47000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000020010000000000000000000000f345a81af5b23ae1fd0d08f97af1ac05ffad825c00000000000000000000000000000000000000000000000000000000000000609132e6942a666d11257f110697e3b563bba66e0a0400be618de95ef8a6dcee4d0e462a5db4071076164fa7a8120e4bd60566fd1f0e9373a21138ba9f9b5cc86866d06ef618fa502c7b60630dfeddf926e6819022196be242b8894361d7f5979d"
    }
  ],
  "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

Field

Description

Type

batch

Batch Deposit

Boolean

depositInput

Data for executing the unsigned deposit transaction on the Beacon Deposit contract. Returns null for non-batch contract staking.

String

withdrawalAddress

Withdrawal address as specified by user

String

withdrawal_credentials

Withdrawal credential is derived from the withdrawal address that's used for deposit to beacon deposit contract

String

validatorsCount

Number of validators created

Number

clientId

Partner identifier associated with the API key

String

provisionId

Unique identifier of provisioning request

String

provisionStatus

String

result

Array of

Array

page

Page number of fetched results

Number

per_page

Number of results per page

Number

pages

Total number of pages

Number

total

Number of results in total

Number

Validator Result Object

Field

Description

Type

amount

amount of ETH to be deposited

Number

validatorIndex

Index of validator on Ethereum chain

Number

status

String

validatorAddress

Validator public key

String

created

Delegation object creation time

String

depositInput

Unsigned deposit object for executing the transaction on the Beacon deposit contract. This field is applicable for non-batch contract staking.

String

Validator Status Enum

Field

Description

CREATED

Validator was provisioned through Luganodes API

DEPOSITED

The deposit is waiting to be seen by the ETH chain

PENDING

Validator is in the queue waiting to go live

ACTIVE

Validator is participating and earning rewards

EXIT_REQUESTED

Exit has been requested by the client to the validator node

EXIT_SENT

Exit transaction for the validator is issued to the beacon chain

EXITED

Validator has exited from the network

UNKNOWN

Error while fetching the status of validator

Provision Status Enum

Field

Description

IN_PROGRESS

Provision request is in progress

CREATED

Provision request successfully created

FAILED

Provision request failed

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

Name

Type

Description

provisionId*

String

provisioning_request_uuid:YOUR UUID

page

Number

page number to be fetched

per_page

Number

Number of results per page

Headers

Name

Type

Description

api-key*

String

API Key provided by Luganodes

{
  "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

Field

Description

Type

batch

Batch Deposit. batch is set to false in this API

Boolean

withdrawal_credentials

Withdrawal credential is derived from the withdrawal address that's used for deposit to beacon deposit contract

String

controllerAddress

Address that can be used to sign the exit message

String

feeRecipient

fee Recipient address of the validator that receive EL rewards

String

validatorsCount

Number of validators created

Number

clientId

Partner identifier associated with the API key

String

provisionId

Unique identifier of provisioning request

String

result

Array of

Array

page

Page number of fetched results

Number

per_page

Number of results per page

Number

pages

Total number of pages

Number

total

Number of results in total

Number

Deposit Details Object

Field

Description

Type

validatorIndex

Index of validator in associated provisioning request

Number

validatorAddress

Validator public key

String

amount

32 ETH

Number

created

Delegation object creation time

String

status

String

signature

Validator signature

String

deposit_data_root

Hash of the deposit data

String

deposit_message_root

Hash of the Merkle tree’s root

String

fork_version

The version of Ethereum fork

String

Get Validator and Provision IDs

GET /api/users

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

Query Parameters

Name

Type

Description

withdrawalAddress

String

withdrawal address as specified by user

page

Number

page number to be fetched

per_page

Number

Number of results per page

Headers

Name

Type

Description

api-key*

String

API key provided by Luganodes

{
  "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

Field

Description

Type

clientID

Partner identifier associated with api key

String

result

Array of

Array

page

Page of fetched results

Number

per_page

Number of results per page

Number

pages

Total number of pages

Number

total

Number of results in total

Number

Validator Result Object

Field

Description

Type

validatorAddress

Validator Public Key

String

withdrawalAddress

Withdrawal address as specified by user

String

controllerAddress

Address that can be used to sign the exit message

String

feeRecipient

fee Recipient address of the validator that receive EL rewards

String

provisionId

Unique identifier of provisioning request

String

created-at

Timestamp of the creation of the provision request

String

status

String

validatorIndex

Index of Validator on Ethereum chain. "0" if not deposited on chain.

Number

Get Validator Count

GET /api/validators/count

Returns the number of validators by their status.

Query Parameters

Name

Type

Description

withdrawalAddress

String

withdrawal address as specified by user

page

Number

page number to be fetched

per_page

Number

Number of results per page

Headers

Name

Type

Description

api-key*

String

API key provided by Luganodes

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

Field

Description

Type

total

Total number of validators provisioned

Number

by_status

Array of validator count by status

Array

Status Object

Field

Description

Type

pending_initialized

First deposit is processed, but not enough funds are available to get validator into activation queue

Number

pending_queued

Validator is waiting to get activated, has enough funds while in the queue

Number

active_ongoing

Validator is currently active and has not initiated any exit

Number

active_slashed

Validator is still active but has a slashed status and is scheduled to exit

Number

exited_unslashed

Validator has reached exit epoch, currently not attesting and not slashed

Number

exited_slashed

Validator has reached exit epoch and was slashed

Number

withdrawal_possible

After validator has exited, the staked balance can be withdrawn

Number

withdrawal_done

Withdrawal has been processed

Number

PreviousAuthentication NextExits

Last updated 4 months ago