Merge branch 'release/v2.12'

Author: KtorZ

docs/api/v2.10.0.yaml docs/api/v2.12.0.yamldocs/api/v2.10.0.yaml renamed to docs/api/v2.12.0.yaml

@@ -5,7 +5,7 @@ servers:
 
 info:
   title: Kupo
-  version: v2.10.0
+  version: v2.12.0
   license:
     name: MPL-2.0
     url: https://raw.githubusercontent.com/cardanosolutions/kupo/master/LICENSE
@@ -81,8 +81,8 @@ info:
     Make sure to have [nix](https://nixos.org/download.html#nix-install-linux) installed with a cache:
 
     ```
-    trusted-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= loony-tools:pr9m4BkM/5/eSTZlkQyRt57Jz7OMBxNSUiMC4FkcNfk=
-    substituters = https://cache.zw3rk.com/ https://cache.nixos.org/
+    trusted-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ=
+    substituters = https://cache.iog.io/ https://cache.nixos.org/
     ```
 
     On MacOS, you'll need to install `libffi` and `bzip2` if they aren't already installed.
@@ -273,6 +273,25 @@ info:
     $ man kupo
     ```
 
+    # Custom database indexes
+
+    Kupo supports custom database indexes, provided by environment variable.
+    Hence, any environment variable prefixed with `KUPO_INDEX_` will be parsed
+    and interpreted as a custom database index, managed with the pre-defined
+    indexes.
+
+    For example, you can add a custom index `inputsByPaymentCredentialUnspent`
+    for matching unspent inputs by payment cred by setting the following
+    environment variable:
+
+    ```env
+    KUPO_INDEX_inputsByPaymentCredentialUnspent="inputs(payment_credential COLLATE NOCASE) WHERE spent_at IS NULL"
+    ```
+
+    Use this carefully, as too many indexes may greatly impact the database sync performances and also other queries.
+
+    Existing indexes and the overall database internal schema is [available here](https://github.com/CardanoSolutions/kupo/tree/master/db#overview).
+
     # Patterns
 
     ## Overview
@@ -569,7 +588,7 @@ info:
       | Last Allegra block | N/A      | N/A                                                              |
       | Last Mary block    | N/A      | N/A                                                              |
       | Last Alonzo block  | 259180   | 0ad91d3bbe350b1cfa05b13dba5263c47c5eca4f97b3a3105eba96416785a487 |
-      | Last Conway block  | 55814394 | bdd4baa2c81d0500a695f836332193ea06c2ce364e585057142220fc0782144c |
+      | Last Babbage block | 55814394 | bdd4baa2c81d0500a695f836332193ea06c2ce364e585057142220fc0782144c |
       | Last Conway block  | N/A      | N/A                                                              |
 
       See <a target="_blank" href="https://github.com/input-output-hk/cardano-configurations/tree/master/network/preview">configuration files for <strong>Preview</strong></a>.
@@ -1260,6 +1279,31 @@ components:
             1220099e5e430475c219518179efc7e6c8289db028904834025d5b086: 231
             289db028904834025d5b085d5b08661220099e5e430475c2195181796.08661220099e: 1
 
+    ValueAsString:
+      type: object
+      description: A (multi-asset) value of a transaction's output.
+      additionalProperties: false
+      required:
+        - coins
+      properties:
+        coins:
+          type: string
+          description: A quantity of Lovelace, encoded as string when 'asset-quantity=string' is specified as media-type parameter.
+          example: "42"
+        assets:
+          type: object
+          description: A _key:value_ map of asset identifier → quantity.
+          propertyNames:
+            type: string
+            pattern: ^[a-f0-9]{56}(.[a-f0-9]{2,64})?$
+          additionalProperties:
+            x-additionalPropertiesName: "{policy-id}.{asset-name}"
+            type: string
+            description: A quantity of some asset, encoded as string when 'asset-quantity=string' is specified as media-type parameter.
+          example:
+            1220099e5e430475c219518179efc7e6c8289db028904834025d5b086: "231"
+            289db028904834025d5b085d5b08661220099e5e430475c2195181796.08661220099e: "1"
+
     Wildcard:
       type: string
       title: Wildcard
@@ -1317,6 +1361,58 @@ components:
             - $ref: "#/components/schemas/SpentAt"
             - type: "null"
 
+    MatchQuantityAsString:
+      type: object
+      additionalProperties: false
+      required:
+        - transaction_index
+        - transaction_id
+        - output_index
+        - address
+        - value
+        - datum_hash
+        - script_hash
+        - created_at
+        - spent_at
+      properties:
+        transaction_index:
+          $ref: "#/components/schemas/TransactionIndex"
+        transaction_id:
+          $ref: "#/components/schemas/TransactionId"
+        output_index:
+          $ref: "#/components/schemas/OutputIndex"
+        address:
+          $ref: "#/components/schemas/Address"
+        value:
+          $ref: "#/components/schemas/ValueAsString"
+        datum_hash:
+          $ref: "#/components/schemas/DatumHash"
+        datum:
+          description: The resolved datum, if available. The field is only and always present (yet may be `null`) if `?resolve_hashes` was set.
+          oneOf:
+            - <<: *BinaryData
+              description: A serialized Plutus' Data.
+            - type: "null"
+              description: None or unknown datum.
+        datum_type:
+          $ref: "#/components/schemas/DatumType"
+        script_hash:
+          $ref: "#/components/schemas/ScriptHash"
+        script:
+          description: The resolved script, if available. The field is only and always present (yet may be `null`) if `?resolve_hashes` was set.
+          oneOf:
+            - $ref: "#/components/schemas/Script"
+            - type: "null"
+              description: None or unknown script.
+        created_at:
+          <<: *Point
+          description: Block reference at which this transaction was included in the ledger.
+        spent_at:
+          description: Block reference at which this transaction input was spent, if any.
+          oneOf:
+            - $ref: "#/components/schemas/SpentAt"
+            - type: "null"
+
     Health:
       type: object
       description: An overview of the server & connection status. Note that, when `most_recent_checkpoint` and `most_recent_node_tip` are equal, the index is fully synchronized.
@@ -1325,6 +1421,8 @@ components:
         - connection_status
         - most_recent_checkpoint
         - most_recent_node_tip
+        - seconds_since_last_block
+        - network_synchronization
         - configuration
         - version
       properties:
@@ -1346,6 +1444,20 @@ components:
               description: Absolute slot number of the current tip of the node.
             - type: "null"
               description: Absolute slot number of the current tip of the node.
+        seconds_since_last_block:
+          oneOf:
+            - type: integer
+              description: Number of seconds elapsed since the last block was ingested by Kupo.
+            - type: "null"
+              description: Number of seconds elapsed since the last block was ingested by Kupo.
+        network_synchronization:
+          oneOf:
+            - type: number
+              minimum: 0
+              maximum: 1
+              description: A progress percentage of the synchronization towards the node tip.
+            - type: "null"
+              description: A progress percentage of the synchronization towards the node tip.
         configuration:
           type: object
           description: A summary of hand-picked configuration parameters.
@@ -1371,20 +1483,6 @@ components:
         - `connected` and `disconnected` (from `connection_status`) are encoded as `1.0` and `0.0` respectively.
         - `installed` and `deferred` (from `configuration.indexes`) are encoded as `1.0` and `0.0` respectively.
         - `version` is not present in the Prometheus metrics.
-      examples:
-        response:
-          value: |
-            # TYPE kupo_connection_status gauge
-            kupo_connection_status  1.0
-
-            # TYPE kupo_most_recent_checkpoint counter
-            kupo_most_recent_checkpoint  294998
-
-            # TYPE kupo_most_recent_node_tip counter
-            kupo_most_recent_node_tip  71753381
-
-            # TYPE kupo_configuration_indexes gauge
-            kupo_configuration_indexes  1.0
 
   parameters:
     asset-name:
@@ -1778,6 +1876,13 @@ paths:
         Optionally, use `?resolve_hashes` to automatically resolve and include `datum` and `script` associated with hash references, if available. Datums and scripts can otherwise be fetched using the [_Get Datum by Hash_](#tag/Datums/paths/~1datums~1{datum-hash}/get) and [_Get Script by Hash_](#tag/Scripts/paths/~1scripts~1{script-hash}/get) endpoints respectively.
 
         Note that it is generally a bad idea to fetch **ALL matches** for indexes built off permissive patterns (e.g. `*`), for the server will yield a large response.
+
+        > <sup><strong>TIP</strong></sup> <br/>
+        >
+        > You can customize coins and assets quantities encoding to always be strings instead of integers through the
+        > `Accept` header media-type as such:
+        >
+        > `Accept: application/json;asset-quantity=string`
       parameters:
         - $ref: "#/components/parameters/resolve-hashes"
         - $ref: "#/components/parameters/spent"
@@ -1801,6 +1906,11 @@ paths:
                 type: array
                 items:
                   $ref: "#/components/schemas/Match"
+            "application/json;charset=utf-8;asset-quantity=string":
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/MatchQuantityAsString"
         304:
           $ref: "#/components/responses/304"
 
@@ -1812,6 +1922,13 @@ paths:
       description: |
         Retrieve matches from the database matching the given pattern, in descending `slot_no` order. Results are streamed to the client for more efficiency.
         See [Patterns](#section/Patterns) for more information about constructing patterns.
+
+        > <sup><strong>TIP</strong></sup> <br/>
+        >
+        > You can customize coins and assets quantities encoding to always be strings instead of integers through the
+        > `Accept` header media-type as such:
+        >
+        > `Accept: application/json;asset-quantity=string`
       parameters:
         - $ref: "#/components/parameters/pattern"
         - $ref: "#/components/parameters/resolve-hashes"
@@ -1836,6 +1953,11 @@ paths:
                 type: array
                 items:
                   $ref: "#/components/schemas/Match"
+            "application/json;charset=utf-8;asset-quantity=string":
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/MatchQuantityAsString"
         304:
           $ref: "#/components/responses/304"
         400:
@@ -2197,6 +2319,24 @@ paths:
             "text/plain;charset=utf-8":
               schema:
                 $ref: "#/components/schemas/HealthPrometheus"
+              example: &HealthPrometheusExample |
+                # TYPE kupo_configuration_indexes gauge
+                kupo_configuration_indexes  1.0
+
+                # TYPE kupo_connection_status gauge
+                kupo_connection_status  1.0
+
+                # TYPE kupo_most_recent_checkpoint counter
+                kupo_most_recent_checkpoint  61264845
+
+                # TYPE kupo_most_recent_node_tip counter
+                kupo_most_recent_node_tip  82838775
+
+                # TYPE kupo_network_synchronization gauge
+                kupo_network_synchronization  0.73956
+
+                # TYPE kupo_seconds_since_last_block gauge
+                kupo_seconds_since_last_block  2.0
 
         202:
           description: Syncing
@@ -2207,6 +2347,7 @@ paths:
                 $ref: "#/components/schemas/Health"
 
             "text/plain;charset=utf-8":
+              example: *HealthPrometheusExample
               schema:
                 $ref: "#/components/schemas/HealthPrometheus"
 
@@ -2219,5 +2360,27 @@ paths:
                 $ref: "#/components/schemas/Health"
 
             "text/plain;charset=utf-8":
+              example: *HealthPrometheusExample
               schema:
                 $ref: "#/components/schemas/HealthPrometheus"
+
+  /metrics:
+    get:
+      operationId: getMetrics
+      tags: ["Health"]
+      summary: Get Metrics
+      description: |
+        Like [`/health`](#operation/getHealth), but always return `200 OK` as a status.
+      responses:
+        200:
+          description: Metrics
+          headers: *default-headers
+          content:
+            "text/plain;charset=utf-8":
+              example: *HealthPrometheusExample
+              schema:
+                $ref: "#/components/schemas/HealthPrometheus"
+
+            "application/json;charset=utf-8":
+              schema:
+                $ref: "#/components/schemas/Health"

docs/index.html

@@ -126,8 +126,8 @@
   </script>
 
   <div id="versions">
-    <a href="#">v2.10.0</a>
     <a href="#">v2.11.0</a>
+    <a href="#">v2.12.0</a>
     <a href="#">nightly</a>
     <script>
       ;[1,2,3].forEach(ix => {