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.