balanceReport sub-class
The following readme describes all the functions and their parameters exposed by the balanceReport
sub-class of the Stakehouse SDK.
getFinalisedEpochReport function
This function accepts a beacon node URL and BLS Public Key to return the most recent finalised epoch report for a validator. This report can then be authenticated using the authenticateReport function and the resulting output can be fed to the reportBalanceIncrease (and many more functions) to submit updated ETH balance to the Balance Reporter Smart Contract.
Input Parameter
beaconNodeURL: URL of the beacon chain node,
blsPublicKey: Validator's BLS Public key
Using getFinalisedEpochReport function
await sdk.balanceReport.getFinalisedEpochReport(beaconNodeURL, blsPublicKey);
Return Parameter
// This is what a finalised epoch report looks like
{
"blsPublicKey":"a97f0308ffffd1d253f35ef4d8309059b7d89fd53...",
"withdrawalCredentials":"010000000000000000000000f847b446...",
"slashed":false,
"activeBalance":"32042871296",
"effectiveBalance":"32000000000",
"exitEpoch":"18446744073709551615",
"activationEpoch":"63601",
"withdrawalEpoch":"18446744073709551615",
"currentCheckpointEpoch":66805
}
authenticateReport function
This function accepts a finalised Beacon Chain report from the user and returns Deposit Router response data if the authentication was successful, otherwise an error statement is returned.
Input Parameter
finalisedBeaconChainReport:
// This is just a sample Finalised Beacon Chain Report
{
"blsPublicKey":"a97f0308ffffd1d253f35ef4d8309059b7d89fd53...",
"withdrawalCredentials":"010000000000000000000000f847b446...",
"slashed":false,
"activeBalance":"32042871296",
"effectiveBalance":"32000000000",
"exitEpoch":"18446744073709551615",
"activationEpoch":"63601",
"withdrawalEpoch":"18446744073709551615",
"currentCheckpointEpoch":66805
}
Using authenticateReport function
await sdk.balanceReport.authenticateReport(finalisedBeaconChainReport);
Return Parameter
If the authentication was successful, then a Deposit Router response is returned. Here is how it looks like:
{
report: {
blsPublicKey: 'a97f0308ffffd1d253f35ef4d8309059b7d89f...',
withdrawalCredentials: '010000000000000000000000f847b...',
slashed: false,
activeBalance: '32042855400',
effectiveBalance: '32000000000',
exitEpoch: '18446744073709551615',
activationEpoch: '63601',
withdrawalEpoch: '18446744073709551615',
currentCheckpointEpoch: 66804
},
deadline: 6199503,
v: 27,
r: '88bf72df9e2b8e4588e26c4a50f4bfaf3746a57b52f50ee61f61...',
s: '129474d568b986e7747b46e63438ab181c861d72831b3a674cbb...'
}
Otherwise, an error response is returned for eg. 'Error: Failed to validate against multiple beacon nodes'
error will appear when the deposit router receives data from nodes that are out of sync.
getFinalisedEpochReportForMultipleBLSKeys function
This function is similar to getFinalisedEpochReport
and helps users to get finalised epoch report for multiple BLS public keys at once.
Input Parameter
beaconNodeURL: URL of the beacon chain node,
blsPublicKeys: Array of BLS public keys,
status: status of the BLS public key. Set to 'active' by default
Using getFinalisedEpochReportForMultipleBLSKeys function
await sdk.balanceReport.getFinalisedEpochReportForMultipleBLSKeys(beaconNodeURL, blsPublicKeys, status = "active");
Return Parameter
Array of finalised epoch reports for each BLS public key supplied
getDETHSweeps function
This function can be used to get all the withdrawal reports for a BLS public key in a given range of slot indexes. Withdrawals are the ETH transferred to the withdrawal address (on the execution layer) of the validators for doing to validator duties. The contracts require all the validators to report their sweeps for claiming maximum possible ETH.
Input Parameter
validatorIndex: validator index of the BLS public key
slotLowerBound: slot index to fetch sweep reports from
slotUpperBound: slot index until which the sweep reports need to be fetched
Using getDETHSweeps function
await sdk.balanceReport.getDETHSweeps(validatorIndex, slotLowerBound, slotUpperBound);
Return Parameter
Returns the sweep report data. For example, here's the sweep report for a BLS public key between the slot indexes "5719550" and "5725960".
{
sweeps: [
{ slot: 5719553, amount: 1255685, withdrawal_index: 6606934 },
{ slot: 5725952, amount: 32000000000, withdrawal_index: 6691483 }
],
sumOfSweeps: '32001255685'
}
getDETHSweepsByWithdrawalIndex function
This function is used to get sweep reports based on the withdrawal index of the validator.
Input Parameter
validatorIndex: Validator index of the BLS public key
withdrawalIndex: Last reported withdrawal index for the BLS public key which can be queried from the subgraph
sweepLimit: Number of sweep reports to fetch for the validator
Using getDETHSweepsByWithdrawalIndex function
await sdk.balanceReport.getDETHSweepsByWithdrawalIndex(validatorIndex, withdrawalIndex, sweepLimit);
Return Parameter
This function returns sweep reports for the BLS public key.
calculateSumOfSweeps function
This function can be used to calculate the sum of all the sweep reports. To get the sweep report use getDETHSweepsByWithdrawalIndex
or getDETHSweeps
function. The function needs only the sweep array and not the sumOfSweeps
param returned along with the sweeps. The sweeps array should not include the final sweep.
Input Parameter
sweeps: Array of sweep reports to calculate sum of
Using calculateSumOfSweeps function
sdk.balanceReport.calculateSumOfSweeps(sweeps);
Return Parameter
Sum of all the sweeps
generateDETHReport function
This function is used to generate a dETH report for a validator with all the sweeps that need to be reported. This is needed as the sweep report by itself doesn't contain much information and is of no use by itself to the contracts.
Input Parameter
beaconNodeUrl: URL of the beacon node to fetch finalised report for the BLS public key
blsPublicKey: BLS public key of the validator
totalETHSentToBLSKey: Total amount of ETH sent to the BLS public key on beacon chain
sweeps: Array of formatted sweeps to be reported for the BLS public key. To format sweeps use the function formatSweepReportForDepositRouter
. The sweeps array should not include the final sweep
totalSumOfSweeps: Sum of all the sweeps to be reported
Using generateDETHReport function
await sdk.balanceReport.generateDETHReport(beaconNodeUrl, blsPublicKey, totalETHSentToBLSKey, sweeps, totalSumOfSweeps);
Return Parameter
A dETH report containing all the information about the BLS public key and sweeps. Here's an example:
{
"totalETHSentToBLSKey": "32000000000",
"beaconChainReport": {
"validatorIndex": "392014",
"blsPublicKey": "9852a8ddf48a3594baebd073813c4d4544d771c5513169f5124ca307ed3295553db5cebe7db4000645207035113a4be1",
"withdrawalCredentials": "010000000000000000000000952295078a226bf40c8cb076c16e0e7229f77b28",
"slashed": false,
"activeBalance": "32002163444",
"effectiveBalance": "32000000000",
"exitEpoch": "18446744073709551615",
"activationEpoch": "126121",
"withdrawalEpoch": "18446744073709551615",
"currentCheckpointEpoch": 185906,
"lastDepositIndex": "187214"
},
"blsPublicKey": "0x9852a8ddf48a3594baebd073813c4d4544d771c5513169f5124ca307ed3295553db5cebe7db4000645207035113a4be1",
"sumOfAllSweeps": "1854713",
"sweeps": [
{
"index": 2342681,
"validatorIndex": "392014",
"recipient": "0x952295078a226bf40c8cb076c16e0e7229f77b28",
"amount": 1854713,
"slotInfo": {
"slot": 5380713
}
}
]
}
formatSweepReportForDepositRouter function
This function can be used to format the sweep reports in the way the deposit router expects. Without formatting, the deposit router will ignore any sweep report and will not generate a valid signature needed by the contracts. This function is designed to format final sweep report, but reporting 50+ sweeps at once during the full withdrawal causes the deposit router to timeout (as it again verifies the reports with multiple sources), so it is advised to report sweeps time to time and this function can be provided a modified input param to make it use for a normal sweep report and not just final sweep report.
Input Parameter
unreportedSweeps: Array of sweeps returned by the previously discussed sweep report functions
finalSweep: Final sweep generated from the generateFinalSweep
function. If the function is being used for a normal sweep report, this input param can be provided a modified object such as:
{ sweep: { slot: 0, amount: 0, withdrawalIndex: 0 } }
validatorIndex: Index of the BLS public key
Using formatSweepReportForDepositRouter function
await sdk.balanceReport.formatSweepReportForDepositRouter(unreportedSweeps, finalSweep, validatorIndex);
Return Parameter
A formatted sweep report which can be sent to deposit router for verification. A formatted sweep report looks like:
[
{
index: 6606934,
validatorIndex: '431826',
recipient: '0x952295078a226bf40c8cb076c16e0e7229f77b28',
amount: 1255685,
slotInfo: { slot: 5719553 }
},
{
index: 6691483,
validatorIndex: '431826',
recipient: '0x952295078a226bf40c8cb076c16e0e7229f77b28',
amount: 32000000000,
slotInfo: { slot: 5725952 }
}
]
verifyDETHReport function
This function is used to verify the sweep reports received before reporting them to the contracts. The deposit router compares these sweep reports with similar reports fetched from 3 different nodes for the same validator. If all of them match, the report is verified and returned along with a signature. To get the dETH report use the function generateDETHReport
.
Input Parameter
dETHReport: dETH report returned by the generateDETHReport
function
Using verifyDETHReport function
await sdk.balanceReport.verifyDETHReport(dETHReport);
Return Parameter
This function returns a dETH report with a valid signature ready to be reported to the contracts. Here's an example verified report:
{
validatorInfo: {
blsPublicKey: 'b2983849759edb443a306e852d99b91143e709604becb9d6ddb0d9c64118eb0abef36799e2ce857a0d522f9bc26fb964',
validatorIndex: '431826',
withdrawalCredentials: '010000000000000000000000952295078a226bf40c8cb076c16e0e7229f77b28',
slashed: false,
activeBalance: '0',
effectiveBalance: '0',
exitEpoch: '178663',
activationEpoch: '156274',
withdrawalEpoch: '178919',
currentCheckpointEpoch: 195289
},
sweeps: [
{
index: 6606934,
validatorIndex: '431826',
recipient: '0x952295078a226bf40c8cb076c16e0e7229f77b28',
amount: 1255685,
slotInfo: [Object]
}
],
sumOfAllSweeps: '1255685',
sumOfTotalETHSentToBLSKey: '32000000000',
designatedVerifierSignature: {
deadline: 9483272,
v: 27,
r: '0xbb8e660094b6a642f85884b8a03453781a4cfe6a99a0a14dc961e31b2b825597',
s: '0x3f4de958db1b38c6238c33fab1dcdae0423e994a4eed6ace2f6ba2b359af6197'
}
}
generateFinalReport function
When a validator has exited from the beacon chain and would want to withdraw all the associated ETH from the contracts, the validator needs to report all unreported sweeps along with the final report. To do so, the user needs to generate a final report, verify it and report it to the contracts. Once done, all the users that hold LP tokens for this BLS public key will be able to claim ETH based on their pro-rata share. It is advised to report all the sweeps (except for the final sweep) separately (unless they are less in number) to avoid router timeout and an easy flow.
Input Parameter
beaconNodeUrl: URL of the beacon node
blsPublicKey: BLS public key to generate final report for
totalETHSentToBLSKey: Total ETH deposited for the BLS public key on beacon chain
sumOfUnreportedSweeps: Sum of all the sweep reports being reported along with the final report
unreportedSweeps: Array of all the unreported sweeps to be reported along with the final report
finalSweep: The last sweep report for the BLS public key. Usually this last sweep amount will be 32 ETH, unless the validator was leaking or slashed in which case it will be less than 32 ETH.
Using generateFinalReport function
await sdk.balanceReport.generateFinalReport(beaconNodeUrl, blsPublicKey, totalETHSentToBLSKey, sumOfUnreportedSweeps, unreportedSweeps, finalSweep);
Return Parameter
This function returns a report consisting of all the unreported sweeps and the final sweep report, along with additional data.
verifyFinalReport function
This function is used to verify the final report generated by the generateFinalReport
function. Once verified, the report can be sent to the contracts (after formatting as per the contract's needs).
Input Parameter
unreportedSweeps: Unformatted array of sweep reports
finalReport: Final report returned by the generateFinalReport
function
Using verifyFinalReport function
await sdk.balanceReport.verifyFinalReport(unreportedSweeps, finalReport);
Return Parameter
Returns final report along with the signature which can then be reported to the contracts.
formatSweepReport function
This function is used to format sweep report as needed by the contracts.
Input Parameter
sweeps: Unformatted array of sweep reports returned by the getDETHSweeps
function
validatorIndex: Validator index of the BLS public key
Using formatSweepReport function
await sdk.balanceReport.formatSweepReport(sweeps, validatorIndex);
Return Parameter
Returns formatted sweep report.
formatSweepReportFromDepositRouterToContractStructure function
This function can be used to format a sweep report directly returned by the deposit router. The formatting helps to re-structure the sweep report in a single step.
Input Parameter
formattedDepositRouterSweepReport: Sweep report received from the deposit router after verification
Using formatSweepReportFromDepositRouterToContractStructure function
await sdk.balanceReport.formatSweepReportFromDepositRouterToContractStructure(formattedDepositRouterSweepReport);
Return Parameter
Returns formatted sweep report in line with the contract specified structure.
isSweepReported function
This is a utility function which can be used as a pre-check to know if the sweep report was already reported to the contracts or not.
Input Parameter
withdrawalIndex: Withdrawal index of the sweep report to check if it was reported or not
Using isSweepReported function
await sdk.balanceReport.isSweepReported(withdrawalIndex);
Return Parameter
Returns boolean value. true
if reported, false
otherwise.
getListOfUnreportedWithdrawalIndexes function
This function can be used to filter out the unreported withdrawal indexes from an array of withdrawal indexes. All the sweeps reported to the contract will be ignored and the function returns an array of unreported withdrawal indexes. This is necessary as the contracts will revert if an already reported sweep report is reported again.
Input Parameter
withdrawalIndexes: Array of withdrawal indexes
Using getListOfUnreportedWithdrawalIndexes function
await sdk.balanceReport.getListOfUnreportedWithdrawalIndexes(withdrawalIndexes);
Return Parameter
Returns array of unreported withdrawal indexes.
getStartAndEndSlotByValidatorIndex function
This function can be used to fetch the start and end slot index for a validator. This is needed to further fetch all the sweep reports within the bounded slot indexes. If the validator is active, then the end slot index will be the most recent withdrawal slot index. In case the validator has exited, the last withdrawal slot index will be the end slot index.
Input Parameter
validatorIndex: Validator index of the BLS public key to fetch slot index range for
Using getStartAndEndSlotByValidatorIndex function
await sdk.balanceReport.getStartAndEndSlotByValidatorIndex(validatorIndex);
Return Parameter
Array containing the start and end slot. End slot index will be the first value in the array and the start slot index will be the second value in the array.
getFinalSweep function
This function allows the user to fetch the final sweep report for a validator. This final sweep report is needed when the validator has exited the beacon chain and the user needs to execute full withdrawal in order to receive all the ETH that has been previously transferred from the consensus layer to the account manager.
Input Parameter
beaconNodeUrl: URL of the beacon node
validatorIndex: Validator index of the BLS public key to get final sweep report for
Using getFinalSweep function
await sdk.balanceReport.getFinalSweep(beaconNodeUrl, validatorIndex);
Return Parameter
Returns the final sweep report object which has following structure:
{
"sweep": {
"index",
"validatorIndex",
"recipient",
"amount"
},
"slot",
"block"
}
generateShanghaiSweepReport function
This function is used to generate Shanghai sweep report in the correct format as needed by the contracts.
Input Parameter
blsPublicKey: BLS public key
stakehouseAddress: Stakehouse address of the BLS public key
totalETHSentToBLSKey: Total ETH deposited for the BLS public key on consensus layer
sumOfAllSweeps: Sum of all the sweeps for which the sweep report is being generated
formattedSweepReports: Formatted sweep reports
Using generateShanghaiSweepReport function
await sdk.balanceReport.generateShanghaiSweepReport(blsPublicKey, stakehouseAddress, totalETHSentToBLSKey, sumOfAllSweeps, formattedSweepReports);
Return Parameter
Formatted Shanghai Sweep report.