### Outline
* Who & Why
* Current Documentation & Data Models
* Validators
* Beacon Chain
* Questions
* Wishlist
* Aggregations
* Advanced Use Cases
## Who & Why
This is a document addressing Ethereum 2.0 data visibility enabling monitoring, health, statistics & alerting for all participants in the ecosystem.
#### Who
* Blockchain operators - Miners, Validators, Node Operators, Aggregators, Ethereum Foundation
* Developers - Core, Smart Contract
* Users - Single/multiple address owners, token holders, perform transactions
* Business - DEX, DeFi, DAO, Etc
#### Why
* Transparency, Health, Sustainability, Community
## Current Documentation & Data Models:
* Sigmaprime REST https://app.swaggerhub.com/apis/spble/lighthouse_rest_api/0.1.0
* Prysmatic Labs REST https://api.prylabs.net/
* Prysmatic Labs PRD https://docs.google.com/document/d/1LmlF0meuzx7LN8fSkuZWtGSZy1K0ZgyTIwL0zdR8Or0/edit#
* Eth 2.0 Spec https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md
* NOTE: I've used JSON notations, which is what I'd expect the API to return.
* Beacon Chain Proto: https://github.com/prysmaticlabs/ethereumapis/blob/master/eth/v1alpha1/beacon_chain.proto
* https://github.com/protolambda/eth2-docs
#### Alert Schema
```json
{
code: Number, // Example: 1001
status: String, // Example: 'validator_activated'
level: Enum, // Example: 'HIGH', Options: 'DEBUG', 'LOW', 'MED', 'HIGH'
payload: Object, // Includes all relevant data pertaining to status & alert type
}
```
## Validators
#### 1. My Validator Alerting
Including but not limited to:
* Rewards: [HIGH] Penalties, Proposals, Whistleblower
* Status: [HIGH] Activated, Exited, Ejected, Deposited, etc
* Participation
* Block Level: [MED] Wrong fork, never seen, skipped, invalid
* All Attestations: [LOW] never seen, skipped, invalid, non-canonical
###### Rewards Example:
* REF: https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#proposerslashing
* Data Sources:
* https://api.prylabs.net/eth/v1alpha1/beacon/blocks
* https://app.swaggerhub.com/apis/spble/lighthouse_rest_api/0.1.0#/Phase0/get_chain_beacon_blocks
```json
{
code: Number, // TBD
status: 'validator_penalty',
level: 'HIGH',
payload: {
eth_penalty: Wei, // Total penalty in Wei
slashed: Boolean,
public_key: String,
epoch: String,
proposer_index: String,
aggregation_bitfield: Bytes,
}
}
```
###### Status Example:
* REF: https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#voluntaryexit
* Data Sources:
* https://api.prylabs.net/eth/v1alpha1/beacon/blocks
* https://app.swaggerhub.com/apis/spble/lighthouse_rest_api/0.1.0#/Phase0/get_chain_beacon_blocks
```json
{
code: Number, // TBD
status: 'voluntary_exit',
level: 'HIGH',
payload: {
public_key: String,
epoch: String,
validator_index: String,
signature: Bytes,
}
}
```
###### Participation Example:
* REF: https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#attestation
* Data Sources:
* https://api.prylabs.net/eth/v1alpha1/beacon/blocks
* https://app.swaggerhub.com/apis/spble/lighthouse_rest_api/0.1.0#/Phase0/get_chain_beacon_blocks
```json
{
code: Number, // TBD
status: 'attestation_skipped',
level: 'LOW',
payload: {
public_key: String,
aggregation_bitfield: Bytes,
custody_bitfield: Bytes,
signature: Bytes,
data: AttestationData,
}
}
```
#### 2. ALL Validators Level Alerting
Including but not limited to:
* Participation: [MED] Percent of total below/above X
* Status: [MED] Totals above/below X
* Rewards: [-] ?? Seems too static to be needed
###### Participation Example:
* REF: https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#beaconstate
* Data Sources:
* https://api.prylabs.net/eth/v1alpha1/beacon/blocks
* https://app.swaggerhub.com/apis/spble/lighthouse_rest_api/0.1.0#/Phase0/get_chain_beacon_blocks
```json
{
code: Number, // TBD
status: 'attestations_low',
level: 'MED',
payload: {
total_attestations: Number,
total_validators: Number,
eth_balance: Wei,
eth_eligible_balance: Wei,
total_previous_epoch_attestations: Number,
total_current_epoch_attestations: Number,
participation_rate: Number, // ether balance vs eligible ether
validator_threshold: Number,
churn_limit: Number,
validator_registry: Array,
}
}
```
###### Status Example:
* REF: https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#beaconstate
* Data Sources:
* https://api.prylabs.net/eth/v1alpha1/beacon/blocks
* https://app.swaggerhub.com/apis/spble/lighthouse_rest_api/0.1.0#/Phase0/get_chain_beacon_blocks
```json
{
code: Number, // TBD
status: 'validators_low',
level: 'MED',
payload: {
total_validators: Number,
validator_threshold: Number,
churn_limit: Number,
validator_registry: Array,
}
}
```
#### 3. View My Validator Balance, Rewards & Participation Overall
Including but not limited to:
* Participation rate, attestation totals & rate,
* Status: Activated At, Activation Epoch, Withdrawal Epoch, Voluntary Exit, status: pendingActivation/pendingExit, Activated, Exited, Ejected
###### Data Example:
* REF:
* Data Sources:
* https://api.prylabs.net/eth/v1alpha1/validator/duties?public_keys=
* https://api.prylabs.net/eth/v1alpha1/validator/block
* https://api.prylabs.net/eth/v1alpha1/validator/attestation
* https://app.swaggerhub.com/apis/spble/lighthouse_rest_api/0.1.0#/Phase0/get_validator_duties
* https://app.swaggerhub.com/apis/spble/lighthouse_rest_api/0.1.0#/Phase0/get_validator_block
* https://app.swaggerhub.com/apis/spble/lighthouse_rest_api/0.1.0#/Phase0/get_validator_attestation
```json
{
public_key: String,
withdrawal_credentials: String,
attestations_total: Number,
proposals_total: Number, // Total number of proposed slots, which may or may not have been included
eth_balance: Wei, // Total validator Ether balance
eth_effective_balance: Wei, // Total validator Ether balance available for voting(?)
participation_rate: Number, // total voting ether vs total eligible ether
eth_transfer_in: Wei, // Total validator Ether amount transfered to this validator, from rewards or transactions
eth_transfer_out: Wei, // Total validator Ether amount transfered from this validator, from rewards or transactions
activation_eligibility_epoch: String,
activation_epoch: String,
exit_epoch: String,
withdrawable_epoch: String,
slashed: Boolean,
status: {
type: Enum, // Options: 'pending_voluntary_exit', 'voluntary_exit', 'pending_activation', 'activated', 'pending_exit', 'exited', 'pending_ejection', 'ejected'
code: '0x1',
},
}
```
#### 4. View My Validator Balances & Rewards Over Time
###### Data Example:
* REF:
* Data Sources:
* https://api.prylabs.net/eth/v1alpha1/validator/block
* https://api.prylabs.net/eth/v1alpha1/validators/balances
* https://app.swaggerhub.com/apis/spble/lighthouse_rest_api/0.1.0#/Phase0/get_validator_block
* https://app.swaggerhub.com/apis/spble/lighthouse_rest_api/0.1.0#/Phase0/get_chain_beacon_validators_balances
```json
{
eth_balances: [Wei],
eth_effective_balances: [Wei],
eth_rewards: [Wei],
eth_penalties: [Wei],
eth_withdrawals: [Wei],
}
```
#### 5. View My Validator Participation(s) Over Time
###### Data Example:
* REF:
* Data Sources:
* https://api.prylabs.net/eth/v1alpha1/validator/block
* https://api.prylabs.net/eth/v1alpha1/validator/duties?public_keys=
* https://app.swaggerhub.com/apis/spble/lighthouse_rest_api/0.1.0#/Phase0/get_validator_block
* https://app.swaggerhub.com/apis/spble/lighthouse_rest_api/0.1.0#/Phase0/get_validator_duties
```json
{
pending_attestations: [
{
epoch: String,
finalized: Boolean,
timestamp: String,
attestations: Number,
eth_voted: Wei,
eth_eligible: Wei,
participation_rate: Number,
}
],
finalized_attestations: [
{
epoch: String,
finalized: Boolean,
timestamp: String,
attestations: Number,
eth_voted: Wei,
eth_effective_balance: Wei,
participation_rate: Number,
}
],
duties: [
{
public_key: String,
attestation_slot: String,
attestation_shard: String,
block_proposal_slot: String
}
]
}
```
#### 6. View ALL Validators List Overall (Current Accepted Validators)
###### Data Example:
* REF:
* Data Sources:
* https://api.prylabs.net/eth/v1alpha1/validators
* https://app.swaggerhub.com/apis/spble/lighthouse_rest_api/0.1.0#/Phase0/get_chain_beacon_validators
```json
{
epoch: String,
total_validators: Number,
validators: [
{
public_key: String,
withdrawal_credentials: String,
activation_eligibility_epoch: String,
activation_epoch: String,
exit_epoch: String,
withdrawal_epoch: String,
effective_balance: Wei,
slashed: Boolean, // Can this be a timestamp? or only slashed once, ever?
eth_eligible: Wei,
participation_rate: Number,
}
]
}
```
#### 7. View ALL Validators Activation/Exit Queue
* Get a list of validators activating & exiting for current block/epoch
* Get a list of pending validators
###### Current validator activation/exits
* REF:
* Data Sources:
* https://api.prylabs.net/eth/v1alpha1/validators/queue
* https://app.swaggerhub.com/apis/spble/lighthouse_rest_api/0.1.0#/Phase0/get_chain_beacon_validators_queue
```json
{
churn_limit: String,
total_validators: Number,
total_activating: Number,
total_exiting: Number,
validators_activating: [
{
public_key: String,
withdrawal_credentials: String,
activation_eligibility_epoch: String,
activation_epoch: String,
exit_epoch: String,
withdrawal_epoch: String,
effective_balance: Wei,
slashed: Boolean,
}
],
validators_exiting: [
{
public_key: String,
withdrawal_credentials: String,
activation_eligibility_epoch: String,
activation_epoch: String,
exit_epoch: String,
withdrawal_epoch: String,
effective_balance: Wei,
slashed: Boolean,
}
],
}
```
#### 8. View ALL Validators Participation
* Current state
* Historical snapshots
* Retention (activated time, exit time, average across X blocks/epochs)
###### Participation Example:
* REF:
* Data Sources:
* https://api.prylabs.net/eth/v1alpha1/validators/participation
* https://app.swaggerhub.com/apis/spble/lighthouse_rest_api/0.1.0#/Phase0/get_chain_beacon_validators_participation
```json
{
global_participation_rate: Number,
participation: [ // NOTE: First item will always be current state
{
epoch: String,
total_validators: Number,
total_activated: Number,
total_exited: Number,
total_ejected: Number,
voted_ether: String,
eligible_ether: String
}
]
}
```
###### Retention Example:
* REF:
* Data Sources:
* https://api.prylabs.net/eth/v1alpha1/validators/participation
* https://api.prylabs.net/eth/v1alpha1/validators/activesetchanges
* https://app.swaggerhub.com/apis/spble/lighthouse_rest_api/0.1.0#/Phase0/get_chain_beacon_validators_participation
* https://app.swaggerhub.com/apis/spble/lighthouse_rest_api/0.1.0#/Phase0/get_chain_beacon_validators_activesetchanges
```json
{
retention: [
[
{
ts: Date,
validators: Number,
},
],
[],
...
]
}
```
#### 9. View Block/Epoch Level Validators Participation
###### Data Example:
* REF:
* Data Sources:
* https://api.prylabs.net/eth/v1alpha1/beacon/blocks
* https://app.swaggerhub.com/apis/spble/lighthouse_rest_api/0.1.0#/Phase0/get_chain_beacon_blocks
```json
{
epoch: String,
block_root: String,
validators: Array, // List of unique validators public_key's, participated in block
attestations: [
{
aggregation_bitfield: String,
data: {
block_root: String,
source_epoch: String,
source_root: String,
target_epoch: String,
target_root: String,
crosslink: {
shard: String,
start_epoch: String,
end_epoch: String,
parent_root: String,
data_root: String
}
},
signature: String
}
]
}
```
#### 10. View Pending Attestations & Validators Participation
###### Data Example:
* REF:
* Data Sources:
* https://api.prylabs.net/eth/v1alpha1/beacon/attestations/pending
* https://api.prylabs.net/eth/v1alpha1/validators/assignments
* https://app.swaggerhub.com/apis/spble/lighthouse_rest_api/0.1.0#/Phase0/get_chain_beacon_validators_assignments
* https://app.swaggerhub.com/apis/spble/lighthouse_rest_api/0.1.0#/Phase0/get_chain_beacon_attestations_pending
```json
{
epoch: String,
assignments: [
{
crosslink_committees: [
String
],
shard: String,
slot: String,
proposer: Boolean,
public_key: String
}
],
pending_attestations: [
{
aggregation_bitfield: String,
data: {
block_root: String,
source_epoch: String,
source_root: String,
target_epoch: String,
target_root: String,
crosslink: {
shard: String,
start_epoch: String,
end_epoch: String,
parent_root: String,
data_root: String
}
},
signature: String
}
]
}
```
## Beacon Chain
#### 1. Beacon Chain Alerts
* Finality: [MED] Forks, Slots, block fullness, Totals above/below X
* Participation: [LOW] Percent of total below/above X, operations/etc
###### Finality Example:
* REF: https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#beaconstate
* REF: https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#beaconblock
* REF: https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#beaconblockbody
* REF: https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#beacon-operations
* Data Sources:
* https://api.prylabs.net/eth/v1alpha1/node/genesis
* https://api.prylabs.net/eth/v1alpha1/beacon/chainhead
* https://app.swaggerhub.com/apis/spble/lighthouse_rest_api/0.1.0#/Phase0/get_node_genesis_time
* https://app.swaggerhub.com/apis/spble/lighthouse_rest_api/0.1.0#/Phase0/get_chain_beacon_chainhead
```json
{
code: Number, // TBD
status: 'finality_time_high',
level: 'MED',
payload: {
// TBD
previous_justified_epoch: String,
current_justified_epoch: String,
previous_justified_root: String,
current_justified_root: String,
justification_bitfield: String,
finalized_epoch: String,
finalized_root: String,
genesis_time: String,
timestamp: String,
}
}
```
###### Participation Example:
* REF: https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#beacon-operations
* Data Sources:
* https://api.prylabs.net/eth/v1alpha1/beacon/blocks
* https://app.swaggerhub.com/apis/spble/lighthouse_rest_api/0.1.0#/Phase0/get_chain_beacon_blocks
```json
{
code: Number, // TBD
status: 'beacon_block_operations_high',
level: 'HIGH',
payload: {
// TBD
}
}
```
#### 2. Beacon Chain Client Alerts
* Connectivity: [HIGH] Peers or networking issues
* Status/State: [LOW] Sync, Root Hash
* Runtime: [LOW] Health, size, cpu, etc
###### Participation Example:
* REF: https://github.com/ethereum/eth2.0-specs/blob/master/specs/core/0_beacon-chain.md#beacon-operations
* Data Sources:
* https://api.prylabs.net/eth/v1alpha1/beacon/blocks
* https://app.swaggerhub.com/apis/spble/lighthouse_rest_api/0.1.0#/Phase0/get_chain_beacon_blocks
```json
{
code: Number, // TBD
status: 'beacon_block_operations_high',
level: 'HIGH',
payload: {
// TBD
}
}
```
#### 3. Get to Beacon Chain Client Status & Info
Including but not limited to:
* Status
* Peers & Connectivity (Latency, peer total, processing times)
* Sync state/status
* capacity/usage
* Fork - orphans, time & depth, responsible party
* Finality - forks & depths, penalty/reward ratio
###### Node information
* REF: https://app.swaggerhub.com/apis/spble/beacon_node_api_for_validator/0.2.0
* REF: https://api.prylabs.net/
* Data Sources:
* https://api.prylabs.net/eth/v1alpha1/beacon/chainhead
* https://api.prylabs.net/eth/v1alpha1/node/services
* https://api.prylabs.net/eth/v1alpha1/node/syncing
* https://api.prylabs.net/eth/v1alpha1/node/version
* https://app.swaggerhub.com/apis/spble/lighthouse_rest_api/0.1.0#/Phase0/get_node_version
* https://app.swaggerhub.com/apis/spble/lighthouse_rest_api/0.1.0#/Phase0/get_node_syncing
* https://app.swaggerhub.com/apis/spble/lighthouse_rest_api/0.1.0#/Phase0/get_chain_beacon_chainhead
* https://app.swaggerhub.com/apis/spble/lighthouse_rest_api/0.1.0#/Phase0/get_node_network_peer_count
* https://app.swaggerhub.com/apis/spble/lighthouse_rest_api/0.1.0#/Future/get_node_stats
* https://app.swaggerhub.com/apis/spble/lighthouse_rest_api/0.1.0#/Future/get_node_network_stats
```json
{
status: Enum, // Example: 'connected'
peer_id: String,
version: String,
metadata: String,
sync_status: {
starting_block: Number,
current_block: Number,
highest_block: Number,
},
peers: Array,
// Optional Properties or Configuration
capacity: {
size: Number, //
used: Number, //
},
}
```
#### 4. Get Beacon Chain Rewards By Block/Epoch Hash
###### Data Example:
* REF:
* Data Sources:
* https://api.prylabs.net/eth/v1alpha1/beacon/blocks
* https://app.swaggerhub.com/apis/spble/lighthouse_rest_api/0.1.0#/Phase0/get_chain_beacon_blocks
```json
{
total_block_reward: Number,
total_block_penalties: Number,
total_slots_reward: Number,
total_slots_penalties: Number,
total_epoch_reward: Number,
total_epoch_penalties: Number,
}
```
#### 5. Get Beacon Chain Totals By Block/Epoch Hash
* validators (including activated, exited, rewarded, etc)
* proposals/attestations & percentages (can be calc'd on FE)
* rewards
* finality & fork info (when applicable)
* Transactions
* Total Times (epoch, block, slot)
###### Data Example:
* REF:
* Data Sources:
* https://api.prylabs.net/eth/v1alpha1/beacon/blocks
* https://api.prylabs.net/eth/v1alpha1/validators/participation
* https://app.swaggerhub.com/apis/spble/lighthouse_rest_api/0.1.0#/Phase0/get_chain_beacon_blocks
* https://app.swaggerhub.com/apis/spble/lighthouse_rest_api/0.1.0#/Phase0/get_chain_beacon_validators_participation
```json
{
global_participation_rate: Number,
total_proposer_slashings: Number,
total_attester_slashings: Number,
total_attestations: Number,
total_validators: Number,
total_validators_activated: Number,
total_validators_exited: Number,
total_validators_ejected: Number,
total_attestations: Number,
total_proposals: Number,
total_shards: Number,
total_crosslinks: Number,
total_deposits: Number,
total_rewards: Wei,
total_penalties: Wei,
total_transfers_amount: Wei,
total_transfers: Number,
total_block_time: Number,
block_root: String,
block_slot: String,
finalized_slot: String,
finalized_block_root: String,
justified_slot: String,
justified_block_root: String,
previous_justified_slot: String,
previous_justified_block_root: String
}
```
#### 6. Block & Epoch Stats Over Time
* validators, participation, duties, attestations
* penalties, rewards, value
###### Data Example:
* REF:
* Data Source:
```json
{
// TBD
}
```
#### 7. Get Deposit Contract Stats
* TBD? See "Genesis" definitions, this contract will live on ETH 1 chain.
* Who holds the keys to the "Deposit" contract?
* How much staked ETH?
###### Data Example:
* REF:
* Data Source:
```json
{
// TBD
}
```
## Questions
1. [x] Committees - how do I get this? (For given slot/block, which validators? I saw how to get it for specific epoch)
2. [x] Deposit contract - where is this development taking place, who is responsible?
3. [x] Slashed is a Boolean: When did validator get slashed? How many times? (Is this a dumb question?)
4. [x] What types of data can I get from a node? I stubbed peers, capacity, sync status, is there other important info?
5. [x] Where/How can i get information on block/epoch rewards? (Assuming this is a sumation of validators activities and using protocol gwei values) - validator status: a big state transitions - list of structs with bools, did they attest/etc, this is used for rewards and penalties based on that. Check that I can get that list
6. [x] Where/How can i get a list of pending validators? (guessing this requires observing the deposit contract) - activation on /queue
## Aggregations
#### 1. Balances over time
#### . Participation over time
#### . ETH Values - Rewards, Penalties, Stakes
#### . Vanity Totals: deposits, validators, crosslinks, shards, attestations,
Sign in with Wallet
Connect another wallet