custom-query-layers.md

• Custom query layers in CTL
  • Adding a new backend
  • Replacing some queries in existing backend
• Configuring CTL's default query layer (Kupo/Ogmios)
  • Kupo
    • Faster sync for Kupo

Custom query layers in CTL

Adding a new backend

CTL can be extended with custom (user) query layers if needed. At this moment it can be done by forking.

Every query CTL uses, except of backend-specific ones, goes through a query handle.

A new backend option should be added, with corresponding initialization code

Replacing some queries in existing backend

Substituting the query layer for a few functions only (assuming the original backend remains available for initial connection) can be done without forking CTL.

ContractEnv contains a QueryHandle (inside a Reader), so a local call with a function that replaces some QueryHandle record entries will just work.

Configuring CTL's default query layer (Kupo/Ogmios)

Optimising storage requirements and performance of the query layer, unfortunately, depends on your app query needs.

Kupo

Kupo is used for "utxos-at-address" query in CTL.

This query is mainly used in two contexts:

• manual utxosAt calls
• wallet <-> backend synchronization (see here)

If you don't need either, consider removing Kupo from the runtime and disabling wallet <-> backend synchronization (IMPORTANT!).

If your app works in a way that only requires UTxO lookups on certain addresses (e.g. script addresses), consider using --match-pattern to drastically reduce DB size. The downside would be that wallet<->backend sync will have to be disabled, because it requires looking up wallet's addresses via the backend.

Faster sync for Kupo

Use --since flag to perform partial incomplete sync. Find block parameters on a block explorer. It will let you sync things faster (than in ~4 days for mainnet), for the price of Kupo not seeing UTxOs created after the specified slot. If you disable wallet<->backend sync, and depending on your use case, that might be acceptable for production.