add spec

specs/payment-api.yaml

@@ -360,25 +360,6 @@ paths:
         500:
           $ref: 'common.yaml#/responses/ServerError'
 
-  /payments/{paymentId}:
-    get:
-      tags:
-        - requestor
-        - provider
-      summary: Get Payment.
-      operationId: getPayment
-      parameters:
-        - $ref: '#/components/parameters/paymentId'
-      responses:
-        200:
-          $ref: '#/components/responses/Payment'
-        401:
-          $ref: 'common.yaml#/responses/Unauthorized'
-        404:
-          $ref: 'common.yaml#/responses/NotFound'
-        500:
-          $ref: 'common.yaml#/responses/ServerError'
-
   /providerAccounts:
     get:
       tags:
@@ -683,6 +664,46 @@ paths:
         500:
           $ref: 'common.yaml#/responses/ServerError'
 
+  /payments/{paymentId}:
+    get:
+      tags:
+        - requestor
+        - provider
+      summary: Get Payment.
+      operationId: getPayment
+      parameters:
+        - $ref: '#/components/parameters/paymentId'
+      responses:
+        200:
+          $ref: '#/components/responses/Payment'
+        401:
+          $ref: 'common.yaml#/responses/Unauthorized'
+        404:
+          $ref: 'common.yaml#/responses/NotFound'
+        500:
+          $ref: 'common.yaml#/responses/ServerError'
+
+  /payments/status:
+    get:
+      tags:
+        - requestor
+        - provider
+      summary: Get status of the payment driver
+      description: >
+        This only relates to the erc20 driver, not erc20legacy. The returned
+        list contains individual status properties, which can be used to identify
+        problems like missing funds or misconfigured max fee per gas on a per-chain
+        (network) basis.
+      parameters:
+        - $ref: '#components/parameters/paymentStatusQuery'
+      responses:
+        200:
+          $ref: '#/components/responses/PaymentStatus'
+        401:
+          $ref: 'common.yaml#/responses/Unauthorized'
+        500:
+          $ref: 'common.yaml#/responses/ServerError'
+
   /requestorAccounts:
     get:
       tags:
@@ -754,6 +775,12 @@ components:
       in: path
       schema:
         type: string
+
+    paymentStatusQuery:
+      name: paymentStatusQuery
+      required: true
+      in: path
+      $ref: '#/components/schemas/PaymentStatusQuery'
 
     allocationIds:
       name: allocationIds
@@ -893,6 +920,15 @@ components:
             items:
               $ref: '#/components/schemas/Payment'
 
+    PaymentStatus:
+      description: OK
+      content:
+        application/json:
+          schema:
+            type: array
+            items:
+              $ref: '#components/schemas/PaymentStatusProperty'
+
     DebitNoteEventList:
       description: OK
       content:
@@ -1243,6 +1279,63 @@ components:
         - activityPayments
         - details
 
+    PaymentStatusQuery:
+      description: Filter for driver status properties
+      type: object
+      properties:
+        network:
+          type: string
+
+    PaymentStatusProperty:
+      type: object
+      description: Individual actionable property of the payment driver status
+      readOnly: true
+      properties:
+        kind:
+          description: >
+            Determines what property this is.
+            - InsufficientGas -- Driver cannot proceed due to missing gas.
+            - InsufficientToken -- Driver cannot proceed due to missing tokens.
+            - CantSign -- Driver cannot sign transactions (locked wallet?).
+            - RpcError -- All configured RPC endpoints are failing.
+            - TxStuck -- Transaction was sent to blockchain successfully but cannot
+              proceed any further. Likely indicative of too low setting of max fee
+              per gas.
+          type: string
+          enum:
+          - InsufficientGas
+          - InsufficientToken
+          - CantSign
+          - TxStuck
+          - RpcError
+        network:
+          description: >
+            Indicates which chain the problem occurs on. No statuses other than
+            CantSign necessarily imply issues on other chains than the one the status
+            property originates from.
+          type: string
+        neededGasEst:
+          description: >
+            Estimate total required gas to complete all outstanding transactions.
+
+            Only present for InsufficientGas
+          type: string
+        neededTokenEst:
+          description: >
+            Estimate total required token to complete all outstanding transactions.
+
+            Only present for InsufficientToken
+          type: string
+        address:
+          description: >
+            Relates the status event to a specific blockchain address.
+
+            Only present for CantSign.
+          type: string
+      required:
+        - kind
+        - network
+
     AgreementPayment:
       description: >
         Share of a Payment assigned to an Agreement, but not to any particular