# Conditions API - Block Conditions Extension to the Builder API

## Abstract
This dpci,emt proposes the Conditions API, an extension to the Ethereum Builder API, allowing Ethereum proposers to specify constraints on blocks built by external builders. This ensures compliance with specific criteria and enhances the block building process for Ethereum’s external block builders.

## Motivation
The current block building process lacks a mechanism for proposers to enforce validity conditions on blocks built by external entities. This document addresses this gap by introducing the Conditions API, enabling proposers to specify and authenticate conditions for block validity, thus enhancing security and compliance. Several groups of use-cases are made possible by this proposal.

### Inclusion Commitments
This extension enables the proposer to commit to an inclusion of transaction in their block in a PBS setting. While the mechanism of commitment and commitment honouring validation is off the scope of this proposal, this extension enables the proposers to communicate their promises with the external block builders.

Some use-cases that fall under this category:

- Inclusion preconfirmations
- Based Sequencing

### Execution Commitments

This extension further enables the proposer to specify the contents on top of their block in a PBS setting. Such constraints enable the proposer to commit not only to the inclusion of a transaction in their block, but can virtually guarantee its post-execution state.

Some use-cases that fall under this category:
- Dex trades & arbitrage

## Specification
The Conditions API extends the existing Ethereum Builder API, introducing new endpoints and data models to facilitate the submission and enforcement of block validity conditions.

### Custom types

Consider the following definitions supplementary to the definitions in consensus-specs.
We define the following Python custom types for type hinting and readability:

| Name | SSZ equivalent | Description |
| - | - | - |
| `ECDSAPubkey` | `Bytes32` | an ECDSA (secp256k1) public key |
| `ECDSASignature` | `Bytes64` | an ECDSA (secp256k1) signature |

### Data Models

#### `ValidatorRegistrationV2`

Note: `SignedValidatorRegistrationV1` is updated indirectly.

class ValidatorRegistrationV2(Container):
    fee_recipient: ExecutionAddress
    gas_limit: uint64
    timestamp: uint64
    pubkey: BLSPubkey
    conditions_version: uint8
    conditions_auth_key: ECDSAPubkey

#### `ValidatorConditionsV1`

class ValidatorConditionsV1(Container):
    top: List[Transaction],
    rest: List[Transaction]

#### `SignedValidatorConditionsV1`

class SignedValidatorConditionsV1(Container):
    message: ValidatorConditionsV1,
    conditions_hash: Hash32,
    signature: ECDSASignature

### Endpoints

#### Builder Registration API Modifications

The Builder API will have minimal backwards compatible modifications to the behavior of the `/eth/v1/builder/validators` endpoint.
`ValidatorRegistrationV1` is updated to its V2 version. `SignedValidatorRegistrationV1` is updated indirectly.

`ValidatorRegistrationV2` has two new fields:
- `conditions_version`: uint8 - unsigned integer describing the version of the ConditionsAPI used by the proposer
- `conditions_auth_key`: ECDSAPubkey - `ECDSA` public key that will be used for signing of conditions by the proposer. More on the choice to use a new ECDSA keypair can be found in the Rationale section.

An omission or zero value for `conditions_version` indicates no support for conditions submission, whereas a non-zero value indicates the version of the Conditions API.

Example Request:

"message": {
    // ValidatorRegistrationV1 fields
    "conditions_version": "1",
    "conditions_key": "0xd12d5a488111e96d4c10f0274361e8902b8550e2619e699eb4d62ef6d80520b7"
},
"signature": "..."

#### Submit Conditions:

- **Endpoint**: POST `/eth/v1/builder/conditions/{slot}/{parent_hash}/{pubkey}`
- **Description**: Sets the validity conditions for the slot identified by `slot` number and `parent_hash` by its proposer.
- **Request**: `SignedValidatorConditionsV1`
- **Notes**:
- Conditions can be submitted as JSON or SSZ, and optionally GZIP encoded.
- `signature` is `ED25519Signature` by the `ED25519` keypair with the public key provided during the registration process

Example Request:

"message": {
	"top": [
            "0x02f878831469668303f51d843b9ac9f9843b9aca0082520894c93269b73096998db66be0441e836d873535cb9c8894a19041886f000080c001a031cc29234036afbf9a1fb9476b463367cb1f957ac0b919b69bbc798436e604aaa018c4e9c3914eb27aadd0b91e10b18655739fcf8c1fc398763a9f1beecb8dddddd"
	],
	"rest": [
            "0x02f878831469668303f51d843b9ac9f9843b9aca0082520894c93269b73096998db66be0441e836d873535cb9c8894a19041886f000080c001a031cc29234036afbf9a1fb9476b463367cb1f957ac0b919b69bbc798436e604aaa018c4e9c3914eb27aadd0b91e10b18655739fcf8c1fc398763a9f1beecb8eeeee",
	]
},
"conditions_hash": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2"
"signature": "0xa3fbf31e93ec66bc0d21cfa049e1e08df4862a777e1f01ca4b4a1a0beeb0969e3b2af02cc5e356b83cceab3c248a1ee90917c179bca2a18b4fdcea4b2380f20c"

### Conditions Key Management
The `ECDSA` keypair - Conditions Key - used for signing conditions can be considered authorised and under control of the validator BLS keypair holder. As such the validator software can change the conditions by triggering the validator registration method.

In order to remove the requirement for management of another key pair, the validator software can safely regenerate and register new conditions keys on startup.

## Rationale

### Why update the Builder API

The design allows proposers to communicate specific requirements for block validity, ensuring external builders produce blocks that meet these criteria. This approach leverages existing authentication mechanisms, using cryptographic signatures to prevent impersonation and ensure integrity.

Such an update gives more control over block production and content to the diverse set of proposers and enables proposer commitment and conditions use cases.

### Why introduce ECDSA key for signing conditions

The operation of submission of validity conditions is expected to be a frequent one. This requires the mechanism to be robust in terms of signing and verification time.

Within Ethereu ECDSA is widely used. It support applications needing quick cryptographic operations and meets the criteria above. Furthermore here are some more favourable characteristics of ECDSA

1. **Speed**: Faster signing and verification processes compared to other elliptic curve algorithms. ECDSA is especially suitable for use-cases requiring high frequency of signing and verification like the conditions submission.
2. **High Security**: Uses modern elliptic curve cryptography, providing strong security guarantees.
3. **Deterministic Signatures**: Ensures the same message always produces the same signature, reducing the risk of side-channel attacks.
4. **High-Performance Implementations**: Efficient algorithms and implementations exist for various platforms.
6. **Battle tested**: Already in production in Ethereum.

## Implementation Approach
The proposed changes need to be implemented in the validator softwares of the various clients. In order to ease the burden of adoption of this proposal in the validator clients, as a first phase it can be implemented within upgraded middleware sidecar software components like `mev-boost`.

Upon detection of registration request with an older version, the upgraded sidecar can upgrade the registration request to the newer version and perform the ECDSA key generation and registration duties. Importantly, in this phase the sidecar middleware would need to have access to the validator BLS keystore.

Such an upgraded sidecar would also be able to receive, format and send conditions through the Conditions API towards the external block builders.

## Backwards Compatibility

This proposal introduces new endpoints and data models but does not affect existing functionalities. It ensures that nodes not supporting the Conditions API can continue operating without modification.

## Security Considerations

The Conditions API relies on cryptographic signatures to authenticate validity conditions submissions, mitigating impersonation risks. In order to optimize for performance, ECDSA public key is communicated as representation to the external builder during registration. External builders are expected to authenticated condition submissions through signature verification.

## References

- [Ethereum Builder API](https://ethereum.github.io/builder-specs/)
- [Based Sequencing](https://ethresear.ch/t/based-rollups-superpowers-from-l1-sequencing/15016)
- [Vanilla Based Rollups Research](https://github.com/LimeChain/based-preconfirmations-research/)