cardano-api-1.22.1
Safe HaskellNone
LanguageHaskell2010

Cardano.Api.MetaData

Synopsis

Transaction metadata type

newtype TxMetadata Source #

Bundled Patterns

pattern TxMetadata :: Map Word64 TxMetadataValue -> TxMetadata 

Instances

Instances details
Eq TxMetadata Source # 
Instance details

Defined in Cardano.Api.Typed

Show TxMetadata Source # 
Instance details

Defined in Cardano.Api.Typed

Semigroup TxMetadata Source #

Merge metadata maps. When there are clashing entries the left hand side takes precedence.

Instance details

Defined in Cardano.Api.Typed

Monoid TxMetadata Source # 
Instance details

Defined in Cardano.Api.Typed

SerialiseAsCBOR TxMetadata Source # 
Instance details

Defined in Cardano.Api.Typed

HasTypeProxy TxMetadata Source # 
Instance details

Defined in Cardano.Api.Typed

Associated Types

data AsType TxMetadata Source #

data AsType TxMetadata Source # 
Instance details

Defined in Cardano.Api.Typed

Constructing metadata

Validating metadata

validateTxMetadata :: TxMetadata -> Either (NonEmpty TxMetadataRangeError) TxMetadata Source #

Validate transaction metadata. This is for use with existing constructed metadata values, e.g. constructed manually or decoded from CBOR directly.

data TxMetadataRangeError Source #

An error in transaction metadata due to an out-of-range value.

Constructors

TxMetadataNumberOutOfRange !Integer

The number is outside the maximum range of -2^64-1 .. 2^64-1.

TxMetadataTextTooLong !Int

The length of a text string metadatum value exceeds the maximum of 64 bytes as UTF8.

TxMetadataBytesTooLong !Int

The length of a byte string metadatum value exceeds the maximum of 64 bytes.

Converstion to/from JSON

data TxMetadataJsonSchema Source #

Tx metadata is similar to JSON but not exactly the same. It has some deliberate limitations such as no support for floating point numbers or special forms for null or boolean values. It also has limitations on the length of strings. On the other hand, unlike JSON, it distinguishes between byte strings and text strings. It also supports any value as map keys rather than just string.

We provide two different mappings between tx metadata and JSON, useful for different purposes:

  1. A mapping that allows almost any JSON value to be converted into tx metadata. This does not require a specific JSON schema for the input. It does not expose the full representation capability of tx metadata.
  2. A mapping that exposes the full representation capability of tx metadata, but relies on a specific JSON schema for the input JSON.

In the "no schema" mapping, the idea is that (almost) any JSON can be turned into tx metadata and then converted back, without loss. That is, we can round-trip the JSON.

The subset of JSON supported is all JSON except: * No null or bool values * No floating point, only integers in the range of a 64bit signed integer * A limitation on string lengths

The approach for this mapping is to use whichever representation as tx metadata is most compact. In particular:

  • JSON lists and maps represented as CBOR lists and maps
  • JSON strings represented as CBOR strings
  • JSON hex strings with "0x" prefix represented as CBOR byte strings
  • JSON integer numbers represented as CBOR signed or unsigned numbers
  • JSON maps with string keys that parse as numbers or hex byte strings, represented as CBOR map keys that are actually numbers or byte strings.

The string length limit depends on whether the hex string representation is used or not. For text strings the limit is 64 bytes for the UTF8 representation of the text string. For byte strings the limit is 64 bytes for the raw byte form (ie not the input hex, but after hex decoding).

In the "detailed schema" mapping, the idea is that we expose the full representation capability of the tx metadata in the form of a JSON schema. This means the full representation is available and can be controlled precisely. It also means any tx metadata can be converted into the JSON and back without loss. That is we can round-trip the tx metadata via the JSON and also round-trip schema-compliant JSON via tx metadata.

Constructors

TxMetadataJsonNoSchema

Use the "no schema" mapping between JSON and tx metadata as described above.

TxMetadataJsonDetailedSchema

Use the "detailed schema" mapping between JSON and tx metadata as described above.

metadataFromJson :: TxMetadataJsonSchema -> Value -> Either TxMetadataJsonError TxMetadata Source #

Convert a value from JSON into tx metadata, using the given choice of mapping between JSON and tx metadata.

This may fail with a conversion error if the JSON is outside the supported subset for the chosen mapping. See TxMetadataJsonSchema for the details.

metadataToJson :: TxMetadataJsonSchema -> TxMetadata -> Value Source #

Convert a tx metadata value into JSON , using the given choice of mapping between JSON and tx metadata.

This conversion is total but is not necessarily invertible. See TxMetadataJsonSchema for the details.