---
# System prepended metadata

title: Untitled

---

### 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, 
