Beacon API v3.0.0 spec compliance

[nflaig]

To be compliant to latest beacon API spec (v2.5.0) several updates are required.

v2.5.0

• Add block_gossip SSE event #6470
• Implement POST endpoints for validators and validator_balances #6058

v2.4.2

• Support blob download API example from recent beacon API test suite #6185

v2.4.1

Nothing

v2.4.0

• Ensure operationIds match spec value
• Add finalized property to HTTP API responses #5693
• Feature: Support el_offline in eth/v1/node/syncing #5542
• Implement beacon rewards APIs #5694
• Implement expected withdrawals API #5696
• Implement publish block v2 APIs #5698
• EIP-4881: Deposit Contract Snapshot Interface #4935
• Implement get blinded block API #5699
• Implement debug fork choice API #5700
• Implement get state randao API #5701
• Add syncing_status query parameter to health API #5702
• Optional randao verification when producing blocks #4638
• Support eventstream example (bls_to_execution_change) from recent beacon API test suite #6167
• Improve API schema validation for tests #6168
• Support eventstream example (light_client_*_update) from recent beacon API test suite #6170
• API error responses are not spec compliant #6480
• Multiple API errors are not spec compliant #6293

All the above issues can be tackled independently. A PR that implements a new API or adds new parameters needs to make sure to update the corresponding ignore list.

lodestar/packages/api/test/unit/beacon/oapiSpec.test.ts

Line 87 in 645d491

const ignoredOperations = [

lodestar/packages/api/test/unit/beacon/oapiSpec.test.ts

Line 108 in 645d491

const ignoredProperties: Record<string, IgnoredProperty> = {

lodestar/packages/api/test/unit/beacon/oapiSpec.test.ts

Line 155 in 645d491

const ignoredTopics = [

[ensi321]

On a related note, at some point we should update the api error messages to be compliant with the Beacon API spec.

eg.

Expected

curl http://localhost:9596/eth/v1/beacon/states/current/root | jq
{
  "code": 400,
  "message": "Invalid state ID: current"
}

Actual

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid block id 'current'"
}

Expected

curl "http://localhost:9596/eth/v1/beacon/pool/attestations?slot=current&committee_index=123" | jq
{
  "code": 400,
  "message": "Invalid slot: current"
}

Actual

[
  {
    "instancePath": "/slot",
    "schemaPath": "#/properties/slot/type",
    "keyword": "type",
    "params": {
      "type": "integer"
    },
    "message": "must be integer"
  }
]

Expected

curl http://localhost:9596/eth/v1/beacon/headers/123 | jq
{
  "code": 404,
  "message": "Block not found"
}

Actual

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "No block found for id '123'"
}

[nflaig]

On a related note, at some point we should update the api error messages to be compliant with the Beacon API spec.

I have looked at this before, it should be possible to transform the error before we send it

lodestar/packages/beacon-node/src/api/rest/base.ts

Line 67 in 54e8c45

server.setErrorHandler((err, req, res) => {

Regarding the statusCode property, this is something fastify sets internally as well I did not find a good way to customize this. e.g. is even hard coded here, I don't think we can override those (other than adding custom default error handler)
fastify.js#L687-L711

body = `{"error":"${errorStatus}","message":"Client Timeout","statusCode":408}`

In case of default json schema error, would have to compile it in a single messages maybe something like

const { instancePath, message } = errors[0]
const message = `${instancePath.substring(instancePath.lastIndexOf("/") + 1)} ${message}`

Even though it would be good if we can support all properties I don't think anyone is actually looking at the json body of an error (unless API is used manually). Most important is the http status code and also res.text as this is used in Lodestar to display the error message.

lodestar/packages/api/src/utils/client/httpClient.ts

Lines 312 to 313 in 71160df

	const errBody = await res.text();
	throw new HttpError(`${res.statusText}: ${getErrorMessage(errBody)}`, res.status, url.toString());

[wemeetagain]

There's a 3.0.0-alpha.6 https://github.com/ethereum/beacon-APIs/releases
Do we want to target 3.0.0 instead?

[nflaig]

Do we want to target 3.0.0 instead?

We do already test against that

lodestar/packages/api/test/unit/beacon/oapiSpec.test.ts

Line 23 in cf72219

const version = "v3.0.0-alpha.6";

and we support all newly added apis already, can update this issue once the 3.0.0 release is out (likely shortly before electra fork)