Evolution SDK
Modules

CBOR.ts

CBOR overview

Table of contents

constants

AIKEN_DEFAULT_OPTIONS

Aiken cbor.serialise() encoding options. Same object as PLUTUS_DATA_OPTIONS.

Aiken writes data in the node layout: non-empty lists and constructor fields indefinite, Pairs as definite maps. Tuples are lists, so they encode as indefinite arrays.

Signature

export declare const AIKEN_DEFAULT_OPTIONS: CodecOptions

Added in v2.0.0

CANONICAL_OPTIONS

Canonical CBOR encoding options with map keys in length-first order: the shorter encoded key first, and keys of equal length bytewise. The order is the one of RFC 7049 Section 3.9 (RFC 8949 Section 4.2.3), which CIP-21 specifies.

Signature

export declare const CANONICAL_OPTIONS: CodecOptions

Added in v1.0.0

CARDANO_NODE_DATA_OPTIONS

Definite-length PlutusData encoding options. Same object as CML_DATA_DEFINITE_OPTIONS.

The name is wrong: the Cardano node writes non-empty lists and constructor fields indefinite. For the node layout use PLUTUS_DATA_OPTIONS.

Signature

export declare const CARDANO_NODE_DATA_OPTIONS: CodecOptions

Added in v2.0.0

CBOR_ADDITIONAL_INFO

CBOR additional information constants

Signature

export declare const CBOR_ADDITIONAL_INFO: {
  readonly DIRECT: 24
  readonly UINT16: 25
  readonly UINT32: 26
  readonly UINT64: 27
  readonly INDEFINITE: 31
}

Added in v1.0.0

CBOR_MAJOR_TYPE

CBOR major types as constants

Signature

export declare const CBOR_MAJOR_TYPE: {
  readonly UNSIGNED_INTEGER: 0
  readonly NEGATIVE_INTEGER: 1
  readonly BYTE_STRING: 2
  readonly TEXT_STRING: 3
  readonly ARRAY: 4
  readonly MAP: 5
  readonly TAG: 6
  readonly SIMPLE_FLOAT: 7
}

Added in v1.0.0

CBOR_SIMPLE

Simple value constants for CBOR

Signature

export declare const CBOR_SIMPLE: { readonly FALSE: 20; readonly TRUE: 21; readonly NULL: 22; readonly UNDEFINED: 23 }

Added in v1.0.0

CML_DATA_DEFAULT_OPTIONS

CBOR encoding options for PlutusData with non-empty lists, constructor fields and maps indefinite, map keys in the order given. This was the Data default before PLUTUS_DATA_OPTIONS.

It matches no tool exactly. The node, cardano-cli and Aiken write maps definite. CML 6.2.0 PlutusData.to_cardano_node_format() writes maps indefinite but also sorts map keys. For a constructor index above 127 the Plutus data encoder writes the tag 102 [index, fields] pair definite under every preset, including this one. Use it only to reproduce the bytes and datum hashes the SDK wrote before PLUTUS_DATA_OPTIONS became the default.

Signature

export declare const CML_DATA_DEFAULT_OPTIONS: CodecOptions

Added in v1.0.0

CML_DATA_DEFINITE_OPTIONS

CBOR encoding options for PlutusData matching CML PlutusData.to_cbor_hex() on freshly built data.

Uses definite-length lists, constructor fields, and maps. It differs from the node layout (PLUTUS_DATA_OPTIONS) by writing lists and constructor fields definite.

Signature

export declare const CML_DATA_DEFINITE_OPTIONS: CodecOptions

Added in v2.0.0

CML_DEFAULT_OPTIONS

Default CBOR encoding options

Signature

export declare const CML_DEFAULT_OPTIONS: CodecOptions

Added in v1.0.0

HW_CLI_OPTIONS

Canonical CBOR encoding options with map keys in bytewise order (RFC 8949 Section 4.2.1). Before it witnesses a transaction, cardano-hw-cli checks that the transaction is canonical in this order: it decodes the transaction, encodes it again as canonical CBOR with keys in bytewise order, and compares the bytes.

No preset passes the check when a redeemer or a witness datum holds a byte string over 64 bytes, the bytes of a bignum included. Plutus requires such a string in 64-byte chunks, and the check requires it in one piece.

Signature

export declare const HW_CLI_OPTIONS: CodecOptions

Added in v2.0.0

PLUTUS_DATA_OPTIONS

CBOR encoding options for PlutusData in the layout the Cardano node writes.

  • Non-empty lists and constructor fields: indefinite-length (9f...ff)
  • Maps: definite-length
  • Empty list: 80; empty map: a0

The Data default. Data.toCBORBytes with these options writes the bytes the node writes. The rules that do not depend on options are applied by the Plutus data encoder under every preset: byte strings over 64 bytes in 64-byte chunks, bignums only outside -2^64 to 2^64 - 1 with their bytes chunked the same way, and a definite [index, fields] pair under tag 102.

Signature

export declare const PLUTUS_DATA_OPTIONS: CodecOptions

Added in v2.0.0

STRUCT_FRIENDLY_OPTIONS

CBOR encoding options that return objects instead of Maps for Schema.Struct compatibility

Signature

export declare const STRUCT_FRIENDLY_OPTIONS: CodecOptions

Added in v2.0.0

TX_CANONICAL_OPTIONS

Canonical options for a transaction: CANONICAL_OPTIONS for both ledger structures and Plutus data, so map keys are in length-first order (RFC 7049 Section 3.9, RFC 8949 Section 4.2.3), as CIP-21 specifies.

Signature

export declare const TX_CANONICAL_OPTIONS: TxCodecOptions

Added in v2.0.0

TX_DEFAULT_OPTIONS

Default options for a transaction.

  • ledger is CML_DEFAULT_OPTIONS, CML's transaction encoding: map keys in insertion order, definite lengths.
  • plutusData is PLUTUS_DATA_OPTIONS, the Data default.

It does not match cardano-cli, which sorts map keys and writes indefinite lengths above 23 entries.

Signature

export declare const TX_DEFAULT_OPTIONS: TxCodecOptions

Added in v2.0.0

TX_HW_CLI_OPTIONS

Options for a transaction: HW_CLI_OPTIONS for both ledger structures and Plutus data. They write map keys in bytewise order (RFC 8949 Section 4.2.1), which cardano-hw-cli checks before it witnesses a transaction.

No preset passes the check when a redeemer or a witness datum holds a byte string over 64 bytes, the bytes of a bignum included. Plutus requires such a string in 64-byte chunks, and the check requires it in one piece.

Signature

export declare const TX_HW_CLI_OPTIONS: TxCodecOptions

Added in v2.0.0

decoding

decodeItemWithOffset

Decode a single CBOR item at a given byte offset, returning the decoded value and the new offset. Useful for extracting raw byte slices from CBOR-encoded data without re-encoding.

Signature

export declare const decodeItemWithOffset: (
  data: Uint8Array,
  offset: number,
  options?: CodecOptions
) => { item: CBOR; newOffset: number }

Added in v2.0.0

encoding

toCBORBytes

Convert a CBOR value to CBOR bytes.

Signature

export declare const toCBORBytes: (value: CBOR, options?: CodecOptions) => Uint8Array

Added in v1.0.0

toCBORBytesWithFormat

Convert a CBOR value to CBOR bytes using an explicit root format tree.

Signature

export declare const toCBORBytesWithFormat: (value: CBOR, format: CBORFormat) => Uint8Array

Added in v2.0.0

toCBORHex

Convert a CBOR value to CBOR hex string.

Signature

export declare const toCBORHex: (value: CBOR, options?: CodecOptions) => string

Added in v1.0.0

toCBORHexWithFormat

Convert a CBOR value to CBOR hex string using an explicit root format tree.

Signature

export declare const toCBORHexWithFormat: (value: CBOR, format: CBORFormat) => string

Added in v2.0.0

equality

equals

Schema-derived structural equivalence for CBOR values. Handles Uint8Array, Array, Map, Tag and all primitives via the recursive CBORSchema definition — no hand-rolled comparison needed.

Derived once at module init; at call time it's a plain function.

Signature

export declare const equals: (a: CBOR, b: CBOR) => boolean

Added in v2.0.0

errors

CBORError (class)

Error class for CBOR value operations

Signature

export declare class CBORError

Added in v1.0.0

model

BoundedBytes

BoundedBytes CBOR node — represents a PlutusData byte string that must comply with the Conway CDDL constraint bounded_bytes = bytes .size (0..64).

The encoding rule is unconditional and options-independent:

  • ≤ 64 bytes → definite-length CBOR bytes

  • 64 bytes → indefinite-length 64-byte chunked byte string (0x5f + chunks + 0xff)

Use BoundedBytes.make to construct the node; the encoder handles the rest.

Signature

export declare const BoundedBytes: {
  readonly make: (bytes: Uint8Array) => CBOR
  readonly is: (value: CBOR) => value is { _tag: "BoundedBytes"; bytes: Uint8Array }
}

Added in v2.0.0

ByteSize (type alias)

Width of a CBOR integer argument: inline (0), 1-byte, 2-byte, 4-byte, or 8-byte.

Signature

export type ByteSize = 0 | 1 | 2 | 4 | 8

Added in v2.0.0

CBOR (type alias)

Type representing a CBOR value with simplified, non-tagged structure

Signature

export type CBOR =
  | bigint // integers (both positive and negative)
  | Uint8Array // byte strings
  | string // text strings
  | ReadonlyArray<CBOR> // arrays
  | ReadonlyMap<CBOR, CBOR> // maps
  | { readonly [key: string | number]: CBOR } // record alternative to maps
  | { _tag: "Tag"; tag: number; value: CBOR } // tagged values
  | boolean // boolean values
  | null // null value
  | undefined // undefined value
  | number // floating point numbers
  | { _tag: "BoundedBytes"; bytes: Uint8Array }

Added in v1.0.0

CBORFormat (type alias)

Tagged discriminated union capturing how each CBOR node was originally serialized. Every variant carries a _tag discriminant. Encoding-detail fields are optional — absent means "use canonical / minimal default".

Signature

export type CBORFormat =
  | CBORFormat.UInt
  | CBORFormat.NInt
  | CBORFormat.Bytes
  | CBORFormat.Text
  | CBORFormat.Array
  | CBORFormat.Map
  | CBORFormat.Tag
  | CBORFormat.Simple

Added in v2.0.0

CBORFormat (namespace)

Added in v2.0.0

Array (type alias)

Array (major 4). length absent → definite, minimal length header.

Signature

export type Array = {
  readonly _tag: "array"
  readonly length?: LengthEncoding
  readonly children: ReadonlyArray<CBORFormat>
}

Bytes (type alias)

Byte string (major 2). encoding absent → definite, minimal length.

Signature

export type Bytes = { readonly _tag: "bytes"; readonly encoding?: StringEncoding }

Map (type alias)

Map (major 5). keyOrder stores CBOR-encoded key bytes for serializable ordering.

Signature

export type Map = {
  readonly _tag: "map"
  readonly length?: LengthEncoding
  readonly keyOrder?: ReadonlyArray<Uint8Array>
  readonly entries: ReadonlyArray<readonly [CBORFormat, CBORFormat]>
}

NInt (type alias)

Negative integer (major 1). byteSize absent → minimal encoding.

Signature

export type NInt = { readonly _tag: "nint"; readonly byteSize?: ByteSize }

Simple (type alias)

Simple value or float (major 7). No encoding choices to preserve.

Signature

export type Simple = { readonly _tag: "simple" }

Tag (type alias)

Tag (major 6). width absent → minimal tag header.

Signature

export type Tag = {
  readonly _tag: "tag"
  readonly width?: ByteSize
  readonly child: CBORFormat
}

Text (type alias)

Text string (major 3). encoding absent → definite, minimal length.

Signature

export type Text = { readonly _tag: "text"; readonly encoding?: StringEncoding }

UInt (type alias)

Unsigned integer (major 0). byteSize absent → minimal encoding.

Signature

export type UInt = { readonly _tag: "uint"; readonly byteSize?: ByteSize }

CodecOptions (type alias)

CBOR codec configuration options

Signature

export type CodecOptions =
  | {
      readonly mode: "canonical"
      readonly mapsAsObjects?: boolean
      /**
       * The order of map keys. `"lengthFirst"`, the default, puts the shorter
       * encoded key first and orders keys of equal length bytewise (RFC 7049
       * Section 3.9). `"bytewise"` orders the encoded keys bytewise, and a key
       * that is a prefix of another comes first (RFC 8949 Section 4.2.1).
       */
      readonly keyOrder?: "lengthFirst" | "bytewise"
      /**
       * Encode every map as an array of `[key, value]` pairs.
       *
       * @deprecated This turns a map into a list, which is a different value
       * with a different hash. No Plutus data encoder writes maps this way, and
       * no option replaces it: leave it unset so maps stay maps.
       */
      readonly encodeMapAsPairs?: boolean
    }
  | {
      readonly mode: "custom"
      readonly useIndefiniteArrays: boolean
      readonly useIndefiniteMaps: boolean
      readonly useDefiniteForEmpty: boolean
      readonly sortMapKeys: boolean
      /**
       * The order of map keys when `sortMapKeys` is true. `"lengthFirst"`,
       * the default, puts the shorter encoded key first and orders keys of
       * equal length bytewise (RFC 7049 Section 3.9). `"bytewise"` orders the
       * encoded keys bytewise, and a key that is a prefix of another comes
       * first (RFC 8949 Section 4.2.1).
       */
      readonly keyOrder?: "lengthFirst" | "bytewise"
      readonly useMinimalEncoding: boolean
      readonly mapsAsObjects?: boolean
      /**
       * Encode every map as an array of `[key, value]` pairs.
       *
       * @deprecated This turns a map into a list, which is a different value
       * with a different hash. No Plutus data encoder writes maps this way, and
       * no option replaces it: leave it unset so maps stay maps.
       */
      readonly encodeMapAsPairs?: boolean
    }

Added in v1.0.0

DecodedWithFormat (type alias)

Decoded value paired with its captured root format tree.

Signature

export type DecodedWithFormat<A> = {
  value: A
  format: CBORFormat
}

Added in v2.0.0

LengthEncoding (type alias)

Container length encoding style captured during decode.

Signature

export type LengthEncoding = { readonly tag: "indefinite" } | { readonly tag: "definite"; readonly byteSize: ByteSize }

Added in v2.0.0

StringEncoding (type alias)

Byte/text string encoding style captured during decode.

Signature

export type StringEncoding =
  | { readonly tag: "definite"; readonly byteSize: ByteSize }
  | {
      readonly tag: "indefinite"
      readonly chunks: ReadonlyArray<{ readonly length: number; readonly byteSize: ByteSize }>
    }

Added in v2.0.0

TxCodecOptions (type alias)

CBOR options for a transaction and the structures in it.

  • ledger: the options for ledger structures: the body, the witness set, and the containers that hold datums and redeemers.
  • plutusData: the options for Plutus data items: new inline datums, new witness datums and redeemer data. A datum that keeps the bytes it was decoded from, such as one from provider.getDatum, is written with those bytes.

Signature

export type TxCodecOptions = {
  readonly ledger: CodecOptions
  readonly plutusData: CodecOptions
}

Added in v2.0.0

parsing

fromCBORBytes

Parse a CBOR value from CBOR bytes.

Signature

export declare const fromCBORBytes: (bytes: Uint8Array, options?: CodecOptions) => CBOR

Added in v1.0.0

fromCBORBytesWithFormat

Parse a CBOR value from CBOR bytes and return the root format tree.

Signature

export declare const fromCBORBytesWithFormat: (bytes: Uint8Array) => DecodedWithFormat<CBOR>

Added in v2.0.0

fromCBORHex

Parse a CBOR value from CBOR hex string.

Signature

export declare const fromCBORHex: (hex: string, options?: CodecOptions) => CBOR

Added in v1.0.0

fromCBORHexWithFormat

Parse a CBOR value from CBOR hex string and return the root format tree.

Signature

export declare const fromCBORHexWithFormat: (hex: string) => DecodedWithFormat<CBOR>

Added in v2.0.0

internalDecodeWithFormatSync

Decode CBOR bytes and return both the decoded value and the root format tree.

Signature

export declare const internalDecodeWithFormatSync: (data: Uint8Array) => DecodedWithFormat<CBOR>

Added in v2.0.0

schemas

CBORSchema

CBOR Value discriminated union schema representing all possible CBOR data types Inspired by OCaml and Rust CBOR implementations

Signature

export declare const CBORSchema: Schema.Schema<CBOR, CBOR, never>

Added in v1.0.0

FromBytes

Create a CBOR bytes schema with custom codec options

Signature

export declare const FromBytes: (
  options: CodecOptions
) => Schema.transformOrFail<typeof Schema.Uint8ArrayFromSelf, Schema.declare<CBOR, CBOR, readonly [], never>, never>

Added in v1.0.0

Integer

CBOR Value schema definitions for each major type

Signature

export declare const Integer: typeof Schema.BigIntFromSelf

Added in v1.0.0

transformation

match

Pattern matching utility for CBOR values

Signature

export declare const match: <R>(
  value: CBOR,
  patterns: {
    integer: (value: bigint) => R
    bytes: (value: Uint8Array) => R
    text: (value: string) => R
    array: (value: ReadonlyArray<CBOR>) => R
    map: (value: ReadonlyMap<CBOR, CBOR>) => R
    record: (value: { readonly [key: string]: CBOR }) => R
    tag: (tag: number, value: CBOR) => R
    boolean: (value: boolean) => R
    null: () => R
    undefined: () => R
    float: (value: number) => R
    boundedBytes: (value: Uint8Array) => R
  }
) => R

Added in v1.0.0

toTxCodecOptions

Turns plain options into transaction options: ledger is the options and plutusData is the options too, except that CML_DEFAULT_OPTIONS gives PLUTUS_DATA_OPTIONS, as TX_DEFAULT_OPTIONS does. Transaction options are returned as they are.

Signature

export declare const toTxCodecOptions: (options: TxCodecOptions | CodecOptions) => TxCodecOptions

Added in v2.0.0

utils

ArraySchema

Signature

export declare const ArraySchema: Schema.Array$<Schema.suspend<CBOR, CBOR, never>>

ByteArray

Signature

export declare const ByteArray: typeof Schema.Uint8ArrayFromSelf

Either (namespace)

Float

Signature

export declare const Float: typeof Schema.Number

FromHex

Signature

export declare const FromHex: (
  options: CodecOptions
) => Schema.transform<
  Schema.Schema<Uint8Array, string, never>,
  Schema.transformOrFail<typeof Schema.Uint8ArrayFromSelf, Schema.declare<CBOR, CBOR, readonly [], never>, never>
>

MapSchema

Signature

export declare const MapSchema: Schema.ReadonlyMapFromSelf<
  Schema.suspend<CBOR, CBOR, never>,
  Schema.suspend<CBOR, CBOR, never>
>

RecordSchema

Signature

export declare const RecordSchema: Schema.Record$<typeof Schema.String, Schema.suspend<CBOR, CBOR, never>>

Simple

Signature

export declare const Simple: Schema.Union<[typeof Schema.Boolean, typeof Schema.Null, typeof Schema.Undefined]>

Tag

Signature

export declare const Tag: Schema.TaggedStruct<
  "Tag",
  { tag: typeof Schema.Number; value: Schema.suspend<CBOR, CBOR, never> }
>

Text

Signature

export declare const Text: typeof Schema.String

encodeArrayAsDefinite

Encode a CBOR definite-length array from already-encoded item bytes. This is a low-level function that constructs: definite_array_header + items.

Signature

export declare const encodeArrayAsDefinite: (items: ReadonlyArray<Uint8Array>) => Uint8Array

encodeArrayAsIndefinite

Encode a CBOR indefinite-length array from already-encoded item bytes. This is a low-level function that constructs: 0x9f + items + 0xff.

Signature

export declare const encodeArrayAsIndefinite: (items: ReadonlyArray<Uint8Array>) => Uint8Array

encodeTaggedValue

Encode a CBOR tagged value from already-encoded value bytes. This is a low-level function that constructs: tag_header + value_bytes.

Signature

export declare const encodeTaggedValue: (tag: number, valueBytes: Uint8Array) => Uint8Array

internalDecodeSync

Signature

export declare const internalDecodeSync: (data: Uint8Array, options?: CodecOptions) => CBOR

internalEncodeSync

Signature

export declare const internalEncodeSync: (value: CBOR, options?: CodecOptions, fmt?: CBORFormat) => Uint8Array

isArray

Signature

export declare const isArray: (u: unknown, overrideOptions?: ParseOptions | number) => u is readonly CBOR[]

isByteArray

Signature

export declare const isByteArray: (u: unknown, overrideOptions?: ParseOptions | number) => u is any

isInteger

Signature

export declare const isInteger: (u: unknown, overrideOptions?: ParseOptions | number) => u is bigint

isMap

Signature

export declare const isMap: (u: unknown, overrideOptions?: ParseOptions | number) => u is ReadonlyMap<CBOR, CBOR>

isRecord

Signature

export declare const isRecord: (
  u: unknown,
  overrideOptions?: ParseOptions | number
) => u is { readonly [x: string]: CBOR }

isTag

Signature

export declare const isTag: (
  u: unknown,
  overrideOptions?: ParseOptions | number
) => u is { readonly _tag: "Tag"; readonly tag: number; readonly value: CBOR }

map

Signature

export declare const map: <K extends CBOR, V extends CBOR>(
  key: Schema.Schema<K>,
  value: Schema.Schema<V>
) => Schema.ReadonlyMapFromSelf<Schema.Schema<K, K, never>, Schema.Schema<V, V, never>>

tag

Signature

export declare const tag: <T extends number, C extends Schema.Schema<any, any>>(
  tag: T,
  value: C
) => Schema.TaggedStruct<"Tag", { tag: Schema.Literal<[T]>; value: C }>

Bytes96.ts

Previous Page

Certificate.ts

Next Page

On this page

CBOR overviewconstantsAIKEN_DEFAULT_OPTIONSCANONICAL_OPTIONSCARDANO_NODE_DATA_OPTIONSCBOR_ADDITIONAL_INFOCBOR_MAJOR_TYPECBOR_SIMPLECML_DATA_DEFAULT_OPTIONSCML_DATA_DEFINITE_OPTIONSCML_DEFAULT_OPTIONSHW_CLI_OPTIONSPLUTUS_DATA_OPTIONSSTRUCT_FRIENDLY_OPTIONSTX_CANONICAL_OPTIONSTX_DEFAULT_OPTIONSTX_HW_CLI_OPTIONSdecodingdecodeItemWithOffsetencodingtoCBORBytestoCBORBytesWithFormattoCBORHextoCBORHexWithFormatequalityequalserrorsCBORError (class)modelBoundedBytesByteSize (type alias)CBOR (type alias)CBORFormat (type alias)CBORFormat (namespace)Array (type alias)Bytes (type alias)Map (type alias)NInt (type alias)Simple (type alias)Tag (type alias)Text (type alias)UInt (type alias)CodecOptions (type alias)DecodedWithFormat (type alias)LengthEncoding (type alias)StringEncoding (type alias)TxCodecOptions (type alias)parsingfromCBORBytesfromCBORBytesWithFormatfromCBORHexfromCBORHexWithFormatinternalDecodeWithFormatSyncschemasCBORSchemaFromBytesIntegertransformationmatchtoTxCodecOptionsutilsArraySchemaByteArrayEither (namespace)FloatFromHexMapSchemaRecordSchemaSimpleTagTextencodeArrayAsDefiniteencodeArrayAsIndefiniteencodeTaggedValueinternalDecodeSyncinternalEncodeSyncisArrayisByteArrayisIntegerisMapisRecordisTagmaptag