Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Proposer config file specification #41

Closed
wants to merge 2 commits into from
Closed

Add Proposer config file specification #41

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
14c7432
Add proposer config file format spec
StefanBratanov Jul 21, 2022
848022f
markdown improvements
StefanBratanov Jul 21, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 66 additions & 0 deletions schemas/mev_boost_proposer_config.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
{
"title": "MevBoostProposerConfig",
"type": "object",
"properties": {
"builder_relays_groups": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"proposer_config": {
"type": "object",
"patternProperties": {
"^0x[a-fA-F0-9]{96}$": {
"type": "object",
"properties": {
"fee_recipient": {
"$ref": "#/$defs/fee_recipient"
},
"builder": {
"$ref": "#/$defs/builder"
}
}
}
},
"additionalProperties": false
},
"default_config": {
"type": "object",
"properties": {
"fee_recipient": {
"$ref": "#/$defs/fee_recipient"
},
"builder": {
"$ref": "#/$defs/builder"
}
}
}
},
"required": [
"default_config"
],
"$defs": {
"fee_recipient": {
"type": "string",
"pattern": "^0x[a-fA-F0-9]{40}$"
},
"builder": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"gas_limit": {
"type": "string"
},
"relays": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}
72 changes: 72 additions & 0 deletions schemas/validator_client_proposer_config.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
{
"title": "ValidatorClientProposerConfig",
"type": "object",
"properties": {
"builder_relays_groups": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"proposer_config": {
"type": "object",
"patternProperties": {
"^0x[a-fA-F0-9]{96}$": {
"type": "object",
"properties": {
"fee_recipient": {
"$ref": "#/$defs/fee_recipient"
},
"builder": {
"$ref": "#/$defs/builder"
}
}
}
},
"additionalProperties": false
},
"default_config": {
"type": "object",
"properties": {
"fee_recipient": {
"$ref": "#/$defs/fee_recipient"
},
"builder": {
"$ref": "#/$defs/builder"
}
},
"required": [
"fee_recipient"
]
}
},
"required": [
"default_config"
],
"$defs": {
"fee_recipient": {
"type": "string",
"pattern": "^0x[a-fA-F0-9]{40}$"
},
"builder": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"gas_limit": {
"type": "string"
},
"relays": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"enabled"
]
}
}
}
68 changes: 68 additions & 0 deletions specs/validator.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,13 @@
- [Relation to local block building](#relation-to-local-block-building)
- [How to avoid slashing](#how-to-avoid-slashing)
- [Proposer slashing](#proposer-slashing)
- [Responsibilites during the Merge transition](#responsibilites-during-the-merge-transition)
- [Proposer config file](#proposer-config-file)
- [File format](#file-format)
- [Specification](#specification)
- [JSON example](#json-example)
- [JSON schemas](#json-schemas)


<!-- END doctoc generated TOC please keep comment here to allow auto update -->

Expand Down Expand Up @@ -161,3 +168,64 @@ any of the builder APIs or run any builder software until the Merge has finalize
[beacon-node-apis]: https://ethereum.github.io/beacon-APIs
[bellatrix-specs]: https://github.com/ethereum/consensus-specs/blob/dev/specs/bellatrix
[bellatrix-validator-specs]: https://github.com/ethereum/consensus-specs/blob/dev/specs/bellatrix/validator.md

## Proposer config file

Proposer config file could be used by `validator client` implementations when more fine-grained proposer configuration is required. The same config file could also be used by [`mev-boost`](https://github.com/flashbots/mev-boost/wiki) implementations.

### File format

A consistent proposer config file format across `validator clients` and `mev-boost` will allow for easier setup and maintenance when participating in a `builder` network. JSON is the recommended data format.

#### Specification

Below is a list of the fields which could be part of the proposer config. The fields which are not specifed as required are optional.

* `builder_relays_groups` : A map of relay endpoints by id, which could later be used to reference a group of relays. It helps with repetition when multiple validators need to be configured with the same set of relays.
* `proposer_config` : A map where the key is the public key of the validator and the value is the proposer configuration for the specific validator.
* `fee_recipient` : `string` an execution layer address where fees for the specific validator should go.
* `builder` : builder configuration for the specific validator
* `enabled` : `boolean [required for validator clients]` Enable or disable the builder network. For `validator clients`, this will mean, no validator registrations will be sent to the external builder. For `mev-boost`, this field does not have any effect.
* `gas_limit` : `string` an uint64 as a string in decimal number format. If no gas_limit is defined, the gas_limit from the `default_config` would be used.
* `relays` : `array` specific relays to use for the specific validator. It can also reference the group ids from `builder_relays_groups`. This field will be used by `mev-boost` implementations to direct validators to certain relays.
* `default_config` : `required` In case no specific configuration is setup for a validator in the `proposer_config`, this default configuration will be used.
* `fee_recipient` : `string [required for validator clients]` an execution layer address where fees for the validators should go.
* `builder` : Default builder configuration. It follows the same structure as the `proposer_config`

#### JSON example

```json
{
"builder_relays_groups": {
"groupB": [
"https://0xb124d80a00...@builder2-relay-kiln.flashbots.net",
"https://0x845bd072b7...@builder2-relay-kiln.flashbots.net"
]
},
"proposer_config": {
"0xa057816155ad77931185101128655c0191bd0214c201ca48ed887f6c4c6adf334070efcd75140eada5ac83a92506dd7a": {
"fee_recipient": "0x50155530FCE8a85ec7055A5F8b2bE214B3DaeFd3",
"builder": {
"enabled": true,
"relays": ["https://0x...@builder-relay-kiln.flashbots.net"],
"gas_limit": "12345654321"
}
}
},
"default_config": {
"fee_recipient": "0x6e35733c5af9B61374A128e6F85f553aF09ff89A",
"builder": {
"enabled": false,
"relays": ["groupB"]
}
}
}
```

#### JSON schemas

The following JSON schemas for `validator clients` and `mev-boost` could be used to validate a proposer config JSON file. They adhere to the [file format specification](#specification) described above.

* [Validator Client proposer config schema](../schemas/validator_client_proposer_config.json)
* [MEV-Boost proposer config schema](../schemas/mev_boost_proposer_config.json)