From 19805d71050a2daa7992e6f64ebde17b21bd1759 Mon Sep 17 00:00:00 2001
From: Justin Traglia <jtraglia@pm.me>
Date: Tue, 8 Nov 2022 15:26:58 -0600
Subject: [PATCH] Update get registrations endpoint

---
 apis/relay/data/validator_registration.yaml | 69 ++++++++++++++++++++-
 relay-oapi.yaml                             |  4 ++
 types/requests.yaml                         | 16 +++++
 types/responses.yaml                        |  5 ++
 4 files changed, 91 insertions(+), 3 deletions(-)

diff --git a/apis/relay/data/validator_registration.yaml b/apis/relay/data/validator_registration.yaml
index e1111a5..0f28270 100644
--- a/apis/relay/data/validator_registration.yaml
+++ b/apis/relay/data/validator_registration.yaml
@@ -1,10 +1,16 @@
 get:
   operationId: "getValidatorRegistration"
-  summary: Check that a validator is registered with the relay.
+  summary: Check if a validator is registered with the relay.
   description: |
-    * Returns the latest validator registration for a given pubkey.
+    * Return `pubkey` if there's a registration with the
+      `pubkey`/`fee_recipient`/`gas_limit` combination.
     
     * Useful to check whether your own registration was successful.
+    
+    * To check if a validator is registered with a relay, you must know the
+      validators public key and its fee recipient. With privacy in mind, it's
+      more difficult for a random person to check if your validator is
+      registered with a particular relay.
   tags:
     - Data
   parameters:
@@ -14,13 +20,70 @@ get:
       description: The validator's public key.
       schema:
         $ref: "../../../relay-oapi.yaml#/components/schemas/Pubkey"
+    - name: fee_recipient
+      in: query
+      required: true
+      description: The fee recipient in the validator's registration.
+      schema:
+        $ref: "../../../beacon-apis/types/primitive.yaml#/ExecutionAddress"
+    - name: gas_limit
+      in: query
+      required: false
+      description: The gas limit in the validator's registration.
+      schema:
+        $ref: "../../../beacon-apis/types/primitive.yaml#/Uint64"
+  responses:
+    "200":
+      description: Success response.
+      content:
+        application/json:
+          schema:
+            $ref: "../../../relay-oapi.yaml#/components/schemas/GetValidatorRegistrationsResponse"
+    "400":
+      description: Error response.
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: "../../../relay-oapi.yaml#/components/schemas/ErrorMessage"
+              - example:
+                  code: 400
+                  message: "missing pubkey argument"
+    "500":
+      $ref: "../../../relay-oapi.yaml#/components/responses/InternalError"
+
+post:
+  operationId: "getValidatorRegistrations"
+  summary: Check if a group of validators is registered with the relay.
+  description: |
+    * Perform a bulk check for validator registrations.
+    
+    * The `missing` query argument alters the behavior of this endpoint. When
+      specified, the relay will only return pubkeys for registrations that it
+      did not find.
+  tags:
+    - Data
+  parameters:
+    - name: missing
+      in: query
+      required: false
+      description: Only return missing pubkeys. No value required.
+      schema:
+        type: string
+  requestBody:
+    description: A list of registrations to check for.
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: "../../../relay-oapi.yaml#/components/schemas/GetValidatorRegistrationsRequest"
   responses:
     "200":
       description: Success response.
       content:
         application/json:
           schema:
-            $ref: "../../../beacon-apis/types/registration.yaml#/SignedValidatorRegistration"
+            $ref: "../../../relay-oapi.yaml#/components/schemas/GetValidatorRegistrationsResponse"
     "400":
       description: Error response.
       content:
diff --git a/relay-oapi.yaml b/relay-oapi.yaml
index 4f008d9..a610d4d 100644
--- a/relay-oapi.yaml
+++ b/relay-oapi.yaml
@@ -51,6 +51,8 @@ components:
       $ref: "./types/misc.yaml#/OrderBy"
     SubmitBlockRequest:
       $ref: "./types/requests.yaml#/SubmitBlockRequest"
+    GetValidatorRegistrationsRequest:
+      $ref: "./types/requests.yaml#/GetValidatorRegistrationsRequest"
     ValidatorsResponse:
       $ref: "./types/responses.yaml#/ValidatorsResponse"
     SubmitBlockResponse:
@@ -59,6 +61,8 @@ components:
       $ref: "./types/responses.yaml#/DeliveredPayloadsResponse"
     ReceivedBlocksResponse:
       $ref: "./types/responses.yaml#/ReceivedBlocksResponse"
+    GetValidatorRegistrationsResponse:
+      $ref: "./types/responses.yaml#/GetValidatorRegistrationsResponse"
 
   responses:
     InternalError:
diff --git a/types/requests.yaml b/types/requests.yaml
index aaa4eca..f22d749 100644
--- a/types/requests.yaml
+++ b/types/requests.yaml
@@ -7,3 +7,19 @@ SubmitBlockRequest:
       $ref: "../beacon-apis/types/bellatrix/execution_payload.yaml#/Bellatrix/ExecutionPayload"
     signature:
       $ref: "../beacon-apis/types/primitive.yaml#/Signature"
+
+GetValidatorRegistrationsRequestEntry:
+  type: object
+  required: [pubkey, fee_recipient]
+  properties:
+    pubkey:
+      $ref: "../beacon-apis/types/primitive.yaml#/Pubkey"
+    fee_recipient:
+      $ref: "../beacon-apis/types/primitive.yaml#/ExecutionAddress"
+    gas_limit:
+      $ref: "../beacon-apis/types/primitive.yaml#/Uint64"
+
+GetValidatorRegistrationsRequest:
+  type: array
+  items:
+    $ref: "./requests.yaml#/GetValidatorRegistrationsRequestEntry"
diff --git a/types/responses.yaml b/types/responses.yaml
index b720c19..03a7490 100644
--- a/types/responses.yaml
+++ b/types/responses.yaml
@@ -36,3 +36,8 @@ SubmitBlockResponse:
       $ref: "./responses.yaml#/SubmitBlockResponseMessage"
     signature:
       $ref: "../beacon-apis/types/primitive.yaml#/Signature"
+
+GetValidatorRegistrationsResponse:
+  type: array
+  items:
+    $ref: "../beacon-apis/types/primitive.yaml#/Pubkey"