From 6bc16604efc76e4c2c4eee0f8f10ff3cc90c9330 Mon Sep 17 00:00:00 2001
From: Valentin <77051586+vkgnosis@users.noreply.github.com>
Date: Mon, 2 May 2022 13:28:01 +0200
Subject: [PATCH 1/2] Document solver competition information route

---
 crates/orderbook/openapi.yml | 39 ++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/crates/orderbook/openapi.yml b/crates/orderbook/openapi.yml
index acddf0c299..61d33aa977 100644
--- a/crates/orderbook/openapi.yml
+++ b/crates/orderbook/openapi.yml
@@ -483,6 +483,30 @@ paths:
           description: Too many order quotes
         500:
           description: Unexpected error quoting an order
+  /api/v1/solver_competition/{auction_id}:
+    get:
+      summary: Information about solver competition
+      description: |
+        Returns the settlements submitted by every solver for a specific auction
+        id. The auction id corresponds to the id external solvers are provided
+        with. Auction ids are not globally unique, they are reused from time to
+        time. The backend keeps the competition information for a limited amount
+        of time.
+      parameters:
+        - name: auction_id
+          in: path
+          required: true
+          schema:
+            type: integer
+      responses:
+        200:
+          description: competition info
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SolverCompetitionResponse"
+        404:
+          description: No competition information available for this auction id.
 components:
   schemas:
     TransactionHash:
@@ -965,3 +989,18 @@ components:
             the fee after this expiration date. Encoded as ISO 8601 UTC.
           type: string
           example: "1985-03-10T18:35:18.814523Z"
+    SolverCompetitionResponse:
+      type: object
+      description: Maps from solver name to object describing that solver's settlement.
+      additionalProperties:
+        "$ref": "#/components/schemas/SolverSettlement"
+    SolverSettlement:
+      type: object
+      properties:
+        objective_value:
+          type: number
+        gas_estimate:
+          type: number
+        call_data:
+          description: Hex encoded transaction calldata.
+          type: string

From 54e39c2b5041c818498ecc65ec94fbbee3219c0d Mon Sep 17 00:00:00 2001
From: Valentin <77051586+vkgnosis@users.noreply.github.com>
Date: Tue, 3 May 2022 11:55:26 +0200
Subject: [PATCH 2/2] Add a bunch more data as suggested in review

---
 crates/orderbook/openapi.yml | 55 ++++++++++++++++++++++++++++++------
 1 file changed, 47 insertions(+), 8 deletions(-)

diff --git a/crates/orderbook/openapi.yml b/crates/orderbook/openapi.yml
index 61d33aa977..503d948420 100644
--- a/crates/orderbook/openapi.yml
+++ b/crates/orderbook/openapi.yml
@@ -991,16 +991,55 @@ components:
           example: "1985-03-10T18:35:18.814523Z"
     SolverCompetitionResponse:
       type: object
-      description: Maps from solver name to object describing that solver's settlement.
-      additionalProperties:
-        "$ref": "#/components/schemas/SolverSettlement"
+      properties:
+        transaction_hash:
+          nullable: true
+          allOf:
+            - $ref: "#/components/schemas/TransactionHash"
+        gas_price:
+          type: number
+          description: gas price used for ranking solutions
+        solutions:
+          type: array
+          description: Maps from solver name to object describing that solver's settlement.
+          items:
+            $ref: "#/components/schemas/SolverSettlement"
     SolverSettlement:
       type: object
       properties:
-        objective_value:
-          type: number
-        gas_estimate:
-          type: number
+        solver:
+          type: string
+          description: name of the solver
+        objective:
+          type: object
+          properties:
+            total:
+              type: number
+              description: the total objective value used for ranking solutions
+            surplus:
+              type: number
+            fees:
+              type: number
+            cost:
+              type: number
+            gas:
+              type: number
+        prices:
+          type: object
+          additionalProperties:
+            $ref: "#/components/schemas/BigUint"
+          description: |
+            The prices of tokens for settled user orders as passed to the settlement contract.
+        orders:
+          type: array
+          description: the touched orders
+          items:
+            type: object
+            properties:
+              id:
+                $ref: "#/components/schemas/UID"
+              executed_amount:
+                $ref: "#/components/schemas/BigUint"
         call_data:
-          description: Hex encoded transaction calldata.
+          description: hex encoded transaction calldata
           type: string