diff --git a/CHANGELOG.md b/CHANGELOG.md index 99a193f4..6733bcfe 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,4 +1,4 @@ -### [2.1.0] - UNRELEASED +### [2.1.0] - 2022-10-22 > **Warning** > **Internal Breaking-Change** @@ -22,7 +22,7 @@ > **Note** - > Filtering is done by scanning linearly over all results, whereas matching is much faster and leverages the database. One can however combine filters and matches in all kind of ways. + > Filtering is done by scanning linearly over all results, whereas matching is much faster and leverages the database's internal indexes. One can however combine filters and matches in all kind of ways. - [📌 #56](https://github.com/CardanoSolutions/kupo/issues/56) - New pattern format to match results by policy id or asset id. Also added two new HTTP query parameters for filtering matches: `policy_id` & `asset_name`. See more information in the [📖 API Reference](https://cardanosolutions.github.io/kupo/#operation/getAllMatches). @@ -37,7 +37,7 @@ > **Note** - > Filtering is done by scanning linearly over all results, whereas matching is much faster and leverages the database. One can however combine filters and matches in all kind of ways. + > Filtering is done by scanning linearly over all results, whereas matching is much faster and leverages the database's internal indexes. One can however combine filters and matches in all kind of ways. - [📌 #51](https://github.com/CardanoSolutions/kupo/issues/51) - New endpoint to retrieve transaction metadata by slot number, possibly filtered by transaction id or output reference. @@ -51,6 +51,8 @@ - `PUT /patterns` → [📖 API Reference](https://cardanosolutions.github.io/kupo/#operation/putPatterns) +- New command-line flag `--defer-db-indexes` to be given during the **very first** synchronization to postpone the creation of some non-essential database indexes. Non-essential refers to indexes that are needed to speed up some queries (e.g. querying by payment credentials) but that do not play a role in synchronization. In fact, maintaining such indexes during synchronizations (millions of blocks) adds a lot of unnecessary overhead. Indexes can be created after the facts in a couple of minutes on a standard laptop. This flag therefore comes in handy to speed up an initial synchronization. Once synchronized, the server can be restarted without the flag to automatically create the necessary indexes. + - The server now makes use of an internal resource pool when it comes to database connections. This pool can be configured using a new command-line option `--max-concurrency`. Users running an instance of Kupo on a capable machine (e.g. 32-cores) may want to increase the default of 50. #### Changed diff --git a/README.md b/README.md index 73d55a5b..756be1d8 100644 --- a/README.md +++ b/README.md @@ -54,38 +54,47 @@ See [projects 🎯](https://github.com/CardanoSolutions/kupo/projects?type=class # Alternatives -Kupo is well-suited for small applications which need either: +Kupo is well-suited for small (or large) applications which need either: -- a global chain index for resolving output references; -- a on-the-fly monitoring of an address over a short period of time. +- a global chain index for resolving outputs by address, policy id or output reference; +- a on-the-fly monitoring of an address, policy id or specific transaction output over a short period of time. It runs in constant memory and is blazing fast. Yet, its use-cases are limited. Here below we provide some possible alternatives with different trade-offs:
- oura + Scrolls -Key difference(s): Oura in itself does not provide any chain-indexing, but it supports pluggable sinks where filtered data from the Cardano blockchain can be dumped into (e.g. Elastic Search or Kafka). It also supports a wider variety of events. All-in-all, a good fit for more elaborate solutions. +Key differences(s): Scrolls provides (at this stage) an in-memory aggregation engine via Redis. It allows applications to watch and react instantly on the evolution of some aggregated metric (see Scrolls' README for details about what metrics are supported). Because the data is fully stored in-memory, it is not possible to index the entire chain without resorting to large memory requirements. Hence it is more tailored to specific handpicked pieces of information. It also synchronizes blocks from the chain using the node-to-node protocol which means that it can do so on any remote node relay, but it is also slower (because a more defensive protocol) than the node-to-client protocol upon which Kupo relies.

- Learn more + Learn more

- scrolls + Oura -Key differences(s): Scrolls provides (at this stage) only an in-memory storage via Redis. This means that it's not possible to index the entire chain without resorting to large memory requirements. It also synchronizes blocks from the chain using the node-to-node protocol which means that it can do so on any remote node relay, but it is also slower (because a more defensive protocol) than the node-to-client protocol upon which Kupo relies. +Key difference(s): Oura in itself does not provide any chain-indexing, but it supports pluggable sinks where filtered data from the Cardano blockchain can be dumped into (e.g. Elastic Search or Kafka). It also supports a wider variety of events. All-in-all, a good fit for more elaborate solutions.

- Learn more + Learn more

+
+ Carp + +Key difference(s): Carp is a modular blockchain indexer built on top of Oura; it synchronizes data in a PostgreSQL database based on behaviors described in _tasks_ (Rust standalone plugins). Some pre-defined common tasks are already available, other can be written on-demand to fit one's use case. As a primary interface, Carps fully relies on PostgreSQL. + +

+ Learn more +

+
cardano-db-sync -Key difference(s): cardano-db-sync synchronizes ALL data from the Cardano blockchain, whereas Kupo focuses only on transaction outputs. This comes with obvious trade-offs in both on-disk storage but also runtime requirements. +Key difference(s): cardano-db-sync synchronizes ALL data from the Cardano blockchain, whereas Kupo focuses only on transaction outputs. This comes with obvious trade-offs in both on-disk storage, runtime requirements and performances. Kupo is usually an order of magnitude faster for retrieving outputs by address, stake address or policy id. Note also that like Carp, cardano-db-sync's primary interface is a PostgreSQL database whereas Kupo offers a higher-level HTTP API over JSON.

Learn more @@ -93,19 +102,18 @@ Key difference(s): cardano-db-sync synchronizes ALL data from the Cardano blockc

- plutus-chain-index + Marconi -Key differences(s): the plutus-chain-index is the native component behind the PAB (Plutus Application Backend). It is however intended to be user-facing and as such, does not provide a friendly user experience for uses outside of the PAB's internals. +Key differences(s): In a similar fashion to Carp, Marconi offers a modular indexer infrastructure where users can customize data streams through standalone plugins (however written in Haskell). It synchronizes data across multiple streams (utxo, datums and scripts), filters them based on custom plugins and stores them in a SQLite database. At this stage, Marconi is also in at an early development phase.

- Learn more + Learn more

## Sponsors 💖

- @@ -117,10 +125,8 @@ Key differences(s): the plutus-chain-index is the native component behind the PA - -

diff --git a/docs/api/latest.yaml b/docs/api/latest.yaml index 16685862..457e8bcb 100644 --- a/docs/api/latest.yaml +++ b/docs/api/latest.yaml @@ -5,7 +5,7 @@ servers: info: title: Kupo - version: "latest: v2.0.0-beta" + version: "latest: v2.1.0" license: name: MPL-2.0 url: https://raw.githubusercontent.com/cardanosolutions/kupo/master/LICENSE diff --git a/docs/api/v2.1.0.yaml b/docs/api/v2.1.0.yaml new file mode 100644 index 00000000..291dc2c4 --- /dev/null +++ b/docs/api/v2.1.0.yaml @@ -0,0 +1,1613 @@ +openapi: 3.0.0 + +servers: + - url: http://localhost:1442/ + +info: + title: Kupo + version: "v2.1.0" + license: + name: MPL-2.0 + url: https://raw.githubusercontent.com/cardanosolutions/kupo/master/LICENSE + x-logo: + url: ./kupo.png + altText: Kupo! + + description: | + # Overview + + **Kupo** is a lightweight, configurable, **chain-index** for the Cardano + blockchain. It synchronizes data from the blockchain according to + **patterns** matching addresses present in transaction outputs, to build a + **lookup table** from matches to their associated **output references, + values and datum hashes.** + + # Installation + + ### From pre-compiled executables + + Pre-compiled static binaries can be downloaded as build artifacts from + [latest releases](https://github.com/CardanoSolutions/kupo/releases) or the + continuous [`Nix` Github workflow](https://github.com/CardanoSolutions/kupo/actions). + + ``` + ... + ├── bin + │ └── kupo + └── share + ├── bash-completion + │   └── completions + │   └── kupo + ├── kupo + │   ├── LICENSE + │   └── api.yaml + ├── man + │   └── man1 + │   └── kupo.1 + └── zsh + └── site-functions + └── _kupo + ``` + + Once installed, `man kupo` or `kupo --help` comes in handy. + + ### From Docker + + Kupo is available as a standalone Docker image on [DockerHub](https://hub.docker.com/repository/docker/cardanosolutions/kupo). + + ```console + $ docker pull cardanosolutions/kupo + ``` + + ### From source + + #### Pre-requisite + + On Linux, make sure to have [nix](https://nixos.org/download.html#nix-install-linux) and [cachix](https://www.cachix.org/) installed. + Configure cachix to use `kupo.cachix.org-1:RzYQ8KVjRJdPNt/Bhq/UqdyGYWFM8ShjEMNG8wzHBQ4=` (`cachix use kupo`). + + On MacOS, you'll need `cabal` as well as a few system dependencies. Follow the [instructions to install `cardano-node` on the developer portal](https://developers.cardano.org/docs/get-started/installing-cardano-node#macos) since Kupo share a similar set of dependencies. + + #### Building + + ```console + $ make + ``` + + # Getting Started + + Kupo connects to a _local [cardano-node](https://github.com/input-output-hk/cardano-node/)_ + in order to receive information from the blockchain. It goes without saying + that an up-and-running cardano-node (or an equivalent Ogmios connection) is + required to run Kupo! + + A single Kupo server is meant to build an index for a specific set of outputs. + Outputs are matched according to flexible patterns. Once + matched, results can be queried as JSON via HTTP GET requests. For + instance, it is possible to synchronize all addresses associated with a + given stake key (e.g. `stake_vkh14hkp0sncfkt76spuqydtww4r900hfmsseezztzlh9sjkkjx6d7q`). + + Provided that the configuration and IPC socket for a cardano-node are + available in `some-folder/cardano-node`, one can start a Kupo server as + follows: + + ```console + $ kupo \ + --node-socket some-folder/cardano-node/node.socket \ + --node-config some-folder/cardano-node/config.json \ + --since origin \ + --defer-db-indexes \ + --match "*/stake_vkh14hkp0sncfkt76spuqydtww4r900hfmsseezztzlh9sjkkjx6d7q" \ + --in-memory + ``` + + #### --in-memory / --workdir \ + + This will build an index from the beginning of the blockchain (i.e.`origin`) + of all transaction outputs where that stake key has been involved in. The + `--in-memory` option tells Kupo to not persist the index on-disk but to + build it fully in-memory. When building such a large index (from origin!), + this is not recommended as it may cause the program memory usage to grow + unbounded. + + Let's fix that: + + ```console + $ kupo \ + --node-socket some-folder/cardano-node/node.socket \ + --node-config some-folder/cardano-node/config.json \ + --since origin \ + --defer-db-indexes \ + --match "*/stake_vkh14hkp0sncfkt76spuqydtww4r900hfmsseezztzlh9sjkkjx6d7q" \ + --workdir ./db + ``` + + Perfect, now Kupo will store all the information in a database on-disk at + the location pointed by `--workdir`. Incidentally, this also allows Kupo to + resume its work from where it lefts it in case the server is interrupted. + Neat! + + #### --since \ + + What if we only need to synchronize from a given point in time? For + example, we may want to skip the entire Byron and Shelley eras because we + know that this stake key may only have been used starting from the Allegra + era onwards. Fortunately, we can use the `--since` to provide a different + starting point! + + ```console + $ kupo \ + --node-socket some-folder/cardano-node/node.socket \ + --node-config some-folder/cardano-node/config.json \ + --since 16588737.4e9bbbb67e3ae262133d94c3da5bffce7b1127fc436e7433b87668dba34c354a \ + --defer-db-indexes \ + --match "*/stake_vkh14hkp0sncfkt76spuqydtww4r900hfmsseezztzlh9sjkkjx6d7q" \ + --workdir ./db + ``` + + Points are given as `{slot_no}.{header_hash}` and define an exclusive + boundary. Said differently, Kupo will start synchronizing from the **next** + block **following the given point**. In case you need them, see the section + [#era-boundaries] which references points at which era ends for mainnet and + testnet; useful to start syncing from a specific era. + + #### --match \ + + Kupo can accept one or more matching patterns using the `--match` option. + In case multiple patterns are provided, they'll ALL be used when looking + for addresses. This allows for example to build an index for a list of + payment keys known of a wallet. The syntax for patterns is explained in + greater details in the [Patterns](#section/Patterns) section below. + + #### --defer-db-indexes + + The careful reader that you are would have noticed the `--defer-db-indexes` + flag that we've been passing around. This is a little trick to speed up the + initial indexer synchronization. Indeed, when synchronizing over large chunks + of the chain, Kupo needs to ingest and filter a lot of data. Later, to serve + this data back through structured queries, Kupo leverages fast lookup indexes + in the database. Yet, lookup indexes come with a little extra cost for writing + stuff into the database. + + Deferring the creation of indexes only to when you'll need to query therefore + comes in handy and can reduce overall synchronization time by a factor of 2 or + 3. The creation of each index is relatively fast (few seconds to a couple of + minutes) and can therefore happen only after a full synchronization by restarting + Kupo without the `--defer-db-indexes` flag. + + #### --prune-utxo + + Sometimes, it isn't necessary to keep old data around. Fear not, Kupo has + got you covered! Using the `--prune-utxo` command-line flag, you can + instrument Kupo to automatically remove inputs that are spent on-chain. + + This makes sure to keep only what's truly available on-chain and has a + positive effect on both the final size of the index and the synchronization + time. If you don't set that flag, then all data are kept in the database + and spent inputs are instead marked to know if and when they were spent. + + Note that spent inputs aren't removed immediately but only after _at least_ + 36h (or 2160 guaranteed blocks). This is because data on-chain only becomes + truly immutable after 2160 blocks (though it is stable with a high probability + much before that). + + You can then use query flags in the API (`?spent` or `?unspent`) to filter + results based on whether or not they've been spent. + + #### --ogmios-host \ / --ogmios-port \ + + So far, we've connected Kupo to a local cardano-node, using a unix domain + socket as a communication channel. However, Kupo can also connect through + [Ogmios](https://github.com/CardanoSolutions/ogmios#readme); and this works + for either a local or remote instance of Ogmios! To do so, simply swap the + `--node-socket` and `--node-config` options for `--ogmios-host` and + `--ogmios-port`. + + For example: + + ```console + $ kupo \ + --ogmios-host my-ogmios-server.io \ + --ogmios-port 443 \ + --since 16588737.4e9bbbb67e3ae262133d94c3da5bffce7b1127fc436e7433b87668dba34c354a \ + --match "*/stake_vkh14hkp0sncfkt76spuqydtww4r900hfmsseezztzlh9sjkkjx6d7q" \ + --workdir ./db + ``` + + Kupo will synchronize data directly from Ogmios! Neat isn't it? + + #### --help + + In case you're lost, don't forget that a summary of this manual is available by running: + + ```console + $ kupo --help + ``` + + Should you have installed Kupo using the pre-packaged archive from releases, you should also have + access to the user manual through + + ```console + $ man kupo + ``` + + # Patterns + + Kupo can construct patterns from pretty much every constituant of an + address, an asset id or an output reference, in any kind of format + (bech32, base16, base58, you name it!). + + It also accepts wildcards using the asterisk symbol `*` in certain places. + Conceptually, patterns match the logical structure of addresses, asset ids + or output references. Each are divided in two parts: + + - for addresses: a payment part and a delegation part, separated by a `/`; + - for asset ids: a policy id and an asset name, separated by a `.`; + - for output references: an output index and a transaction id, separated by a `@` + + > **Note** + > + > To learn more about Cardano addresses, feel free to look [CIP-0019](https://github.com/cardano-foundation/CIPs/tree/master/CIP-0019#readme) + for a deep dive! + + Here below is summarized the general syntax for valid patterns. Note that + different patterns may match the same object. By convention `*` will match + _any Cardano address (Byron included)_, whereby `*/*` will match only + Shelley-based addresses (since legacy Byron addresses do not have any + delegation part!). + + ``` + PATTERN = + + ┏━━━━━━━━━┓ + ╾┬─┫ ADDRESS ┣───────────────────────────────┬╼ + │ ┗━━━━━━━━━┛ │ + │ ┏━━━━━━━━━━━━┓ ╭───╮ ┏━━━━━━━━━━━━┓ │ + ├─┫ CREDENTIAL ┣───┤ / ├─┫ CREDENTIAL ┣─────┤ + │ ┗━━━━━━━━━━━━┛ ╰───╯ ┗━━━━━━━━━━━━┛ │ + │ ┏━━━━━━━━━━━┓ ╭───╮ ┏━━━━━━━━━━━━┓ │ + ├─┫ POLICY_ID ┣────┤ . ├─┫ ASSET_NAME ┣─────┤ + │ ┗━━━━━━━━━━━┛ ╰───╯ ┗━━━━━━━━━━━━┛ │ + │ ┏━━━━━━━━━━━━━━┓ ╭───╮ ┏━━━━━━━━━━━━━━━━┓ │ + └─┫ OUTPUT_INDEX ┣─┤ @ ├─┫ TRANSACTION_ID ┣─┘ + ┗━━━━━━━━━━━━━━┛ ╰───╯ ┗━━━━━━━━━━━━━━━━┛ + ``` + + ``` + ADDRESS = + + ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ + ╾┬─┫ ADDRESS OR LEGACY ADDRESS ┣─────────────┬╼ + │ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ │ + │ ┏━━━━━━━━━━━━━━━┓ │ + ├─┫ STAKE ADDRESS ┣─────────────────────────┤ + │ ┗━━━━━━━━━━━━━━━┛ │ + │ ╭───╮ │ + └─┤ * ├─────────────────────────────────────┘ + ╰───╯ + ``` + + ``` + CREDENTIAL = + + ┏━━━━━━━━━━━┓ + ╾┬─┫ 64 HEXDIG ┣───────────────────────────────────────────┬╼ + │ ┗━━━━━━━━━━━┛ │ + │ ┏━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┏━━━━━━━━━━━━┓ │ + ├─┫ vk / addr_vk / stake_vk ┣──────────────┫ *BECH32DIG ┣─┤ + │ ┗━━━━━━━━━━━━━━━━━━━━━━━━━┛ ┗━━━━━━━━━━━━┛ │ + │ ┏━━━━━━━━━━━┓ │ + ├─┫ 56 HEXDIG ┣───────────────────────────────────────────┤ + │ ┗━━━━━━━━━━━┛ │ + │ ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┏━━━━━━━━━━━━┓ │ + ├─┫ vkh / addr_vkh / stake_vkh / script ┣──┫ *BECH32DIG ┣─┤ + │ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ ┗━━━━━━━━━━━━┛ │ + │ ╭───╮ │ + └─┤ * ├───────────────────────────────────────────────────┘ + ╰───╯ + + BECH32DIG = %x61 / %x63-68 / %x6A-6E / %x70-7A / 0-9 + ``` + + ``` + POLICY_ID = ASSET_NAME = + + ┏━━━━━━━━━━━┓ ┏━━━━━━━━━━━━━┓ + ╾┬─┫ 56 HEXDIG ┣─┬╼ ╾┬─┫ 0*64 HEXDIG ┣─┬╼ + │ ┗━━━━━━━━━━━┛ │ │ ┗━━━━━━━━━━━━━┛ │ + │ ╭───╮ │ │ ╭───╮ │ + └─┤ * ├─────────┘ └─┤ * ├───────────┘ + ╰───╯ ╰───╯ + ``` + + ``` + OUTPUT_INDEX = TRANSACTION_ID = + + ┏━━━━━━━━━━━┓ ┏━━━━━━━━━━━┓ + ╾┬─┫ 1*3 DIGIT ┣─┬╼ ╾─┫ 64 HEXDIG ┣─╼ + │ ┗━━━━━━━━━━━┛ │ ┗━━━━━━━━━━━┛ + │ ╭───╮ │ + └─┤ * ├─────────┘ + ╰───╯ + ``` + + ``` + HEXDIG = %x30–39 / %x41-%46 + ``` + + ### Examples: + + | Pattern | Description | + | --- | --- | + | `*` | Any output (incl. to legacy addresses) | + | `*/*` | Any output to a Shelley-based address | + | `addr1vyc29pvl2uyzqt8nwxrcxnf558ffm27u3d9calxn8tdudjgz4xq9p` | Outputs to a specific address | + | `stake1vyc29pvl2uyzqt8nwxrcxnf558ffm27u3d9calxn8tdudjgydsx9n` | Outputs whose address is delegated to a specific stake address | + | `addr_vk1x7da0l25j04my8sej5ntrgdn38wmshxhplxdfjskn07ufavsgtkqn5hljl/*` | Outputs whose address carries a specific payment key (bech32 encoded) | + | `dca1e44765b9f80c8b18105e17de90d4a07e4d5a83de533e53fee32e0502d17e/*` | Outputs whose address carries a specific payment key (hex encoded) | + | `*/script1cda3khwqv60360rp5m7akt50m6ttapacs8rqhn5w342z7r35m37` | Outputs whose stake is governed by a specific script | + | `dca1e44765b9f80c8b18105e17de90d4a07e4d5a83de533e53fee32e0502d17e.*` | Outputs that contains a token from a specific policy | + | `dca1e44765b9f80c8b18105e17de90d4a07e4d5a83de533e53fee32e0502d17e.TOKNAME` | Outputs that contains a specific token (any quantity) | + | `*@dca1e44765b9f80c8b18105e17de90d4a07e4d5a83de533e53fee32e0502d17e` | Outputs from a specific transaction | + + # Accessing Results + + Matches can be queried from the server via HTTP GET requests. For example: + + ```console + $ curl http://localhost:1442/matches + ``` + + will return all matches currently present in the database (be careful when + combined with very permissive patterns and wildcards!). The `/matches` + endpoint actually accept patterns, which may be different from the one + provided in the command-line. So it for instance possible to build an index + for all addresses but then, lookup only a single address as: + + ```console + $ curl http://localhost:1442/matches/addr1vyc29pvl2uyzqt8nwxrcxnf558ffm27u3d9calxn8tdudjgz4xq9p + ``` + + Optionally, you can query only `unspent` or `spent` results using the respective query flags: + + ```console + $ curl http://localhost:1442/matches/*/*?unspent + ``` + + The complete API reference is available below. + + # Era Boundaries + + ### Mainnet + + | Era Bound | SlotNo | Hash | + | --- | --- | --- | + | Last Byron Block | 4492799 | f8084c61b6a238acec985b59310b6ecec49c0ab8352249afd7268da5cff2a457 | + | Last Shelley Block | 16588737 | 4e9bbbb67e3ae262133d94c3da5bffce7b1127fc436e7433b87668dba34c354a | + | Last Allegra Block | 23068793 | 69c44ac1dda2ec74646e4223bc804d9126f719b1c245dadc2ad65e8de1b276d7 | + | Last Mary Block | 39916796 | e72579ff89dc9ed325b723a33624b596c08141c7bd573ecfff56a1f7229e4d09 | + | Last Alonzo Block | N/A | N/A | + + ### Testnet + + | Era Bound | SlotNo | Hash | + | --- | --- | --- | + | Last Byron block | 1598399 | 7e16781b40ebf8b6da18f7b5e8ade855d6738095ef2f1c58c77e88b6e45997a4 | + | Last Shelley block | 13694363 | b596f9739b647ab5af901c8fc6f75791e262b0aeba81994a1d622543459734f2 | + | Last Allegra block | 18014387 | 9914c8da22a833a777d8fc1f735d2dbba70b99f15d765b6c6ee45fe322d92d93 | + | Last Mary block | 36158304 | 2b95ce628d36c3f8f37a32c2942b48e4f9295ccfe8190bcbc1f012e1e97c79eb | + | Last Alonzo block | 62510369 | d931221f9bc4cae34de422d9f4281a2b0344e86aac6b31eb54e2ee90f44a09b9 | + | Last Babbage Block | N/A | N/A | + + +

+ +
+ 
+               ●
+            /\__\__/\
+           /✿        \
+        \ (ﾐ  ⌒ ● ⌒  ﾐ) つ ━✫ ✧･ﾟ* KUPO! *:･ﾟ✧*:･ﾟ💖
+
+
+ +components: + headers: &default-headers + Content-Type: + schema: + type: string + enum: + - "application/json;charset=utf-8" + + X-Most-Recent-Checkpoint: + description: | + Kupo's most recent indexed checkpoint's slot number. This allows to know which slot a query is accurate of. + schema: + type: integer + minimum: 0 + + schemas: + Address_Shelley: &Address_Shelley + title: Shelley + oneOf: + - title: bech32 + type: string + contentEncoding: bech32 + description: A standard payment address, in bech32 (i.e. starting with `addr|addr_test`). + example: addr1vy3qpx09uscywhpp0ekg9zwmq2yj5vp08husfq6qyh2mpps865j6t + - title: base16 + type: string + contentEncoding: base16 + description: A standard payment address, in base16 + example: 7a5e61936081db3b2117cbf59bd2123748f58ac96786567067f3314661 + + Address_Stake: &Address_Stake + title: Stake + oneOf: + - title: bech32 + type: string + contentEncoding: bech32 + description: A stake address, in bech32 (i.e. starting with `stake|stake_test`). + example: stake1vyc29pvl2uyzqt8nwxrcxnf558ffm27u3d9calxn8tdudjgydsx9n + - title: base16 + type: string + contentEncoding: bech32 + description: A stake address, in base16. + example: 7a5e61936081db3b2117cbf59bd2123748f58ac96786567067f3314661 + + Address_Bootstrap: &Address_Bootstrap + title: Bootstrap + oneOf: + - title: base58 + description: A Bootstrap (a.k.a Byron) address (legacy), in base58. + type: string + contentEncoding: base58 + example: DdzFFzCqrhsnWCKDVxHipmLW7acroB11zWxe1BGP1gCh7EqmgjVPe2qes6HrsQs + - title: base16 + description: A Bootstrap (a.k.a Byron) address (legacy), in base16. + type: string + contentEncoding: base16 + example: 73b81dc65c31ab02195bb9264982233513cabc14df8ff07ed7c55cc326833753a5c23b10ef4121f1757cdf3c0038 + + Address_Credentials: &Address_Credentials + type: string + title: Credentials + description: | + ``` + ┏━━━━━━━━━━━━┓ ╭───╮ ┏━━━━━━━━━━━━┓ + ╾─┫ CREDENTIAL ┣─┤ / ├─┫ CREDENTIAL ┣─╼ + ┗━━━━━━━━━━━━┛ ╰───╯ ┗━━━━━━━━━━━━┛ + ``` + + One or two address credentials, separated by a `/`. The left-side identifies the payment + part of the address, and the right-side identifies the delegation part. Both are optional + an can be instead a wildcard (`*`). + + Examples: + - `addr_vk1x7da0l25j04my8sej5ntrgdn38wmshxhplxdfjskn07ufavsgtkqn5hljl/*` + - `*/script1cda3khwqv60360rp5m7akt50m6ttapacs8rqhn5w342z7r35m37` + - `dca1e44765b9f80c8b18105e17de90d4a07e4d5a83de533e53fee32e0502d17e/*` + - `*/4fc6bb0c93780ad706425d9f7dc1d3c5e3ddbf29ba8486dce904a5fc` + - `*/*` + examples: + - "addr_vk1x7da0l25j04my8sej5ntrgdn38wmshxhplxdfjskn07ufavsgtkqn5hljl/*" + - "*/script1cda3khwqv60360rp5m7akt50m6ttapacs8rqhn5w342z7r35m37" + - "dca1e44765b9f80c8b18105e17de90d4a07e4d5a83de533e53fee32e0502d17e/*" + - "*/4fc6bb0c93780ad706425d9f7dc1d3c5e3ddbf29ba8486dce904a5fc" + - "*/*" + + Address: + description: A Cardano address, in any era. + anyOf: + - <<: *Address_Shelley + - <<: *Address_Bootstrap + + AddressPattern: + title: Address + description: A Cardano address or stake address. + anyOf: + - <<: *Address_Credentials + - <<: *Address_Shelley + - <<: *Address_Stake + - <<: *Address_Bootstrap + + AssetIdPattern: + type: string + title: AssetId + pattern: "[0-9a-f]{56}\\.(*|[0-9a-f]{2,64})" + description: | + ``` + ┏━━━━━━━━━━━┓ ╭───╮ ┏━━━━━━━━━━━━┓ + ╾─┫ POLICY_ID ┣─┤ . ├─┫ ASSET_NAME ┣─╼ + ┗━━━━━━━━━━━┛ ╰───╯ ┗━━━━━━━━━━━━┛ + ``` + + A policy id (base16-encoded) and an optional asset name (base16-encoded), dot-separated. + + Examples: + - `1220099e5e430475c219518179efc7e6c8289db028904834025d5b086.*` + - `1220099e5e430475c219518179efc7e6c8289db028904834025d5b086.08661220099e` + examples: + - "1220099e5e430475c219518179efc7e6c8289db028904834025d5b086.*" + - "1220099e5e430475c219518179efc7e6c8289db028904834025d5b086.08661220099e" + + BadRequest: + type: object + additionalProperties: false + properties: + hint: + type: string + description: Some hint about what went wrong. + + Datum: + title: Datum + type: object + required: + - datum + additionalProperties: false + properties: + datum: + type: string + description: A serialized Plutus' datum. + contentEncoding: base16 + example: d87980 + + DatumHash: + description: A blake2b-256 hash digest of a Plutus' datum, if any. + oneOf: + - title: Digest + type: string + description: A blake2b-256 hash digest of a Plutus' datum. + contentEncoding: base16 + example: 3097...b635 + minLength: 64 + maxLength: 64 + - title: Nothing + description: N/A + type: "null" + + Deleted: + type: object + required: + - deleted + properties: + deleted: + description: Number of entities effectively deleted. + type: integer + minimum: 0 + + ForcedRollback: + type: object + additionalProperties: false + required: + - rollback_to + properties: + rollback_to: + type: object + required: + - slot_no + description: | + A mandatory point to rollback the synchronization to. + Note that the synchronization will therefore begin starting from the point **immediately after** the provided point! + + > NOTE (1)
+ > If you need to query ancestors from any given known point, see [GET /checkpoints/{slot-no}](http://localhost:8000/#operation/getCheckpointBySlot) + + > NOTE (2)
+ > The `header_hash` is **optional**! However if provided, Kupo will check that it rolls back exactly to the specified point by comparing header hashes. + properties: + slot_no: + $ref: "#/components/schemas/SlotNo" + header_hash: + $ref: "#/components/schemas/HeaderHash" + limit: + type: string + description: | + Specify the server behavior when rolling back out of the _safe + zone_. As mentioned in the user manual, when running Kupo with + `--prune-utxo` enabled, the server gets rid of spent UTxOs, but it + only does so after a certain time. That time is exactly `129600` + slots (or 36h on Mainnet/Testnet). This is because the core + protocol cannot roll back further than this particular depth and it + is the point after which it is 100% safe to remove data from the + database. + + However, this endpoint allows you to break this invariant and + rollback to points that are even older in the past. As a + consequence, while syncing, the index may be in a somewhat + inconsistent state because some inputs spent at a later time may + not have been recovered during the rollback. This may be surprising + if you're expecting to see and query those transient inputs after + rolling back. + + By default, you won't be allowed to rollback beyond the safe zone. + If, however, you know what you're doing, you're kindly asked to + pass `unsafe_allow_beyond_safe_zone` as a token of acknowledgment. + Passing `within_safe_zone` has no effects other than the default. + + Note that, once synchronized again, the index will always be in the + expected state and problems reflecting reality only occurs _while + catching up_, after a long rollback. + default: within_safe_zone + enum: + - unsafe_allow_beyond_safe_zone + - within_safe_zone + + HeaderHash: &HeaderHash + type: string + description: A blake2b-256 hash digest of a block header. + contentEncoding: base16 + example: 9d09...31bf + minLength: 64 + maxLength: 64 + + Metadata: + type: object + additionalProperties: false + required: + - hash + - schema + - raw + properties: + hash: + type: string + description: A blake2b-256 hash digest of the raw serialized data + contentEncoding: base16 + example: cd6a5d31bf9d309706b92ad83402e682fdab9fc889b1b63565ee3de14e09dedf + minLength: 64 + maxLength: 64 + + raw: + type: string + description: A [CBOR](https://www.rfc-editor.org/rfc/rfc8949.html)-encoded binary payload. + contentEncoding: base16 + + schema: + type: object + description: | + A high-level description of the raw data. The top-level object is an object where all keys are integers (possibly negative) and points to objects representing one of 5 primitives: + + - int + - string + - bytes + - list + - map + + This schema is meant to give a faithful representation of the underlying [CBOR](https://www.rfc-editor.org/rfc/rfc8949.html) encoding, which is slightly more expressive than pure JSON (e.g. keys of maps can be arbitrary CBOR objects). + + This is why it is generally not possible to ensure a 1:1 conversion between low-level CBOR and JSON, and why this intermediate representation is necessary to safely represent **any** metadata object. + propertyNames: + type: integer + additionalProperties: + x-additionalPropertiesName: "label (integer)" + $ref: "#/components/schemas/Metadatum" + example: + { + "64": {"string": "some text"}, + "32": {"int": 42}, + "16": { + "map": [ + { + "k": {"string": "numbers"}, + "v": {"list": [{"int": 1}, {"int": 2}, {"int": 4}, {"int": 8}]} + }, + { + "k": {"string": "alphabet"}, + "v": { + "map": [ + {"k": {"string": "A"}, "v": {"int": 65}}, + {"k": {"string": "B"}, "v": {"int": 66}}, + {"k": {"string": "C"}, "v": {"int": 67}} + ] + } + } + ] + }, + "-8": { "bytes": "48656c6c6f2c2043617264616e6f21" } + } + + Metadatum: + oneOf: + - $ref: "#/components/schemas/Metadatum_Int" + - $ref: "#/components/schemas/Metadatum_String" + - $ref: "#/components/schemas/Metadatum_Bytes" + - $ref: "#/components/schemas/Metadatum_List" + - $ref: "#/components/schemas/Metadatum_Map" + + Metadatum_Int: + title: int + type: object + additionalProperties: false + required: + - int + properties: + int: + type: integer + description: | + An integer or arbitrary size. + + Example: + + ```json + { "int": 42 } + ``` + + Metadatum_String: + title: string + type: object + additionalProperties: false + required: + - string + properties: + string: + type: string + contentEncoding: utf-8 + maxLength: 64 + description: | + A text string, which is at most 64 bytes. + + Example: + + ```json + { "string": "kupo!" } + ``` + + Metadatum_Bytes: + title: bytes + type: object + additionalProperties: false + required: + - bytes + properties: + bytes: + type: string + contentEncoding: base16 + maxLength: 128 + description: | + A base16 byte string, which is at most 64 bytes + + Example: + + ```json + { "bytes": "6b75706f21" } + ``` + + Metadatum_List: + title: list + type: object + additionalProperties: false + required: + - list + properties: + list: + type: array + additionalItems: false + items: + $ref: "#/components/schemas/Metadatum" + description: | + A (possibly heterogeneous) list of metadatum + + Example: + + ```json + { + "list": [ + { + "int": 14 + }, + { + "list": [ + { "string": "kupo!" }, + { "bytes": "6b75706f21" } + ] + } + ] + } + ``` + + Metadatum_Map: + title: map + type: object + additionalProperties: false + required: + - map + properties: + map: + type: array + items: + type: object + additionalItems: false + required: + - k + - v + properties: + k: + $ref: "#/components/schemas/Metadatum" + v: + $ref: "#/components/schemas/Metadatum" + description: | + A list of key:value objects. Both keys and values can be any sort metadatum. + + Example: + + ```json + { + "map": [ + { + "k": { "int": 14 }, + "v": { + "list": [ + { "string": "kupo!" }, + { "bytes": "6b75706f21" } + ] + } + } + ] + } + ``` + + OutputIndex: + type: integer + description: The index of the output within the transaction carrying it. + minimum: 0 + example: 2 + + OutputReferencePattern: + title: OutputReference + type: string + pattern: (*|[0-9]+)@[0-9a-f]{64} + description: | + ``` + ┏━━━━━━━━━━━━━━┓ ╭───╮ ┏━━━━━━━━━━━━━━━━┓ + ╾─┫ OUTPUT_INDEX ┣─┤ @ ├─┫ TRANSACTION_ID ┣─╼ + ┗━━━━━━━━━━━━━━┛ ╰───╯ ┗━━━━━━━━━━━━━━━━┛ + ``` + + An (optional) output index and transaction id (base16-encoded), separated by a `@`. + + Examples: + - `42@35d8340cd6a5d31bf9d09706b92adedf9b1b632e682fdab9fc8865ee3de14e09` + - `*@35d8340cd6a5d31bf9d09706b92adedf9b1b632e682fdab9fc8865ee3de14e09` + examples: + - "42@35d8340cd6a5d31bf9d09706b92adedf9b1b632e682fdab9fc8865ee3de14e09" + - "*@35d8340cd6a5d31bf9d09706b92adedf9b1b632e682fdab9fc8865ee3de14e09" + + Pattern: + description: | + A matching pattern for addresses, assets or transactions. + + See [Patterns](#section/Patterns) for more details. + title: + anyOf: + - $ref: "#/components/schemas/Wildcard" + - $ref: "#/components/schemas/AddressPattern" + - $ref: "#/components/schemas/AssetIdPattern" + - $ref: "#/components/schemas/OutputReferencePattern" + + Point: &Point + title: Point + type: object + additionalProperties: false + required: + - slot_no + - header_hash + properties: + slot_no: + $ref: "#/components/schemas/SlotNo" + header_hash: + $ref: "#/components/schemas/HeaderHash" + + Script: + title: Script + type: object + required: + - script + - language + additionalProperties: false + properties: + language: + type: string + description: The type of script. `native` refers to pre-Alonzo scripts made of the native DSL to combine keys. + enum: + - native + - 'plutus:v1' + - 'plutus:v2' + script: + type: string + description: A serialized script (native or Plutus). + contentEncoding: base16 + example: 4d01000033222220051200120011 + examples: + - language: 'native' + script: 8201838200581c3c07030e36bfffe67e2e2ec09e5293d384637cd2f004356ef320f3fe8204186482051896 + - language: 'plutus:v1' + script: 4d01000033222220051200120011 + + ScriptHash: + description: A blake2b-224 hash digest of a Native or Plutus script, if any. + oneOf: + - title: Digest + description: A blake2b-224 hash digest of a Native or Plutus script. + type: string + contentEncoding: base16 + example: 3097...9ded + minLength: 56 + maxLength: 56 + - title: Nothing + description: N/A + type: "null" + + SlotNo: &slotNo + type: integer + description: An absolut slot number. + minimum: 0 + example: 51540727 + + TransactionId: + type: string + description: A blake2b-256 hash digest of a transaction body. + contentEncoding: base16 + example: 35d8...4e09 + minLength: 64 + maxLength: 64 + + TransactionIndex: + type: integer + description: The index of the transaction within the block including it. + minimum: 0 + example: 14 + + Value: + type: object + description: A (multi-asset) value of a transaction's output. + additionalProperties: false + required: + - coins + properties: + coins: + type: integer + description: A quantity of Lovelace. + 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: integer + description: A quantity of some asset. + example: + 1220099e5e430475c219518179efc7e6c8289db028904834025d5b086: 231 + 289db028904834025d5b085d5b08661220099e5e430475c2195181796.08661220099e: 1 + + Wildcard: + type: string + title: Wildcard + enum: ["*"] + + Match: + 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/Value" + datum_hash: + $ref: "#/components/schemas/DatumHash" + script_hash: + $ref: "#/components/schemas/ScriptHash" + 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/Point" + - 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. + additionalProperties: false + required: + - connection_status + - most_recent_checkpoint + - most_recent_node_tip + properties: + connection_status: + type: string + description: Condition of the connection with the underlying node. + enum: + - connected + - disconnected + most_recent_checkpoint: + oneOf: + - <<: *slotNo + description: Absolute slot number of the most recent database checkpoint. + - type: "null" + description: Absolute slot number of the most recent database checkpoint. + most_recent_node_tip: + oneOf: + - <<: *slotNo + description: Absolute slot number of the current tip of the node. + - type: "null" + description: Absolute slot number of the current tip of the node. + + parameters: + asset-name: + deprecated: true + name: asset_name + in: query + required: false + allowEmptyValue: false + schema: + type: string + contentEncoding: base16 + pattern: ^[a-f0-9]{2,64}$ + description: | + Use an explicit [Pattern](#section/Patterns) as _path-parameter_ instead. + + datum-hash: + name: datum_hash + in: path + required: true + schema: + type: string + contentEncoding: base16 + minLength: 64 + maxLength: 64 + pattern: ^[a-f0-9]{64}$ + example: 3097...b635 + description: + A datum blake2b-256 hash digest. + + order: + name: order + in: query + required: false + schema: + type: string + enum: + - most_recent_first + - oldest_first + description: | + Order results by their location on-chain. By default, most recent results are returned first (i.e. by descending `created_at.slot_no`). + Within a same slot, results are ordered in function of their position in the block (i.e. `transaction_index`). + + pattern: + name: pattern + in: path + required: true + schema: + title: pattern + anyOf: + - $ref: "#/components/schemas/Wildcard" + - $ref: "#/components/schemas/AddressPattern" + - $ref: "#/components/schemas/AssetIdPattern" + - $ref: "#/components/schemas/OutputReferencePattern" + description: | + A matching pattern on addresses, assets or transactions. + + See [Patterns](#section/Patterns) for more details. + + policy-id: + deprecated: true + name: policy_id + in: query + required: false + allowEmptyValue: false + schema: + type: string + contentEncoding: base16 + minLength: 56 + maxLength: 56 + pattern: ^[a-f0-9]{56}$ + description: | + Use an explicit [Pattern](#section/Patterns) as _path-parameter_ instead. + + script-hash: + name: script_hash + in: path + required: true + schema: + type: string + contentEncoding: base16 + minLength: 56 + maxLength: 56 + pattern: ^[a-f0-9]{56}$ + example: 3097...9ded + description: + A script blake2b-224 hash digest of a script. + + slot-no: + name: slot_no + in: path + required: true + schema: + type: integer + minimum: 0 + + spent: + name: spent + in: query + required: false + allowEmptyValue: true + description: | + A query flag (i.e. `?spent`) to filter matches by status, to get only 'spent' matches. Note that, when running kupo with `--prune-utxo`, this will always return an empty list of results. + + strict: + name: strict + in: query + required: false + allowEmptyValue: true + description: | + A query flag (i.e. `?strict`) to only look for checkpoints that strictly match the provided slot. The behavior otherwise is to look for the largest nearest slot smaller or equal to the one provided. + + transaction-id: + name: transaction_id + in: query + required: false + description: | + An optional transaction id to retrieve items associated with the transaction only. + schema: + $ref: "#/components/schemas/TransactionId" + + unspent: + name: unspent + in: query + required: false + allowEmptyValue: true + description: | + A query flag (i.e. `?unspent`) filter matches by status, to get only 'unspent' matches. + +tags: + - name: Matches + description: | + Accessing results matched by a certain configuration. Results can be retrieve using **any** pattern (and not only those defined in configuration). So it is possible for example to + index data using quite wide patterns (e.g. `*`) but only query a single address later on. + - name: Checkpoints + description: | + An API for inspecting checkpoints known of the database. A checkpoint really is a point on-chain that directly references a block. They are comprised of an absolute slot + number and a block header hash. Kupo records all such points as it processes blocks. In particular, they are also used to resume synchronization upon restart. + - name: Datums + description: | + Accessing datums indexed by the server. By default, the engine indexes **every** datum present in transaction witnesses and inline datums present in **matched** transaction outputs. However, + a periodic garbage collector will automatically remove datums that aren't associated to any matched output. Said differently, any datum hash present in a matched output can be queried (so long + as its datum has been seen on-chain one way or another). Other hashes _may_ work but aren't guaranteed. + - name: Scripts + description: | + Accessing scripts indexed by the server. By default, the engine indexes **every** script present in transaction witnesses and inline scripts present in **matched** transaction outputs. However, + a periodic garbage collector will automatically remove scripts that aren't associated to any matched output. Said differently, any script hash present in a matched output can be queried (so long + as its script has been seen on-chain one way or another). Other hashes _may_ work but aren't guaranteed. + - name: Metadata + description: | + Accessing metadata present in blocks/transactions. Unlike most other resources, metadata are **not** indexed by the server and are retrieved on-the-fly directly from the node. This is generally quite fast but likely not suitable for fetching large batches of metadata. + - name: Patterns + description: | + Dynamically managing the server's configuration. Note that modifying patterns after the server has started indexing may break the server's data integrity -- or more exactly, data completeness. + The server does not re-synchronize past blocks unless explicitly told so. + - name: Health + description: | + Monitoring endpoints to assess the server's health. + +paths: + /matches: + get: + operationId: getAllMatches + tags: ["Matches"] + summary: Get All Matches + description: | + Retrieve all matches from the database, in descending `slot_no` order. Results are streamed to the client for more efficiency. + Note that this is generally a bad idea for indexes built off permissive patterns (e.g. `*`) for the server will yield a large response. + parameters: + - $ref: "#/components/parameters/spent" + - $ref: "#/components/parameters/unspent" + - $ref: "#/components/parameters/order" + - $ref: "#/components/parameters/policy-id" + - $ref: "#/components/parameters/asset-name" + responses: + 200: + description: OK + headers: *default-headers + content: + "application/json;charset=utf-8": + schema: + type: array + items: + $ref: "#/components/schemas/Match" + + /matches/{pattern}: + get: &getMatches + operationId: getMatches + tags: ["Matches"] + summary: Get Matches (*) + 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. + parameters: + - $ref: "#/components/parameters/pattern" + - $ref: "#/components/parameters/spent" + - $ref: "#/components/parameters/unspent" + - $ref: "#/components/parameters/order" + - $ref: "#/components/parameters/policy-id" + - $ref: "#/components/parameters/asset-name" + responses: + 200: + description: OK + headers: *default-headers + content: + "application/json;charset=utf-8": + schema: + type: array + items: + $ref: "#/components/schemas/Match" + 400: + description: Bad Request + content: + "application/json;charset=utf-8": + schema: + $ref: "#/components/schemas/BadRequest" + + delete: &deleteMatches + operationId: deleteMatches + tags: ["Matches"] + summary: Delete Matches (*) + description: | + Delete all matches matching the given pattern. Note that this operation is only allowed if the provided pattern isn't a currently active pattern. + parameters: + - $ref: "#/components/parameters/pattern" + responses: + 200: + description: OK + headers: *default-headers + content: + "application/json;charset=utf-8": + schema: + $ref: "#/components/schemas/Deleted" + 400: + description: Bad Request + content: + "application/json;charset=utf-8": + schema: + $ref: "#/components/schemas/BadRequest" + + /datums/{datum-hash}: + get: + operationdId: getDatumByHash + tags: ["Datums"] + summary: Get Datum by Hash + description: | + Retrieve the datum pre-image (i.e. full resolved datum) associated to a given datum hash digest. + parameters: + - $ref: "#/components/parameters/datum-hash" + responses: + 200: + description: OK + headers: *default-headers + content: + "application/json;charset=utf-8": + schema: + oneOf: + - $ref: "#/components/schemas/Datum" + - title: Nothing + type: "null" + 400: + description: Bad Request + content: + "application/json;charset=utf-8": + schema: + $ref: "#/components/schemas/BadRequest" + + /scripts/{script-hash}: + get: + operationdId: getScriptByHash + tags: ["Scripts"] + summary: Get Script by Hash + description: | + Retrieve the raw script (i.e. full resolved script) associated to a given script hash digest. + + > NOTE
+ > + > Raw scripts aren't exact pre-image of their hash digest. Before hashing, scripts are prefixed with a + > certain discriminator byte depending on the language. For instance, any native script is prefixed with + > `00` before hashing. + > + > Here's a table summarizing all discriminators: + > + > | Language | Discriminator Byte | + > | --- | --- | + > | `native` | `00` | + > | `plutus:v1` | `01` | + > | `plutus:v2` | `02` | + parameters: + - $ref: "#/components/parameters/script-hash" + responses: + 200: + description: OK + headers: *default-headers + content: + "application/json;charset=utf-8": + schema: + oneOf: + - $ref: "#/components/schemas/Script" + - title: Nothing + type: "null" + 400: + description: Bad Request + content: + "application/json;charset=utf-8": + schema: + $ref: "#/components/schemas/BadRequest" + + /patterns: + get: + operationId: getPatterns + tags: ["Patterns"] + summary: Get Patterns + description: | + Retrieve all patterns currently configured on the server. + responses: + 200: + description: OK + headers: *default-headers + content: + "application/json;charset=utf-8": + schema: + type: array + items: + $ref: "#/components/schemas/Pattern" + + put: &putPatterns + operationId: putPatterns + tags: [ "Patterns" ] + summary: Bulk Add Patterns + description: | + Add many patterns at once. See [Add Pattern (*)](#operation/putPattern) for more details. + requestBody: + content: + "application/json;charset=utf-8": + schema: + type: object + additionalProperties: false + required: + - patterns + - rollback_to + properties: + patterns: + type: array + description: + A list of patterns on addresses, assets or transactions as described in [Patterns](#section/Patterns). + items: + $ref: "#/components/schemas/Pattern" + rollback_to: + $ref: "#/components/schemas/ForcedRollback/properties/rollback_to" + limit: + $ref: "#/components/schemas/ForcedRollback/properties/limit" + responses: + 200: + description: OK + headers: *default-headers + content: + "application/json;charset=utf-8": + schema: + type: array + items: + $ref: "#/components/schemas/Pattern" + 400: + description: Bad Request + content: + "application/json;charset=utf-8": + schema: + $ref: "#/components/schemas/BadRequest" + + /patterns/{pattern}: + get: &getPattern + operationId: matchPattern + tags: ["Patterns"] + summary: Get Pattern (*) + description: | + Retrieve all patterns that include* the provided pattern. Remember that an address is itself a pattern! + This endpoint is thereby useful to check is an address is matched by a given pattern configuration (the returned + list would be non-empty). + + > (*) Definition
+ > If all results matched by `y` are also matched by `x`, then `x` is said to include `y`. + parameters: + - $ref: "#/components/parameters/pattern" + responses: + 200: + description: OK + headers: *default-headers + content: + "application/json;charset=utf-8": + schema: + type: array + items: + $ref: "#/components/schemas/Pattern" + + delete: &deletePattern + operationId: deletePattern + tags: ["Patterns"] + summary: Delete Pattern (*) + description: | + Removes patterns from the database and active filtering. Note that this does + **NOT** remove the corresponding matches nor will it halt or restart synchronization. + The server will continue filtering new blocks but, will that pattern removed. + parameters: + - $ref: "#/components/parameters/pattern" + responses: + 200: + description: OK + headers: *default-headers + content: + "application/json;charset=utf-8": + schema: + $ref: "#/components/schemas/Deleted" + 400: + description: Bad Request + content: + "application/json;charset=utf-8": + schema: + $ref: "#/components/schemas/BadRequest" + + put: &putPattern + operationId: putPattern + tags: [ "Patterns" ] + summary: Add Pattern (*) + description: | + Add a new pattern to watch and force the server to re-sync from a given point. Only blocks discovered from that point will be matched against the new pattern. + + This endpoint may not be instantaneous as the forced rollback may only occur after the next block arrives in the indexer. On the main network, this takes usually + no more than 20 seconds. On test networks however where the block density tends to be much lower, this may take longer. + + Note also that, very long rollback will take a substantial amount of time to be processed by the server; if the server is shut down while a rollback is ongoing, the + rollback will be aborted and the server will remain where it was, although with the extra pattern added. + parameters: + - $ref: "#/components/parameters/pattern" + requestBody: + content: + "application/json;charset=utf-8": + schema: + $ref: "#/components/schemas/ForcedRollback" + responses: + 200: + description: OK + headers: *default-headers + content: + "application/json;charset=utf-8": + schema: + type: array + items: + $ref: "#/components/schemas/Pattern" + 400: + description: Bad Request + content: + "application/json;charset=utf-8": + schema: + $ref: "#/components/schemas/BadRequest" + + /checkpoints: + get: + operationId: sampleCheckpoints + tags: ["Checkpoints"] + summary: Sample Checkpoints + description: | + Retrieve a **sample of** all checkpoints currently in the database, in descending `slot_no` order. + This is useful to know where the synchronization is at. On restart, the synchronization will continue from the most recent + checkpoints that is also valid on the network. + responses: + 200: + description: OK + headers: *default-headers + content: + "application/json;charset=utf-8": + schema: + type: array + items: + $ref: "#/components/schemas/Point" + + /checkpoints/{slot-no}: + get: + operationId: getCheckpointBySlot + tags: ["Checkpoints"] + summary: Get Checkpoint By Slot + description: | + Retrieve a checkpoint by its (absolute) slot number. The query is flexible by default. Meaning that, if there's no checkpoint at the given slot, the server + will for for the closest (i.e. most recent) slot that is **before** the provided slot number. This is particularly useful to find ancestors to known slots + in order to use them for references on-chain. + parameters: + - $ref: "#/components/parameters/slot-no" + - $ref: "#/components/parameters/strict" + responses: + 200: + description: OK + headers: *default-headers + content: + "application/json;charset=utf-8": + schema: + oneOf: + - $ref: "#/components/schemas/Point" + - type: "null" + + /metadata/{slot-no}: + get: + operationId: getMetadataBySlot + tags: ["Metadata"] + summary: Get Metadata By Slot + description: | + Retrieve all metadata data seen in a block at the given slot, possibly filtered by transaction id. + + Metadata are ordered according to their respective transaction's order in the block. + parameters: + - $ref: "#/components/parameters/transaction-id" + responses: + 200: + description: OK + headers: + <<: *default-headers + X-Block-Header-Hash: + <<: *HeaderHash + description: | + The block's header hash digest (`blake2b-256`) of the corresponding block at the provided slot. Clients are expected to control that this hash matches the one they expect, especially when fetching metadata from blocks in the unstable region (i.e. less than `k=2160` blocks from the network tip). Indeed, Cardano is a distributed system after all and data isn't guaranteed to be immediately immutable. Data present in very recent blocks may therefore be different between two successive requests. + content: + "application/json;charset=utf-8": + schema: + type: array + items: + $ref: "#/components/schemas/Metadata" + + /health: + get: + operationId: getHealth + tags: ["Health"] + summary: Get Health + description: | + Retrieve Kupo's application health status. Note that this call is cheap and does not halt the various concurrent tasks performed by the Kupo. + + This endpoint has two possible content-types: `application/json` or `text/plain`. The latter returns health in a format suitable for [Prometheus](https://prometheus.io/docs/introduction/overview/). The server defaults to `application/json`, but you can control this behavior by passing a corresponding `Accept` header. + responses: + 200: + description: OK + headers: *default-headers + content: + "application/json;charset=utf-8": + schema: + $ref: "#/components/schemas/Health" + + "text/plain;charset=utf-8": + schema: + type: string + description: | + A key-value export compatible with Prometheus. + + `connected` and `disconnected` are encoded as `1.0` and `0.0` respectively. + 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 diff --git a/docs/index.html b/docs/index.html index 1ddf5b6c..cc860966 100644 --- a/docs/index.html +++ b/docs/index.html @@ -86,8 +86,8 @@
- v1.0.1 v2.0.0-beta + v2.1.0 latest