Skip to content

test(api): add API endpoint response conformance test vectors#617

Merged
tcoratger merged 1 commit intoleanEthereum:mainfrom
tcoratger:test/api-endpoint-test-vectors
Apr 16, 2026
Merged

test(api): add API endpoint response conformance test vectors#617
tcoratger merged 1 commit intoleanEthereum:mainfrom
tcoratger:test/api-endpoint-test-vectors

Conversation

@tcoratger
Copy link
Copy Markdown
Collaborator

Summary

  • New ApiEndpointTest fixture that generates JSON test vectors for the 4 deterministic API endpoints
  • Given genesis parameters (validator count + genesis time), computes the exact expected HTTP response
  • Client teams build the same genesis store, query their endpoint, and compare against the fixture

Endpoints covered

Endpoint Content-Type What the vector contains
GET /lean/v0/health application/json Fixed status + service name
GET /lean/v0/checkpoints/justified application/json Slot + root from latest justified checkpoint
GET /lean/v0/states/finalized application/octet-stream Hex-encoded SSZ bytes of finalized state
GET /lean/v0/fork_choice application/json Full tree: nodes with weights, head, checkpoints, validator count

Vectors (6 total)

Test Genesis What it validates
health 4 validators Static payload independent of state
justified_checkpoint_4v 4 validators Slot 0 + genesis root
justified_checkpoint_12v 12 validators Different root (different state root)
finalized_state_4v 4 validators Full SSZ encoding of genesis state
fork_choice_4v 4 validators Single node, zero weights
fork_choice_12v 12 validators Same shape, higher validator count

Test plan

  • uvx tox -e all-checks passes
  • uv run fill --fork=devnet --clean -n auto -- tests/consensus/devnet/api/ generates all 6 fixtures
  • Verified health returns {"status": "healthy", "service": "lean-rpc-api"}
  • Verified justified root differs between 4v and 12v configurations
  • Verified fork choice tree has single genesis node with weight 0

🤖 Generated with Claude Code

Introduces an ApiEndpointTest fixture that generates JSON test vectors
for the 4 deterministic API endpoints. Given genesis parameters, the
fixture builds a store and computes the exact expected HTTP response
(status code, content type, body) for each endpoint.

Endpoints covered:
- GET /lean/v0/health (static JSON payload)
- GET /lean/v0/checkpoints/justified (slot + root from store)
- GET /lean/v0/states/finalized (hex-encoded SSZ bytes)
- GET /lean/v0/fork_choice (full tree with weights and checkpoints)

6 test vectors with two genesis configurations (4 and 12 validators)
to verify that different validator counts produce different roots.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@tcoratger tcoratger merged commit a333d12 into leanEthereum:main Apr 16, 2026
12 of 13 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant