api

README

Oracle api docs

This document contains some non-exhaustive documentation for the oracle api, with some examples on how it can be used to retrieve different information from the validators such as their accumulated balance, claimable balances, proofs to claim their balance, wrong/valid/missed proposed blocks into the pool, etc.

General endpoints

Fetches the status of the oracle, indicating if the underlying consensus and execution clients are in in sync, and if the oracle is in sync and how far behind head is.

curl url:7300/status

Returns the configuration parameters of the smoothing pool.

curl url:7300/config

Returns if a given validator public key is registered in a set of relays. Use to know if a validator

curl url:7300/registeredrelays/0xb1ce83f50ba296bdfedba0e4a42a65f8cee1bdeb2ba78aaa61b452141684930406412bbef6c0f65b4121f8fc82dbb6ba

Returns the whole oracle state.

curl url:7300/state

Memory endpoints

Memory endpoints return the latest known state by the oracle.

Returns all the validators that are tracked by the smoothing pool in any state.

curl url:7300/memory/validators

Returns the configuration of the pool

curl url:7300/config

Return information of a given validator index registered in the pool.

curl url:7300/memory/validator/408120

Return information of all subscribed validators from a withdrawal address, including validators not tracked by the pool

curl url:7300/memory/validators/0xa111B576408B1CcDacA3eF26f22f082C49bcaa55

Returns information on the fees that the pool takes, such as percent, address and fees so far.

curl url:7300/memory/feesinfo

Return all proposed blocks to the pool

curl url:7300/memory/proposedblocks

Return all the missed blocks in the smoothing pool.

curl url:7300/memory/missedblocks

Return all blocks that were wrong (wrong fee recipient of subscribed validators)

curl url:7300/memory/wrongfeeblocks

Returns all blocks that the pool has knowledge of (proposedblocks, missedblocks, wrongfeeblocks)

curl url:7300/memory/allblocks

Return a list of all donations to the pool

curl url:7300/memory/donations

General statistics of the pool such as rewards received, amount of block, average reward, etc.

curl url:7300/memory/statistics

Onchain endpoints

Onchain endpoints return information from the point of view of the latest stored state (as a merkle root) in the blockchain.

Returns the merkle proofs of the given withdrawal address, that can be used on chain to claim the rewards. Note that this endpoint can be used by the account that gets the fees of the pool.

curl url:7300/onchain/proof/0xa111b576408b1ccdaca3ef26f22f082c49bcaa55

Documentation

Index

• Variables
• func AreAddressEqual(address1 string, address2 string) bool
• func IsValidAddress(v string) bool
• func IsValidIndex(v string) (uint64, bool)
• func IsValidPubkey(v string) bool
• type ApiService
  • func NewApiService(cfg *oracle.Config, cliCfg *config.CliConfig, oracle *oracle.Oracle, ...) *ApiService
  • func (m *ApiService) ApplyNonFinalizedState(subs []Subscription, unsubs []Unsubscription, ...)
  • func (m *ApiService) GetSubscriptionsTillHead(latestProcessedBlock uint64) ([]Subscription, error)
  • func (m *ApiService) GetUnsubscriptionsTillHead(latestProcessedBlock uint64) ([]Unsubscription, error)
  • func (m *ApiService) OracleReady(maxSlotsBehind uint64) bool
  • func (m *ApiService) StartHTTPServer()
• type Subscription
  • func GetSubInBlock(subs []Subscription, block uint64) []Subscription
• type Unsubscription
  • func GetUnsubInBlock(subs []Unsubscription, block uint64) []Unsubscription

Variables

var MaxSlotsBehind = uint64(64)

Oracle does not serve some endpoint if not in sync to latest finalized epoch. Some slots behind are allowed, since its normal that when a new epoch is finalized, some slots are still pending to be processed. This is the max number of slots allowed

var SlotsInOneMonth = uint64(216000)

30 days/month * 24 hours/day * 3600 seconds/day / 12 seconds/slot

Functions

func AreAddressEqual

func AreAddressEqual(address1 string, address2 string) bool

Copied from oracle/utils. Cant import due to circular dependency TODO: Move to utils package

func IsValidAddress

func IsValidAddress(v string) bool

func IsValidIndex

func IsValidIndex(v string) (uint64, bool)

func IsValidPubkey

func IsValidPubkey(v string) bool

Types

type ApiService

type ApiService struct {
	Onchain *oracle.Onchain

	ApiListenAddr string
	Network       string
	// contains filtered or unexported fields
}

func NewApiService

func NewApiService(
	cfg *oracle.Config,
	cliCfg *config.CliConfig,
	oracle *oracle.Oracle,
	onchain *oracle.Onchain) *ApiService

func (*ApiService) ApplyNonFinalizedState

func (m *ApiService) ApplyNonFinalizedState(
	subs []Subscription,
	unsubs []Unsubscription,
	validators map[uint64]*oracle.ValidatorInfo)

func (*ApiService) GetSubscriptionsTillHead

func (m *ApiService) GetSubscriptionsTillHead(latestProcessedBlock uint64) ([]Subscription, error)

TODO: unsure if move this somewhere else

func (*ApiService) GetUnsubscriptionsTillHead

func (m *ApiService) GetUnsubscriptionsTillHead(latestProcessedBlock uint64) ([]Unsubscription, error)

func (*ApiService) OracleReady

func (m *ApiService) OracleReady(maxSlotsBehind uint64) bool

func (*ApiService) StartHTTPServer

func (m *ApiService) StartHTTPServer()

type Subscription

type Subscription struct {
	Event     *contract.ContractSubscribeValidator `json:"event"`
	Validator *v1.Validator                        `json:"validator"`
}

Subscription event and the associated validator (if any) TODO: Perhaps remove, no longer need if refactored a bit

func GetSubInBlock

func GetSubInBlock(subs []Subscription, block uint64) []Subscription

type Unsubscription

type Unsubscription struct {
	Event     *contract.ContractUnsubscribeValidator `json:"event"`
	Validator *v1.Validator                          `json:"validator"`
}

Unsubscription event and the associated validator (if any) TODO: Perhaps remove, no longer need if refactored a bit

func GetUnsubInBlock

func GetUnsubInBlock(subs []Unsubscription, block uint64) []Unsubscription