The following readme describes all the functions and their parameters exposed by the utils class of the K2 SDK.

​
add0x function

This function can be used to append 0x towards the start of a string to convert it into a hex string accepted by the contracts. If the input string already contains the 0x, the function will return the string as is.

​
Input Parameters

data: string which needs to be appended by 0x

​
Using add0x function

await sdk.utils.add0x(data);

​
Return Parameter

Returns hex string

​
remove0x function

This function removes 0x from the beginning of a string. If the input string doesn’t contain 0x, it will return the string as is.

​
Input Parameters

data: string to remove 0x from

​
Using remove0x function

await sdk.utils.remove0x(data);

​
Return Parameter

Returns string without 0x in the beginning.

​
generateLivenessReport function

This function can be used to generate a liveness reports of the software being run.

​
Input Parameters

middlewareAPI: API endpoint of the middleware

​
Using generateLivenessReport function

await sdk.utils.generateLivenessReport(middlewareAPI);

​
Return Parameter

Returns a liveness report. Here’s a sample liveness report:

{
  "rpbsSelfAttestation": {
    "signature": {
      "z1Hat": "6404105216342bd57fa13ea8...310b519feb117f9e25087fe584f2",
      "c1Hat": "1e4b7e54b1ba032ef94f2b89...b6ef01c823e20454c1166fb9aa19",
      "s1Hat": "1d4a3c56bf2be321d0a6aac4...7a19ed3082b21c94357e16885278",
      "c2Hat": "16755d115768ef6ebb0c45d...f4b9ffe0126b599d5d486f5574653",
      "s2Hat": "1140c70f8b38105aca1d465...3bbe9f89dbc00da6646c48aa5eaa1",
      "m1Hat": "6404223e9396cce38a9bf6a...48d0df6055de44898ecd0e0004ca4"
    },
    "commonInfo": {
      "numOfValidatorsOnline": "8",
      "numOfValidatorsOffline": "2",
      "totalValidators": "10"
    },
    "publicKey": "630409260df6b583400e97...42db0603ca1fe7766d45ac42f6c0"
  },
  "eventType": "LIVENESS",
  "version": "1",
  "eventData": {
    "numOfValidatorsOnline": "8",
    "numOfValidatorsOffline": "2",
    "totalValidators": "10",
    "proposedSlashing": "0"
  }
}

​
getMiddlewareInfo function

This function can be used to get the info from the middleware endpoint.

​
Input Parameters

middlewareAPI: API endpoint of the middleware

​
Using getMiddlewareInfo function

await sdk.utils.getMiddlewareInfo(middlewareAPI);

​
Return Parameter

The function returns info related to the middleware API. Here’s an example of the info:

{
    "VERSION":"1",
    "CHAIN_ID":"5","SERVICE_PROVIDER_BORROW_ADDRESS":"0xEa0F09A471dCe34d7d3675787B1D68D841FF56D2","K2_LENDING_CONTRACT":"0x7E015fa28e05eD002Ac166D230cD3c3726CC2e7E","K2_REPORTER_REGISTRY":"0x88Cc3B6e96ef8E78b592eaDc135a0DF31991bE20",
    "LIVENESS_ENDPOINT":"https://endpoint.amazonaws.com/goerli/liveness",
    "REPORT_DEADLINE_LENGTH_IN_ETH_BLOCKS":"125"
}

​
verifyReport function

Once the liveness or the corruption report has been generated, it needs to be verified before submitting it to the reporter registry. To verify the report, verifyReport function should be used.

​
Input Parameters

middlewareAPI: API endpoint of the middleware
report: Liveness or the corruption report returned by the respective function

​
Using verifyReport function

await sdk.utils.verifyReport(middlewareAPI, report);

​
Return Parameter

The function returns a verified report which contains the liveness report along with a signature valid for 20 minutes. Here’s how a verified report looks like:

{
  "inputs": {
    "rpbsSelfAttestation": {
      "signature": {
      "z1Hat": "6404105216342bd57fa13ea8...310b519feb117f9e25087fe584f2",
      "c1Hat": "1e4b7e54b1ba032ef94f2b89...b6ef01c823e20454c1166fb9aa19",
      "s1Hat": "1d4a3c56bf2be321d0a6aac4...7a19ed3082b21c94357e16885278",
      "c2Hat": "16755d115768ef6ebb0c45d...f4b9ffe0126b599d5d486f5574653",
      "s2Hat": "1140c70f8b38105aca1d465...3bbe9f89dbc00da6646c48aa5eaa1",
      "m1Hat": "6404223e9396cce38a9bf6a...48d0df6055de44898ecd0e0004ca4"
    },
      "commonInfo": {
        "numOfValidatorsOnline": "8",
        "numOfValidatorsOffline": "2",
        "totalValidators": "10"
      },
      "publicKey": "630409260df6b583400e97...42db0603ca1fe7766d45ac42f6c0"
    },
    "eventType": "LIVENESS",
    "version": "1",
    "eventData": {
      "numOfValidatorsOnline": "8",
      "numOfValidatorsOffline": "2",
      "totalValidators": "10",
      "proposedSlashing": "100000000000000000"
    }
  },
  "signedReport": {
    "slashType": "0",
    "debtor": "0x70997970C51812dc3A010C7d01b50e0d17dc79C8",
    "block": 9819746,
    "signature": "0x3634303432336464663333323864663263623136393239373137626261356634353366323963396637623832313062343537633436633237363731383938303230386533306432346662636537316531333061366538663364346161333731616461646464653639663834346163316464616365386363663562626632653561633166643a313838333339343262373434633436323232343865323862346465353963613930633639366530623538633336393433666362643566386136383361656461653a306631316464373530393337306632316339393534643063373432313338303632323931323734393961373961386663376633353963643434353439306363353a323631363139626337656338306630613863663333643836643430373062636465313262383138303632653437396236333235623836396438323066343933633a313662383438646230666533303561363366353061346633613661383963613165326531616165626363653630363431623865633931643438323439363335343a363430343136373630313961363065396135336563323766303835363638336433653039396130616331643938376665633165636464383663636536633866643438363232306237373165643464303836343730376334666436386631386363663831333135643533303531373964346237346233363530343933346164306130326163",
    "amount": {
      "type": "BigInt",
      "hex": "0x016345785d8a0000"
    },
    "identifier": 1
  },
  "designatedVerifierSignature": {
    "deadline": 9819746,
    "v": 27,
    "r": "0x3a61148c3a2fdd3a9fe2c6133bbddf579333a630663f0c19dce8ecfb62484392",
    "s": "0x1b4f68b48c177edf8f10f1f382cfb0c73920ecac7ed564e82909d57f119b3a11"
  }
}

​
verifyEffectiveBalance function

This function can be used to batch verify effective balance of a list of BLS public keys.

​
Input Parameters

blsPublicKeys: List of BLS public keys in string format
effectiveBalances: List of effective balance in string corresponding to each BLS public key

​
Using verifyEffectiveBalance function

await sdk.utils.verifyEffectiveBalance(blsPublicKeys, effectiveBalances);

​
Return Parameter

The function returns a list of verified effective balance report after it has been successfully verified and error otherwise.

// Format of verified effective balance reports
[
report: {
    blsKey: string,
    effectiveBalance: string
  },
  designatedVerifierSignature: {
    v: string,
    r: string,
    s: string
  }
]

​
readUsingMulticall function

Allows to read batch values from a contract in a single RPC call.

​
Input Parameters

targetContract: Address of the target contract in string format
allowFailure: Boolean. Set to true to throw error if any one value is rejected by the contract
calldata: List of calldata in string

​
Using readUsingMulticall function

await sdk.utils.readUsingMulticall(targetContract, allowFailure, calldata);

​
Return Parameter

Returns a list of response for each call data in the format:

{
  bool success; // True if the call succeeded, false otherwise.
  bytes returnData; // Return data if the call succeeded, or revert data if the call reverted.
}

The result will have to be decoded to correctly get all the values.

/// Example: decode the values from the result after using multicall read method
/// on the claimableKETHForNodeOperator function.
/// contractInterface: ABI interface of the contract that defines said function, created using ethersjs
const previewValues = multicall.map(({ success, returnData }, i) => {
  if (!success) throw new Error(`Failed to resolve data for calldata[${i}]`);
  return contractInterface.decodeFunctionResult(
    "claimableKETHForNodeOperator",
    returnData
  )[0];
});

​
getEffectiveBalance function

Get effective balance of a BLS public key from the consensus layer.

​
Input Parameters

beaconNodeUrl: Beacon node URL string
blsPublicKey: BLS public key in string format to get effective balance of

​
Using getEffectiveBalance function

await sdk.utils.getEffectiveBalance(beaconNodeUrl, blsPublicKey);

​
Return Parameter

Effective balance in numbers

​
generateCorruptionReport function

Generate corruption report from the data received from middleware API endpoint.

​
Input Parameters

middlewareAPI: API endpoint of the middleware
eventData: event data of the format CorruptionEventDataT
message: string message which needs to be mentioned in the report. Default value: ''
debtorOverride: optional debtor address. Can be left null for the function to fetch debtor address from the middlewareAPI

​
Using generateCorruptionReport function

await sdk.utils.generateCorruptionReport(
  middlewareAPI,
  eventData,
  message,
  debtorOverride
);

​
Return Parameter

Returns corruption report of the format:

{
    rpbsSelfAttestation: {
    signature: marshalledSignature,
      commonInfo: commonInfo,
      publicKey: rpbsPublicKey
    },
    eventType: "CORRUPTION",
    version: version,
    eventData: eventData,
    serviceProviderAddress: debtor
}

​
claimEffectiveBalance function

Claim effective balance for all the BLS public keys delegated by the user.

​
Input Parameters

beaconNodeUrl: Beacon node URL in string
userAddress: user address in string

​
Using claimEffectiveBalance function

await sdk.utils.claimEffectiveBalance(beaconNodeUrl, userAddress);

​
Return Parameter

Transaction hash

​
getClaimableKETHForNodeOperator function

Preview claimable effective balance for all the BLS public keys delegated by the user.

​
Input Parameters

userAddress: user address in string

​
Using getClaimableKETHForNodeOperator function

await sdk.utils.getClaimableKETHForNodeOperator(userAddress);

​
Return Parameter

List of claimable kETH in Big Numbers

​
getAllDelegetedBLSPublicKeysForNodeRunner function

Get a list of BLS public keys delegated by a node operator.

​
Input Parameters

nodeRunnerAddress: Address of the node runner in string

​
Using getAllDelegetedBLSPublicKeysForNodeRunner function

await sdk.utils.getAllDelegetedBLSPublicKeysForNodeRunner(nodeRunner);

​
Return Parameter

List of BLS public keys

​
getAllDelegetedBLSPublicKeys function

List of all the delegated BLS public keys in the K2 protocol.

​
Using getAllDelegetedBLSPublicKeys function

await sdk.utils.getAllDelegetedBLSPublicKeys();

​
Return Parameter

List of BLS public keys

The following readme describes all the functions and their parameters exposed by the utils class of the K2 SDK.

​
add0x function

This function can be used to append 0x towards the start of a string to convert it into a hex string accepted by the contracts. If the input string already contains the 0x, the function will return the string as is.

​
Input Parameters

data: string which needs to be appended by 0x

​
Using add0x function

await sdk.utils.add0x(data);

​
Return Parameter

Returns hex string

​
remove0x function

This function removes 0x from the beginning of a string. If the input string doesn’t contain 0x, it will return the string as is.

​
Input Parameters

data: string to remove 0x from

​
Using remove0x function

await sdk.utils.remove0x(data);

​
Return Parameter

Returns string without 0x in the beginning.

​
generateLivenessReport function

This function can be used to generate a liveness reports of the software being run.

​
Input Parameters

middlewareAPI: API endpoint of the middleware

​
Using generateLivenessReport function

await sdk.utils.generateLivenessReport(middlewareAPI);

​
Return Parameter

Returns a liveness report. Here’s a sample liveness report:

{
  "rpbsSelfAttestation": {
    "signature": {
      "z1Hat": "6404105216342bd57fa13ea8...310b519feb117f9e25087fe584f2",
      "c1Hat": "1e4b7e54b1ba032ef94f2b89...b6ef01c823e20454c1166fb9aa19",
      "s1Hat": "1d4a3c56bf2be321d0a6aac4...7a19ed3082b21c94357e16885278",
      "c2Hat": "16755d115768ef6ebb0c45d...f4b9ffe0126b599d5d486f5574653",
      "s2Hat": "1140c70f8b38105aca1d465...3bbe9f89dbc00da6646c48aa5eaa1",
      "m1Hat": "6404223e9396cce38a9bf6a...48d0df6055de44898ecd0e0004ca4"
    },
    "commonInfo": {
      "numOfValidatorsOnline": "8",
      "numOfValidatorsOffline": "2",
      "totalValidators": "10"
    },
    "publicKey": "630409260df6b583400e97...42db0603ca1fe7766d45ac42f6c0"
  },
  "eventType": "LIVENESS",
  "version": "1",
  "eventData": {
    "numOfValidatorsOnline": "8",
    "numOfValidatorsOffline": "2",
    "totalValidators": "10",
    "proposedSlashing": "0"
  }
}

​
getMiddlewareInfo function

This function can be used to get the info from the middleware endpoint.

​
Input Parameters

middlewareAPI: API endpoint of the middleware

​
Using getMiddlewareInfo function

await sdk.utils.getMiddlewareInfo(middlewareAPI);

​
Return Parameter

The function returns info related to the middleware API. Here’s an example of the info:

{
    "VERSION":"1",
    "CHAIN_ID":"5","SERVICE_PROVIDER_BORROW_ADDRESS":"0xEa0F09A471dCe34d7d3675787B1D68D841FF56D2","K2_LENDING_CONTRACT":"0x7E015fa28e05eD002Ac166D230cD3c3726CC2e7E","K2_REPORTER_REGISTRY":"0x88Cc3B6e96ef8E78b592eaDc135a0DF31991bE20",
    "LIVENESS_ENDPOINT":"https://endpoint.amazonaws.com/goerli/liveness",
    "REPORT_DEADLINE_LENGTH_IN_ETH_BLOCKS":"125"
}

​
verifyReport function

Once the liveness or the corruption report has been generated, it needs to be verified before submitting it to the reporter registry. To verify the report, verifyReport function should be used.

​
Input Parameters

middlewareAPI: API endpoint of the middleware
report: Liveness or the corruption report returned by the respective function

​
Using verifyReport function

await sdk.utils.verifyReport(middlewareAPI, report);

​
Return Parameter

The function returns a verified report which contains the liveness report along with a signature valid for 20 minutes. Here’s how a verified report looks like:

{
  "inputs": {
    "rpbsSelfAttestation": {
      "signature": {
      "z1Hat": "6404105216342bd57fa13ea8...310b519feb117f9e25087fe584f2",
      "c1Hat": "1e4b7e54b1ba032ef94f2b89...b6ef01c823e20454c1166fb9aa19",
      "s1Hat": "1d4a3c56bf2be321d0a6aac4...7a19ed3082b21c94357e16885278",
      "c2Hat": "16755d115768ef6ebb0c45d...f4b9ffe0126b599d5d486f5574653",
      "s2Hat": "1140c70f8b38105aca1d465...3bbe9f89dbc00da6646c48aa5eaa1",
      "m1Hat": "6404223e9396cce38a9bf6a...48d0df6055de44898ecd0e0004ca4"
    },
      "commonInfo": {
        "numOfValidatorsOnline": "8",
        "numOfValidatorsOffline": "2",
        "totalValidators": "10"
      },
      "publicKey": "630409260df6b583400e97...42db0603ca1fe7766d45ac42f6c0"
    },
    "eventType": "LIVENESS",
    "version": "1",
    "eventData": {
      "numOfValidatorsOnline": "8",
      "numOfValidatorsOffline": "2",
      "totalValidators": "10",
      "proposedSlashing": "100000000000000000"
    }
  },
  "signedReport": {
    "slashType": "0",
    "debtor": "0x70997970C51812dc3A010C7d01b50e0d17dc79C8",
    "block": 9819746,
    "signature": "0x3634303432336464663333323864663263623136393239373137626261356634353366323963396637623832313062343537633436633237363731383938303230386533306432346662636537316531333061366538663364346161333731616461646464653639663834346163316464616365386363663562626632653561633166643a313838333339343262373434633436323232343865323862346465353963613930633639366530623538633336393433666362643566386136383361656461653a306631316464373530393337306632316339393534643063373432313338303632323931323734393961373961386663376633353963643434353439306363353a323631363139626337656338306630613863663333643836643430373062636465313262383138303632653437396236333235623836396438323066343933633a313662383438646230666533303561363366353061346633613661383963613165326531616165626363653630363431623865633931643438323439363335343a363430343136373630313961363065396135336563323766303835363638336433653039396130616331643938376665633165636464383663636536633866643438363232306237373165643464303836343730376334666436386631386363663831333135643533303531373964346237346233363530343933346164306130326163",
    "amount": {
      "type": "BigInt",
      "hex": "0x016345785d8a0000"
    },
    "identifier": 1
  },
  "designatedVerifierSignature": {
    "deadline": 9819746,
    "v": 27,
    "r": "0x3a61148c3a2fdd3a9fe2c6133bbddf579333a630663f0c19dce8ecfb62484392",
    "s": "0x1b4f68b48c177edf8f10f1f382cfb0c73920ecac7ed564e82909d57f119b3a11"
  }
}

​
verifyEffectiveBalance function

This function can be used to batch verify effective balance of a list of BLS public keys.

​
Input Parameters

blsPublicKeys: List of BLS public keys in string format
effectiveBalances: List of effective balance in string corresponding to each BLS public key

​
Using verifyEffectiveBalance function

await sdk.utils.verifyEffectiveBalance(blsPublicKeys, effectiveBalances);

​
Return Parameter

The function returns a list of verified effective balance report after it has been successfully verified and error otherwise.

// Format of verified effective balance reports
[
report: {
    blsKey: string,
    effectiveBalance: string
  },
  designatedVerifierSignature: {
    v: string,
    r: string,
    s: string
  }
]

​
readUsingMulticall function

Allows to read batch values from a contract in a single RPC call.

​
Input Parameters

targetContract: Address of the target contract in string format
allowFailure: Boolean. Set to true to throw error if any one value is rejected by the contract
calldata: List of calldata in string

​
Using readUsingMulticall function

await sdk.utils.readUsingMulticall(targetContract, allowFailure, calldata);

​
Return Parameter

Returns a list of response for each call data in the format:

{
  bool success; // True if the call succeeded, false otherwise.
  bytes returnData; // Return data if the call succeeded, or revert data if the call reverted.
}

The result will have to be decoded to correctly get all the values.

/// Example: decode the values from the result after using multicall read method
/// on the claimableKETHForNodeOperator function.
/// contractInterface: ABI interface of the contract that defines said function, created using ethersjs
const previewValues = multicall.map(({ success, returnData }, i) => {
  if (!success) throw new Error(`Failed to resolve data for calldata[${i}]`);
  return contractInterface.decodeFunctionResult(
    "claimableKETHForNodeOperator",
    returnData
  )[0];
});

​
getEffectiveBalance function

Get effective balance of a BLS public key from the consensus layer.

​
Input Parameters

beaconNodeUrl: Beacon node URL string
blsPublicKey: BLS public key in string format to get effective balance of

​
Using getEffectiveBalance function

await sdk.utils.getEffectiveBalance(beaconNodeUrl, blsPublicKey);

​
Return Parameter

Effective balance in numbers

​
generateCorruptionReport function

Generate corruption report from the data received from middleware API endpoint.

​
Input Parameters

middlewareAPI: API endpoint of the middleware
eventData: event data of the format CorruptionEventDataT
message: string message which needs to be mentioned in the report. Default value: ''
debtorOverride: optional debtor address. Can be left null for the function to fetch debtor address from the middlewareAPI

​
Using generateCorruptionReport function

await sdk.utils.generateCorruptionReport(
  middlewareAPI,
  eventData,
  message,
  debtorOverride
);

​
Return Parameter

Returns corruption report of the format:

{
    rpbsSelfAttestation: {
    signature: marshalledSignature,
      commonInfo: commonInfo,
      publicKey: rpbsPublicKey
    },
    eventType: "CORRUPTION",
    version: version,
    eventData: eventData,
    serviceProviderAddress: debtor
}

​
claimEffectiveBalance function

Claim effective balance for all the BLS public keys delegated by the user.

​
Input Parameters

beaconNodeUrl: Beacon node URL in string
userAddress: user address in string

​
Using claimEffectiveBalance function

await sdk.utils.claimEffectiveBalance(beaconNodeUrl, userAddress);

​
Return Parameter

Transaction hash

​
getClaimableKETHForNodeOperator function

Preview claimable effective balance for all the BLS public keys delegated by the user.

​
Input Parameters

userAddress: user address in string

​
Using getClaimableKETHForNodeOperator function

await sdk.utils.getClaimableKETHForNodeOperator(userAddress);

​
Return Parameter

List of claimable kETH in Big Numbers

​
getAllDelegetedBLSPublicKeysForNodeRunner function

Get a list of BLS public keys delegated by a node operator.

​
Input Parameters

nodeRunnerAddress: Address of the node runner in string

​
Using getAllDelegetedBLSPublicKeysForNodeRunner function

await sdk.utils.getAllDelegetedBLSPublicKeysForNodeRunner(nodeRunner);

​
Return Parameter

List of BLS public keys

​
getAllDelegetedBLSPublicKeys function

List of all the delegated BLS public keys in the K2 protocol.

​
Using getAllDelegetedBLSPublicKeys function

await sdk.utils.getAllDelegetedBLSPublicKeys();

​
Return Parameter

List of BLS public keys