constraints-API revision & finalization

[mempirate]

The current constraints-API versions are documented at

• https://chainbound.github.io/bolt-docs/api/builder
• https://chainbound.github.io/bolt-docs/api/relay
• https://right-knife-e11.notion.site/V2-Aligning-Preconfirmation-APIs-b6b5e0df097d40e2b05cd8e1460cada9

In this discussion, we'll try to re-align everything.

Notes

• Everything should be under current namespaces, i.e. /eth/v1/builder and /relay/v1/builder
• Since REST, no use of verbs in URIs (HTTP method expresses the action already)

Questions

Constraint submission

The current Bolt POST /eth/v1/builder/constraints endpoint does not allow for cancellations. It allows for batch submission, but each constraint could have a different target slot. Would it be better to just have batch submission of constraints with the same target slot? The behaviour would then be:

• Proposers post constraints for their slot by some deadline $T$ into the slot.
• If there already was a submission for that slot, the submission is overridden. This implicitly allows for cancellations at the cost of having to re-submit all other constraints. We also modify a constraint entry with the following schema:

struct Constraint {
  txs: Vec<Bytes>, // List of raw transaction bytes, if len > 1, this is a bundle
  top: bool, // Flag indicating whether bundle / tx should be ToB
}

Example simplified body

{
  "message": {
    "slot": 12345,
    "validatorIndex": 97,
    "constraints": [
      {
        "txs": ["0x02f876018204db8405f5e100850218711a00825208949d22816f6611cfcb0cde5076c5f4e4a269e79bef8904563918244f40000080c080a0ee840d80915c9b506537909a5a6cf1ca2c5b47140d6585adab6ec0faf75fdcb7a07692785c5cb43c7cf02b800f", "0x02f876018204dbd405f5e12285f218711a0082d208949da2816f6611bcab0cde5076c5f4e4a269e79bef8904563918244f40111180c080a0ee840d80915c9b506537909a5a6cf1ca2c5b47140d6585adab6ec0faf75fdcb7a07692785c5cb43c7cf02b800f"],
        "top": false
      }
    ]
  },
  "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"
}

Pros

• Simpler
• More logical treatment of a constraint batch as being on a per-slot basis
• Allows for cancellations

Cons

• ?

Constraint polling

The current builder-facing constraints-API is an SSE stream with a backfill option. Given that we now treat constraints as more logical units, we could replace this with a simple poll endpoint with a slot query parameter, i.e.

GET /relay/v1/builder/constraints?slot=12345

that the builder could call at their discretion. We don't need an additional SSE stream for realtime streaming of constraints, the builder can engage in continuous polling if they want to have a more up-to-date view of the constraints.

Important

Question: Should we still expose an SSE endpoint as an optimization?

Example response

{
  "message": {
    "slot": 12345,
    "validatorIndex": 97,
    "constraints": [
      {
        "txs": ["0x02f876018204db8405f5e100850218711a00825208949d22816f6611cfcb0cde5076c5f4e4a269e79bef8904563918244f40000080c080a0ee840d80915c9b506537909a5a6cf1ca2c5b47140d6585adab6ec0faf75fdcb7a07692785c5cb43c7cf02b800f", "0x02f876018204dbd405f5e12285f218711a0082d208949da2816f6611bcab0cde5076c5f4e4a269e79bef8904563918244f40111180c080a0ee840d80915c9b506537909a5a6cf1ca2c5b47140d6585adab6ec0faf75fdcb7a07692785c5cb43c7cf02b800f"],
        "top": false
      }
    ]
  },
  "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"
}

Constraint & proof versioning

Currently, constraints are pretty simple (spot ILs with expressivity for bundles and ToB / RoB distinction). The associated proofs are also of a very specific format (SSZ Merkle multiproofs). If in the future, new constraint types arise, we'll have to modify the API spec. To allow for extensibility, we could leverage versioning. Example:

{
  "message": {
    "slot": 12345,
    "validatorIndex": 97,
    "constraints": [
      {
        "version": 0,
        "data": {
          "txs": ["0x02f876018204db8405f5e100850218711a00825208949d22816f6611cfcb0cde5076c5f4e4a269e79bef8904563918244f40000080c080a0ee840d80915c9b506537909a5a6cf1ca2c5b47140d6585adab6ec0faf75fdcb7a07692785c5cb43c7cf02b800f", "0x02f876018204dbd405f5e12285f218711a0082d208949da2816f6611bcab0cde5076c5f4e4a269e79bef8904563918244f40111180c080a0ee840d80915c9b506537909a5a6cf1ca2c5b47140d6585adab6ec0faf75fdcb7a07692785c5cb43c7cf02b800f"],
          "top": false
        }
      }
    ]
  },
  "signature": "0x1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505cc411d61252fb6cb3fa0017b679f8bb2305b26a285fa2737f175668d0dff91cc1b66ac1fb663c9bc59509846d6ec05345bd908eda73e670af888da41af171505"
}

[ltitanb]

Do you think it would make sense to separate namespaces like this:

• endpoints that are called by the preconfer (which may or may not be a proposer), under something like /constraints/v1/
• endpoints that are called by the proposer under the extended Builder API /eth/v1/builder (e.g. get header with proofs)
• endpoints that are implemented by the relay and called by builders under /relay/v1/builder

Constraint submission
I think from a builder perspective, having a single list which acts as the source of truth for the slot would be ideal. Since anyway there's a deadline T what's the advantage of sending the list multiple times? The preconfer could just handle cancellations internally and send a single list per slot before T

Would also add a note in the API that for a List<Constraints> to be valid, at most one Constraint can have top = true .

Constraint polling
I think could be useful to still keep the stream, sending the full list. This was also suggested by a relay operator in ZuBerlin to avoid replicating the issue where builders spam getHeader on relays (though probably wouldn't be as bad if builders can send once after T)

Constraint & proof versioning
This makes complete sense to me

A few other open questions:

• would it make sense to replace validatorIndex with preconferPubkey (which could be the validator pubkey, a proxy key for the validator, or a delegated 3rd party preconfer) in the ConstraintsMessage? Would also make it easier to verify the signature
• should the chainId be added in some of the structs?
• would it make sense to keep the same get_header endpoint and only change the version of the bid, to make it easier on relays to implement?

[mempirate]

Seperating namespaces
Yeah that also works. The endpoints we're considering for the constraints namespace would be the following right?

builder-API:

• POST /constraints/v1/builder/constraints: submitting a batch of constraints for a slot from authorized key
• POST /constraints/v1/builder/delegate: delegating constraint submission to another BLS keypair (renamed this from elect_preconfer to be more general about delegating someone else to submit constraints for you, not strictly a preconfer only in the case of proposer commitments)

In the relay API we'd just implement them under the relay namespace?
relay-API:

• GET /relay/v1/builder/constraints_stream: stream of constraint submissions
• GET /relay/v1/builder/constraints?slot=x: getting all constraints for a certain slot

Constraint submission
Yes you're right, cancellations should probably just be handled internally. This forces the proposer / preconfer to only submit constraints late though, is there any advantage to builders for getting them earlier? If not, this works.

Constraint polling
Agreed it would be useful to keep the stream for builder & relay ease. Will do!

Other open questions

• We chose validatorIndex because of how the other builder-API endpoints work. If the relay keeps a mapping from validatorIndex => pubkey and for validatorIndex => delegated_pubkey signature verification should not be an issue right? Maybe i'm missing something.
• Would this be to prevent replay attacks? First thoughts would be that for contraints, we have the (validatorIndex, slot) in the signed message, as well as serialized transactions which already contain the chain ID
• No strong preference here. The only reason I see to make it an explicit get_header_with_proofs endpoint is to make it less ambiguous. Should we request external feedback here?

[ltitanb]

This forces the proposer / preconfer to only submit constraints late though, is there any advantage to builders for getting them earlier?

As long as they come with some reasonable time frame (eg 8 seconds is more than enough), should be fine

• For validatorIndex was thinking of a situation where the message has to be verified by a 3rd party which will have to reconstruct the index map, but no strong opinion on this
• More than replay attacks, was thinking of a situation where commitments are submitted for different chains? Think was briefly discussed in zuBerlin but without coming to a decision, we can also leave it for now and add it later if needed
• Sounds good