Questions on CIP-139 Block Endpoint Design (Universal Query Layer)

[satran004]

We’re looking into adding support for the Universal Query Layer (CIP-139) in Yaci Store

I have a couple of questions around the block API endpoint (block by number or hash). Maybe there are good reasons for the current design, but I am just trying to understand the thinking behind it.

1. Response size

The block endpoint [ spec here ] currently returns the entire block in JSON (basically CBOR converted to JSON).
For consumers or dApps this could be quite heavy. With a max block size around ~90KB, the JSON payload might end up being a few times bigger.

Is it the right approach to always return the full block? Or should it be something lighter, like what Blockfrost does, where you get the block header, summaries, and maybe just transaction hashes? Most dApps probably don’t need the whole block every time, maybe just a single transaction.

2. JSON structure

The current response follows CBOR structure exactly: lists for auxiliary_data, transaction_bodies, witnesses, etc. To get all data for one transaction, you need to get the body from one list, then use the same index to fetch metadata and witnesses from the others.

Wouldn’t it be easier for dApps if there was a wrapper Transaction object that included the body, auxiliary data, and witnesses together? That way, a developer doesn’t need to piece things together from multiple lists.

If the goal is just to mirror CBOR into JSON, then these points may not be valid.

But if the main users of this API are dApp developers or enterprise apps, making the block endpoint lighter and more developer-friendly might be a better fit. This may apply to the transaction endpoint as well.

Curious to hear what others think.

[rdlrt]

Cant talk about Universal query layer without something that captures all requirements. All we can do is provide different flavours of endpoints (one important dimension of which is size and performance), should there be enough demand/adoption of this CIP

[rphair]

I've also linked & invited users to this discussion from channel #query-layer-standard on the CIP Discord (invite can be found on CIPs Wiki). Mainly it was the CIP/CPS authors and editors on that channel... but it would be great to see more current participation there for lightweight community discussions, then accumulate key points & resolutions here on GitHub.

[nazrhom]

Hi @satran004, thanks for the feedback!

As you mentioned, the initial goal for this API was to simply mirror the CBOR structure into JSON, but I do understand your concern and ideally we would like to strike a balance between covering as many use cases as possible without bloating the API too much.

I think you make a fair point, and most of the common general-purpose indexers (Blockfrost, Maestro, and Koios are the ones we looked at most) follow a similar pattern to what you describe. I wonder if modifying the block endpoint to just return the tx hashes as you describe would cover the most common cases, while still allowing to query individual transactions by hash, should a dApp need the full tx information.

Are there any other endpoints that you think might benefit from having some light-weight alternatives?

[satran004]

Hi @nazrhom,

Thanks for your response.

1. Changing the block endpoint to return only transaction hashes would be very useful. Another option could be to return a list of tuples like <tx_hash, isValid>, so clients can also check validity in a single call.

For transaction witnesses, I think it makes more sense to have a separate endpoint, for example:

/transaction/<hash>/witnesses

Another one in block level also could be useful.

2. I understand pagination isn’t planned for the first version. But without it, some endpoints like /utxos/payment_credential could become difficult to use if there are too many UTXOs for one address (common with exchange or script addresses, where we’ve seen tens of thousands of UTXOs).
   Adding optional parameters like page and limit might help. If not provided, the endpoint could still return everything, but that could put a lot of load on the backend.

If we can handle these two points, I think we will have a good start point.

There are also a few other minor observations. I will revisit the spec and post them here later, but they’re not blockers for now.