v2.3.4

Added

v2.3.0

• Support for ETag/If-None-Match standard HTTP caching. ETag in kupo matches the most recent block header hash. This allows clients to perform efficient polling and caching on their end. This also comes as an additional protection for rollbacks as one can control the ETag between two requests and assess whether a rollback happened.

• 📌 #96 (:bulb: @cortsf) Matches can now be fetched in a paginated fashion, using slot ranges. Ranges can be made on either created_at or spent_at fields, and are inclusive. Besides, clients have two ways to define ranges:

  • by absolute slot number;
  • by point (slot number + block header hash).

  The latter performs an extra check and will fail should the provided point not exist. This is handy to fetch collections over multiple pages while ensuring that the underlying data doesn't change due to a new fork of the chain being adopted behind the scene. Here are some examples of queries with (valid) ranges:

  /matches?created_after=1234
  

  /matches?created_after=1234&created_before=5678
  

  /matches?spent&spent_before=1234
  

  /matches?spent&created_after=1234.4675360c80235b60b127222702b6e9b2b5c20dee7115acfc46eb6f3e9fd97ff0&spent_before=5678
  

  See:

  • GET /matches → 📖 API Reference
  • GET /matches/{pattern} → 📖 API Reference

Changed

v2.3.4

• (:bug: @mmahut) Fixed negotiation of the intersection point after loosing (and recovering) connection from its block provider (cardano-node or ogmios). Kupo would restart synchronizing back to the checkpoint known at startup instead of the latest known checkpoint in the indexer.

v2.3.3

• (:bug: @Quantumplation) Fixed a bug where Kupo would prune inputs at regular interval even if --prune-utxo isn't set. This only occurs when matching patterns are neither * nor */*. Related, Kupo would also never prune binary data as it should; even with --prune-utxo enabled.

v2.3.2

• (:bug: @mmahut @scarmuega) Bumped version of the embedded SQLite stack to v3.40.1 and changed the main writer process journaling mode to TRUNCATE. These two changes come as a mitigation of an SQLite bug that resulted in sometimes throwing:

  Error while attempting to perform step: cannot rollback - no transaction is active.

  The root cause for this error is hard to identify and may be due to a full disk space; It's been also linked to the write-ahead logging journal mode; which Kupo benefits only a little and only during syncing.

v2.3.1

• 📌 #101 (:bug: @jy14898) Starting from the Babbage era, transactions that fail phase-2 validations (i.e. script execution) can use a collateral return output where to send change from a lost collateral. This makes collateral management easier for client applications and result in a special kind of UTxO in the ledger. Kupo has been wrongly attributing an index of 0 to those outputs, whereas the ledger indicates the following:

  Note that the new $collOuts$ function generates a single output with an index $|txOuts_{txb}|$.

  This is now fixed. Database patches are provided for preview, preprod with the release notes of v2.3.1 to update already indexed collateral returns if any.

  Note

  There's no patch for mainnet because, to this date, there hasn't been any phase-2 failure on mainnet making use of collateral returns.

• (:bug: @mmahut) Make internal db garbage-collection more incremental. This has two main benefits:

  1. It allows the consumer to preempt the database connection for writing blocks while a GC is happening. This is crucial to not start lagging behind because of a long-running (several minutes) garbage collection.
  2. It breaks the inputs pruning over multiple smaller transaction, which are much faster to process than a single (sometimes excessively large) transaction by SQLite under the hood; considerably reducing the garbage-collection delays.

• Passing --defer-db-indexes now also removes query indexes if present.

  Prior to this commit, passing --defer-db-indexes on a database with already present indexes would only raise a warning and there was no practical way to remove indexes from the database (other than doing it manually). Now, --defer-db-indexes will systematically make sure that indexes are dropped when set. Thus, this flag effectively controls the existence (or more specifically, the absence) of query indexes in the database. Starting kupo without this flag still creates the indexes should they not exist.

v2.3.0

• 📌 #94 (:bulb: @mpizenberg) Improved user-experience on start-up when providing invalid or missing working directory. Kupo will now recursively create the working directory if it's missing and otherwise provide a more informative error if it can't (e.g. because the directory already exists and is a file or because of a lack of permissions).

• 📌 #95 (:bulb: @Quantumplation) The behavior associated with rollback_to (when dynamically inserting new patterns) has been slightly altered. Before, it used to fail when providing only a slot number not associated with any on-chain point. Now, Kupo will rollback to the closest ancestor of the given slot number. When there's an existing point, or when a header-hash is provided alonside the slot number; the behavior remains unchanged.

• 📌 #98 Logs are now shown in a human-friendly way when stdout is an ANSI-capable terminal. When sent to a file or to a non-terminal, the behaviour is unchanged (i.e. structured JSON).

• (:bug: @scarmuega) Kupo will no longer crash when loosing connection with the underlying cardano-node or Ogmios server. Instead, it'll recover from the issue and try to reconnect automatically.

Removed

v2.3.0

• The /patterns family of endpoints no longer return a X-Most-Recent-Checkpoint for it doesn't make much sense for these endpoints. Indeed, they may change regardless of what is processed by the indexer.

Benchmarks

See benchmarks/README.md.

Snapshots

In the release artifacts, you can find multiple snapshots (kupo.sqlite3-{mainnet, preview, preprod}.tar.gz). These snapshots were obtained from the following options:

• --match *
• --since origin
• --prune-utxo

They can be used as starting points to get started quickly. Note that the mainnet archive is split in multiple parts; the original archive can be recovered as such:

❯ cat kupo.sqlite3-mainnet.tar.gz.part_* > kupo.sqlite3-mainnet.tar.gz

Then, verify the archive's integrity using md5, it should match the checksum below:

❯ md5 kupo.sqlite3-mainnet.tar.gz
MD5 (kupo.sqlite3-mainnet.tar.gz) = dba114c96a81be73c7fbccb596bcfe60

Dependencies

Dependency	Tested With
cardano-node	1.35.x
ogmios	v5.5.x

Details

v2.2.1...v2.3.4