Document solver competition information route

[vkgnosis]

Part of #127

This is the openapi documentation for the public route showing solver competition information.

Test Plan

CI

[codecov-commenter]

Codecov Report

Merging #185 (6bc1660) into main (3011d69) will increase coverage by 0.02%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##             main     #185      +/-   ##
==========================================
+ Coverage   64.55%   64.57%   +0.02%     
==========================================
  Files         185      185              
  Lines       38602    38602              
==========================================
+ Hits        24920    24928       +8     
+ Misses      13682    13674       -8     

[vkgnosis]

Comment by Filius on Discord:

From what I read, auctions (and their solutions) are only stored temporarily on the backend. As a solver developer, the process I would follow to benchmark my solution would be: (i) select an auction ID I would like to benchmark from my own logs, (ii) query solver competition endpoint to obtain maps of solvers -> settlements and (iii) try to understand why the solution with the highest objective value is better than mine. For (iii) I would need to be sure the response I obtained from the endpoint really corresponds to the auction I selected (input -> output). Since auction IDs are not unique, an auction timestamp would help me ensure I am looking at the right auction.

[vkgnosis]

We want to eventually store this information in our database for a long time but it might take a bit longer until we have this implemented. Until then we are planning on using a simple in memory store with some size limit. The auction ids are probably going to be truly unique in the future too but not yet.

Until we have both of that maybe it would reasonable for solver developers to persist the competition information on their own? In their solver implementations they get the auction id and could query the competition info ~a minute after solving and persist it locally.

[felixjff]

Agree.

[vkgnosis]

Comment by Filius on Discord:

With regards to the calldata, I wonder if it would be fair to expose the complete solution provided by solvers. In the information I requested, I explicitly mentioned clearing prices without the actual liquidity sources, so that at least the liquidity sources are kept "hidden". Would it be fair to show everyone what liquidity sources different solvers are using? After all, this is a competition.

[vkgnosis]

To me it makes sense to treat this as public because if your solution is the winning one it will be public anyway as part of the public transaction on chain.

[fleupold]

I think this is a very interesting question. Especially solvers with inventory might prefer not to expose their quotes publicly unless they have an upside (winning the batch). I wouldn't want them to not submit a solution if they think their chance of winning is small (but we can also wait and change the model when this happens).

For users however it would definitely be good to see the alternative prices (to highlight the price improvement competition brings) and maybe even simulate and plot the alternative solution. For a solver it might also be helpful to see the full simulation link to debug why the settlement was failing in the driver.

Maybe we start with all public and then adapt if it becomes an issue (winning solver will reveal their logic for sure)?

[nlordell]

We can start by only exposing name of winning solver while the competition is on-going. This way, other solvers don't have information on:

• Winning objective value (so they can penny the surplus by making the prices slightly better for the users at the expense of the buffers and their weekly payout - as long as its less than 100 COW - in order to win with a slight advantage)
• Calldata - the current routes being proposed and liquidity being used.

[vkgnosis]

It feels like our current goal with this route is to make it easier for external solver creators to get insight into the competition. If that is the goal then we don't need to show anything live. It is enough to only make this information available after a winning settlement has been picked and it has been settled.

If the goal is also to provide information that can be used live for example by the frontend to show a user that their order is part of some solutions or has been picked for the currently settling transaction, then we need to include more information.

I feel that there is little reason to show the competition while we're still collecting solutions from all the solvers. This part only takes 10 seconds. Once the driver has all the settlements and has decided which one the winner is but before waiting for the on chain transaction, we can publish all the information. Since the solutions have been collected there shouldn't be worries about pennying.

[nlordell]

If the goal is also to provide information that can be used live for example by the frontend to show a user that their order is part of some solutions or has been picked for the currently settling transaction, then we need to include more information.

I think this will eventually be the goal, however I think that we can get around to this once we do it the "right" way (i.e. implement one of your ideas from the discussion #175).

[nlordell]

Created #187 to discuss what the "complete" API can look like for use with the FE (where the current auction status is useful to display some extra information to the user).

[nlordell]

LGTM.

Might also be helpful for us - debugging wise - to include block information of the liquidity_collected_block and competition_simulation_block - but only if its easily accessible. Can also add this later, so approving regardless.

[vkgnosis]

Going to merge now with potentially changing something when I get to the implementation.