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 to create the transaction objects needed to sign

2. Get Delegation Objects API: The client calls this API to receive the transaction objects that are used to stake with the Ethereum staking contract

3. Add Stake API: The client calls this API add more stake to an existing validator by retrieving the transaction objects used to stake with the Beacon deposit contract.

4. Active Indexes API

   The client calls this API to receive indexes of all current active validators associated with an API key.

The Node Provisioning APIs allow clients to spin up new Ethereum nodes via APIs. The APIs can be used to create and receive the transaction objects that need to be signed using the Ethereum Staking contract. The APIs involved are

API Reference

Provisioning Request

POST /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.

Query Parameters

Name	Type	Description
api_key*	String	API Key provided by Luganodes

Request Body

Name	Type	Description
attributes*	Object	Attributes Object

200: OK

{
    "clientId": "994e7c18-731d-41de-94c7-fba818ab4fc4",
    "created": "2023-07-05T06:03:38.101Z",
    "status": "CREATED",
    "uuid": "0911b005-decd-4086-aef9-708e5e4bb401",
    "attributes": {
        "validators": [
            {
                "count": 10
            }
        ],
        "withdrawalKey": "0x0100000000000000000000007e2a2fa2a064f693f0a55c5639476d913ff12d05"
        "compounding":true,
        "amountPerValidator":33, 
    }
}

Attributes Object

Property	Description	Type
eth1Address*	Ethereum wallet address which will be used to create withdrawal credentials for the validator	String
validators*	Array of Validator Config Object	Array
compounding	true will return transaction objects for 0x02 type withdrawal credentials false will return transactions objects for 0x01 type withdrawal credentials NOTE: 0x02 type validators can accommodate stake between 32 - 2048 ETH and are eligible for partial withdrawals. Default is false	Boolean
amountPerValidator	Stake amount that can be set for each validator with 0x02 type withdrawal credentials. Default is 32 ETH	Number

Validator Config Object

// example request body   
{
 "attributes": {
        "eth1address": "0x0100000000000000000000007e2a2fa2a064f693f0a55c5639476d913ff12d05",
        "compounding":true, // optional
        "amountPerValidator":33, // optional
        "validators": [ // only one object and should contain the count
            {
                "count": 10 
            }
        ]
    }
} 

The validators property in the request body accepts an array as its value. This enables easy migration from the previous staking provider. The array must possess only one object with count as the sole property of that object.

A maximum of 100 nodes can only be requested in a single Provision request. To do more, a new Provision request can be triggered

Provisioning Response Object

Property	Description	Type
uuid	Unique identifier of provisioning request	String
withdrawalKey	withdrawal key added to the validators	String
status	Provisioning request status - "CREATED"	String
clientId	Client identifier associated with api key	String
attributes	attributes object that is passed in the request's body	Object
created	Timestamp of the creation of the provision request	String

Get Delegation Objects

GET /validators

Fetch the transaction objects that need to be signed by sending the UUID received in the Provisioning Request API.

Query Parameters

Name	Type	Description
api_key*	String	API key provided by Luganodes
filters*	String	provisioning_request_uuid:YOUR UUID
page	Number	page number to be fetched
per_page	Number	Number of results per page

200: OK paginated response containing delegation objects

{
    "results": [
        {
            "address": "8bfa7f6d6d402cde2506c5b3ac4f7e97e87a0602dbb17d2856c04ae1bb5fa0e14eb5c3bab9316ebcd03e0ada9f5f54fb",
            "id": "4e101e24-b7ba-4991-96b4-19b66ade5cf2",
            "attributes": {
                "count": 10,
                "index": 0,
                "depositInput": "0x2895118000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000e00000000000000000000000000000000000000000000000000000000000000120a1771582fd3bc89b2afecc304fafd54dc114c9822992b9186b5c41ea1dd3822f00000000000000000000000000000000000000000000000000000000000000308bfa7f6d6d402cde2506c5b3ac4f7e97e87a0602dbb17d2856c04ae1bb5fa0e14eb5c3bab9316ebcd03e0ada9f5f54fb000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000020009b201e75b311a871532528454fa85b290b60e9d47d50b7b9a36cc252ad9dbb0000000000000000000000000000000000000000000000000000000000000060ad1c95f419e1e4bd51531334080d93699897b5720f105b0ab7b2e7f035a0b69903fa4318434ae4f9f3b00e9f5dcf25a403f58e3fe07d47ccd08af5fbcfa2c3c39e3230247766e889774370d41126454c3a7cc54e63d88b1fcac012798cba0e38",
                "validatorKey": "8bfa7f6d6d402cde2506c5b3ac4f7e97e87a0602dbb17d2856c04ae1bb5fa0e14eb5c3bab9316ebcd03e0ada9f5f54fb"
            },
            "amount": "32000000000",
            "created": "2023-06-29T04:34:28.862Z",
            "status": "PENDING",
            "clientId": "b5537a4d-bee9-441c-90a8-f46d326ca5b6",
            "provisioning_request_uuid": "0911b005-decd-4086-aef9-708e5e4bb401"
        },
        {
            "address": "b1b213f3452d1c05bb2b92d2e73903b0b643c7aa5babf279c7e1059dca9a197153716cd1fb1af822668d6247d3514b9a",
            "id": "4e101e24-b7ba-4991-96b4-19b66ade5cf2",
            "attributes": {
                "count": 10,
                "index": 1,
                "depositInput": "0x2895118000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000e00000000000000000000000000000000000000000000000000000000000000120c6730ba94b536198e6436077173b89411ed9482cbc03c58ad9dab89ef3b542ce0000000000000000000000000000000000000000000000000000000000000030b1b213f3452d1c05bb2b92d2e73903b0b643c7aa5babf279c7e1059dca9a197153716cd1fb1af822668d6247d3514b9a00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002000985913ffb530ca10282fc016e3e3f52c2789fbb6a0d6a5e6ea56e31534e88f000000000000000000000000000000000000000000000000000000000000006097f3580e85143c7b49da0a420fb372d4887ca632aa7c9ae54ce438ba2be449422a458f45077c15ab990b662d8176215f0b531e31ae0e81af7642d153ae9dcc12366e85765bd83c1d67f3ce95a779b921cefdf965d79cc376f9543414b8b93eac",
                "validatorKey": "b1b213f3452d1c05bb2b92d2e73903b0b643c7aa5babf279c7e1059dca9a197153716cd1fb1af822668d6247d3514b9a"
            },
            "amount": "32000000000",
            "created": "2023-06-29T04:34:28.862Z",
            "status": "PENDING",
            "clientId": "b5537a4d-bee9-441c-90a8-f46d326ca5b6",
            "provisioning_request_uuid": "0911b005-decd-4086-aef9-708e5e4bb401"
        },
        {
            "address": "919a3954bed9022f467a735205eef6b32e5b63c149f5821867e6efb18d61f83743219349d61bdfba263fad95ba8154c0",
            "id": "4e101e24-b7ba-4991-96b4-19b66ade5cf2",
            "attributes": {
                "count": 10,
                "index": 2,
                "depositInput": "0x2895118000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000e00000000000000000000000000000000000000000000000000000000000000120c3608278e5d7a9a5274f0b955353371ec3e2f95cfc4528ed83c8245d190f23d80000000000000000000000000000000000000000000000000000000000000030919a3954bed9022f467a735205eef6b32e5b63c149f5821867e6efb18d61f83743219349d61bdfba263fad95ba8154c0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000020002ff74f2f650cf92d4b0cc280598cd2b07d244718a171a2c1ee66a52d537d6600000000000000000000000000000000000000000000000000000000000000608f6e7284e1053373e506fa155002e3493382b35e7d1435d185ea0af3f82577df59de266f3c20f2f110dbd328067b7fde0cd56f3c3b5e09841a723452d109b0abf02592e580af74463aad1598b76b5b12fe8072468e951aefbf9bea018365f228",
                "validatorKey": "919a3954bed9022f467a735205eef6b32e5b63c149f5821867e6efb18d61f83743219349d61bdfba263fad95ba8154c0"
            },
            "amount": "32000000000",
            "created": "2023-06-29T04:34:28.862Z",
            "status": "PENDING",
            "clientId": "b5537a4d-bee9-441c-90a8-f46d326ca5b6",
            "provisioning_request_uuid": "0911b005-decd-4086-aef9-708e5e4bb401"
        },
    ],
    "page": 1,
    "per_page": 3,
    "total": 10,
    "pages": 4
}

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

Paginated Response Object

Field	Description	Type
results	Array of ETH2 delegation 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

Delegation Object

Field	Description	Type
id	Identifier of delegation object	String
address	Validator public key	String
attributes	Delegation attributes object	Object
amount	Amount currently delegated	String
created	Delegation object creation time	String
status	Delegation status enum	String
clientId	Partner identifier associated with api key	String
provisioning_request_uuid	Associated provisioning request unique identifier	String

Delegation Attributes Object

Field	Description	Type
count	Total number of validators in associated provisioning request	Number
index	Index of validator in associated provisioning request	Number
depositInput	Validator deposit transaction data	String
validatorKey	Validator public key	String

Delegation Status Enum

Field	Description
CREATED	Validator was provisioned through Luganodes API
DEPOSITED	Deposit is waiting to be seen by ETH2 chain
PENDING	Validator is in the queue waiting to go live
ACTIVE	Validator is participating and earning rewards
EXIT_SENT	Exit transaction for the validator is issued
EXITED	Validator has exited from the network
UNKNOWN	Error while fetching the status of validator

Add Stake Request

POST /validators/add-stake

Submits a request to generate the transaction objects required to stake with the beacon deposit contract. This request allows users to add more stake to only active validators having 0x02 type withdrawal credentials. If validator does not have 0x02 type withdrawal credentials, it can be switched through the Switch API.

Query Parameters

Name	Type	Description
api_key*	String	API Key provided by Luganodes

Request Body

Name	Type	Description
address*	String	Public address of validator
amount*	Number	Amount to be staked

200: OK Add Stake Response Object

{
    "address": "0x81d90c9600a4fc1f69dfe4b4e3e708abb162b2122f2ef56ea79b48708c809005cc105b8e554856ce16a5c597dbfe1770",
    "addStakeAmount": 33000000000,
    "depositInput": "0x22895118000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000e00000000000000000000000000000000000000000000000000000000000000120a7d807a1cac3d595c52f7b56aa5c17883e405ed1d654929dce97754ecef25170000000000000000000000000000000000000000000000000000000000000003081d90c9600a4fc1f69dfe4b4e3e708abb162b2122f2ef56ea79b48708c809005cc105b8e554856ce16a5c597dbfe17700000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000200200000000000000000000008c24b68141552e0844354b0b638031918caafaeb0000000000000000000000000000000000000000000000000000000000000060906721ab6235bc3d9f4291fe35faf9e579c1de843b3c421ff2fbc0e7eaccd80d7389969970b5ca69f43ecd644df9107d0995880a9bf7028f2f31b425cff23a735f7d29f1488443ba96d579d6db8371527757a73030b2d1f6e6832cfbea231c03"
}

Add stake operations can only be performed on active validators and cannot exceed a balance of 2048 ETH. Additionally. this operation can only be performed on 0x02 type validators.

Sample Request

curl --location '{{url}}/api/validators/add-stake?api_key=B4GOl%%3D' \
--header 'Content-Type: application/json' \
--data '{
    "address":"b938fb66a7794767f1d9a115cba6b3be8385474531c4572d7067bb1051cc00eaef35f9c38690fa3fb2bf46e1f5b3d8b8",
    "amount":33
}'

Types

Add Stake Response Object

Property	Description	Type
address	Public address of validator	String
addStakeAmount	Amount which needs to be staked	Object
depositInput	Unsigned deposit object for executing the transaction on the Beacon deposit contract.	String

Get Active Indexes

GET /active-indexes

Fetch the indexes of all current active validators associated with an API key.

Query Parameters

Name	Type	Description
api_key*	String	API key provided by Luganodes

200: OK Response

{
    "activeIndexes": [
        1169390,
        1170062,
        1170052,
        1170049,
        1170055,
        1370059,
        1670060
       
    ]
}

Response Object

Field	Description	Type
activeIndexes	Array of indexes of all active validators	Array