The Stakehouse SDK is a NPM Package which can be used to carry out everything from depositing 32ETH to the Ethereum Deposit Contract to leaving Stakehouse. The SDK supports Goerli Testnet and Ethereum Mainnet.
To install the package use the command npm i @blockswaplab/stakehouse-sdk
One of the ways to import and initialise the SDK is:
const { StakehouseSDK } = require('@blockswaplab/stakehouse-sdk');
const provider = new ethers.providers.InfuraProvider("goerli", {
projectId: INFURA_PROJECT_ID,
projectSecret: INFURA_PROJECT_SECRET
});
const signer = new ethers.Wallet(PRIV_KEY, provider);
const sdk = new StakehouseSDK(signer);
Please note that the SDK is an
ethers.js
based SDK and hence requiresethers
based signer. It also returns values inethers.js
supported format. For example, it returnsBigNumbers
for the smart contract view functions that might returnuint
.
The SDK exposes various sub-classes:
The following is a list of functionalities, their usage and directions to use them.
This function allows validators to report their updated ETH balance to the Deposit Router. Reporting a balance increase allows users to self report that a KNOT has received consensus rewards for performing duties which is reflected in dETH.
stakehouseAddress: Address of the Stakehouse
authenticatedReport: Deposit Router response obtained from the authenticateReport
function
await sdk.reportBalanceIncrease(stakehouseAddress, authenticatedReport);
Returns the transaction data
This function combines the reportBalanceIncrease
and the slash
function. If the validator's balance has increased, it calls the reportBalanceIncrease
. Otherwise, it slashes the validator.
beaconNodeURL: Consensus layer node URL
blsPublicKey: BLS Public Key of the validator
stakehouseAddress: Address of the Stakehouse
await sdk.balanceReport(beaconNodeURL, blsPublicKey, stakehouseAddress);
Returns the transaction data
This function allows users to register their validator's initials i.e. execution layer address, BLS Public Key and BLS Signature. This helps Stakehouse to maintain the data of all the validators registered via the protocol.
userAddress: Address of the user
blsPublicKey: User's BLS Public Key
blsSignature: BLS Signature
await sdk.registerValidatorInitials(userAddress, blsPublicKey, blsSignature);
Returns the transaction data
This function allows users to register their validator. After the validator's initials are registered by the protocol, this step sends 32ETH to the Ethereum Foundation's deposit contract to stake the validator. Please be very careful while using this function as this requires ETH.
userAddress: Execution layer address of the user
authenticationPackage: Return paramter of the BLSAuthentication
function
await sdk.registerValidator(userAddress, authenticationPackage);
Returns the transaction data
This function allows users to create a Stakehouse with their validator credentials
userAddress: Address of the user
ticker: String name of ticker (3-5 characters)
savETHIndexId: ID of SavETH Index. Set this to zero to auto-create a new savETH index that the depositor will own.
authenticatedReport: report obtained from authenticateReport
function
await sdk.createStakehouse(userAddress, ticker, savETHIndexId, authenticatedReport);
Returns the transaction data
This function allows users to join a Stakehouse with their validator credentials
userAddress: Address of the user
stakehouseAddress: Address of Stakehouse
brandTokenId: Token ID of Brand
savETHIndexId: ID of SavETH Index. Set this to zero to auto-create a new savETH index that the depositor will own.
authenticatedReport: report obtained from authenticateReport
function
await sdk.joinStakehouse(userAddress, stakehouseAddress, brandTokenId, savETHIndexId, authenticatedReport);
Returns the transaction data
This function allows users to move their KNOT to the Open Index and withdraw their dETH.
stakehouseAddress: Address of Stakehouse
memberID: Member ID of the KNOT in the Stakehouse
recipientAddress: Address of Recipient who receives the dETH
await sdk.addKnotToOpenIndexAndWithdraw(stakehouseAddress, memberID, recipientAddress);
Returns the transaction data
This function allows users to move a batch of KNOTs to the Open Index and withdraw their dETH.
stakehouses: Array of stakehouse addresses
memberIDs: Array of member ID of the KNOTs in the stakehouses
recipient: Address of recipient who receives the dETH
await sdk.batchAddKnotToOpenIndexAndWithdraw(stakehouses, memberIDs, recipient);
Returns the transaction data
This function allows users to move a batch of KNOTs to an index. Read more about savETH Indexes here
stakehouses: Array of stakehouse addresses
memberIDs: Array of member ID of the KNOTs in the stakehouses
targetSavETHIndexID: savETH Index where the KNOTs will be transferred
await sdk.batchTransferKnotsToSingleIndex(stakehouses, memberIDs, targetSavETHIndexID);
Returns the transaction data
This function allows users to authenticate their BLS Public Key. The authentication makes sure that the generated credentials are valid and belong to the correct network. The successful response is then used as a parameter to send 32 ETH to the Ethereum Deposit Contract.
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
await sdk.BLSAuthentication(keystorePassword, keystore, depositData, depositorSignaturePayload);
Returns the BLS Auth response
This function allows users to call Rage Quit without any pre-condition checks. A validator must still meet all the conditions prior to exiting.
stakehouseAddress: Stakehouse Address of the KNOT
authenticatedReport: Report obtained from the authenticateReport
function
topUpAmountInWei: amount of top-up required to Rage Quit.
await sdk.rageQuitKnot(stakehouseAddress, authenticatedReport, topUpAmountInWei);
Returns the transaction data
This funciton allows users to Rage Quit. The function also checks if all the conditions are satisfied for the KNOT to Rage Quit.
stakehouseAddress: Stakehouse Address of the KNOT
userAddress: Execution layer address of the user
authenticatedReport: Report obtained from the authenticateReport
function
await sdk.rageQuit(stakehouseAddress, userAddress, authenticatedReport);
Returns the transaction data
This function allows users to deposit dETH into the savETH registry
savETHRecipient: savETH receiver of the funds
amount: amount of funds being deposited into savETH
await sdk.depositIntoSavETHRegistry(savETHRecipient, amount);
Returns transaction data
This function allows users to deposit funds and isolate the KNOT into an index.
stakehouseAddress: Stakehouse address of the user
blsPublicKey: BLS Public Key of the KNOT
indexID: index ID in which the KNOT is to be isolated
await sdk.depositAndIsolateKnotIntoIndex(stakehouseAddress, blsPublicKey, indexID);
Returns the transaction data.
This function allows the user to slash any KNOT if their balance falls below the last reported balance to the Stakehouse.
stakehouseAddress: Stakehouse address of the KNOT being slashed
authenticatedReport: report obtained from the authenticateReport
function
await sdk.slash(stakehouseAddress, authenticatedReport);
Returns the transaction data.
This function allows a user to slash a KNOT with balance a below 32 ETH and then top-up the slashed SLOT tokens. The user who calls the function then becomes a collateralized owner of the slashed KNOT. A KNOT can be slashed only if the current balance has gone below the last reported balance.
stakehouseAddress: Stakehouse address of the KNOT to be slashed
slasherAddress: Execution layer address of the user calling the function. This address also receives the collateralized SLOTs.
buyAmount: amount of slashed SLOT tokens that the slasher wants to top-up denominated in WEI
ethValue: ETH to be sent along with the transaction. This amount can be higher than the top up amount (the top up amount is always capped at the amount of SLOT that is slashed) in the event that a user wishes to flush the queue by reaching the minimum amount of ETH required to send transactions to the Ethereum Deposit Contract (1 ETH).
authenticatedReport: The Report obtained from the authenticateReport
function
await sdk.slashAndTopUpSlot(stakehouseAddress, slasherAddress, buyAmount, ethValue, authenticatedReport);
Returns the transaction data
This function allows the user to create a new index and become its owner. This allows users to create savETH index portfolios for curating savETH and dETH from any KNOT in any stakehouse. Read more about savETH here.
ownerAddress: Address of the creator of the index
await sdk.createIndex(ownerAddress);
Returns the transaction data
This function allows user to approve the transfer of ownership of their savETH index
indexID: index ID of the savETH index to be transferred
spender: receiver of the savETH index
await sdk.approveTransferOfIndexOwnership(indexID, spender);
Returns the transaction data
This function allows user to transfer the owner of their index
indexID: index ID of the index being transferred
recipient: new owner of the index
await sdk.transferIndexOwnership(indexID, recipient);
Returns the transaction data
This function allows users to move their KNOT to a new index.
stakehouseAddress: Stakehouse address of the KNOT
blsPublicKey: BLS Public Key of the KNOT
newIndexID: index ID of the index that the KNOT is being transferred to
await sdk.transferKnotToAnotherIndex(stakehouseAddress, blsPublicKey, newIndexID);
Returns the transaction data
stakehouseAddress: Stakehouse address of the KNOT
blsPublicKey: BLS Public Key of the KNOT
spender: Ethereum execution layer address of the user allowed to spend dETH of the KNOT
await sdk.approveSpendingOfKnotInIndex(stakehouseAddress, blsPublicKey, spender);
Returns the transaction data
This function allows the user to join an existing Stakehouse and create a brand.
userAddress: Ethereum execution layer address of the user
brandTicker: String input for the brand name
stakehouseAddress: Stakehouse address that the KNOT wants to join
savETHIndexId: savETH Index ID. A default value of 0
will auto-create the index
authenticatedReport: report obtained from the authenticateReport
function
await sdk.joinStakeHouseAndCreateBrand(userAddress, brandTicker, stakehouseAddress, savETHIndexId, authenticatedReport);
Returns the transaction data
This function allows the user to authorize a representative to stake 32ETH and carry out other functions on behalf of them.
representative: Execution layer address of the representative
enable: Boolean. Can be set to true
to authorize representative or false
to revoke privileges
await sdk.authorizeRepresentative(representative, enable);
Returns transaction data
This function allows anyone to check whether a representative and a representee have a valid relationship.
representative: Execution layer address of the representative
representee: Execution layer address of the representee (the user being represented)
await sdk.isRepresentativeAuthorized(representative, representee);
Returns boolean. true
if a valid relationship exists, false
otherwise.
This function allows the user to deposit their 32ETH to the Ethereum Foundation deposit contract via the Stakehouse Protocol. The function does all the heavy-lifting for the user, such as registering validator's initials, signing personal initials (to be signed by the user), authenticating the BLS credentials and registering the validator. A user can go through all of these steps individually with the help of the SDK, but the deposit
function does it all in a single step. The function can either be called by the user themselves or by their representative. If the representative calls the function, they will receive an encoded
data which should be signed and sent by the user to the transaction router to deposit the 32ETH.
keystore: BLS keystore of the KNOT
password: password of the keystore
depositData: deposit data file of the KNOT
privateKey: Optional parameter. The user/representative can provide their privateKey to directly sign a transaction. If no value is provided, the transaction should be signed using the ECDSA wallet
user: Optional parameter. If the representative calls the function, they should specify the execution layer address of the representee
. Otherwise, if the user themselves are calling the function, then the parameter can be null
.
await sdk.deposit(keystore, password, depositData, privateKey=null, user=null);
Returns transaction data if the user called the function. Otherwise, returns the encoded
data if the representative calls the function.