@blockswaplab/stakehouse-sdk

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.

Installation

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

Using 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 requires ethers based signer. It also returns values in ethers.js supported format. For example, it returns BigNumbers for the smart contract view functions that might return uint.

The SDK exposes various sub-classes:

• utils
• subgraph
• multipartyRageQuit
• cip
• balanceReport
• constants
• contractInstance

The following is a list of functionalities, their usage and directions to use them.

reportBalanceIncrease function

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.

Input Parameters

stakehouseAddress: Address of the Stakehouse
authenticatedReport: Deposit Router response obtained from the authenticateReport function

Using reportBalanceIncrease function

await sdk.reportBalanceIncrease(stakehouseAddress, authenticatedReport);

Return Parameter

Returns the transaction data

balanceReport function

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.

Input Parameters

beaconNodeURL: Consensus layer node URL
blsPublicKey: BLS Public Key of the validator
stakehouseAddress: Address of the Stakehouse

Using balanceReport function

await sdk.balanceReport(beaconNodeURL, blsPublicKey, stakehouseAddress);

Return Parameter

Returns the transaction data

registerValidatorInitials function

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.

Input Parameters

userAddress: Address of the user
blsPublicKey: User's BLS Public Key
blsSignature: BLS Signature

Using registerValidatorInitials function

await sdk.registerValidatorInitials(userAddress, blsPublicKey, blsSignature);

Return Parameter

Returns the transaction data

registerValidator function

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.

Input Parameters

userAddress: Execution layer address of the user
authenticationPackage: Return paramter of the BLSAuthentication function

Using registerValidator function

await sdk.registerValidator(userAddress, authenticationPackage);

Return Parameter

Returns the transaction data

createStakehouse function

This function allows users to create a Stakehouse with their validator credentials

Input Parameters

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

Using createStakehouse function

await sdk.createStakehouse(userAddress, ticker, savETHIndexId, authenticatedReport);

Return Parameter

Returns the transaction data

joinStakehouse function

This function allows users to join a Stakehouse with their validator credentials

Input Parameters

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

Using joinStakehouse function

await sdk.joinStakehouse(userAddress, stakehouseAddress, brandTokenId, savETHIndexId, authenticatedReport);

Return Parameter

Returns the transaction data

addKnotToOpenIndexAndWithdraw function

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

Input Parameters

stakehouseAddress: Address of Stakehouse
memberID: Member ID of the KNOT in the Stakehouse
recipientAddress: Address of Recipient who receives the dETH

Using addKnotToOpenIndexAndWithdraw function

await sdk.addKnotToOpenIndexAndWithdraw(stakehouseAddress, memberID, recipientAddress);

Return Parameter

Returns the transaction data

batchAddKnotToOpenIndexAndWithdraw function

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

Input Parameters

stakehouses: Array of stakehouse addresses
memberIDs: Array of member ID of the KNOTs in the stakehouses
recipient: Address of recipient who receives the dETH

Using batchAddKnotToOpenIndexAndWithdraw function

await sdk.batchAddKnotToOpenIndexAndWithdraw(stakehouses, memberIDs, recipient);

Return Parameter

Returns the transaction data

batchTransferKnotsToSingleIndex function

This function allows users to move a batch of KNOTs to an index. Read more about savETH Indexes here

Input Parameters

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

Using batchAddKnotToOpenIndexAndWithdraw function

await sdk.batchTransferKnotsToSingleIndex(stakehouses, memberIDs, targetSavETHIndexID);

Return Parameter

Returns the transaction data

BLSAuthentication function

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.

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

Using BLSAuthentication function

await sdk.BLSAuthentication(keystorePassword, keystore, depositData, depositorSignaturePayload);

Return Parameter

Returns the BLS Auth response

rageQuitKnot function

This function allows users to call Rage Quit without any pre-condition checks. A validator must still meet all the conditions prior to exiting.

Input Parameters

stakehouseAddress: Stakehouse Address of the KNOT
authenticatedReport: Report obtained from the authenticateReport function
topUpAmountInWei: amount of top-up required to Rage Quit.

Using rageQuitKnot function

await sdk.rageQuitKnot(stakehouseAddress, authenticatedReport, topUpAmountInWei);

Return Parameter

Returns the transaction data

rageQuit function

This funciton allows users to Rage Quit. The function also checks if all the conditions are satisfied for the KNOT to Rage Quit.

Input Parameters

stakehouseAddress: Stakehouse Address of the KNOT
userAddress: Execution layer address of the user authenticatedReport: Report obtained from the authenticateReport function

Using rageQuit function

await sdk.rageQuit(stakehouseAddress, userAddress, authenticatedReport);

Return Parameter

Returns the transaction data

depositIntoSavETHRegistry function

This function allows users to deposit dETH into the savETH registry

Input Parameters

savETHRecipient: savETH receiver of the funds
amount: amount of funds being deposited into savETH

Using depositIntoSavETHRegistry function

await sdk.depositIntoSavETHRegistry(savETHRecipient, amount);

Return Parameter

Returns transaction data

depositAndIsolateKnotIntoIndex function

This function allows users to deposit funds and isolate the KNOT into an index.

Input Parameters

stakehouseAddress: Stakehouse address of the user
blsPublicKey: BLS Public Key of the KNOT
indexID: index ID in which the KNOT is to be isolated

Using depositAndIsolateKnotIntoIndex function

await sdk.depositAndIsolateKnotIntoIndex(stakehouseAddress, blsPublicKey, indexID);

Return Parameter

Returns the transaction data.

slash function

This function allows the user to slash any KNOT if their balance falls below the last reported balance to the Stakehouse.

Input Parameters

stakehouseAddress: Stakehouse address of the KNOT being slashed
authenticatedReport: report obtained from the authenticateReport function

Using slash function

await sdk.slash(stakehouseAddress, authenticatedReport);

Return Parameter

Returns the transaction data.

slashAndTopUpSlot function

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.

Input Parameters

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

Using slashAndTopUpSlot function

await sdk.slashAndTopUpSlot(stakehouseAddress, slasherAddress, buyAmount, ethValue, authenticatedReport);

Return Parameter

Returns the transaction data

createIndex function

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.

Input Parameters

ownerAddress: Address of the creator of the index

Using createIndex function

await sdk.createIndex(ownerAddress);

Return Parameter

Returns the transaction data

approveTransferOfIndexOwnership function

This function allows user to approve the transfer of ownership of their savETH index

Input Parameters

indexID: index ID of the savETH index to be transferred
spender: receiver of the savETH index

Using approveTransferOfIndexOwnership function

await sdk.approveTransferOfIndexOwnership(indexID, spender);

Return Parameter

Returns the transaction data

transferIndexOwnership function

This function allows user to transfer the owner of their index

Input Parameters

indexID: index ID of the index being transferred
recipient: new owner of the index

Using transferIndexOwnership function

await sdk.transferIndexOwnership(indexID, recipient);

Return Parameter

Returns the transaction data

transferKnotToAnotherIndex function

This function allows users to move their KNOT to a new index.

Input Parameters

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

Using transferKnotToAnotherIndex function

await sdk.transferKnotToAnotherIndex(stakehouseAddress, blsPublicKey, newIndexID);

Return Parameter

Returns the transaction data

approveSpendingOfKnotInIndex function

Input Parameters

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

Using approveSpendingOfKnotInIndex function

await sdk.approveSpendingOfKnotInIndex(stakehouseAddress, blsPublicKey, spender);

Return Parameter

Returns the transaction data

joinStakeHouseAndCreateBrand function

This function allows the user to join an existing Stakehouse and create a brand.

Input Parameters

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

Using joinStakeHouseAndCreateBrand function

await sdk.joinStakeHouseAndCreateBrand(userAddress, brandTicker, stakehouseAddress, savETHIndexId, authenticatedReport);

Return Parameter

Returns the transaction data

authorizeRepresentative function

This function allows the user to authorize a representative to stake 32ETH and carry out other functions on behalf of them.

Input Parameters

representative: Execution layer address of the representative
enable: Boolean. Can be set to true to authorize representative or false to revoke privileges

Using authorizeRepresentative function

await sdk.authorizeRepresentative(representative, enable);

Return Parameter

Returns transaction data

isRepresentativeAuthorized function

This function allows anyone to check whether a representative and a representee have a valid relationship.

Input Parameters

representative: Execution layer address of the representative
representee: Execution layer address of the representee (the user being represented)

Using isRepresentativeAuthorized function

await sdk.isRepresentativeAuthorized(representative, representee);

Return Parameter

Returns boolean. true if a valid relationship exists, false otherwise.

deposit function

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.

Input Parameters

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.

Using deposit function

await sdk.deposit(keystore, password, depositData, privateKey=null, user=null);

Return Parameter

Returns transaction data if the user called the function. Otherwise, returns the encoded data if the representative calls the function.