From 56b64bd8c5bf7e36b4c320c65485bcba3895d166 Mon Sep 17 00:00:00 2001
From: rdlrt <3169068+rdlrt@users.noreply.github.com>
Date: Mon, 27 Feb 2023 02:09:54 +0000
Subject: [PATCH] credential_utxos: Add to specs and fix output vars to align
 with other endpoints

---
 files/grest/rpc/address/credential_utxos.sql |  4 +-
 specs/results/koiosapi-guild.yaml            | 50 ++++++++++++++++++++
 specs/results/koiosapi-mainnet.yaml          | 50 ++++++++++++++++++++
 specs/results/koiosapi-preprod.yaml          | 50 ++++++++++++++++++++
 specs/results/koiosapi-preview.yaml          | 50 ++++++++++++++++++++
 specs/templates/3-api-requestBodies.yaml     | 18 +++++++
 specs/templates/4-api-schemas.yaml           | 11 +++++
 specs/templates/api-main.yaml                | 21 ++++++++
 8 files changed, 252 insertions(+), 2 deletions(-)

diff --git a/files/grest/rpc/address/credential_utxos.sql b/files/grest/rpc/address/credential_utxos.sql
index c4f13cb9..02b3a1d8 100644
--- a/files/grest/rpc/address/credential_utxos.sql
+++ b/files/grest/rpc/address/credential_utxos.sql
@@ -1,8 +1,8 @@
 CREATE OR REPLACE FUNCTION grest.credential_utxos (_payment_credentials text[])
   RETURNS TABLE (
     tx_hash text,
-    index smallint,
-    balance text
+    tx_index smallint,
+    value text
   )
   LANGUAGE PLPGSQL
   AS $$
diff --git a/specs/results/koiosapi-guild.yaml b/specs/results/koiosapi-guild.yaml
index c31b8b89..2d93ab29 100644
--- a/specs/results/koiosapi-guild.yaml
+++ b/specs/results/koiosapi-guild.yaml
@@ -584,6 +584,27 @@ paths:
           $ref: "#/components/responses/NotFound"
       summary: Address Transactions
       description: Get the transaction hash list of input address array, optionally filtering after specified block height (inclusive)
+  /credential_utxos: #RPC
+    post:
+      tags:
+        - Address
+    requestBody:
+      $ref: "#/components/requestBodies/credential_utxos"
+    responses:
+        "200":
+          description: Array of UTxOs with balances
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/credential_utxos"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+      summary: UTxOs from payment credentials
+      description: Get a list of UTxO against input payment credential array including their balances
   /address_assets: #RPC
     post:
       tags:
@@ -1807,6 +1828,24 @@ components:
                 - b6b4b2b1e9e78369992aa5dd108aa4c3328fa228794ea9693400c2a0
                 - 35e45387fc2acdd5cd641e339990e665ad4d9d065a41c94bc0b4be13
               _after_block_height: 120000
+    credential_utxos:
+      content:
+        application/json:
+          schema:
+            required:
+              - _payment_credentials
+            type: object
+            properties:
+              _payment_credentials:
+                format: text
+                type: array
+                items:
+                  type: string
+                description: Array of Cardano payment credential(s) in hex format
+            example:
+              _payment_credentials:
+                - b6b4b2b1e9e78369992aa5dd108aa4c3328fa228794ea9693400c2a0
+                - 35e45387fc2acdd5cd641e339990e665ad4d9d065a41c94bc0b4be13
     tx_ids:
       content:
         application/json:
@@ -2805,6 +2844,17 @@ components:
             $ref: "#/components/schemas/account_assets/items/properties/asset_list"
     credential_txs:
       $ref: "#/components/schemas/address_txs"
+    credential_utxos:
+      type: array
+      items:
+        type: object
+        properties:
+          tx_hash:
+            $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/tx_hash"
+          tx_index:
+            $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/tx_index"
+          value:
+            $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/value"
     account_list:
       type: array
       items:
diff --git a/specs/results/koiosapi-mainnet.yaml b/specs/results/koiosapi-mainnet.yaml
index efdecb82..bf5586f4 100644
--- a/specs/results/koiosapi-mainnet.yaml
+++ b/specs/results/koiosapi-mainnet.yaml
@@ -584,6 +584,27 @@ paths:
           $ref: "#/components/responses/NotFound"
       summary: Address Transactions
       description: Get the transaction hash list of input address array, optionally filtering after specified block height (inclusive)
+  /credential_utxos: #RPC
+    post:
+      tags:
+        - Address
+    requestBody:
+      $ref: "#/components/requestBodies/credential_utxos"
+    responses:
+        "200":
+          description: Array of UTxOs with balances
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/credential_utxos"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+      summary: UTxOs from payment credentials
+      description: Get a list of UTxO against input payment credential array including their balances
   /address_assets: #RPC
     post:
       tags:
@@ -1807,6 +1828,24 @@ components:
                 - 025b0a8f85cb8a46e1dda3fae5d22f07e2d56abb4019a2129c5d6c52
                 - 13f6870c5e4f3b242463e4dc1f2f56b02a032d3797d933816f15e555
               _after_block_height: 6238675
+    credential_utxos:
+      content:
+        application/json:
+          schema:
+            required:
+              - _payment_credentials
+            type: object
+            properties:
+              _payment_credentials:
+                format: text
+                type: array
+                items:
+                  type: string
+                description: Array of Cardano payment credential(s) in hex format
+            example:
+              _payment_credentials:
+                - 025b0a8f85cb8a46e1dda3fae5d22f07e2d56abb4019a2129c5d6c52
+                - 13f6870c5e4f3b242463e4dc1f2f56b02a032d3797d933816f15e555
     tx_ids:
       content:
         application/json:
@@ -2805,6 +2844,17 @@ components:
             $ref: "#/components/schemas/account_assets/items/properties/asset_list"
     credential_txs:
       $ref: "#/components/schemas/address_txs"
+    credential_utxos:
+      type: array
+      items:
+        type: object
+        properties:
+          tx_hash:
+            $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/tx_hash"
+          tx_index:
+            $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/tx_index"
+          value:
+            $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/value"
     account_list:
       type: array
       items:
diff --git a/specs/results/koiosapi-preprod.yaml b/specs/results/koiosapi-preprod.yaml
index b3681a1d..409c1030 100644
--- a/specs/results/koiosapi-preprod.yaml
+++ b/specs/results/koiosapi-preprod.yaml
@@ -584,6 +584,27 @@ paths:
           $ref: "#/components/responses/NotFound"
       summary: Address Transactions
       description: Get the transaction hash list of input address array, optionally filtering after specified block height (inclusive)
+  /credential_utxos: #RPC
+    post:
+      tags:
+        - Address
+    requestBody:
+      $ref: "#/components/requestBodies/credential_utxos"
+    responses:
+        "200":
+          description: Array of UTxOs with balances
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/credential_utxos"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+      summary: UTxOs from payment credentials
+      description: Get a list of UTxO against input payment credential array including their balances
   /address_assets: #RPC
     post:
       tags:
@@ -1807,6 +1828,24 @@ components:
                 - b429738bd6cc58b5c7932d001aa2bd05cfea47020a556c8c753d4436
                 - 82e016828989cd9d809b50d6976d9efa9bc5b2c1a78d4b3bfa1bb83b
               _after_block_height: 9417
+    credential_utxos:
+      content:
+        application/json:
+          schema:
+            required:
+              - _payment_credentials
+            type: object
+            properties:
+              _payment_credentials:
+                format: text
+                type: array
+                items:
+                  type: string
+                description: Array of Cardano payment credential(s) in hex format
+            example:
+              _payment_credentials:
+                - b429738bd6cc58b5c7932d001aa2bd05cfea47020a556c8c753d4436
+                - 82e016828989cd9d809b50d6976d9efa9bc5b2c1a78d4b3bfa1bb83b
     tx_ids:
       content:
         application/json:
@@ -2805,6 +2844,17 @@ components:
             $ref: "#/components/schemas/account_assets/items/properties/asset_list"
     credential_txs:
       $ref: "#/components/schemas/address_txs"
+    credential_utxos:
+      type: array
+      items:
+        type: object
+        properties:
+          tx_hash:
+            $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/tx_hash"
+          tx_index:
+            $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/tx_index"
+          value:
+            $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/value"
     account_list:
       type: array
       items:
diff --git a/specs/results/koiosapi-preview.yaml b/specs/results/koiosapi-preview.yaml
index 3e1ba175..f883968e 100644
--- a/specs/results/koiosapi-preview.yaml
+++ b/specs/results/koiosapi-preview.yaml
@@ -584,6 +584,27 @@ paths:
           $ref: "#/components/responses/NotFound"
       summary: Address Transactions
       description: Get the transaction hash list of input address array, optionally filtering after specified block height (inclusive)
+  /credential_utxos: #RPC
+    post:
+      tags:
+        - Address
+    requestBody:
+      $ref: "#/components/requestBodies/credential_utxos"
+    responses:
+        "200":
+          description: Array of UTxOs with balances
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/credential_utxos"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+      summary: UTxOs from payment credentials
+      description: Get a list of UTxO against input payment credential array including their balances
   /address_assets: #RPC
     post:
       tags:
@@ -1807,6 +1828,24 @@ components:
                 - 33c378cee41b2e15ac848f7f6f1d2f78155ab12d93b713de898d855f
                 - 52e63f22c5107ed776b70f7b92248b02552fd08f3e747bc745099441
               _after_block_height: 40356
+    credential_utxos:
+      content:
+        application/json:
+          schema:
+            required:
+              - _payment_credentials
+            type: object
+            properties:
+              _payment_credentials:
+                format: text
+                type: array
+                items:
+                  type: string
+                description: Array of Cardano payment credential(s) in hex format
+            example:
+              _payment_credentials:
+                - 33c378cee41b2e15ac848f7f6f1d2f78155ab12d93b713de898d855f
+                - 52e63f22c5107ed776b70f7b92248b02552fd08f3e747bc745099441
     tx_ids:
       content:
         application/json:
@@ -2805,6 +2844,17 @@ components:
             $ref: "#/components/schemas/account_assets/items/properties/asset_list"
     credential_txs:
       $ref: "#/components/schemas/address_txs"
+    credential_utxos:
+      type: array
+      items:
+        type: object
+        properties:
+          tx_hash:
+            $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/tx_hash"
+          tx_index:
+            $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/tx_index"
+          value:
+            $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/value"
     account_list:
       type: array
       items:
diff --git a/specs/templates/3-api-requestBodies.yaml b/specs/templates/3-api-requestBodies.yaml
index 639f9267..0b69563f 100644
--- a/specs/templates/3-api-requestBodies.yaml
+++ b/specs/templates/3-api-requestBodies.yaml
@@ -148,6 +148,24 @@ requestBodies:
                 - ##credential_txs_payment_credentials1_rb##
                 - ##credential_txs_payment_credentials2_rb##
               _after_block_height: ##address_txs_after_block_height_rb##
+    credential_utxos:
+      content:
+        application/json:
+          schema:
+            required:
+              - _payment_credentials
+            type: object
+            properties:
+              _payment_credentials:
+                format: text
+                type: array
+                items:
+                  type: string
+                description: Array of Cardano payment credential(s) in hex format
+            example:
+              _payment_credentials:
+                - ##credential_txs_payment_credentials1_rb##
+                - ##credential_txs_payment_credentials2_rb##
     tx_ids:
       content:
         application/json:
diff --git a/specs/templates/4-api-schemas.yaml b/specs/templates/4-api-schemas.yaml
index f8f4669a..9977e156 100644
--- a/specs/templates/4-api-schemas.yaml
+++ b/specs/templates/4-api-schemas.yaml
@@ -898,6 +898,17 @@ schemas:
             $ref: "#/components/schemas/account_assets/items/properties/asset_list"
     credential_txs:
       $ref: "#/components/schemas/address_txs"
+    credential_utxos:
+      type: array
+      items:
+        type: object
+        properties:
+          tx_hash:
+            $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/tx_hash"
+          tx_index:
+            $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/tx_index"
+          value:
+            $ref: "#/components/schemas/tx_info/items/properties/outputs/items/properties/value"
     account_list:
       type: array
       items:
diff --git a/specs/templates/api-main.yaml b/specs/templates/api-main.yaml
index 9576440f..62926a96 100644
--- a/specs/templates/api-main.yaml
+++ b/specs/templates/api-main.yaml
@@ -389,6 +389,27 @@ paths:
           $ref: "#/components/responses/NotFound"
       summary: Address Transactions
       description: Get the transaction hash list of input address array, optionally filtering after specified block height (inclusive)
+  /credential_utxos: #RPC
+    post:
+      tags:
+        - Address
+    requestBody:
+      $ref: "#/components/requestBodies/credential_utxos"
+    responses:
+        "200":
+          description: Array of UTxOs with balances
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/credential_utxos"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+      summary: UTxOs from payment credentials
+      description: Get a list of UTxO against input payment credential array including their balances
   /address_assets: #RPC
     post:
       tags: