v6.0.0 API Breaking Changes 'Wishlist'

[KtorZ]

There are few pain points in the current API which can't be improved without introducing breaking-changes. This ticket summarizes / keep track of those desired changes as long as the motivation behind them.

Use tagged objects instead of singleton.

Right now, many objects are serialized as:

{
    "Constructor": {
        "field1": "...",
        "field2": "..."
    }
}

However, this can be hard to parse in some languages and even awkward in FP languages like Haskell when there are multiple possible constructors expected (this requires to define alternative parsers <|> and try them in sequence). Instead, it would be a lot easier if the constructor was encoded as a tag field, allowing clients to first decode the tag field and then drive the parser accordingly based on the tag. So, with the example above:

{
    "tag": "Constructor"
    "field1": "...",
    "field2": "..."
}

Replace usage of base64 with base16

The rationale behind choice of encoding in Ogmios was detailed in discussion #115. However, this is utterly inconsistent and only introduce confusion for users. When Ogmios was originally created, tools and interfaces were still in flux. Over time, base16 has imposed itself as the encoding of choice for pretty much everything (everything but agreed-upon small binary data specified in CIP-0005).

Omit empty fields instead of returning null

Right now, the API always returns all possible fields and assign them null values when they aren't set. However, this creates quite a lot of noise and does not provide much additional value despite showing that a certain fields exist -- but there's the API reference for that.
In many cases, transactions contains less than half of the possible fields, so that's a lot of serialization and on-the-wire transfers for little value.

Remove compact mode

The compact mode does not provide massive improvements in syncing (~15%), is hard to document and adds complexity to the code base. Plus, as pointed in #272, it is even used through a slight abuse of the RFC6455. The only driving reason for the compact was a performance concern which was actually never clearly stated out by any user. Plus, the above change (omit empty fields) should by itself have a similar effect for synchronization over large windows.

Align representation of Byron witnesses with other eras.

Right now, Byron witnesses are represented as a list of items, whereas Shelley witnesses and beyond are a key:value map. This needs fixing, likely align on the Shelley's representation.

Fix confusing "ByronWitness"

At the moment, the addressAttributes in Byron witnesses is returned as null when there are actually no address attributes whatsoever; Yet, on-chain, these are still serialized as an empty ByteString which make the current format confusing (and pushes extra logic down to client). Instead, one could expect to systematically be able to verify a Byron witness by appending the pieces together without the need to handle the null case when it occurs.

Align representation of Byron blocks & block header with other eras

Byron is weird. It has epoch-boundary blocks (EBB) and the terminology was oddly different. There are several 'pain point' regarding the current format when parsing blocks:

• There's no slot number in Byron blocks somehow.
• It uses different names for the same concepts; e.g. Byron has txPayload but no body.
• Currently, blocks are a sum type of the form: Byron | Shelley | ... | Babbage. Then, Byron is itself a sum-type of StandardBlock | EpochBoundaryBlock. This in practice makes it a bit unpractical for clients to process blocks because Byron needs a special treatment. Besides, in 99% of the cases one does not care about the epoch boundary block and would simply discard them.

It might be easier instead to 'promote EBBs' and to instead have Block | LegacyEpochBoundaryBlock. So one could easily discard all legacy EBBs and deal with a Block type that have has much overlap as possible in the structure, so it would be possible to access some known fields present in all blocks without having to "pattern match" on blocks. This should also play well with "Use tagged objects instead of singleton" described above.

Nest headerHash field under header, and rename it as hash

Block headers do contain a prevHash but somehow, no hash; the headerHash is provided outside of the block heade. It makes sense in some ways: how would the hash of X be part of X itself? Yet, intuitively, when digesting data from the chain, we would rather look for header.hash than an object with both a header property and headerHash property. It's not like it'd be easy anyway to recalculate the header hash itself given that the original hash is calculated on the CBOR-encoded version of the header. Hence why the hash is provided in the first place.

Rename extraData → scriptIntegrityHash

The script integrity hash was introduced in Alonzo to enforce that protocols parameters given to script are consistent with what's expected of the building transaction. Historically, it was first called "extra data" and the name was later refined in the ledger. Ogmios stuck to historical version which is somewhat confusing. Errors like extraDataMismatch can be hard to correlate to the script integrity hash.

Rename metadata → auxiliaryData

And consequently rename blob as metadata. This is an artifact from the moment where scripts where added to the transaction's metadata. Metadata was renamed into auxiliaryData which now contains both the user-defined metadata and, possibly, scripts data. Ogmios has kept metadata for the outermost field to keep backward compatibility.

Rework representation of Value

• coins is a bad name / confusing
• The dot-notation for asset id {policy-id}.{asset-name} is cumbersome to construct and manipulate.

Suggestion represent values as list of records with three fields policyId, assetName, quantity; In the case of Ada, policyId and assetName are set to null.

Rework representation of 'DelegationsAndRewards'

At this moment, this is an object with two optional fields: delegate and rewards. This is because behind the scene, this object is an aggregate of 2 other maps, one for delegates and one for rewards and thus keys may be missing in both. However, while it makes sense to have no delegate at some point (referring to an account that is no longer delegated, but has been); having no rewards field is a bit unpractical. At the very least, rewards can be defaulted to 0 when there's no rewards in the map.

[MartinSchere]

For the rework representation of Value, we could have it exactly like Blockfrost:

[{
   unit: "<policy><asset_name>", // In the case of `lovelace`, we use 'lovelace'
   quantity: "qty_string"
}]

That would compatibility across libraries. It's comfortable, although we would lose the performance of the unit -> qty lookup in the object.

[szist]

Rework representation of Value

For interacting with smart contracts, the most "ergonomic" is using the same format as Plutus is using:
Map<policyId, Map<assetName, quantity>> with policyId and assetName set to empty string "" not null. Null would need to be handled differently in most languages and if the fields are not nullable it could actually help. This approach is in theory more space-saving as policyIds are not repeated, but it rarely happens that tokens with the same policyIds are in a single utxo.

The only pain with this format is that you need a lot of helper function to manipulate it (adding/removing quantities).

I believe cardano-serialization-lib that is used by many projects use the closer-to-chain [coins, Map<policyId, Map<assetName, qty>>] https://github.com/dcSpark/cardano-multiplatform-lib/blob/2332c1340f24f02510ecd9a437435b0bdf02017e/rust/src/ledger/common/value.rs#L179

Using the blockfrost format seems rather arbitrary and don't see the value compared to how it is now. If anything it's even more involved to parse and work with, as you need to check if it's lovelace or get the first 56 characters for policyId.

[szist]

Use tagged objects instead of singleton.

Yes, please. It would help avoid pattern matching the TS types. Using discriminated unions would be much better. See e.g. (https://github.com/zoeldevapps/cardano-assets-server/blob/e6435e939c3d2db5940eb196362ee56abf6d8f8b/src/onchain/recorders/utils.ts#L37)

[leobel]

Change typescript native script atLeast or nOfk model from

export interface NOf {
  [k: string]: ScriptNative[];
}

to something more intuitive like this:

export interface NOf {
  n: number;
  scripts: ScriptNative[];
}