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

• Provision Request

  • Sample Request

  • Types

    • Attributes Object

    • Provision Response Object

• Get Validator Objects

  • Sample Request

  • Types

    • Paginated Response Object

    • Validator Result Object

    • Provision Status Enum

    • Validator Status Enum

• Get Deposit Details

  • Sample Request

  • Types

    • Paginated Response Object

    • Deposit Details Object

• Get Validator and Provision ID

  • Sample Request

  • Types

    • Paginated Response Object

    • Validator Result Object

• Get Validator Count

  • Sample Request

  • Types

    • Result Object

    • Status Object

Supported Environments

Luganodes supports the following environments on ETH, as defined below

https://holesky.eth-staking.lgns.net	Holesky Testnet
https://mainnet.eth-staking.lgns.net	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	Attributes Object

200: OK Provision Response 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

200: OK Batch Contract Response

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

200: OK Non-Batch Contract Response

{
  "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	Status of provision request	String
result	Array of validator objects	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	Validator 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

200: OK Response with deposit details

{
  "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 deposit details objects	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	Validator 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

200: OK

{
  "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 Validator Objects	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	Validator Status	String
validatorIndex	Index of Validator on Ethereum chain	Number

Get Validator Count

GET /api/validators/count

Returns the number of validators by their status.

Headers

Name	Type	Description
api-key*	String	API key provided by Luganodes

Response

200

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