Ethereum Beacon APIs

The Ethereum Beacon APIs are a collection of RESTful APIs provided by Ethereum Beacon nodes. They expose an interface based on the Ethereum consensus layer specifications to promote interoperability between different beacon node implementations.

Key Concepts

• API Interface: A REST interface accessed via HTTP, currently supporting JSON as the only return data type.
• Beacon Node (BN): Maintains the state of the beacon chain by communicating with other nodes. It does not maintain the keypairs used for participating in the chain.
• Validator Client (VC): A conceptually separate entity that uses private keys to perform validator duties, such as producing beacon blocks and signing attestations.

Security Warning

Unless protected by additional security layers, these APIs should not be exposed to the public internet. Certain endpoints can trigger heavy processing, making the node vulnerable to denial-of-service (DoS) attacks.

To perform attestations, a validator follows these steps:

1. Fetch Duties: At the start of every epoch, call for attester duties for epoch + 1. This returns an array of objects containing the validator, their committee, and the attestation slot.
2. Prepare Subnet:
   • Determine if you are an aggregator by computing the slot_signature.
   • Call prepareBeaconCommitteeSubnet. If any validators in the committee are aggregators, set is_aggregator=True. You only need to call this once per committee/slot assignment.
3. Wait for Block: Wait for the BeaconBlock for the assigned slot (via streaming or polling):
   • Pre-Gloas: Max wait is SECONDS_PER_SLOT / 3 seconds into the slot.
   • Post-Gloas: Max wait is ATTESTATION_DUE_BPS_GLOAS seconds into the slot.
4. Attest:
   • Call produceAttestationData to fetch AttestationData.
   • Call submitPoolAttestations with the AttestationData and a Bitlist of aggregation bits. The bit at validator_committee_index must be set to true.
5. Aggregator Duties (If applicable):
   • Wait for SECONDS_PER_SLOT * 2 / 3 (Pre-Gloas) or AGGREGATE_DUE_BPS_GLOAS (Post-Gloas) seconds into the slot.
   • Call getAggregatedAttestation from the beacon node subscribed to your subnet.
   • Call publishAggregateAndProofs.

Reorg Handling: Monitor for reorganization events. If a reorg occurs, re-fetch attester duties and restart.

Post-Gloas, builders are non-validating actors that submit execution payload bids. Builders register using BUILDER_WITHDRAWAL_PREFIX credentials.

1. Fetch Bid: Call getExecutionPayloadBid from the beacon node for the current or next slot's proposer. The beacon node retrieves this via engine_getPayload from the execution client.
2. Prepare Bid: Cache the fields required to form an ExecutionPayloadEnvelope and sign the ExecutionPayloadBid to create a SignedExecutionPayloadBid.
3. Submit Bid: Call publishExecutionPayloadBid for the proposer to consider.
4. Handle Selected Bid: If your bid is selected, you must submit the payload before PAYLOAD_DUE_BPS:
   • If the beacon node built the payload: Call getExecutionPayloadEnvelope from that node, sign it, and submit SignedExecutionPayloadEnvelope to the same node (it attaches blobs/proofs from cache).
   • If payload was constructed externally: Sign the envelope and submit SignedExecutionPayloadEnvelopeContents (envelope + blobs + KZG proofs) via any beacon node.

Monitoring: Monitor for block proposals containing your bid to trigger the envelope release process.

To propose a block, a validator must follow these steps at the start of every epoch and slot:

1. Fetch Duties: At the start of every epoch, call getProposerDuties to retrieve an array of objects containing proposer pubkeys and their assigned slots.
2. Retrieve Block: At the immediate start of the assigned slot, request a BeaconBlock from the Beacon Node:
   • Pre-Gloas forks: Use produceBlockV3.
   • Post-Gloas forks: Use produceBlockV4.
     • include_payload=true: Returns BlockContents (beacon block, execution payload envelope, blobs, and KZG proofs). This enables stateless operation.
     • include_payload=false: Returns only the BeaconBlock. The beacon node caches the execution payload and blobs internally (stateful operation).
     • Note: If using an external builder's bid, only the BeaconBlock is returned regardless of the include_payload setting.
3. Sign and Submit: Sign the block and call publishBlock with the BeaconBlock and signature.
4. Post-Gloas Payload Submission (Self-Building): If the proposer's own bid is included in the block, you must submit the payload before PAYLOAD_DUE_BPS:
   • Stateless (include_payload=true): Sign the envelope and submit SignedExecutionPayloadEnvelopeContents (envelope + blobs + KZG proofs).
   • Stateful (include_payload=false): Call getExecutionPayloadEnvelope from the same beacon node, sign the envelope, and submit SignedExecutionPayloadEnvelope (the node attaches blobs/proofs from its cache).

Reorg Handling: Monitor for chain reorganization events. If a reorg is detected, re-fetch proposer duties and restart the process.