Teku (v21.4.1+6-gaf1a961)

License: Apache 2.0

Overview

A minimal API specification for the beacon node, which enables a validator to connect and perform its obligations on the Ethereum 2.0 phase 0 beacon chain.

Authentication

All endpoints requires the use of basic auth with a standard Ethereum project ID as the username, and project secret as the password if required in the project's settings.

basicAuth

Security Scheme Type HTTP
HTTP Authorization Scheme basic

Choose a Network

Use one of these endpoints as your Ethereum 2 client provider.

Network URL
Beacon Mainnet https://eth2-beacon-mainnet.infura.io
Beacon Pyrmont Testnet https://eth2-beacon-pyrmont.infura.io

Rate Limiting

During the beta, a global rate limit per Infura account of 5 requests per second is enforced. If you need more than this, please contact us.

Beacon

Get chain genesis details

Retrieve details of the chain's genesis which can be used to identify chain.

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get state root

Calculates HashTreeRoot for state with given 'state_id'. If stateId is root, same value will be returned.

Authorizations:
path Parameters
state_id
required
string

State identifier. Can be one of: "head" (canonical head in node's view), "genesis", "finalized", "justified", <slot>, <hex encoded stateRoot with 0x prefix>.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get state fork

Returns Fork object for state with given 'state_id'.

Authorizations:
path Parameters
state_id
required
string

State identifier. Can be one of: "head" (canonical head in node's view), "genesis", "finalized", "justified", <slot>, <hex encoded stateRoot with 0x prefix>.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get state finality checkpoints

Returns finality checkpoints for state with given 'state_id'. In case finality is not yet achieved, checkpoint should return epoch 0 and ZERO_HASH as root.

Authorizations:
path Parameters
state_id
required
string

State identifier. Can be one of: "head" (canonical head in node's view), "genesis", "finalized", "justified", <slot>, <hex encoded stateRoot with 0x prefix>.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get validators from state

Returns filterable list of validators with their balance, status and index.

Authorizations:
path Parameters
state_id
required
string

State identifier. Can be one of: "head" (canonical head in node's view), "genesis", "finalized", "justified", <slot>, <hex encoded stateRoot with 0x prefix>.

query Parameters
id
Array of strings

Either hex encoded public key (with 0x prefix) or validator index

status
Array of strings

valid values: pending_initialized, pending_queued, active_ongoing, active_exiting, active_slashed, exited_unslashed, exited_slashed, withdrawal_possible, withdrawal_done

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get validator from state

Returns validator specified by state and id or public key along with status and balance.

Authorizations:
path Parameters
state_id
required
string

State identifier. Can be one of: "head" (canonical head in node's view), "genesis", "finalized", "justified", <slot>, <hex encoded stateRoot with 0x prefix>.

validator_id
required
string

Either hex encoded public key (with 0x prefix) or validator index

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get validator balances from state

Returns filterable list of validator balances.

Authorizations:
path Parameters
state_id
required
string

State identifier. Can be one of: "head" (canonical head in node's view), "genesis", "finalized", "justified", <slot>, <hex encoded stateRoot with 0x prefix>.

query Parameters
id
Array of strings

Either hex encoded public key (with 0x prefix) or validator index

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get committees at state

Retrieves the committees for the given state.

Authorizations:
path Parameters
state_id
required
string

State identifier. Can be one of: "head" (canonical head in node's view), "genesis", "finalized", "justified", <slot>, <hex encoded stateRoot with 0x prefix>.

query Parameters
epoch
string

uint64 Epoch number to query.

index
string

uint64 Committee index to query.

slot
string

UInt64 Slot to query in the canonical chain.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get block headers

Retrieves block headers matching given query. By default it will fetch current head slot blocks.

Authorizations:
query Parameters
slot
string
parent_root
string

Not currently supported.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get block header

Retrieves block header for given block id.

Authorizations:
path Parameters
block_id
required
string

Block identifier. Can be one of: "head" (canonical head in node's view), "genesis", "finalized", <slot>, <hex encoded blockRoot with 0x prefix>.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Publish a signed block

Submit a signed beacon block to the beacon node to be imported. The beacon node performs the required validation.

Authorizations:
Request Body schema: application/json
object (BeaconBlock)
signature
string <byte>

Bytes96 hexadecimal

Responses

Request samples

Content type
application/json
{
  • "message": {
    },
  • "signature": "string"
}

Get block

Retrieves block details for given block id.

Authorizations:
path Parameters
block_id
required
string

Block identifier. Can be one of: "head" (canonical head in node's view), "genesis", "finalized", <slot>, <hex encoded blockRoot with 0x prefix>.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get block root

Retrieves hashTreeRoot of BeaconBlock/BeaconBlockHeader

Authorizations:
path Parameters
block_id
required
string

Block identifier. Can be one of: "head" (canonical head in node's view), "genesis", "finalized", <slot>, <hex encoded blockRoot with 0x prefix>.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get block attestations

Retrieves attestations included in requested block.

Authorizations:
path Parameters
block_id
required
string

Block identifier. Can be one of: "head" (canonical head in node's view), "genesis", "finalized", <slot>, <hex encoded blockRoot with 0x prefix>.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get attestations

Retrieves attestations known by the node but not necessarily incorporated into any block.

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Submit signed attestations

Submit signed attestations to the beacon node to be validated and submitted if valid.

This endpoint does not protected against slashing.

Authorizations:
Request Body schema: application/json
Array ()
aggregation_bits
string <byte>

SSZ hexadecimal

object (AttestationData)
signature
string <byte>

Bytes96 hexadecimal

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Get AttesterSlashings

Retrieves attester slashings known by the node but not necessarily incorporated into any block.

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Submit attester slashing object

Submits attester slashing object to node's pool and if passes validation node MUST broadcast it to network.

Authorizations:
Request Body schema: application/json
object (IndexedAttestation)
object (IndexedAttestation)

Responses

Request samples

Content type
application/json
{
  • "attestation_1": {
    },
  • "attestation_2": {
    }
}

Get proposer slashings

Retrieves proposer slashings known by the node but not necessarily incorporated into any block.

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Submit proposer slashing object

Submits proposer slashing object to node's pool and if passes validation node MUST broadcast it to network.

Authorizations:
Request Body schema: application/json
object (SignedBeaconBlockHeader)
object (SignedBeaconBlockHeader)

Responses

Request samples

Content type
application/json
{
  • "signed_header_1": {
    },
  • "signed_header_2": {
    }
}

Get signed voluntary exits

Retrieves voluntary exits known by the node but not necessarily incorporated into any block.

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Submit signed voluntary exit

Submits signed voluntary exit object to node's pool and if it passes validation node MUST broadcast it to network.

Authorizations:
Request Body schema: application/json
object (VoluntaryExit)
signature
string <byte>

Bytes96 hexadecimal

Responses

Request samples

Content type
application/json
{
  • "message": {
    },
  • "signature": "string"
}

Validator Required Api

Get chain genesis details

Retrieve details of the chain's genesis which can be used to identify chain.

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get state fork

Returns Fork object for state with given 'state_id'.

Authorizations:
path Parameters
state_id
required
string

State identifier. Can be one of: "head" (canonical head in node's view), "genesis", "finalized", "justified", <slot>, <hex encoded stateRoot with 0x prefix>.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get validator from state

Returns validator specified by state and id or public key along with status and balance.

Authorizations:
path Parameters
state_id
required
string

State identifier. Can be one of: "head" (canonical head in node's view), "genesis", "finalized", "justified", <slot>, <hex encoded stateRoot with 0x prefix>.

validator_id
required
string

Either hex encoded public key (with 0x prefix) or validator index

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Publish a signed block

Submit a signed beacon block to the beacon node to be imported. The beacon node performs the required validation.

Authorizations:
Request Body schema: application/json
object (BeaconBlock)
signature
string <byte>

Bytes96 hexadecimal

Responses

Request samples

Content type
application/json
{
  • "message": {
    },
  • "signature": "string"
}

Submit signed attestations

Submit signed attestations to the beacon node to be validated and submitted if valid.

This endpoint does not protected against slashing.

Authorizations:
Request Body schema: application/json
Array ()
aggregation_bits
string <byte>

SSZ hexadecimal

object (AttestationData)
signature
string <byte>

Bytes96 hexadecimal

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Subscribe to node events

Provides endpoint to subscribe to beacon node Server-Sent-Events stream. Consumers should use eventsource implementation to listen on those events.

Authorizations:
query Parameters
topics
required
string

Event types to subscribe to. Available values include: [head, finalized_checkpoint, chain_reorg, block, attestation, voluntary_exit]

Responses

Get node syncing status

Requests the beacon node to describe if it's currently syncing or not, and if it is, what block it is up to.

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get attester duties

Requests the beacon node to provide a set of attestation duties, which should be performed by validators, for a particular epoch. Duties should only need to be checked once per epoch, however a chain reorganization (of > MIN_SEED_LOOKAHEAD epochs) could occur, resulting in a change of duties. For full safety, you should monitor head events and confirm the dependent root in this response matches:

  • event.previous_duty_dependent_root when compute_epoch_at_slot(event.slot) == epoch
  • event.current_duty_dependent_root when compute_epoch_at_slot(event.slot) + 1 == epoch
  • event.block otherwise

The dependent_root value is get_block_root_at_slot(state, compute_start_slot_at_epoch(epoch - 1) - 1) or the genesis block root in the case of underflow.

Authorizations:
path Parameters
epoch
required
string
Request Body schema: application/json

An array of the validator indices for which to obtain the duties.

[
  "(uint64)",
  ...
]
Array ()
string

Responses

Request samples

Content type
application/json
[
  • "string"
]

Response samples

Content type
application/json
{
  • "dependent_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
  • "data": [
    ]
}

Get proposer duties

Request beacon node to provide all validators that are scheduled to propose a block in the given epoch.

Duties should only need to be checked once per epoch, however a chain reorganization could occur that results in a change of duties. For full safety, you should monitor head events and confirm the dependent root in this response matches:

  • event.current_duty_dependent_root when compute_epoch_at_slot(event.slot) == epoch
  • event.block otherwise

The dependent_root value is get_block_root_at_slot(state, compute_start_slot_at_epoch(epoch) - 1) or the genesis block root in the case of underflow.

Authorizations:
path Parameters
epoch
required
string

Responses

Response samples

Content type
application/json
{
  • "dependent_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
  • "data": [
    ]
}

Produce unsigned block

Requests a beacon node to produce a valid block, which can then be signed by a validator.

Authorizations:
path Parameters
slot
required
string

The slot for which the block should be proposed.

query Parameters
randao_reveal
required
string

BLSSignature Hex BLS12-381 signature for the current epoch.

graffiti
string

Bytes32 Hex Graffiti.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Produce an AttestationData

Returns attestation data for the block at the specified non-finalized slot.

This endpoint is not protected against slashing. Signing the returned attestation data can result in a slashable offence.

Authorizations:
query Parameters
slot
required
string

uint64 The slot for which an attestation data should be created.

committee_index
required
integer <int32>

Integer The committee index for which an attestation data should be created.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get aggregated attestations

Aggregates all attestations matching given attestation data root and slot.

Authorizations:
query Parameters
attestation_data_root
required
string

String HashTreeRoot of AttestationData that validator wants aggregated.

slot
required
string

uint64 Non-finalized slot for which to create the aggregation.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Publish aggregate and proofs

Verifies given aggregate and proofs and publishes it on appropriate gossipsub topic.

Authorizations:
Request Body schema: application/json
Array ()
object (AggregateAndProof)
signature
string <byte>

Bytes96 hexadecimal

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Subscribe to a committee subnet

After Beacon node receives this request, search using discv5 for peers related to this subnet and replace current peers with those ones if necessary If validator is_aggregator, beacon node must:

  • announce subnet topic subscription on gossipsub
  • aggregate attestations received on that subnet
Authorizations:
Request Body schema: application/json
Array ()
validator_index
integer <int32>
committee_index
integer <int32>
committees_at_slot
string <uint64>
slot
string <uint64>
is_aggregator
boolean

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Get spec params

Retrieve specification configuration used on this node.

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Experimental

Get block

Retrieves block details for given block id.

Authorizations:
path Parameters
block_id
required
string

Block identifier. Can be one of: "head" (canonical head in node's view), "genesis", "finalized", <slot>, <hex encoded blockRoot with 0x prefix>.

Responses

Response samples

Content type
application/json
{
  • "version": "PHASE0",
  • "data": {
    }
}

Events

Subscribe to node events

Provides endpoint to subscribe to beacon node Server-Sent-Events stream. Consumers should use eventsource implementation to listen on those events.

Authorizations:
query Parameters
topics
required
string

Event types to subscribe to. Available values include: [head, finalized_checkpoint, chain_reorg, block, attestation, voluntary_exit]

Responses

Node

Get node health

Returns node health status in http status codes. Useful for load balancers.

Authorizations:

Responses

Get node identity

Retrieves data about the node's network presence.

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get node peers

Retrieves data about the node's network peers.

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get node peer

Retrieves data about the given peer.

Authorizations:
path Parameters
peer_id
required
string

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get node syncing status

Requests the beacon node to describe if it's currently syncing or not, and if it is, what block it is up to.

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get node version

similar to HTTP User-Agent.

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Validator

Get attester duties

Requests the beacon node to provide a set of attestation duties, which should be performed by validators, for a particular epoch. Duties should only need to be checked once per epoch, however a chain reorganization (of > MIN_SEED_LOOKAHEAD epochs) could occur, resulting in a change of duties. For full safety, you should monitor head events and confirm the dependent root in this response matches:

  • event.previous_duty_dependent_root when compute_epoch_at_slot(event.slot) == epoch
  • event.current_duty_dependent_root when compute_epoch_at_slot(event.slot) + 1 == epoch
  • event.block otherwise

The dependent_root value is get_block_root_at_slot(state, compute_start_slot_at_epoch(epoch - 1) - 1) or the genesis block root in the case of underflow.

Authorizations:
path Parameters
epoch
required
string
Request Body schema: application/json

An array of the validator indices for which to obtain the duties.

[
  "(uint64)",
  ...
]
Array ()
string

Responses

Request samples

Content type
application/json
[
  • "string"
]

Response samples

Content type
application/json
{
  • "dependent_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
  • "data": [
    ]
}

Get proposer duties

Request beacon node to provide all validators that are scheduled to propose a block in the given epoch.

Duties should only need to be checked once per epoch, however a chain reorganization could occur that results in a change of duties. For full safety, you should monitor head events and confirm the dependent root in this response matches:

  • event.current_duty_dependent_root when compute_epoch_at_slot(event.slot) == epoch
  • event.block otherwise

The dependent_root value is get_block_root_at_slot(state, compute_start_slot_at_epoch(epoch) - 1) or the genesis block root in the case of underflow.

Authorizations:
path Parameters
epoch
required
string

Responses

Response samples

Content type
application/json
{
  • "dependent_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
  • "data": [
    ]
}

Produce unsigned block

Requests a beacon node to produce a valid block, which can then be signed by a validator.

Authorizations:
path Parameters
slot
required
string

The slot for which the block should be proposed.

query Parameters
randao_reveal
required
string

BLSSignature Hex BLS12-381 signature for the current epoch.

graffiti
string

Bytes32 Hex Graffiti.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Produce an AttestationData

Returns attestation data for the block at the specified non-finalized slot.

This endpoint is not protected against slashing. Signing the returned attestation data can result in a slashable offence.

Authorizations:
query Parameters
slot
required
string

uint64 The slot for which an attestation data should be created.

committee_index
required
integer <int32>

Integer The committee index for which an attestation data should be created.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get aggregated attestations

Aggregates all attestations matching given attestation data root and slot.

Authorizations:
query Parameters
attestation_data_root
required
string

String HashTreeRoot of AttestationData that validator wants aggregated.

slot
required
string

uint64 Non-finalized slot for which to create the aggregation.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Publish aggregate and proofs

Verifies given aggregate and proofs and publishes it on appropriate gossipsub topic.

Authorizations:
Request Body schema: application/json
Array ()
object (AggregateAndProof)
signature
string <byte>

Bytes96 hexadecimal

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Subscribe to a committee subnet

After Beacon node receives this request, search using discv5 for peers related to this subnet and replace current peers with those ones if necessary If validator is_aggregator, beacon node must:

  • announce subnet topic subscription on gossipsub
  • aggregate attestations received on that subnet
Authorizations:
Request Body schema: application/json
Array ()
validator_index
integer <int32>
committee_index
integer <int32>
committees_at_slot
string <uint64>
slot
string <uint64>
is_aggregator
boolean

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Config

Get deposit contract address

Retrieve deposit contract address and genesis fork version.

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get scheduled forks

Retrieve all scheduled upcoming forks this node is aware of.

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get spec params

Retrieve specification configuration used on this node.

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Debug

Get fork choice leaves

Retrieves all possible chain heads (leaves of fork choice tree).

Authorizations:

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get state

Returns full BeaconState object for given state_id.

Use Accept header to select application/octet-stream if SSZ response type is required.

Authorizations:
path Parameters
state_id
required
string

State identifier. Can be one of: "head" (canonical head in node's view), "genesis", "finalized", "justified", <slot>, <hex encoded stateRoot with 0x prefix>.

Responses

Response samples

Content type
{
  • "data": {
    }
}