chore: Enable quoting with JIT orders liquidity

[squadgazzz]

Background

From #3027:

Currently CoW Protocol is in an awkward spot because it can not be the only source of liquidity yet. If all liquidity for a token rests in CoW Protocol's orderbook or some CoW AMM solvers would have no way of using it to quote a price for a given token.

Details

Previous attempts to implement it(#3033 and #3038) showed that this is a more involved change than anticipated, which also requires breaking API changes.

Currently, JIT orders get simulated on limit prices which means they will not get any surplus. Any surplus that can be generated by using a CoW AMM would, therefore, go to the user quote. In reality, the user order that comes out of the quote would be settled at a worse price because if it gets settled against a CoW AMM order surplus will have to be shared. So, the solvers should be able to tell us at which price things should get settled so that we can reason about distributing surplus even in quotes.

To fix that we should allow solvers to return pre-interactions, JIT orders and uniform clearing prices with their quote. That way solvers could quote with CoW AMMs (require JIT orders, pre-interactions and UCP). They could also index the orderbook and return resting limit orders as JIT orders.

Tasks

• Update the driver's OpenAPI schema quote object with an enum with the old and new versions. Trade verifier returns error in case a new version is received.

Example

Quote:
  type: object
  properties:
    ..existing fields
Quote:
  oneOf:
    - $ref: "#/components/schemas/LegacyQuote"
    - $ref: "#/components/schemas/QuoteWithJitOrders"
  
LegacyQuote:
  type: object
  properties:
    ..existing fields

QuoteWithJitOrders:
  type: object
  properties:
    ..existing fields, where out_amount is replaced with the clearingPrices

    clearingPrices:
      type: array
      items:
        $ref: "#/components/schemas/Price"
      nullable: true
    jitOrders:
      type: array
      items:
        $ref: "#/components/schemas/JITOrder"
      nullable: true
    preInteractions:
      type: array
      items:
        $ref: "#/components/schemas/Interaction"
      nullable: true

• In a separate PR, support the new quote version in the trade verifier. This would be properly tested only in the following task since it requires an e2e test with all the components that already support the feature.
• Support the feature in the driver crate and start sending the new quote version. Implement e2e tests.
• Remove the legacy quote version once all the external drivers have switched to the new API.

[MartinquaXD]

nit: The new quote struct should have the uniform clearing prices instead of out_amount because the out_amount can be computed based on the prices. Other than that the plan looks good.
Also clearingPrices currently contains JITOrders in your suggested openapispec. But I assume this was more for demonstration purposes anyway.

[squadgazzz]

The new quote struct should have the uniform clearing prices instead of out_amount because the out_amount can be computed based on the prices. Other than that the plan looks good.

Ah, right. Updated the example.

Also clearingPrices currently contains JITOrders in your suggested openapispec. But I assume this was more for demonstration purposes anyway.

Thanks, it was a typo, replaced with a Price object.