Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/ralexstokes/relay-monitor

Last synced: 2 months ago
JSON representation

Host: GitHub
URL: https://github.com/ralexstokes/relay-monitor
Owner: ralexstokes
License: mit
Created: 2022-08-23T20:22:23.000Z (almost 2 years ago)
Default Branch: main
Last Pushed: 2023-10-31T15:31:10.000Z (8 months ago)
Last Synced: 2024-01-28T13:12:18.141Z (5 months ago)
Language: Go
Size: 171 KB
Stars: 57
Watchers: 5
Forks: 16
Open Issues: 20
Metadata Files:
- Readme: README.md
- License: LICENSE

Lists

awesome-blockspace - relay monitor

README

# relay-monitor

A service to monitor a set of relayers in the external builder network on Ethereum.

## NOTE

Work in progress. Not ready for use yet.

## Dependencies

Go v1.19+

Requires a consensus client that implements the **dev** version of the standard [beacon node APIs](https://ethereum.github.io/beacon-APIs). This includes the standard set and [the RANDAO endpoint](https://ethereum.github.io/beacon-APIs/?urls.primaryName=dev#/Beacon/getStateRandao).

Every other required information is given in the configuration, e.g. `config.example.yaml`.

## Operation

`$ go run ./cmd/relay-monitor/main.go -config config.example.yaml`

## Implementation

The monitor is structured as a series of components that ingest data and produce a live stream of fault data for each configured relay.

### `collector`

The `collector` gathers data from either connected validators or relays it is configured to scan.

- validator registrations
- bids from relays
- auction transcript (bid + signed blinded beacon block) from connected proposers
- execution payload (conditional on auction transcript)
- signed beacon block (collected from a consensus client)

### `analyzer`

The `analyzer` component derives faults from the collected data.

Each slot of the consensus protocol has a unique analysis which tries to derive any configured faults based on the observed data at a given time.

It is defined as set of rules (defined in Go for now) that should be re-evaluated when any dependent piece of data is collected.

The current fault count for each relay summarizing their behavior is maintained by the monitor and exposed via API.

## API docs

### POST `/eth/v1/builder/validators`

Expose the `registerValidator` endpoint from the `builder-specs` APIs to accept `SignedValidatorRegistrationsV1` from connected proposers.

See the [definition from the builder specs](https://ethereum.github.io/builder-specs/#/Builder/registerValidator) for more information.

### POST `/monitor/v1/transcript`

Accept complete transcripts from proposers to verify the proposer's leg of the auction was performed correctly.

This endpoint accepts the JSON encoding of the signed builder bid under a top-level key `"bid"` and the signed blinded beacon block under a top-level key `"acceptance"`. Encodings follow the JSON definition given in the [builder-specs](https://github.com/ethereum/builder-specs).

This endpoint returns HTTP 200 OK upon success and HTTP 4XX otherwise.

Example request:

```json
{
"bid": {
"data": {
"message": {
"header": {
"parent_hash": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"fee_recipient": "0xabcf8e0d4e9587369b2301d0790347320302cc09",
"state_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"receipts_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"logs_bloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
"prev_randao": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"block_number": "1",
"gas_limit": "1",
"gas_used": "1",
"timestamp": "1",
"extra_data": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"base_fee_per_gas": "1",
"block_hash": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"transactions_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2"
},
"value": "1",
"pubkey": "0x93247f2209abcacf57b75a51dafae777f9dd38bc7053d1af526f220a7489a6d3a2753e5f3e8b1cfe39b56f43611df74a"
},
"signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"
}
},
"acceptance": {
"message": {
"slot": "1",
"proposer_index": "1",
"parent_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"state_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"body": {
... fields omitted ...
"execution_payload_header": {
"parent_hash": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"fee_recipient": "0xabcf8e0d4e9587369b2301d0790347320302cc09",
"state_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"receipts_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"logs_bloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
"prev_randao": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"block_number": "1",
"gas_limit": "1",
"gas_used": "1",
"timestamp": "1",
"extra_data": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"base_fee_per_gas": "1",
"block_hash": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2",
"transactions_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2"
}
}
},
"signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"
}
}
```

### GET `/monitor/v1/faults`

Exposes a summary of faults per relay.

This response contains a map of relay public key to a mapping of observed fault counts. The response also contains the start and end epochs the observation window spans.

The types of faults and their meaning can be found here: https://hackmd.io/A2uex3QFSfiaJJ9BKxw-XA?view#behavior-faults

#### Optional query params:

Query param: `start`, an unsigned 64-bit integer indicating the lower bound for an epoch to provide fault data for
Query param: `end`, an unsigned 64-bit integer indicating the upper bound for an epoch to provide fault data for.
Query param: `window`, an unsigned 64-bit integer indicating the size of the window to provide fault data for

NOTE: if only `start` (or `end`) is provided then the response will only span the `window` size amount of epochs after (or before) the given parameter. the `window` parameter can optionally be specified as a query param or a default of `256` will be used if the query param is missing.
NOTE: if neither parameter is provided, the response will be `256` epochs behind from the current epoch, inclusive.

#### Example request:

`GET /monitor/v1/faults?start=100`

#### Example response:

```json
{
"span": {
"start_epoch": "100",
"end_epoch": "356",
},
"data": {
"0x845bd072b7cd566f02faeb0a4033ce9399e42839ced64e8b2adcfc859ed1e8e1a5a293336a49feac6d9a5edb779be53a": {
"stats": {
"total_bids": 1153,
"malformed_bids": 0,
"consensus_invalid_bids": 1,
"payment_invalid_bids": 12,
"ignored_preferences_bids": 5,
"malformed_payloads": 0,
"consensus_invalid_payloads": 1,
"unavailable_payloads": 10
},
"meta": {
"endpoint": "builder-relay-sepolia.flashbots.net"
}
}
}
}
```