From 0dd6217a49c7940ee1191ab05b09d4fa6cbff86b Mon Sep 17 00:00:00 2001
From: muXxer <git@muxxer.de>
Date: Wed, 20 Sep 2023 09:29:29 +0200
Subject: [PATCH] Add new outputs endpoint and `unlockableByAddress` query
 parameter

---
 tips/TIP-0026/indexer-rest-api.yaml | 112 ++++++++++++++++++++++++++++
 1 file changed, 112 insertions(+)

diff --git a/tips/TIP-0026/indexer-rest-api.yaml b/tips/TIP-0026/indexer-rest-api.yaml
index e824a7633..559337cec 100644
--- a/tips/TIP-0026/indexer-rest-api.yaml
+++ b/tips/TIP-0026/indexer-rest-api.yaml
@@ -14,6 +14,8 @@ externalDocs:
 servers:
   - url: 'http://127.0.0.1:14265'
 tags:
+  - name: outputs
+    description: Query all Outputs.
   - name: basic outputs
     description: Query Basic Outputs.
   - name: alias outputs
@@ -23,6 +25,98 @@ tags:
   - name: nft outputs
     description: Query NFT Outputs.
 paths:
+  /api/indexer/v1/outputs:
+    get:
+      tags:
+        - outputs
+      summary: Returns outputs filtered based on parameters.
+      description: Returns outputs filtered based on parameters.
+      parameters:
+        - in: query
+          name: unlockableByAddress
+          schema:
+            type: string
+          example: iota1qrhacyfwlcnzkvzteumekfkrrwks98mpdm37cj4xx3drvmjvnep6xqgyzyx
+          description: The Bech32-encoded address that should be searched for in all possible Unlock Conditions of outputs.
+        - in: query
+          name: hasNativeTokens
+          schema:
+            type: boolean
+          example: true
+          description: Filters outputs based on the presence of native tokens.
+        - in: query
+          name: minNativeTokenCount
+          schema:
+            type: integer
+          example: 2
+          description: Filters outputs that have at least a certain number of distinct native tokens.
+        - in: query
+          name: maxNativeTokenCount
+          schema:
+            type: integer
+          example: 5
+          description: Filters outputs that have at most a certain number of distinct native tokens.
+        - in: query
+          name: createdBefore
+          schema:
+            type: integer
+          example: 1643383242
+          description: Return outputs that were created before a certain Unix timestamp.
+        - in: query
+          name: createdAfter
+          schema:
+            type: integer
+          example: 1643383242
+          description: Return outputs that were created after a certain Unix timestamp.
+        - in: query
+          name: pageSize
+          schema:
+            type: integer
+          example: 10
+          description: The maximum amount of items returned in one call. If there are more items, a cursor to the next page is returned too.
+            The parameter is ignored when pageSize is defined via the cursor parameter.
+        - in: query
+          name: cursor
+          schema:
+            type: string
+          example: 0c78e998f5177834ecb3bae1596d5056af76e487386eecb19727465b4be86a790200.10
+          description: Starts the search from the cursor (confirmationMS+outputId.pageSize).
+      responses:
+        '200':
+          description: "Successful operation."
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OutputsResponse'
+              examples:
+                Query results in 3 outputs:
+                  $ref: >-
+                    #/components/examples/get-outputs-response-three-example
+                No matching outputIds found:
+                  $ref: >-
+                    #/components/examples/get-outputs-empty-response-example
+                Paging - more items found than it can fit on single page:
+                  $ref: >-
+                    #/components/examples/get-outputs-pagesize2-response-example
+        '400':
+          description: "Unsuccessful operation: indicates that the provided data is invalid."
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/BadRequestResponse'
+        '403':
+          description: "Unsuccessful operation: indicates that the endpoint is not available for public use."
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ForbiddenResponse'
+        '500':
+          description: "Unsuccessful operation: indicates that an unexpected, internal server error happened which prevented the node from fulfilling the request."
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/InternalErrorResponse'
+
   /api/indexer/v1/outputs/basic:
     get:
       tags:
@@ -36,6 +130,12 @@ paths:
             type: string
           example: iota1qrhacyfwlcnzkvzteumekfkrrwks98mpdm37cj4xx3drvmjvnep6xqgyzyx
           description: The Bech32-encoded address that should be searched for in the Address Unlock Condition of outputs.
+        - in: query
+          name: unlockableByAddress
+          schema:
+            type: string
+          example: iota1qrhacyfwlcnzkvzteumekfkrrwks98mpdm37cj4xx3drvmjvnep6xqgyzyx
+          description: The Bech32-encoded address that should be searched for in all possible Unlock Conditions of outputs.
         - in: query
           name: hasNativeTokens
           schema:
@@ -202,6 +302,12 @@ paths:
             type: string
           example: iota1qrhacyfwlcnzkvzteumekfkrrwks98mpdm37cj4xx3drvmjvnep6xqgyzyx
           description: Filter outputs based on bech32-encoded governor (governance controller) address.
+        - in: query
+          name: unlockableByAddress
+          schema:
+            type: string
+          example: iota1qrhacyfwlcnzkvzteumekfkrrwks98mpdm37cj4xx3drvmjvnep6xqgyzyx
+          description: The Bech32-encoded address that should be searched for in all possible Unlock Conditions of outputs.
         - in: query
           name: issuer
           schema:
@@ -498,6 +604,12 @@ paths:
             type: string
           example: iota1qrhacyfwlcnzkvzteumekfkrrwks98mpdm37cj4xx3drvmjvnep6xqgyzyx
           description: The Bech32-encoded address that should be searched for in the Address Unlock Condition of outputs.
+        - in: query
+          name: unlockableByAddress
+          schema:
+            type: string
+          example: iota1qrhacyfwlcnzkvzteumekfkrrwks98mpdm37cj4xx3drvmjvnep6xqgyzyx
+          description: The Bech32-encoded address that should be searched for in all possible Unlock Conditions of outputs.
         - in: query
           name: issuer
           schema: