@orbs-network/pos-analytics-lib
v0.9.8
Published
PoS analytics library. For web based queries of aggregated data.
Downloads
58
Maintainers
Keywords
Readme
ORBS PoS analytics lib
Library to use to extract PoS data of the Orbs Network (for V2).
Users
Install
npm i @orbs-network/pos-analytics-lib
Functions
- getDelegator
Used to query information about delegator's stake, previous actions and optional rewards. Funciton's input is the requested delegator's address, an Ethereum endpoint (for example infura link with apikey) and optional options object to modify output (see below).
const delegatorInfo = await getDelegator(
'0xB4D4f0E476Afe791B26B39985A65B1bC1BBAcdcA',
ethereumEndpoint
);
Or
const delegatorAndRewardsInfo = await getDelegator(
'0xB4D4f0E476Afe791B26B39985A65B1bC1BBAcdcA',
ethereumEndpoint, {read_from_block: -1000000}
);
- getDelegatorStakingRewards
Used to query information about delegator's staking rewards history & claim action history. Funciton's input is the requested delegator's address, an Ethereum endpoint (for example infura link with apikey) and optional options object to modify output (see below).
const { rewards, claimActions } = await getDelegatorStakingRewards(
'0xB4D4f0E476Afe791B26B39985A65B1bC1BBAcdcA',
ethereumEndpoint
);
- getGuardians
Used to query the list of all current Guardians and their names and weights. Function's input is a list of ORBS node management status URLs.
const guardians = await getGuardians(nodeEndpoints);
- getGuardian
Used to query a guardian's staking and delegator history, list all current delegators and event history. Function's input is the requested guardian's address, an Ethereum endpoint (for example infura link with apikey) and optional options object to modify output (see below). Please note: as long as history reading is not disabled all of the delegation history of the guardian is always read.
const guardianInfo = await getGuardian(
'0xf7ae622c77d0580f02bcb2f92380d61e3f6e466c',
ethereumEndpoint
);
Or
const guardianAndRewardsInfo = await getGuardian(
'0xf7ae622c77d0580f02bcb2f92380d61e3f6e466c',
ethereumEndpoint, {read_from_block: -1000000, read_rewards_disable: true}
);
- getGuardianStakingRewards
Used to query information about guardian's staking rewards history (both as guardian and as self-delegator) & claim action history. Funciton's input is the requested guardian's address, an Ethereum endpoint (for example infura link with apikey) and optional options object to modify output (see below).
const { rewardsAsGuardian, rewardsAsDelegator, claimActions } = await getGuardianStakingRewards(
'0xf7ae622c77d0580f02bcb2f92380d61e3f6e466c',
ethereumEndpoint
);
- getOverview
Used to get an overview of the ORBS network nodes (guardians) stakes and weight history. Function's input is a list of ORBS node management status URLs and an Ethereum endpoint.
const overview = await getOverview(nodeEndpoints, ethereumEndpoint);
- getAllDelegators
Used to get a map of all the delegators of the ORBS network (including guardians who are self-delegators) with their current staked and non-staked balances and the last block that they changed their delegation. Function's input is an Ethereum endpoint.
const delegatorMap = await getAllDelegators(ethereumEndpoint);
Helper Functions
- delegatorToXlsx
Used to translate the output of getDelegator
to xlsx format. Input is delegatorInfo object and output-type
which is one of "buffer" or "array" or "binary" or "string" or "base64" (depending what you want to do with the output).
const delegatorInfo = await getDelegator('0x1e9673315e0ada0db640c299ddd2a1d81d220180', ethereumEndpoint);
const delegatorXlsx = delegatorToXlsx(delegatorInfo, 'buffer');
fs.writeFileSync(path, delegatorXlsx);
- guardianToXlsx
Used to translate the output of getGuardian
to xlsx format. Input is guardianInfo object and output-type
which is one of "buffer" or "array" or "binary" or "string" or "base64" (depending what you want to do with the output).
const guardianInfo = await getGuardian('0xc5e624d6824e626a6f14457810e794e4603cfee2', ethereumEndpoint);
const guardianXlsx = guardianToXlsx(guardianInfo, 'buffer');
fs.writeFileSync(path, guardianXlsx);
- allDelegatorsToXlsx
Used to translate the output of getAllDelegators
to xlsx format. Input is map of Delegators ({[key: string]: Delegator}) object and output-type
which is one of "buffer" or "array" or "binary" or "string" or "base64" (depending what you want to do with the output).
const delegatorMap = await getAllDelegators(ethereumEndpoint)
const delegatorsXlsx = allDelegatorsToXlsx(guardianInfo, 'buffer');
fs.writeFileSync(path, delegatorsXlsx);
Inputs
- Address - Ethereum address of delegator or guardian to test
- EthereumEndpoit - Ethereum url for web3 http provider such as Infura (i.e: https://mainnet.infura.io/v3/)
- NodesEndpoint - a list of one or more ORBS node management status URLs (i.e: http://54.168.36.177/services/management-service/status), these will be queries in order and first one that answers is the one used.
- options (for getDelegator, getGuardian, getDelegatorStakingRewards & getGuardianStakingRewards only) - a modifier object. The default values are shown after each key:
{
read_history: true,
read_from_block: 0,
read_rewards_disable: false,
}
| Field | Explanation |
| ---------------------- | -------------------- |
| read_history
| Read the historical changes (events) from ethereum event histor and generate the corresponding arrays of values (rewards, stakes, actions etc). Default is true
A false
value is quicker but returns only the current state values of the participant (guardian or delegator) |
| read_from_block
| Start block of reading events.Possible Values: 0/-1 - block number of contract deployment (earliest available), positive - block to start from, negative - how many blocks back to start from (i.e. -500 = 500 block before 'latest')Please note you cannot query events from blocks before first contract of the type was deployed.Value has no effect if read_history is set to false
. |
| read_rewards_disable
| Read and calculate rewards slows down respons time so with this field can disable just the stake rewards part. Default is false
.Value has no effect if read_history is false
. |
Please note:
- For the functions getDelegatorStakingRewards & getGuardianStakingRewards only the
read_from_block
is used. - For function getGuardian when
read_history
is true the whole delegation history is read regardless of theread_from_block
. This also mean that staking history is also read from at least the begining of Delegation contract deployment (In full history mode there may be self-stake event before delegation).
Outputs
Please have a look at the model.ts for the full output definisions.
Contract Deployments Block Numbers
- Orbs ERC20 - 740000
- Staking Contract - 9830000
- Delegation - 11180000
- Rewards - 11145373
Development
Download
git clone https://github.com/orbs-network/pos-analytics-lib
cd pos-analytics-lib
Build
npm run build
Clean
npm run clean
Test
There is only an "E2E" like test that calls all functions of the library, to run it you must setup an Ethereum-Endpoint for web3 http provider. This can be done by setting an enviroment variable in your running IDEA named ETHEREUM_ENDPOINT
, or adding a file named .env
at the root of the directory and in that file have one line ETHEREUM_ENDPOINT=https://mainnet.infura.io/v3/<YOUR-INFURA-KEY>
Then you can run the test
npm run test
The results will be in a direcotry data
under root direcotry of the project. You will see 4 json files, one for each function call.