Skip to main content

Stakehouse SDK

The Stakehouse SDK is a NPM package which can be used by anyone who wants to interact with the Stakehouse Protocol to:

  • Interact with the Balance Reporter smart contract
  • Retrieve a finalized epoch report from the Beacon Chain
  • Authenticate the finalized epoch report
  • Update their increased ETH balance
  • Register the validator
  • Join a Stakehouse
  • Withdraw dETH
  • Batch withdraw dETH
  • BLS Authentication
  • Rage Quit

The SDK also provides utils sub package which can be used to:

  • Self Authenticate the Keystore password
  • Format data to ensure that hex data types are correct
  • Get the lifecycle status of a validator
  • Generate BLS credentials which are Stakehouse ready
  • Sign a message to authenticate the user for off chain interactions
  • Form Deposit Data SSZ Object
  • Get the last Deposit Index
  • Get a KNOT's dETH balance in an index
  • Validate checks for rage quit
  • Calculate Exit fee required for rage quit

The constants sub package provides:

  • Contract addresses used by Stakehouse
  • URLs used by Stakehouse

Installation

To install the package use the comamnd npm i @blockswaplab/stakehouse-sdk

Balance Reporting

Balance Reporting is the process of fetching a finalized balance report, authenticating the report, and submitting the signed report to the Stakehouse protocol smart contracts. This is done to retrieve dETH associated with staking rewards. Balance Reporting have been elaborated in the Balance Reporting using the SDK section. Please refer to the link if you are not familiar.

Functions exposed in the SDK

The following functions can be imported using the stakehouse-sdk as shown below.

const { getFinalisedEpochReport,
authenticateReport,
reportBalanceIncrease,
registerValidator,
registerValidatorInitials,
createStakehouse,
joinStakehouse,
addKnotToOpenIndexAndWithdraw,
batchAddKnotToOpenIndexAndWithdraw,
BLSAuthentication,
rageQuitKnot,
rageQuit } = require("@blockswaplab/stakehouse-sdk");

Registering Validator Initials

The initial step is to register the basic data of the validator (BLS Signature generated by the validator, Ethereum EOA Address of the depositor, and the BLS Public Key of the validator.) This is necessary to perform further security checks.

registerValidatorInitials(signer, userAddress, blsPublicKey, blsSignature)

Input Parameters:

signer - signer instance of the execution layer Address of the user
userAddress - execution layer address of the user
blsPublicKey - BLS Public Key of the validator
blsSignature - BLS Signature of the provided BLS Public Key

Returns:

Transaction data

Registering a Validator

This function is the critical portion of the Stakehouse Protocol. It routes 32 ETH to the Ethereum Foundation’s Deposit Contract and collects all the data about the deposit in order to later mint derivatives related to this exact deposit. This happens only after security checks have been passed.

registerValidator(signer, userAddress, balanceReport, cipherText, aesEncryptorKey, blsSignature)

Input Parameters:

signer - signer instance of the execution layer Address of the user
userAddress - execution layer address of the user
balanceReport - Aathenticated Balance Report
cipherText - encrypted BLS signing key
aesEncryptorKey - randomly generated AES public key in the control of the CIP MPC system
blsSignature - BLS Signature of the provided BLS Public Key

Returns:

Transaction data

Creating a Stakehouse

This function allows the user to create a Stakehouse.

createStakehouse(signer, userAddress, ticker, savETHIndexId, balanceReport)

Input Parameters:

signer - signer instance of the execution layer Address of the user
userAddress - Address of the user
ticker - String name of ticker (3-5 charachters)
savETHIndexId - ID of SavETH Index
balanceReport - report obtained from authenticateReport function

Returns:

Transaction data

Joining a Stakehouse

This function allows the user to join a Stakehouse and mint their derivative tokens in the savETH registry and SLOT registry.

joinStakehouse(signer, userAddress, stakeHouseAddr, brandTokenId, savETHIndexId, balanceReport)

Input Parameters:

signer - signer instance of the execution layer Address of the user
userAddress - execution layer address of the user
stakeHouseAddr - Stakehouse Address that
brandTokenId - Brand Token ID of the Stakehouse
savETHIndexId - SavETH INdex ID of the Stakehouse
balanceReport - Balance report of validator received from the getFinalisedEpochReport

Returns:

Transaction data

Withdrawing dETH

This function allows users to move their KNOT to Open Market and withdraw their dETH.

addKnotToOpenIndexAndWithdraw(signer, stakehouseAddress, memberID, recipientAddress)

Input Parameters:

signer - signer instance of the execution layer Address of the user
stakehouseAddress : Address of Stakehouse
memberID : Member ID of the KNOT in the Stakehouse
recipientAddress : Address of Recipient who receives the dETH

Returns:

Transaction data  

Batch withdrawal of dETH

This function allows users to move a batch of KNOTs to Open Market and withdraw their dETH.

batchAddKnotToOpenIndexAndWithdraw(signer, stakehouses, memberIDs, recipient)

Input Parameters:

signer : signer instance of the execution layer Address of the user
stakehouses : Array of stakehouse addresses
memberIDs : Array of member ID of the KNOTs in the stakehouses
recipient : Array of address of recipients who receive the dETH

Returns:

Transaction data  

BLS Authentication

This function allows users to authenticate their BLS Public Key.

BLSAuthentication(keystorePassword, keystore, depositData, depositorSignaturePayload)

Input Parameters:

keystorePassword : Password of the Keystore file
keystore : Contents of the Keystore file
depositData : Deposit Data obtained when generating credentials
depositorSignaturePayload : Signature payload obtained from getPersonalSignInitials function

Returns:

BLS auth response  

Rage Quit (without pre-condition checks)

This function allows users to Rage Quit.

rageQuitKnot(signer, stakehouseAddress, balanceReport, topUpAmountInWei)

Input Parameters:

signer : signer instance of the execution layer Address of the user
stakehouseAddress : Stakehouse address of the KNOT
balanceReport : Authenticated Balance Report of the KNOT
topUpAmountInWei : Top-up amount required for the KNOT to rage quit

Returns:

Transaction data  

Rage Quit (with pre-condition checks)

This function checks for all the required conditions and allows users to Rage Quit.

rageQuit(signer, stakehouseAddress, userAddress, balanceReport)

Input Parameters:

signer : signer instance of the execution layer Address of the user
stakehouseAddress : Stakehouse address of the KNOT
userAddress : execution layer Address of the user
balanceReport : Authenticated Balance Report of the KNOT

Returns:

Transaction data  

Functions exposed in the utils sub-package.

The following functions can be imported using the utils sub-package of the SDK:

const { checkKeystorePass,
add0x,
remove0x,
getPersonalSignInitials,
generateCredentials,
getValidatorLifecycleStatus,
formDepositDataRoot,
getLastDepositIndex,
getDETHBalanceInIndex,
calculateExitFee,
rageQuitChecks } = require("@blockswaplab/stakehouse-sdk/utils");

Checking if the Keystore Password is correct

This function allows the user to check if their password follows all the requirements for the Deposit Router.

checkKeystorePass(password)

Input Parameters:

password - Password provided by the user

Returns:

boolean. `true` if the password passes all the requirements of the Ethereum Foundation’s Deposit Contract. Otherwise, `false`.

Adding 0x to a Parameter

This function adds 0x to the input parameters. Users can provide data and the function will automatically add 0x if the data doesn’t have it already.

add0x(data)

Input Parameters:

data - It can be String, Buffer or Object

Returns:

Modified data with `0x`

Removing 0x from a Parameter

This function removes 0x from the input parameter. Users can provide data and the function will automatically remove 0x if the data already has 0x.

remove0x(data)

Input Parameters:

data - It can be String, Buffer or Object

Returns:

Modified data without `0x`

Getting the Lifecycle Status of a Validator

This function lets the users know the lifecycle of any validator registered via the Stakehouse Protocol. The lifecycle status ranges from 0 to 4.
0 - Validator has had no previous interaction with the TransactionRouter.
1 - BLS Public Key and signatures of the validator are registered.
2 - The deposit of 32 ETH has been successfully registered in the EF’s Deposit Contract.
3 - Validator is correctly initiated on the Consensus Layer and derivative tokens are minted.
4 - Validator has successfully exited the Stakehouse Protocol.

getValidatorLifecycleStatus(signer, blsPublicKey)

Input Parameters:

signer - signer instance of the execution layer Address of the user
blsPublicKey - BLS Public Key of the registered validator

Returns:

Integer. Ranging from 0 to 4.

Generating BLS Credentials

This function is elaborated in the BLS Key Generator section of the docs.

generateCredentials(password)

Input Parameters:

password - Password required to encrypt the keystore file.

Returns:

a JSON data consisting of depositObject and keystore.

Follow this link to view a sample JSON file returned by this function and all the information related to it.

Sign Personal Initials

This function helps users to sign their personal initials (which consists of the BLS Public Key and BLS Signature.) This signed message helps to prove an off chain entity that the user performed a deposit transaction of 32 ETH for the given BLS Public Key.

getPersonalSignInitials(blsPublicKey, blsSignature, account)

Input Parameters:

blsPublicKey - BLS Public Key of the validator
blsSignature - BLS Signature of the provided BLS Public Key
account - ETH1 account address of the respective BLS Public Key

Returns:

JSON data consisting of JSON message, hex of the JSON message and signature of the hex

Form Deposit Data Object

This function helps users to form a DepositData SSZ object which is required by the Ethereum Foundation deposit contract. The exact fields are specified in the Beacon Chain spec which can be found here.

formDepositDataRoot(signer, blsPublicKey, blsSignature)

Input Parameters:

signer : signer instance of the execution layer Address of the user  
blsPublicKey : BLS Public Key
blsSignature : BLS Signature

Returns:

Deposit Data

Get Last Deposit Index

This function helps users fetch the last deposit index.

getLastDepositIndex(blsPubKey)

Input Parameters:

blsPubKey : BLS Public Key  

Returns:

Last Deposit Index

Get a KNOTs dETH balance in an Index

This function allows users to fetch their dETH balance in the Index

getDETHBalanceInIndex(signer, blsPublicKey)

Input Parameters:

signer : signer instance of the execution layer Address of the user
blsPublicKey : BLS Public Key

Returns:

dETH balance 

Calculate exit fee for rage quit

This function helps users to calculate the exit fee required to successfully rage quit.

calculateExitFee(signer, balanceReport)

Input Parameters:

signer : signer instance of the execution layer Address of the user  
balanceReport : Authenticated Balance Report of the KNOT

Returns:

Exit fee in wei

Check conditions for rage quit

This function checks if a KNOT is allowed to rage quit.

rageQuitChecks(signer, stakehouseAddress, userAddress, balanceReport)

Input Parameters:

signer : signer instance of the execution layer Address of the user
stakehouseAddress : Stakehouse address of the KNOT
userAddress : execution layer Address of the user
balanceReport : Authenticated Balance Report of the KNOT

Returns:

True if the KNOT is allowed to rage quit, otherwise throws error

Parameters exposed in the constants sub-package of the SDK

The following constants can be imported using the code shown below:

const { stakehouseAddresses,
stakehouseUrls } = require("@blockswaplab/stakehouse-sdk/constants");

Stakehouse Addresses

The following addresses can be obtained from the SDK:

  • Transaction Router
  • Account Manager
  • SavETH Registry
  • SavETH Batch Transaction

Stakehouse URLs

The following URLs can be obtained from the SDK:

  • stakehouseUrls.DEPOSIT_ROUTER - URL of the deposit router used by the Stakehouse Protocol.
  • stakehouseUrls.SUBGRAPH_ENDPOINTS - URL of the Subgraph API.
  • stakehouseUrls.CREDENTIAL_GENERATOR - URL of the BLS Credential Generator API provided by the Stakehouse Protocol.