@helios-lang/contract-utils 0.3.5 → 0.3.7

package/src/cast/UserFunc.js

@@ -37,7 +37,6 @@ class UserFuncImpl {
     uplc
 
     /**
-     * @private
      * @readonly
      * @type {UserFuncProps}
      */
@@ -65,45 +64,7 @@ class UserFuncImpl {
      * @returns {RetT}
      */
     eval(namedArgs, logOptions = undefined) {
-        /**
-         * @type {{[argName: string]: any}}
-         */
-        const unsafeNamedArgs = {}
-
-        Object.entries(namedArgs).forEach(([argName, argValue]) => {
-            const argDetails = this.props.arguments.find(
-                (a) => a.name == argName
-            )
-
-            if (argDetails) {
-                const typeSchema = argDetails.type
-
-                unsafeNamedArgs[argName] = makeCast(
-                    typeSchema,
-                    this.props.castConfig
-                ).toUplcData(argValue)
-            } else if (["$currentScript", "$scriptContext"].includes(argName)) {
-                unsafeNamedArgs[argName] = argValue
-            } else {
-                console.error(
-                    `invalid arg '${argName}' for user function ${this.props.name}`
-                )
-            }
-        })
-
-        const result = this.evalUnsafe(
-            /** @type {UnsafeArgsT<ArgsT>} */ (unsafeNamedArgs),
-            logOptions
-        )
-
-        if (this.props.returns) {
-            return makeCast(
-                this.props.returns,
-                this.props.castConfig
-            ).fromUplcData(expectDefined(/** @type {any} */ (result)))
-        } else {
-            return /** @type {any} */ (undefined)
-        }
+        return evalUserFunc(this.uplc, this.props, namedArgs, logOptions)
     }
 
     /**
@@ -112,17 +73,7 @@ class UserFuncImpl {
      * @returns {RetT extends void ? void : UplcData}
      */
     evalUnsafe(namedArgs, logOptions = undefined) {
-        const result = this.profile(namedArgs, logOptions).result
-
-        if (isLeft(result)) {
-            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) {
-            throw new Error(`${result.right.toString()} isn't a UplcDataValue`)
-        } else {
-            return /** @type {any} */ (undefined)
-        }
+        return evalUserFuncUnsafe(this.uplc, this.props, namedArgs, logOptions)
     }
 
     /**
@@ -131,108 +82,208 @@ class UserFuncImpl {
      * @returns {CekResult}
      */
     profile(namedArgs, logOptions = undefined) {
-        const isMain = this.name == "main"
-
-        /**
-         * @type {UplcData[]}
-         */
-        const args = []
-
-        this.props.arguments.forEach(({ name, type, isOptional }) => {
-            if (isMain) {
-                if (isOptional) {
-                    // used for $datum in mixed script
-                    if (name in namedArgs && namedArgs[name]) {
-                        args.push(namedArgs[name])
-                    }
-                } else {
-                    args.push(expectDefined(namedArgs[name]))
+        return profileUserFunc(this.uplc, this.props, namedArgs, logOptions)
+    }
+}
+
+/**
+ * @template {{[argName: string]: any}} ArgsT
+ * @template RetT
+ * @param {UplcProgram} program
+ * @param {UserFuncProps} props
+ * @param {ArgsT} namedArgs
+ * @param {UplcLogger | undefined} logOptions
+ * @returns {RetT}
+ */
+export function evalUserFunc(
+    program,
+    props,
+    namedArgs,
+    logOptions = undefined
+) {
+    /**
+     * @type {{[argName: string]: any}}
+     */
+    const unsafeNamedArgs = {}
+
+    Object.entries(namedArgs).forEach(([argName, argValue]) => {
+        const argDetails = props.arguments.find((a) => a.name == argName)
+
+        if (argDetails) {
+            const typeSchema = argDetails.type
+
+            unsafeNamedArgs[argName] = makeCast(
+                typeSchema,
+                props.castConfig
+            ).toUplcData(argValue)
+        } else if (["$currentScript", "$scriptContext"].includes(argName)) {
+            unsafeNamedArgs[argName] = argValue
+        } else {
+            console.error(
+                `invalid arg '${argName}' for user function ${props.name}`
+            )
+        }
+    })
+
+    const result = evalUserFuncUnsafe(
+        program,
+        props,
+        /** @type {UnsafeArgsT<ArgsT>} */ (unsafeNamedArgs),
+        logOptions
+    )
+
+    if (props.returns) {
+        return makeCast(props.returns, props.castConfig).fromUplcData(
+            expectDefined(/** @type {any} */ (result))
+        )
+    } else {
+        return /** @type {any} */ (undefined)
+    }
+}
+
+/**
+ * @template {{[argName: string]: any}} ArgsT
+ * @template RetT
+ * @param {UplcProgram} program
+ * @param {UserFuncProps} props
+ * @param {UnsafeArgsT<ArgsT>} namedArgs
+ * @param {UplcLogger | undefined} logOptions
+ * @returns {RetT extends void ? void : UplcData}
+ */
+export function evalUserFuncUnsafe(
+    program,
+    props,
+    namedArgs,
+    logOptions = undefined
+) {
+    const result = profileUserFunc(program, props, namedArgs, logOptions).result
+
+    if (isLeft(result)) {
+        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 (props.returns) {
+        throw new Error(`${result.right.toString()} isn't a UplcDataValue`)
+    } else {
+        return /** @type {any} */ (undefined)
+    }
+}
+
+/**
+ * @template {{[argName: string]: any}} ArgsT
+ * @param {UplcProgram} program
+ * @param {UserFuncProps} props
+ * @param {UnsafeArgsT<ArgsT>} namedArgs
+ * @param {UplcLogger | undefined} logOptions - optional, passed to UplcProgram.eval if provided
+ * @returns {CekResult}
+ */
+export function profileUserFunc(
+    program,
+    props,
+    namedArgs,
+    logOptions = undefined
+) {
+    const isMain = props.name == "main"
+
+    /**
+     * @type {UplcData[]}
+     */
+    const args = []
+
+    props.arguments.forEach(({ name, type, isOptional }) => {
+        if (isMain) {
+            if (isOptional) {
+                // used for $datum in mixed script
+                if (name in namedArgs && namedArgs[name]) {
+                    args.push(namedArgs[name])
                 }
             } else {
-                if (isOptional) {
-                    if (name in namedArgs && namedArgs[name]) {
-                        args.push(makeConstrData(0, [namedArgs[name]]))
-                    } else {
-                        args.push(makeConstrData(1, []))
-                    }
+                args.push(expectDefined(namedArgs[name]))
+            }
+        } else {
+            if (isOptional) {
+                if (name in namedArgs && namedArgs[name]) {
+                    args.push(makeConstrData(0, [namedArgs[name]]))
                 } else {
-                    args.push(expectDefined(namedArgs[name]))
+                    args.push(makeConstrData(1, []))
                 }
+            } else {
+                args.push(expectDefined(namedArgs[name]))
             }
-        })
-
-        if (this.props.requiresScriptContext) {
-            args.push(expectDefined(namedArgs["$scriptContext"]))
         }
+    })
 
-        if (this.props.requiresCurrentScript) {
-            const currentScriptName = expectDefined(
-                /** @type {any} */ (namedArgs)["$currentScript"]
-            )
+    if (props.requiresScriptContext) {
+        args.push(expectDefined(namedArgs["$scriptContext"]))
+    }
 
-            const index = expectDefined(
-                expectDefined(this.props.validatorIndices)[currentScriptName]
-            )
+    if (props.requiresCurrentScript) {
+        const currentScriptName = expectDefined(
+            /** @type {any} */ (namedArgs)["$currentScript"]
+        )
 
-            args.push(makeConstrData(index, []))
-        }
+        const index = expectDefined(
+            expectDefined(props.validatorIndices)[currentScriptName]
+        )
+
+        args.push(makeConstrData(index, []))
+    }
 
-        const argValues = args.map((a) => makeUplcDataValue(a))
+    const argValues = args.map((a) => makeUplcDataValue(a))
 
-        const cekResult = this.uplc.eval(argValues, {
+    const cekResult = program.eval(argValues, {
+        logOptions: logOptions ?? undefined
+    })
+
+    if (program.alt?.plutusVersion == "PlutusScriptV2") {
+        const cekResultUnoptim = program.alt.eval(argValues, {
             logOptions: logOptions ?? undefined
         })
+        const resultUnoptim = cekResultUnoptim.result
+        const resultUnoptimStr = evalResultToString(resultUnoptim)
+        const resultStr = evalResultToString(cekResult.result)
+
+        if (resultStr != resultUnoptimStr) {
+            console.error(
+                `## Unoptimized IR:\n${program.alt.ir ?? "not available"}`
+            )
 
-        if (this.uplc.alt?.plutusVersion == "PlutusScriptV2") {
-            const cekResultUnoptim = this.uplc.alt.eval(argValues, {
-                logOptions: logOptions ?? undefined
+            args.forEach((a, i) => {
+                console.error(`## Arg ${i}: ${bytesToHex(a.toCbor())}`)
             })
-            const resultUnoptim = cekResultUnoptim.result
-            const resultUnoptimStr = evalResultToString(resultUnoptim)
-            const resultStr = evalResultToString(cekResult.result)
-
-            if (resultStr != resultUnoptimStr) {
-                console.error(
-                    `## Unoptimized IR:\n${this.uplc.alt.ir ?? "not available"}`
-                )
-
-                args.forEach((a, i) => {
-                    console.error(`## Arg ${i}: ${bytesToHex(a.toCbor())}`)
-                })
-
-                throw new Error(
-                    `Critical error: expected ${resultUnoptimStr}, but got ${resultStr}. Contact Helios maintainers and share this console output`
-                )
-            }
 
-            // also make sure the cost is an improvement
-            if (cekResult.cost.mem > cekResultUnoptim.cost.mem) {
-                throw new Error(
-                    `Critical error: optimizer worsened memory cost of ${this.props.name}`
-                )
-            }
+            throw new Error(
+                `Critical error: expected ${resultUnoptimStr}, but got ${resultStr}. Contact Helios maintainers and share this console output`
+            )
+        }
 
-            if (cekResult.cost.cpu > cekResultUnoptim.cost.cpu) {
-                throw new Error(
-                    `Critical error: optimizer worsened cpu cost of ${this.props.name}`
-                )
-            }
+        // also make sure the cost is an improvement
+        if (cekResult.cost.mem > cekResultUnoptim.cost.mem) {
+            throw new Error(
+                `Critical error: optimizer worsened memory cost of ${props.name}`
+            )
+        }
 
-            if (
-                cekResult.cost.mem == cekResultUnoptim.cost.mem &&
-                cekResult.cost.cpu == cekResultUnoptim.cost.cpu
-            ) {
-                console.error(
-                    `Warning: optimizer didn't improve cost of ${this.props.name}`
-                )
-            }
+        if (cekResult.cost.cpu > cekResultUnoptim.cost.cpu) {
+            throw new Error(
+                `Critical error: optimizer worsened cpu cost of ${props.name}`
+            )
+        }
 
-            // overwrite the optimized cekResult.result with the unoptimized result because it contains more information
-            cekResult.result = resultUnoptim
+        if (
+            cekResult.cost.mem == cekResultUnoptim.cost.mem &&
+            cekResult.cost.cpu == cekResultUnoptim.cost.cpu
+        ) {
+            console.error(
+                `Warning: optimizer didn't improve cost of ${props.name}`
+            )
         }
 
-        return cekResult
+        // overwrite the optimized cekResult.result with the unoptimized result because it contains more information
+        cekResult.result = resultUnoptim
     }
+
+    return cekResult
 }
 
 /**

package/src/cast/index.js

@@ -1,3 +1,12 @@
-export { makeCast } from "./Cast.js"
-export { configureCast } from "./Cast.js"
-export { makeUserFunc } from "./UserFunc.js"
+export {
+    configureCast,
+    convertFromUplcData,
+    convertToUplcData,
+    makeCast
+} from "./Cast.js"
+export {
+    evalUserFunc,
+    evalUserFuncUnsafe,
+    makeUserFunc,
+    profileUserFunc
+} from "./UserFunc.js"

package/src/codegen/LoadedScriptsWriter.js

@@ -134,9 +134,8 @@ class LoadedScriptsWriterImpl {
      * @returns {LoadedScriptsWriter}
      */
     writeImportType(path, ...typeNames) {
-        this.definition.writeLine("/**")
-
         this.definition
+            .writeLine("/**")
             .writeLine(` * @import { ${typeNames.join(", ")} } from "${path}";`)
             .writeLine(" */")
         ;[this.declaration, this.combined].forEach((w) => {
@@ -389,29 +388,54 @@ ${datumTypes ? `    $Datum: (config: CastConfig) => makeCast<${datumTypes[0]}, $
 }
 
 /**
- * @param {TypeCheckedUserFunc} fn
- * @returns {[string, string]}
+ * @param {TypeCheckedUserFunc} props
+ * @param {boolean} unsafe
+ * @returns {string}
+ */
+export function genUserFuncRetType(props, unsafe = false) {
+    const retTypeStr = props?.returns ? genTypes(props.returns)[0] : "void"
+
+    if (unsafe) {
+        return retTypeStr == "void" ? "void" : "UplcData"
+    } else {
+        return retTypeStr
+    }
+}
+
+/**
+ * @param {TypeCheckedUserFunc} props
+ * @param {boolean} [unsafe]
+ * @returns {string}
  */
-function genFuncType(fn) {
+export function genUserFuncArgsType(props, unsafe = false) {
     /**
      * @type {string[]}
      */
     const fields = []
 
-    if (fn.requiresScriptContext) {
+    if (props.requiresScriptContext) {
         fields.push("$scriptContext: UplcData")
     }
 
-    if (fn.requiresCurrentScript) {
+    if (props.requiresCurrentScript) {
         fields.push("$currentScript: string")
     }
 
-    fn.arguments.forEach(({ name, type, isOptional }, i) => {
-        fields.push(`${name}${isOptional ? "?" : ""}: ${genTypes(type)[1]}`)
+    props.arguments.forEach(({ name, type, isOptional }, i) => {
+        fields.push(
+            `${name}${isOptional ? "?" : ""}: ${unsafe ? "UplcData" : genTypes(type)[1]}`
+        )
     })
 
     const argsTypeStr = `{${fields.join(", ")}}`
-    const retTypeStr = fn?.returns ? genTypes(fn.returns)[0] : "void"
 
-    return [argsTypeStr, retTypeStr]
+    return argsTypeStr
+}
+
+/**
+ * @param {TypeCheckedUserFunc} fn
+ * @returns {[string, string]}
+ */
+export function genFuncType(fn) {
+    return [genUserFuncArgsType(fn, false), genUserFuncRetType(fn)]
 }

package/src/codegen/TypeSchema.js

@@ -166,3 +166,129 @@ export function genTypes(schema) {
             throw new Error(`unhandled TypeSchema kind '${kind}'`)
     }
 }
+
+/**
+ * @param {TypeSchema} schema
+ * @returns {Map<string, string>} - key=name, value=from
+ */
+export function collectBuiltinTypes(schema) {
+    /**
+     * @type {Map<string, string>}
+     */
+    const m = new Map()
+
+    collectBuiltinTypesInternal(schema, m)
+
+    return m
+}
+
+/**
+ * @param {TypeSchema} schema
+ * @param {Map<string, string>} m - key=name, value=from
+ */
+function collectBuiltinTypesInternal(schema, m) {
+    const kind = schema.kind
+
+    switch (kind) {
+        case "internal":
+            const name = schema.name
+            switch (name) {
+                case "Bool":
+                case "ByteArray":
+                case "Real":
+                case "String":
+                    break
+                case "AssetClass":
+                    m.set("AssetClass", "@helios-lang/ledger")
+                    m.set("MintingPolicyHash", "@helios-lang/ledger")
+                    break
+                case "Any":
+                case "Data":
+                    m.set("UplcData", "@helios-lang/uplc")
+                    break
+                case "Int":
+                case "Duration":
+                case "Ratio":
+                    m.set("IntLike", "@helios-lang/codec-utils")
+                    break
+                case "Time":
+                    m.set("TimeLike", "@helios-lang/ledger")
+                    break
+                case "Address":
+                case "MintingPolicyHash":
+                case "PubKey":
+                case "PubKeyHash":
+                case "SpendingCredential":
+                case "StakingCredential":
+                case "StakingValidatorHash":
+                case "TimeLike":
+                case "TxId":
+                case "TxInput":
+                case "TxOutput":
+                case "TxOutputId":
+                case "ValidatorHash":
+                    m.set(name, "@helios-lang/ledger")
+                    break
+                case "StakingHash":
+                    // TODO: implement this
+                    return ["never", "never"]
+                case "TimeRange":
+                    m.set("TimeRange", "@helios-lang/ledger")
+                    m.set("TimeLike", "@helios-lang/ledger")
+                    break
+                case "TxOutputDatum":
+                    m.set("TxOutputDatum", "@helios-lang/ledger")
+                    m.set("DatumHash", "@helios-lang/ledger")
+                    m.set("UplcData", "@helios-lang/uplc")
+                    break
+                case "Value":
+                    m.set("Value", "@helios-lang/ledger")
+                    m.set("IntLike", "@helios-lang/codec-utils")
+                    m.set("MintingPolicyHash", "@helios-lang/ledger")
+                    break
+                default:
+                    throw new Error(`unhandled primitive '${name}' in hl2ts`)
+            }
+            break
+        case "list": {
+            collectBuiltinTypesInternal(schema.itemType, m)
+            break
+        }
+        case "map": {
+            collectBuiltinTypesInternal(schema.keyType, m)
+            collectBuiltinTypesInternal(schema.valueType, m)
+            break
+        }
+        case "tuple": {
+            schema.itemTypes.forEach((it) => collectBuiltinTypesInternal(it, m))
+            break
+        }
+        case "option": {
+            collectBuiltinTypesInternal(schema.someType, m)
+            break
+        }
+        case "struct": {
+            schema.fieldTypes.forEach(({ type }) => {
+                collectBuiltinTypesInternal(type, m)
+            })
+            break
+        }
+        case "enum": {
+            schema.variantTypes.forEach((variant) => {
+                collectBuiltinTypesInternal(variant, m)
+            })
+            break
+        }
+        case "variant": {
+            schema.fieldTypes.forEach(({ type }) => {
+                collectBuiltinTypesInternal(type, m)
+            })
+
+            break
+        }
+        case "reference":
+            throw new Error("recursive data structures not yet handled")
+        default:
+            throw new Error(`unhandled TypeSchema kind '${kind}'`)
+    }
+}

package/src/context/index.js

@@ -1,2 +1,3 @@
 export { makeContractContextBuilder } from "./ContractContextBuilder.js"
+
 export { contractContextCache } from "./ContractContextCache.js"

package/src/hl2ts.js

@@ -13,10 +13,6 @@ import { makeLoadedScriptsWriter } from "./codegen/index.js"
 import { loadCompilerLib } from "./compiler/index.js"
 import { typeCheckFiles } from "./compiler/ops.js"
 
-/**
- * @import { CompilerLib, TypeCheckedModule, TypeCheckedValidator } from "./index.js"
- */
-
 /**
  * @typedef {{
  *   name: string