Metrics & REST API

Metrics

TPS

Transactions per second. Sliding window of 2.5 blocks (~1 s at 400 ms block time).

{"seq": 43, "TPS": 2450}

ContentionData

Storage slot contention analysis. Sent once per block (at BlockEnd).

Field	Type	Description
block_number	u64	Block number
block_wall_time_ns	u64	Block execution wall time (ns)
total_tx_time_ns	u64	Total transaction time (ns)
parallel_efficiency_pct	f64	Parallel execution efficiency (%)
total_unique_slots	u32	Total unique slots
contended_slot_count	u32	Slots with contention
contention_ratio	f64	Ratio of contended slots
total_txn_count	u32	Total transactions
top_contended_slots	array	Top contended slots
top_contended_contracts	array	Top contended contracts
contract_edges	array	Links between contracts via shared transactions

How to interpret ContentionData:

• parallel_efficiency_pct is the key metric: 90%+ = excellent parallelization, 70-90% = some contention bottlenecks, <70% = significant sequential execution due to storage conflicts
• contention_ratio shows what fraction of accessed slots had competing transactions. High ratio + low efficiency = many transactions hitting the same storage slots
• top_contended_contracts helps identify which contracts cause parallelization bottlenecks
• contract_edges reveals contract interdependencies: contracts sharing transactions may create implicit dependencies

TopAccesses

Most accessed accounts and storage slots, tracked using the Space-Saving algorithm. Useful for identifying storage hot spots and optimizing contract design.

{
  "seq": 45,
  "TopAccesses": {
    "account": [{"key": "0xADDRESS", "count": 150}],
    "storage": [{"key": ["0xADDRESS", "0xSLOT"], "count": 80}]
  }
}

Lifecycle

Block stage transitions. See Lifecycle subscription reference for full field descriptions.

---

REST Endpoints

All REST endpoints are available by default on the same address as the WebSocket (:8443).

GET /v1/tps

{"tps": 2450}

GET /v1/contention

Latest ContentionData (same format as in WebSocket).

GET /v1/status

{
  "status": "healthy",
  "block_number": 56147820,
  "connected_clients": 12,
  "uptime_secs": 86400,
  "last_event_age_secs": 0,
  "ring_seqno": 54321,
  "oldest_seqno": 4321,
  "newest_seqno": 54321
}

Field	Description
status	"healthy" (events within 10s) or "degraded"
block_number	Latest block
connected_clients	Active WebSocket connections
uptime_secs	Server uptime
last_event_age_secs	Seconds since the last event
ring_seqno	Current seq in the event ring
oldest_seqno	Oldest seq in the resume buffer (0 = buffer empty)
newest_seqno	Newest seq

GET /v1/blocks/lifecycle

Array of lifecycle records for all tracked blocks.

GET /v1/blocks/:number/lifecycle

Lifecycle of a specific block by number. Returns an error if the block is not in the tracker.

GET /health

{"jsonrpc": "2.0", "result": {"healthy": true, "number": 56147820, "last_event_age_secs": 0}}

• 200: healthy
• 503: no events for 30+ seconds → {"healthy": false, ...} + graceful shutdown

GET /metrics

Prometheus metrics in text format (counters, histograms, gauges).

POST / (JSON-RPC 2.0)

{"jsonrpc": "2.0", "method": "eth_getBlockByNumber", "params": [], "id": 1}

Response: {"jsonrpc": "2.0", "result": {"number": "0x359a8fc"}, "id": 1}

Unsupported methods: -32601 Method not found.