@helios-lang/contract-utils 0.2.69 → 0.2.71

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helios-lang/contract-utils",
-  "version": "0.2.69",
+  "version": "0.2.71",
   "description": "Convenience and type-safety utilities for using Helios validators from within Typescript",
   "main": "src/index.js",
   "types": "types/index.d.ts",
@@ -27,10 +27,10 @@
   "dependencies": {
     "@helios-lang/cli-utils": "^0.1.6",
     "@helios-lang/codec-utils": "^0.1.35",
-    "@helios-lang/compiler-utils": "^0.1.57",
-    "@helios-lang/ledger": "^0.5.4",
-    "@helios-lang/type-utils": "^0.1.22",
-    "@helios-lang/uplc": "^0.3.12"
+    "@helios-lang/compiler-utils": "^0.1.61",
+    "@helios-lang/ledger": "^0.5.6",
+    "@helios-lang/type-utils": "^0.1.23",
+    "@helios-lang/uplc": "^0.4.13"
   },
   "scripts": {
     "build": "pnpm run prettify && pnpm run build:types && pnpm run test:suite",
@@ -40,8 +40,8 @@
     "test": "pnpm run test:pretty && pnpm run test:types && pnpm run test:suite",
     "test:pretty": "prettier . --check",
     "test:suite": "node --test",
-    "testing": "node --test --watch",
-    "testing:debug": "node --inspect-brk --test --watch",
-    "test:types": "pnpm run build:types"
+    "test:types": "pnpm run build:types",
+    "testing": "HL_TEST_TRACE=ok node --test --watch",
+    "testing:debug": "HL_TEST_TRACE=ok node --inspect-brk --test --watch"
   }
 }

package/src/cast/Cast.js

@@ -20,7 +20,7 @@ import {
     ValidatorHash,
     Value
 } from "@helios-lang/ledger"
-import { None, expectSome, isSome } from "@helios-lang/type-utils"
+import { None, expectSome } from "@helios-lang/type-utils"
 import {
     ByteArrayData,
     ConstrData,
@@ -59,6 +59,19 @@ import {
  * @typedef {Cast<TStrict, TPermissive> | ConfigurableCast<TStrict, TPermissive>} CastLike
  */
 
+/**
+ * @typedef {Object} SchemaToUplcContext
+ * @property {Record<string, TypeSchema>} defs - symbol table permitting recursive schema references
+ * @property {string} dataPath - provides developer-facing cues for any parsing errors, showing the deep field path of any error
+ */
+
+/**
+ * @typedef {Object} UplcToSchemaContext
+ * @property {Record<string, TypeSchema>} defs - symbol table permitting recursive schema references
+ * @property {string} dataPath - provides developer-facing cues for any parsing errors, showing the deep field path of any error
+ * @property {CastConfig} config - has isMainnet indicator
+ */
+
 /**
  * @template TStrict
  * @template TPermissive=TStrict
@@ -87,10 +100,15 @@ export class Cast {
 
     /**
      * @param {UplcData} data
+     * @param {string} [dataPath] - can be used to indicate the kind or context of data-decoding
      * @returns {TStrict}
      */
-    fromUplcData(data) {
-        return uplcToSchema(this.schema, data, this.config)
+    fromUplcData(data, dataPath = "") {
+        return uplcToSchemaWithDataPath(this.schema, data, {
+            config: this.config,
+            dataPath,
+            defs: {}
+        })
     }
 
     /**
@@ -105,7 +123,10 @@ export class Cast {
      * @returns {UplcData}
      */
     toUplcData(x, dataPath = "") {
-        const t = schemaToUplcWithDataPath(this.schema, x, {}, dataPath)
+        const t = schemaToUplcWithDataPath(this.schema, x, {
+            defs: {},
+            dataPath
+        })
         t.rawData = x
         return t
     }
@@ -114,19 +135,18 @@ export class Cast {
 /**
  * @param {TypeSchema} schema
  * @param {any} x
- * @param {Record<string, TypeSchema>} defs
- * @param {string} dataPath
+ * @param {SchemaToUplcContext} context
  * @returns {UplcData}
  */
-function schemaToUplcWithDataPath(schema, x, defs = {}, dataPath = "") {
+function schemaToUplcWithDataPath(schema, x, context) {
     try {
-        const t = schemaToUplc(schema, x, defs, dataPath)
-        t.dataPath = dataPath
+        const t = schemaToUplc(schema, x, context)
+        t.dataPath = context.dataPath
         return t
     } catch (e) {
         if (!e.uplcDataPath) {
-            e.message = `${e.message}\n ... at ${dataPath}`
-            e.uplcDataPath = dataPath
+            e.message = `${e.message}\n ... at ${context.dataPath}`
+            e.uplcDataPath = context.dataPath
         }
         debugger
         throw e
@@ -136,21 +156,25 @@ function schemaToUplcWithDataPath(schema, x, defs = {}, dataPath = "") {
 /**
  * @param {TypeSchema} schema
  * @param {any} x
- * @param {Record<string, TypeSchema>} defs
- * @param {string} dataPath
+ * @param {SchemaToUplcContext} inputContextOnly
  * @returns {UplcData}
  */
-function schemaToUplc(schema, x, defs = {}, dataPath = "") {
+function schemaToUplc(schema, x, inputContextOnly) {
+    // const { defs = {}, dataPath = "" } = inputContext
+    // important: DON'T extend the inputContext for use in nested calls.
+    const { dataPath, defs } = inputContextOnly
+
+    // Only the defs can be passed down, and it's simpler syntactically
+    //   ... just use the defs directly in the nested calls.
+
     const kind = schema.kind
     switch (kind) {
         case "reference": {
             const def = expectSome(defs[schema.id])
-            return schemaToUplcWithDataPath(
-                def,
-                x,
+            return schemaToUplcWithDataPath(def, x, {
                 defs,
-                `${dataPath}::ref{${schema.id}}`
-            )
+                dataPath: `${dataPath}::ref{${schema.id}}`
+            })
         }
         case "internal": {
             const name = schema.name
@@ -228,12 +252,10 @@ function schemaToUplc(schema, x, defs = {}, dataPath = "") {
         case "list":
             return new ListData(
                 x.map((x, i) =>
-                    schemaToUplcWithDataPath(
-                        schema.itemType,
-                        x,
+                    schemaToUplcWithDataPath(schema.itemType, x, {
                         defs,
-                        `${dataPath}.list[${i}]`
-                    )
+                        dataPath: `${dataPath}.list[${i}]`
+                    })
                 )
             )
         case "map": {
@@ -244,42 +266,37 @@ function schemaToUplc(schema, x, defs = {}, dataPath = "") {
                       ? x
                       : Object.entries(x)
             return new MapData(
-                entries.map(([k, v]) => [
-                    schemaToUplcWithDataPath(
-                        schema.keyType,
-                        k,
-                        defs,
-                        `${dataPath}[mapKey '${k}']`
-                    ),
-                    schemaToUplcWithDataPath(
-                        schema.valueType,
-                        v,
-                        defs,
-                        `${dataPath}[map].${k}`
-                    )
-                ])
+                entries.map(([k, v], i) => {
+                    const displayKey = "string" == typeof k ? `'${k}'` : `@{i}`
+                    return [
+                        schemaToUplcWithDataPath(schema.keyType, k, {
+                            defs,
+                            dataPath: `${dataPath}[mapKey ${displayKey}]`
+                        }),
+                        schemaToUplcWithDataPath(schema.valueType, v, {
+                            defs,
+                            dataPath: `${dataPath}[mapVal ${displayKey}]`
+                        })
+                    ]
+                })
             )
         }
         case "tuple":
             return new ListData(
                 x.map((x, i) =>
-                    schemaToUplcWithDataPath(
-                        schema.itemTypes[i],
-                        x,
+                    schemaToUplcWithDataPath(schema.itemTypes[i], x, {
                         defs,
-                        `${dataPath}[tuple@${i}]`
-                    )
+                        dataPath: `${dataPath}[tuple@${i}]`
+                    })
                 )
             )
         case "option":
             return encodeOptionData(
                 x
-                    ? schemaToUplcWithDataPath(
-                          schema.someType,
-                          x,
+                    ? schemaToUplcWithDataPath(schema.someType, x, {
                           defs,
-                          `${dataPath}::Some`
-                      )
+                          dataPath: `${dataPath}::Some`
+                      })
                     : None
             )
         case "struct": {
@@ -290,63 +307,81 @@ function schemaToUplc(schema, x, defs = {}, dataPath = "") {
                     return schemaToUplcWithDataPath(
                         schema.fieldTypes[0].type,
                         x[singleFieldName],
-                        defs,
-                        `${dataPath}[sStruct.${singleFieldName}]`
+                        {
+                            defs,
+                            dataPath: `${dataPath}[sfStruct.${singleFieldName}]`
+                        }
                     )
                 case "list":
                     return new ListData(
                         schema.fieldTypes.map(({ name, type }) =>
-                            schemaToUplcWithDataPath(
-                                type,
-                                x[name],
-                                {},
-                                `${dataPath}[fStruct].${name}`
-                            )
+                            schemaToUplcWithDataPath(type, x[name], {
+                                defs,
+                                dataPath: `${dataPath}[fStruct].${name}`
+                            })
                         )
                     )
                 case "map": {
                     // first make sure all fields are present
                     schema.fieldTypes.forEach((ft) => {
+                        // todo: ? allow Option[T] fields to be missing?
+
                         if (!(ft.name in x)) {
-                            throw new Error(`missing field ${ft.name}`)
+                            if (ft.key && ft.key in x) {
+                                const encodingInfo = ft.key
+                                    ? `incorrectly specified as encoding-key '${ft.key}'`
+                                    : ""
+                                throw new Error(
+                                    `field '${ft.name}' ${encodingInfo}`
+                                )
+                            }
+                            throw new Error(`missing field '${ft.name}'`)
                         }
                     })
 
-                    // respect order of entries
+                    // respect order of entries in provided data
+                    // todo: ? allow encoding-order to match schema-defined order instead ?
+                    // todo: ? allow the encoding to follow the encoding keys in sorted order?
                     /**
                      * @type {[UplcData, UplcData][]}
                      */
                     const pairs = []
 
-                    Object.entries(x).forEach(([key, value]) => {
+                    Object.entries(x).forEach(([fieldName, value]) => {
                         const ft = schema.fieldTypes.find(
-                            (ft) => ft.name == key
+                            (ft) => ft.name == fieldName
                         )
 
                         if (ft) {
-                            debugger
-                            // const rawKey = ft.key || ft.name
-                            const rawKey = ft.name
+                            const encodingKey = ft.key || ft.name
+                            const encodingInfo = ft.key ? ` as '${ft.key}'` : ""
                             const keyData = new ByteArrayData(
-                                encodeUtf8(rawKey)
+                                encodeUtf8(encodingKey)
                             )
+
                             const valueData = schemaToUplcWithDataPath(
                                 ft.type,
                                 value,
-                                defs,
-                                `${dataPath}[mStruct][${key}]`
+                                {
+                                    defs,
+                                    dataPath: `${dataPath}[mStruct].${fieldName}${encodingInfo}`
+                                }
                             )
 
                             pairs.push([keyData, valueData])
                         }
                     })
 
-                    // wrapped in ConstrData
-                    return new ConstrData(0, [new MapData(pairs)])
+                    // A struct targeting CIP-68 compliance must have ConstrData
+                    // ... due to its explicitly-declared Enum variant in developer-land.
+                    //
+                    // We just return our MapData, and we don't care whether it's used in any particular context.
+
+                    return new MapData(pairs)
                 }
                 default:
                     throw new Error(
-                        `unhandled struct format '${schema.format}'`
+                        `unhandled struct format '${/** @type {any} */ (schema).format}'`
                     )
             }
         }
@@ -364,15 +399,15 @@ function schemaToUplc(schema, x, defs = {}, dataPath = "") {
                 )
             }
 
+            // Gives the encoding of nested data a context to prevent a second ConstrData wrapper on the MapData
+            // ... only for the first field.
             return new ConstrData(
                 tag,
-                schema.variantTypes[tag].fieldTypes.map((f) =>
-                    schemaToUplcWithDataPath(
-                        f.type,
-                        variantFields[f.name],
+                schema.variantTypes[tag].fieldTypes.map((f, i) =>
+                    schemaToUplcWithDataPath(f.type, variantFields[f.name], {
                         defs,
-                        `${dataPath}[${schema.name}::${variantName}].${f.name}`
-                    )
+                        dataPath: `${dataPath}[${schema.name}::${variantName}].${f.name}`
+                    })
                 )
             )
         }
@@ -382,12 +417,10 @@ function schemaToUplc(schema, x, defs = {}, dataPath = "") {
             return new ConstrData(
                 schema.tag,
                 schema.fieldTypes.map(({ name, type }) =>
-                    schemaToUplcWithDataPath(
-                        type,
-                        x[name],
-                        {},
-                        `${dataPath}.${name}`
-                    )
+                    schemaToUplcWithDataPath(type, x[name], {
+                        defs,
+                        dataPath: `${dataPath}[enumVariant ${schema.id}.${name}`
+                    })
                 )
             )
         default:
@@ -395,16 +428,41 @@ function schemaToUplc(schema, x, defs = {}, dataPath = "") {
     }
 }
 
+/**
+ * @param {TypeSchema} schema
+ * @param {UplcData} data
+ * @param {UplcToSchemaContext} context
+ * @returns {any}
+ */
+function uplcToSchemaWithDataPath(schema, data, context) {
+    try {
+        const t = uplcToSchema(schema, data, context)
+        return t
+    } catch (e) {
+        if (!e.uplcDataPath) {
+            e.message =
+                `decoding UPLC data: ${e.message}` +
+                (context.dataPath ? `\n ... at ${context.dataPath}` : "")
+            e.uplcDataPath = context.dataPath
+        }
+        debugger
+        throw e
+    }
+}
+
 /**
  * This should fail when deviating
  * @param {TypeSchema} schema
  * @param {UplcData} data
- * @param {CastConfig} config
- * @param {Record<string, TypeSchema>} defs
+ * @param {UplcToSchemaContext} inputContextOnly
  * @returns {any}
  */
-function uplcToSchema(schema, data, config, defs = {}) {
+function uplcToSchema(schema, data, inputContextOnly) {
     const kind = schema.kind
+    const { config, defs } = inputContextOnly
+    // Note: don't use the inputContext directly in nested calls.
+    const { dataPath, ...context } = inputContextOnly
+    //   use { ... context } augmented with a de-novo `dataPath` attr
 
     switch (kind) {
         case "internal": {
@@ -482,24 +540,44 @@ function uplcToSchema(schema, data, config, defs = {}) {
             }
         }
         case "list":
-            return ListData.expect(data).items.map((x) =>
-                uplcToSchema(schema.itemType, x, config, defs)
+            return ListData.expect(data).items.map((x, i) =>
+                uplcToSchemaWithDataPath(schema.itemType, x, {
+                    ...context,
+                    dataPath: `${dataPath}[${i}]`
+                })
             )
         case "map":
             return new Map(
-                MapData.expect(data).items.map(([k, v]) => [
-                    uplcToSchema(schema.keyType, k, config, defs),
-                    uplcToSchema(schema.valueType, v, config, defs)
-                ])
+                MapData.expect(data).items.map(([k, v], i) => {
+                    const key = uplcToSchemaWithDataPath(schema.keyType, k, {
+                        ...context,
+                        dataPath: `${dataPath}[mapKey @${i}]`
+                    })
+                    const displayKey =
+                        "string" == typeof key ? `'${key}'` : `@{i}`
+                    return [
+                        key,
+                        uplcToSchemaWithDataPath(schema.valueType, v, {
+                            ...context,
+                            dataPath: `${dataPath}[mapVal ${displayKey}]`
+                        })
+                    ]
+                })
             )
         case "tuple":
             return ListData.expect(data).items.map((x, i) =>
-                uplcToSchema(schema.itemTypes[i], x, config, defs)
+                uplcToSchemaWithDataPath(schema.itemTypes[i], x, {
+                    ...context,
+                    dataPath: `${dataPath}[tuple@${i}]`
+                })
             )
         case "option": {
             const optionData = decodeOptionData(data)
             return optionData
-                ? uplcToSchema(schema.someType, optionData, config, defs)
+                ? uplcToSchemaWithDataPath(schema.someType, optionData, {
+                      ...context,
+                      dataPath: `${dataPath}::Some`
+                  })
                 : None
         }
         case "struct": {
@@ -507,11 +585,10 @@ function uplcToSchema(schema, data, config, defs = {}) {
             switch (schema.format) {
                 case "singleton":
                     return {
-                        [schema.fieldTypes[0].name]: uplcToSchema(
+                        [schema.fieldTypes[0].name]: uplcToSchemaWithDataPath(
                             schema.fieldTypes[0].type,
                             data,
-                            config,
-                            defs
+                            { ...context, dataPath: `${dataPath}[sfStruct]` }
                         )
                     }
                 case "list": {
@@ -524,53 +601,83 @@ function uplcToSchema(schema, data, config, defs = {}) {
                     }
 
                     return Object.fromEntries(
-                        fields.map((field, i) => [
-                            schema.fieldTypes[i].name,
-                            uplcToSchema(
-                                schema.fieldTypes[i].type,
-                                field,
-                                config,
-                                defs
-                            )
-                        ])
+                        fields.map((field, i) => {
+                            // "field-list" structs don't have encoding-keys, by definition.
+                            const { name, type } = schema.fieldTypes[i]
+                            return [
+                                name,
+                                uplcToSchemaWithDataPath(type, field, {
+                                    ...context,
+                                    dataPath: `${dataPath}[fStruct].${name}`
+                                })
+                            ]
+                        })
                     )
                 }
                 case "map": {
-                    // wrapped in ConstrData
-                    const entries = MapData.expect(
-                        ConstrData.expect(data).fields[0]
-                    ).items
+                    // never uses a ConstrData (one MAY be used in the Enum layer, if needed)
+                    const encodedEntries = MapData.expect(data).items
 
-                    if (entries.length != schema.fieldTypes.length) {
+                    if (encodedEntries.length != schema.fieldTypes.length) {
                         throw new Error(
-                            `expected ${schema.fieldTypes.length} fields in struct, got ${entries.length} fields`
+                            `expected ${schema.fieldTypes.length} fields in struct, got ${encodedEntries.length} fields`
                         )
                     }
 
+                    /**
+                     * @param {string} targetName
+                     * @returns {number}
+                     */
+                    function findSerializedFieldIndex(targetName) {
+                        return encodedEntries.findIndex(([key, _]) => {
+                            return (
+                                targetName ==
+                                decodeUtf8(ByteArrayData.expect(key).bytes)
+                            )
+                        })
+                    }
+                    // loops over the Schema fields:
                     return Object.fromEntries(
                         schema.fieldTypes
-                            .map(({ name, type }) => {
+                            .map(({ name, type, key: encodingKey }) => {
                                 const i = expectSome(
-                                    entries.findIndex(
-                                        ([key, _]) =>
-                                            decodeUtf8(
-                                                ByteArrayData.expect(key).bytes
-                                            ) == name
+                                    findSerializedFieldIndex(
+                                        encodingKey || name
                                     )
                                 )
 
                                 if (i == -1) {
+                                    // todo: ? allow Option[T] fields to be missing?
+                                    if (encodingKey) {
+                                        if (
+                                            findSerializedFieldIndex(name) > -1
+                                        ) {
+                                            throw new Error(
+                                                `field '${name}' encoded by name (must be encoded as '${encodingKey}')`
+                                            )
+                                        }
+                                        throw new Error(
+                                            `field '${name}' missing (must be encoded as '${encodingKey}')`
+                                        )
+                                    }
                                     throw new Error(
-                                        `field ${name} not found in MapData`
+                                        `field '${name}' missing from field map`
                                     )
                                 }
 
-                                const pair = entries[i]
+                                const encodedDataPair = encodedEntries[i]
 
                                 return /** @type {const} */ ([
                                     i,
                                     name,
-                                    uplcToSchema(type, pair[1], config, defs)
+                                    uplcToSchemaWithDataPath(
+                                        type,
+                                        encodedDataPair[1],
+                                        {
+                                            ...context,
+                                            dataPath: `${dataPath}[mStruct].${name}`
+                                        }
+                                    )
                                 ])
                             })
                             .sort((a, b) => a[0] - b[0])
@@ -579,7 +686,7 @@ function uplcToSchema(schema, data, config, defs = {}) {
                 }
                 default:
                     throw new Error(
-                        `unhandled struct format '${schema.format}'`
+                        `unhandled struct format '${/** @type {any} */ (schema).format}'`
                     )
             }
         }
@@ -601,15 +708,18 @@ function uplcToSchema(schema, data, config, defs = {}) {
                 )
             }
 
+            const fieldCount = variantSchema.fieldTypes.length
             return {
                 [variantSchema.name]: Object.fromEntries(
                     fields.map((f, i) => [
                         variantSchema.fieldTypes[i].name,
-                        uplcToSchema(
+                        uplcToSchemaWithDataPath(
                             variantSchema.fieldTypes[i].type,
                             f,
-                            config,
-                            defs
+                            {
+                                ...context,
+                                dataPath: `${dataPath}[${schema.name}::${variantSchema.name}]`
+                            }
                         )
                     ])
                 )
@@ -622,7 +732,10 @@ function uplcToSchema(schema, data, config, defs = {}) {
             return Object.fromEntries(
                 fields.map((field, i) => [
                     schema.fieldTypes[i].name,
-                    uplcToSchema(schema.fieldTypes[i].type, field, config, defs)
+                    uplcToSchemaWithDataPath(schema.fieldTypes[i].type, field, {
+                        ...context,
+                        dataPath: `${dataPath}[enumVariant ${schema.id}].${schema.fieldTypes[i].name}`
+                    })
                 ])
             )
         }

package/src/cast/UserFunc.js

@@ -1,8 +1,7 @@
 import { bytesToHex } from "@helios-lang/codec-utils"
-import { expectSome, isLeft, isString } from "@helios-lang/type-utils"
-import { ConstrData, IntData, UplcDataValue } from "@helios-lang/uplc"
+import { expectSome, isLeft, isString, None } from "@helios-lang/type-utils"
+import { ConstrData, UplcDataValue, UplcRuntimeError } from "@helios-lang/uplc"
 import { Cast } from "./Cast.js"
-import { BasicUplcLogger } from "@helios-lang/uplc"
 
 /**
  * @typedef {import("@helios-lang/type-utils").TypeSchema} TypeSchema
@@ -15,6 +14,7 @@ import { BasicUplcLogger } from "@helios-lang/uplc"
  */
 
 /**
+ * TODO: add logOptions here as well (which can be overridden by logOptions passed directly to eval(), evalUnsafe() and profile())?
  * `returns` is optional to accomodate main functions that return void
  * @typedef {{
  *   name: string
@@ -72,10 +72,10 @@ export class UserFunc {
 
     /**
      * @param {ArgsT} namedArgs
-     * @param {UplcLoggingI} [logOptions]
+     * @param {Option<UplcLoggingI>} logOptions
      * @returns {RetT}
      */
-    eval(namedArgs, logOptions) {
+    eval(namedArgs, logOptions = None) {
         /**
          * @type {{[argName: string]: any}}
          */
@@ -119,22 +119,14 @@ export class UserFunc {
 
     /**
      * @param {UnsafeArgsT<ArgsT>} namedArgs
-     * @param {UplcLoggingI} [logOptions]
+     * @param {Option<UplcLoggingI>} logOptions
      * @returns {RetT extends void ? void : UplcData}
      */
-    evalUnsafe(namedArgs, logOptions) {
+    evalUnsafe(namedArgs, logOptions = None) {
         const result = this.profile(namedArgs, logOptions).result
 
         if (isLeft(result)) {
-            const stackTrace = result.left.callSites.map((s) => s.toString())
-
-            let msg = result.left.error
-
-            if (stackTrace.length > 0) {
-                msg = `Stack trace:\n    ${stackTrace.join("\n    ")}\n${msg}`
-            }
-
-            throw new Error(msg)
+            throw new UplcRuntimeError(result.left.error, result.left.callSites)
         } else if (!isString(result.right) && result.right.kind == "data") {
             return /** @type {any} */ (result.right.value)
         } else if (this.props.returns) {
@@ -146,10 +138,10 @@ export class UserFunc {
 
     /**
      * @param {UnsafeArgsT<ArgsT>} namedArgs
-     * @param {UplcLoggingI} [logOptions] - optional, passed to UplcProgram.eval if provided
+     * @param {Option<UplcLoggingI>} logOptions - optional, passed to UplcProgram.eval if provided
      * @returns {CekResult}
      */
-    profile(namedArgs, logOptions) {
+    profile(namedArgs, logOptions = None) {
         const isMain = this.name == "main"
 
         /**
@@ -198,11 +190,13 @@ export class UserFunc {
 
         const argValues = args.map((a) => new UplcDataValue(a))
 
-        const cekResult = this.uplc.eval(argValues, { logOptions })
+        const cekResult = this.uplc.eval(argValues, {
+            logOptions: logOptions ?? undefined
+        })
 
         if (this.uplc.alt?.plutusVersion == "PlutusScriptV2") {
             const cekResultUnoptim = this.uplc.alt.eval(argValues, {
-                logOptions
+                logOptions: logOptions ?? undefined
             })
             const resultUnoptim = cekResultUnoptim.result
             const resultUnoptimStr = evalResultToString(resultUnoptim)
@@ -243,6 +237,9 @@ export class UserFunc {
                     `Warning: optimizer didn't improve cost of ${this.props.name}`
                 )
             }
+
+            // overwrite the optimized cekResult.result with the unoptimized result because it contains more information
+            cekResult.result = resultUnoptim
         }
 
         return cekResult

package/src/codegen/TypeSchema.js

@@ -9,6 +9,8 @@ const NONE = "null"
  * @param {TypeSchema} schema
  * @returns {[string, string]} - the first entry is the strict canonical type, the second is the permissive type
  */
+// XXX * @param {string} [encodingKey] - optional field-name (encoding-key) for map-typed struct fields only
+// XXX export function genTypes(schema, encodingKey) {
 export function genTypes(schema) {
     const kind = schema.kind
 
@@ -126,10 +128,13 @@ export function genTypes(schema) {
             return [`(${c}) | ${NONE}`, `(${p}) | null | undefined`]
         }
         case "struct": {
-            const fieldTypes = schema.fieldTypes.map(({ name, type }) => ({
-                name: name,
-                types: genTypes(type)
-            }))
+            const fieldTypes = schema.fieldTypes.map(
+                ({ name, type /* key - not used for type */ }) => ({
+                    name: name,
+                    // .. the field's definition name is always used, not the encoding key
+                    types: genTypes(type)
+                })
+            )
 
             return [
                 `{${fieldTypes.map(({ name, types: [c, p] }) => `${name}: ${c}`).join(", ")}}`,
@@ -152,7 +157,7 @@ export function genTypes(schema) {
             ]
         }
         case "variant": {
-            // similar to structure
+            // similar to a list-typed struct (no encoding keys allowed)
             const fieldTypes = schema.fieldTypes.map(({ name, type }) => ({
                 name: name,
                 types: genTypes(type)

package/src/compiler/CompilerLib_v0_17.js

@@ -159,7 +159,7 @@ export class CompilerLib_v0_17 {
             cborHex: bytesToHex(uplc.toCbor()),
             plutusVersion: uplc.plutusVersion,
             sourceMap: sourceMap.toJsonSafe(),
-            ir: uplc.ir ?? undefined
+            ir: options.debug ? (uplc.ir ?? undefined) : undefined
         }
     }
 

package/src/context/ContractContextCache.js

@@ -5,9 +5,9 @@ import {
     StakingValidatorHash,
     ValidatorHash
 } from "@helios-lang/ledger"
-import { Cast } from "../cast/Cast.js"
 import { None, expectSome } from "@helios-lang/type-utils"
 import { UplcProgramV1, UplcProgramV2, UplcSourceMap } from "@helios-lang/uplc"
+import { Cast } from "../cast/Cast.js"
 
 /**
  * @typedef {import("@helios-lang/uplc").PlutusVersion} PlutusVersion

package/types/cast/Cast.d.ts

@@ -26,6 +26,17 @@ export function configureCast<TStrict, TPermissive>(cast: CastLike<TStrict, TPer
  * @template TPermissive
  * @typedef {Cast<TStrict, TPermissive> | ConfigurableCast<TStrict, TPermissive>} CastLike
  */
+/**
+ * @typedef {Object} SchemaToUplcContext
+ * @property {Record<string, TypeSchema>} defs - symbol table permitting recursive schema references
+ * @property {string} dataPath - provides developer-facing cues for any parsing errors, showing the deep field path of any error
+ */
+/**
+ * @typedef {Object} UplcToSchemaContext
+ * @property {Record<string, TypeSchema>} defs - symbol table permitting recursive schema references
+ * @property {string} dataPath - provides developer-facing cues for any parsing errors, showing the deep field path of any error
+ * @property {CastConfig} config - has isMainnet indicator
+ */
 /**
  * @template TStrict
  * @template TPermissive=TStrict
@@ -48,9 +59,10 @@ export class Cast<TStrict, TPermissive> {
     readonly config: CastConfig;
     /**
      * @param {UplcData} data
+     * @param {string} [dataPath] - can be used to indicate the kind or context of data-decoding
      * @returns {TStrict}
      */
-    fromUplcData(data: UplcData): TStrict;
+    fromUplcData(data: UplcData, dataPath?: string | undefined): TStrict;
     /**
      * converts javascript object to UPLC data, according to the schema.
      * @remarks
@@ -74,4 +86,28 @@ export type ConfigurableCast<TStrict, TPermissive> = (config: CastConfig) => Cas
  * StrictType and PermissiveType work for both Cast and ConfigurableCast
  */
 export type CastLike<TStrict, TPermissive> = Cast<TStrict, TPermissive> | ConfigurableCast<TStrict, TPermissive>;
+export type SchemaToUplcContext = {
+    /**
+     * - symbol table permitting recursive schema references
+     */
+    defs: Record<string, TypeSchema>;
+    /**
+     * - provides developer-facing cues for any parsing errors, showing the deep field path of any error
+     */
+    dataPath: string;
+};
+export type UplcToSchemaContext = {
+    /**
+     * - symbol table permitting recursive schema references
+     */
+    defs: Record<string, TypeSchema>;
+    /**
+     * - provides developer-facing cues for any parsing errors, showing the deep field path of any error
+     */
+    dataPath: string;
+    /**
+     * - has isMainnet indicator
+     */
+    config: CastConfig;
+};
 //# sourceMappingURL=Cast.d.ts.map

package/types/cast/Cast.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Cast.d.ts","sourceRoot":"","sources":["../../src/cast/Cast.js"],"names":[],"mappings":"AAynBA;;;;;;GAMG;AACH,8BANa,OAAO,EACP,WAAW,QACb,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,UAC9B,UAAU,GACR,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,CAQtC;AAjmBD;;;GAGG;AAEH;;;;GAIG;AAEH;;;;GAIG;AAEH;;;;;GAKG;AAEH;;;GAGG;AACH,kBAHa,OAAO,EACP,WAAW;IAepB;;;OAGG;IACH,oBAHW,UAAU,UACV,UAAU,EAKpB;IAnBD;;;OAGG;IACH,iBAFU,UAAU,CAEd;IAEN;;;OAGG;IACH,iBAFU,UAAU,CAEd;IAWN;;;OAGG;IACH,mBAHW,QAAQ,GACN,OAAO,CAInB;IAED;;;;;;;;;;OAUG;IACH,cAJW,WAAW,aACX,MAAM,GACJ,QAAQ,CAMpB;CACJ;uBAzEY,OAAO,mBAAmB,EAAE,QAAQ;yBACpC,OAAO,qBAAqB,EAAE,UAAU;yBAIxC;IACZ,SAAa,EAAE,OAAO,CAAA;CACnB;6BAIS,OAAO,EACP,WAAW,IACX,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC;;;;qBAKlD,OAAO,EACP,WAAW,IACX,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,GAAG,gBAAgB,CAAC,OAAO,EAAE,WAAW,CAAC"}
+{"version":3,"file":"Cast.d.ts","sourceRoot":"","sources":["../../src/cast/Cast.js"],"names":[],"mappings":"AA0uBA;;;;;;GAMG;AACH,8BANa,OAAO,EACP,WAAW,QACb,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,UAC9B,UAAU,GACR,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,CAQtC;AAltBD;;;GAGG;AAEH;;;;GAIG;AAEH;;;;GAIG;AAEH;;;;;GAKG;AAEH;;;;GAIG;AAEH;;;;;GAKG;AAEH;;;GAGG;AACH,kBAHa,OAAO,EACP,WAAW;IAepB;;;OAGG;IACH,oBAHW,UAAU,UACV,UAAU,EAKpB;IAnBD;;;OAGG;IACH,iBAFU,UAAU,CAEd;IAEN;;;OAGG;IACH,iBAFU,UAAU,CAEd;IAWN;;;;OAIG;IACH,mBAJW,QAAQ,kCAEN,OAAO,CAQnB;IAED;;;;;;;;;;OAUG;IACH,cAJW,WAAW,aACX,MAAM,GACJ,QAAQ,CASpB;CACJ;uBA9FY,OAAO,mBAAmB,EAAE,QAAQ;yBACpC,OAAO,qBAAqB,EAAE,UAAU;yBAIxC;IACZ,SAAa,EAAE,OAAO,CAAA;CACnB;6BAIS,OAAO,EACP,WAAW,IACX,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC;;;;qBAKlD,OAAO,EACP,WAAW,IACX,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,GAAG,gBAAgB,CAAC,OAAO,EAAE,WAAW,CAAC;;;;;UAKlE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC;;;;cAC1B,MAAM;;;;;;UAKN,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC;;;;cAC1B,MAAM;;;;YACN,UAAU"}

package/types/cast/UserFunc.d.ts

@@ -8,6 +8,7 @@
  * @typedef {import("./Cast.js").CastConfig} CastConfig
  */
 /**
+ * TODO: add logOptions here as well (which can be overridden by logOptions passed directly to eval(), evalUnsafe() and profile())?
  * `returns` is optional to accomodate main functions that return void
  * @typedef {{
  *   name: string
@@ -56,22 +57,22 @@ export class UserFunc<ArgsT extends {
     get name(): string;
     /**
      * @param {ArgsT} namedArgs
-     * @param {UplcLoggingI} [logOptions]
+     * @param {Option<UplcLoggingI>} logOptions
      * @returns {RetT}
      */
-    eval(namedArgs: ArgsT, logOptions?: import("@helios-lang/uplc/types/logging/UplcLoggingI.js").UplcLoggingI | undefined): RetT;
+    eval(namedArgs: ArgsT, logOptions?: Option<UplcLoggingI>): RetT;
     /**
      * @param {UnsafeArgsT<ArgsT>} namedArgs
-     * @param {UplcLoggingI} [logOptions]
+     * @param {Option<UplcLoggingI>} logOptions
      * @returns {RetT extends void ? void : UplcData}
      */
-    evalUnsafe(namedArgs: UnsafeArgsT<ArgsT>, logOptions?: import("@helios-lang/uplc/types/logging/UplcLoggingI.js").UplcLoggingI | undefined): RetT extends void ? void : UplcData;
+    evalUnsafe(namedArgs: UnsafeArgsT<ArgsT>, logOptions?: Option<UplcLoggingI>): RetT extends void ? void : UplcData;
     /**
      * @param {UnsafeArgsT<ArgsT>} namedArgs
-     * @param {UplcLoggingI} [logOptions] - optional, passed to UplcProgram.eval if provided
+     * @param {Option<UplcLoggingI>} logOptions - optional, passed to UplcProgram.eval if provided
      * @returns {CekResult}
      */
-    profile(namedArgs: UnsafeArgsT<ArgsT>, logOptions?: import("@helios-lang/uplc/types/logging/UplcLoggingI.js").UplcLoggingI | undefined): CekResult;
+    profile(namedArgs: UnsafeArgsT<ArgsT>, logOptions?: Option<UplcLoggingI>): CekResult;
 }
 export type TypeSchema = import("@helios-lang/type-utils").TypeSchema;
 export type CekResult = import("@helios-lang/uplc").CekResult;
@@ -81,6 +82,7 @@ export type UplcProgram = import("@helios-lang/uplc").UplcProgram;
 export type UplcValue = import("@helios-lang/uplc").UplcValue;
 export type CastConfig = import("./Cast.js").CastConfig;
 /**
+ * TODO: add logOptions here as well (which can be overridden by logOptions passed directly to eval(), evalUnsafe() and profile())?
  * `returns` is optional to accomodate main functions that return void
  */
 export type UserFuncProps = {

package/types/cast/UserFunc.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"UserFunc.d.ts","sourceRoot":"","sources":["../../src/cast/UserFunc.js"],"names":[],"mappings":"AAMA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;;GAeG;AAEH;;;GAGG;AAEH;;;GAGG;AACH,sBAHwC,KAAK,SAAhC;IAAE,CAAC,OAAO,EAAE,MAAM,GAAG,GAAG,CAAA;CAAE,EAC1B,IAAI;IAgBb;;;OAGG;IACH,kBAHW,WAAW,SACX,aAAa,EAKvB;IApBD;;;OAGG;IACH,eAFU,WAAW,CAEjB;IAEJ;;;;OAIG;IACH,uBAAK;IAWL;;OAEG;IACH,mBAEC;IAED;;;;OAIG;IACH,gBAJW,KAAK,oGAEH,IAAI,CA0ChB;IAED;;;;OAIG;IACH,sBAJW,WAAW,CAAC,KAAK,CAAC,oGAEhB,IAAI,SAAS,IAAI,GAAG,IAAI,GAAG,QAAQ,CAsB/C;IAED;;;;OAIG;IACH,mBAJW,WAAW,CAAC,KAAK,CAAC,oGAEhB,SAAS,CAmGrB;CACJ;yBAlPY,OAAO,yBAAyB,EAAE,UAAU;wBAC5C,OAAO,mBAAmB,EAAE,SAAS;uBACrC,OAAO,mBAAmB,EAAE,QAAQ;2BACpC,OAAO,mBAAmB,EAAE,YAAY;0BACxC,OAAO,mBAAmB,EAAE,WAAW;wBACvC,OAAO,mBAAmB,EAAE,SAAS;yBACrC,OAAO,WAAW,EAAE,UAAU;;;;4BAK9B;IACZ,IAAQ,EAAE,MAAM,CAAA;IAChB,qBAAyB,EAAE,OAAO,CAAA;IAClC,qBAAyB,EAAE,OAAO,CAAA;IAClC,SAAa,EAAE;QACf,IAAU,EAAE,MAAM,CAAA;QAClB,IAAU,EAAE,UAAU,CAAA;QACtB,UAAgB,EAAE,OAAO,CAAA;KACpB,EAAE,CAAA;IACP,OAAW,CAAC,EAAE,UAAU,CAAA;IACxB,gBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC7C,UAAc,EAAE,UAAU,CAAA;CACvB;wBAIS,KAAK,IACL,GAAE,CAAgB,IAAX,MAAM,KAAK,GAAG,CAAC,SAAS,gBAAgB,GAAG,MAAM,GAAG,QAAQ,GAAC"}
+{"version":3,"file":"UserFunc.d.ts","sourceRoot":"","sources":["../../src/cast/UserFunc.js"],"names":[],"mappings":"AAKA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;;;GAgBG;AAEH;;;GAGG;AAEH;;;GAGG;AACH,sBAHwC,KAAK,SAAhC;IAAE,CAAC,OAAO,EAAE,MAAM,GAAG,GAAG,CAAA;CAAE,EAC1B,IAAI;IAgBb;;;OAGG;IACH,kBAHW,WAAW,SACX,aAAa,EAKvB;IApBD;;;OAGG;IACH,eAFU,WAAW,CAEjB;IAEJ;;;;OAIG;IACH,uBAAK;IAWL;;OAEG;IACH,mBAEC;IAED;;;;OAIG;IACH,gBAJW,KAAK,eACL,MAAM,CAAC,YAAY,CAAC,GAClB,IAAI,CA0ChB;IAED;;;;OAIG;IACH,sBAJW,WAAW,CAAC,KAAK,CAAC,eAClB,MAAM,CAAC,YAAY,CAAC,GAClB,IAAI,SAAS,IAAI,GAAG,IAAI,GAAG,QAAQ,CAc/C;IAED;;;;OAIG;IACH,mBAJW,WAAW,CAAC,KAAK,CAAC,eAClB,MAAM,CAAC,YAAY,CAAC,GAClB,SAAS,CAwGrB;CACJ;yBAhPY,OAAO,yBAAyB,EAAE,UAAU;wBAC5C,OAAO,mBAAmB,EAAE,SAAS;uBACrC,OAAO,mBAAmB,EAAE,QAAQ;2BACpC,OAAO,mBAAmB,EAAE,YAAY;0BACxC,OAAO,mBAAmB,EAAE,WAAW;wBACvC,OAAO,mBAAmB,EAAE,SAAS;yBACrC,OAAO,WAAW,EAAE,UAAU;;;;;4BAM9B;IACZ,IAAQ,EAAE,MAAM,CAAA;IAChB,qBAAyB,EAAE,OAAO,CAAA;IAClC,qBAAyB,EAAE,OAAO,CAAA;IAClC,SAAa,EAAE;QACf,IAAU,EAAE,MAAM,CAAA;QAClB,IAAU,EAAE,UAAU,CAAA;QACtB,UAAgB,EAAE,OAAO,CAAA;KACpB,EAAE,CAAA;IACP,OAAW,CAAC,EAAE,UAAU,CAAA;IACxB,gBAAoB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC7C,UAAc,EAAE,UAAU,CAAA;CACvB;wBAIS,KAAK,IACL,GAAE,CAAgB,IAAX,MAAM,KAAK,GAAG,CAAC,SAAS,gBAAgB,GAAG,MAAM,GAAG,QAAQ,GAAC"}

package/types/codegen/TypeSchema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TypeSchema.d.ts","sourceRoot":"","sources":["../../src/codegen/TypeSchema.js"],"names":[],"mappings":"AAMA;;;;GAIG;AACH,iCAHW,UAAU,GACR,CAAC,MAAM,EAAE,MAAM,CAAC,CAiK5B;yBAzKY,OAAO,yBAAyB,EAAE,UAAU"}
+{"version":3,"file":"TypeSchema.d.ts","sourceRoot":"","sources":["../../src/codegen/TypeSchema.js"],"names":[],"mappings":"AAMA;;;;GAIG;AAGH,iCALW,UAAU,GACR,CAAC,MAAM,EAAE,MAAM,CAAC,CAsK5B;yBA9KY,OAAO,yBAAyB,EAAE,UAAU"}