@helios-lang/contract-utils 0.3.5 → 0.3.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helios-lang/contract-utils",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "Convenience and type-safety utilities for using Helios validators from within Typescript",
   "main": "src/index.js",
   "types": "types/index.d.ts",

package/src/artifacts/Artifact.js

@@ -0,0 +1,14 @@
+/**
+ * @import { FileSystem } from "../index.js"
+ */
+
+/**
+ * @typedef {object} Artifact
+ * @prop {string} dir
+ * @prop {FileSystem} fs
+ * @prop {boolean} isMainnet
+ * @prop {(line: string) => void} writeDeclLine
+ * @prop {(line: string) => void} writeDefLine
+ * @prop {(name: string) => void} writeAggregateExport
+ * @prop {() => void} save
+ */

package/src/artifacts/ArtifactWriter.js

@@ -0,0 +1,199 @@
+import { makeStringWriter } from "@helios-lang/codec-utils"
+import { expectDefined } from "@helios-lang/type-utils"
+
+/**
+ * @import { StringWriter } from "@helios-lang/codec-utils"
+ * @import { FileSystem } from "../index.js"
+ */
+
+export class ArtifactWriter {
+    /**
+     * @readonly
+     * @type {FileSystem}
+     */
+    fs
+
+    /**
+     * @readonly
+     * @type {string}
+     */
+    dir
+
+    /**
+     * @private
+     * @type {StringWriter}
+     */
+    decl
+
+    /**
+     * @private
+     * @type {StringWriter}
+     */
+    def
+
+    /**
+     * @private
+     * @type {[string, string, boolean][]}
+     */
+    imports
+
+    /**
+     * @param {FileSystem} fs
+     * @param {string} dir
+     */
+    constructor(fs, dir) {
+        this.fs = fs
+        this.dir = dir
+
+        this.decl = makeStringWriter()
+        this.def = makeStringWriter()
+        this.imports = []
+    }
+
+    /**
+     * @param {string} name
+     * @param {string} from
+     * @param {boolean} [isType]
+     * @returns {ArtifactWriter}
+     */
+    addImport(name, from, isType = false) {
+        this.imports.push([name, from, isType])
+        return this
+    }
+
+    /**
+     * @param {string} line
+     * @returns {ArtifactWriter}
+     */
+    writeDeclLine(line) {
+        this.decl.writeLine(line)
+        return this
+    }
+
+    /**
+     * @param {string} line
+     * @returns {ArtifactWriter}
+     */
+    writeDefLine(line) {
+        this.def.writeLine(line)
+        return this
+    }
+
+    /**
+     * @param {string} name
+     * @returns {ArtifactWriter}
+     */
+    writeAggregateExport(name) {
+        return this.writeDeclLine(
+            `export * as ${name} from "./${name}/index.js"`
+        ).writeDefLine(`export * as ${name} from "./${name}/index.js"`)
+    }
+
+    /**
+     * Write the .d.ts and .js files to the FS
+     */
+    save() {
+        this.fs.mkdirSync(this.dir, { recursive: true })
+
+        let declString = this.decl.finalize()
+        let defString = this.def.finalize()
+
+        if (this.imports.length > 0) {
+            const imps = groupImports(this.imports)
+
+            const declImp = makeStringWriter()
+            const defImp = makeStringWriter()
+
+            for (let imp of imps) {
+                const { from, typeSymbols, defSymbols } = imp
+
+                if (typeSymbols.length == 1) {
+                    declImp.writeLine(
+                        `import type { ${typeSymbols[0]} } from "${from}"`
+                    )
+                } else if (typeSymbols.length > 1) {
+                    declImp.writeLine(`import type {`)
+
+                    typeSymbols.forEach((s, i) => {
+                        declImp.writeLine(
+                            `    ${s}${i < typeSymbols.length - 1 ? "," : ""}`
+                        )
+                    })
+
+                    declImp.writeLine(`} from "${from}"`)
+                }
+
+                if (defSymbols.length == 1) {
+                    defImp.writeLine(
+                        `import { ${defSymbols[0]} } from "${from}"`
+                    )
+                } else if (defSymbols.length > 1) {
+                    defImp.writeLine(`import {`)
+
+                    defSymbols.forEach((s, i) => {
+                        defImp.writeLine(
+                            `    ${s}${i < defSymbols.length - 1 ? "," : ""}`
+                        )
+                    })
+
+                    defImp.writeLine(`} from "${from}"`)
+                }
+            }
+
+            const declImports = declImp.finalize()
+            const defImports = defImp.finalize()
+
+            if (declImports.length > 0) {
+                declString = `${declImports}\n${declString}`
+            }
+
+            if (defImports.length > 0) {
+                defString = `${defImports}\n${defString}`
+            }
+        }
+
+        this.fs.writeFileSync(`${this.dir}/index.d.ts`, declString)
+        this.fs.writeFileSync(`${this.dir}/index.js`, defString)
+    }
+}
+
+/**
+ * @param {[string, string, boolean][]} imports
+ * @returns {{from: string, typeSymbols: string[], defSymbols: string[]}[]}
+ */
+function groupImports(imports) {
+    /**
+     * @type {Map<string, {name: string, isType: boolean}[]>}
+     */
+    const m = new Map()
+
+    for (let imp of imports) {
+        const [name, from, isType] = imp
+
+        const prev = m.get(from)
+
+        if (prev) {
+            prev.push({ name, isType })
+        } else {
+            m.set(from, [{ name, isType }])
+        }
+    }
+
+    const keys = Array.from(m.keys()).sort()
+
+    return keys.map((key) => {
+        const symbols = expectDefined(m.get(key))
+
+        return {
+            from: key,
+            typeSymbols: symbols
+                .filter((symbol) => symbol.isType)
+                .sort((a, b) => a.name.localeCompare(b.name))
+                .map((symbol) => symbol.name),
+            defSymbols: symbols
+                .filter((symbol) => !symbol.isType)
+                .sort((a, b) => a.name.localeCompare(b.name))
+                .map((symbol) => symbol.name)
+        }
+    })
+}

package/src/artifacts/ChildArtifactWriter.js

@@ -0,0 +1,118 @@
+import { bytesToHex } from "@helios-lang/codec-utils"
+import { makeUplcSourceMap } from "@helios-lang/uplc"
+import { ArtifactWriter } from "./ArtifactWriter.js"
+
+/**
+ * @import { UplcProgram } from "@helios-lang/uplc"
+ * @import { Artifact } from "./Artifact.js"
+ */
+
+export class ChildArtifactWriter extends ArtifactWriter {
+    /**
+     * @readonly
+     * @type {Artifact}
+     */
+    parent
+
+    /**
+     * @readonly
+     * @type {string}
+     */
+    name
+
+    /**
+     * @param {Artifact} parent
+     * @param {string} name
+     */
+    constructor(parent, name) {
+        super(parent.fs, `${parent.dir}/${name}`)
+
+        this.parent = parent
+        this.name = name
+    }
+
+    /**
+     * @type {boolean}
+     */
+    get isMainnet() {
+        return this.parent.isMainnet
+    }
+
+    /**
+     * @param {string} name
+     * @param {UplcProgram} program
+     * @returns {ChildArtifactWriter}
+     */
+    writeProgram(name, program) {
+        if (program.plutusVersion == "PlutusScriptV1") {
+            this.addImport("UplcProgramV1", "@helios-lang/uplc", true)
+            this.addImport("decodeUplcProgramV1FromCbor", "@helios-lang/uplc")
+
+            this.writeDeclLine(
+                `export const ${name}: UplcProgramV1`
+            ).writeDefLine(
+                `export const ${name} = ${stringifyProgram("decodeUplcProgramV1FromCbor", program)}`
+            )
+        } else if (program.plutusVersion == "PlutusScriptV2") {
+            this.addImport("UplcProgramV2", "@helios-lang/uplc", true)
+            this.addImport("decodeUplcProgramV2FromCbor", "@helios-lang/uplc")
+
+            this.writeDeclLine(
+                `export const ${name}: UplcProgramV2`
+            ).writeDefLine(
+                `export const ${name} = ${stringifyProgram("decodeUplcProgramV2FromCbor", program)}`
+            )
+        } else if (program.plutusVersion == "PlutusScriptV3") {
+            this.addImport("UplcProgramV3", "@helios-lang/uplc", true)
+            this.addImport("decodeUplcProgramV3FromCbor", "@helios-lang/uplc")
+
+            this.writeDeclLine(
+                `export const ${name}: UplcProgramV3`
+            ).writeDefLine(
+                `export const ${name} = ${stringifyProgram("decodeUplcProgramV3FromCbor", program)}`
+            )
+        } else {
+            throw new Error("unhandled Plutus version")
+        }
+
+        return this
+    }
+}
+
+/**
+ *
+ * @param {string} decoderName
+ * @param {UplcProgram} program
+ * @returns {string}
+ */
+function stringifyProgram(decoderName, program) {
+    const sourceMap = makeUplcSourceMap({ term: program.root })
+
+    return `${decoderName}(
+    "${bytesToHex(program.toCbor())}",
+    {${stringifyAlt("decodeUplcProgramV2FromCbor", program.alt)}
+        sourceMap: ${JSON.stringify(sourceMap.toJsonSafe(), undefined, 4).split("\n").join("\n        ")}
+    }
+)`
+}
+
+/**
+ * @param {string} decoderName
+ * @param {UplcProgram |  undefined} alt
+ * @returns {string}
+ */
+function stringifyAlt(decoderName, alt) {
+    if (!alt) {
+        return ""
+    }
+
+    const sourceMap = makeUplcSourceMap({ term: alt.root })
+
+    return `
+        alt: ${decoderName}(
+            "${bytesToHex(alt.toCbor())}",
+            {
+                sourceMap: ${JSON.stringify(sourceMap.toJsonSafe(), undefined, 4).split("\n").join("\n                ")}
+            }
+        ),`
+}

package/src/artifacts/FunctionArtifact.js

@@ -0,0 +1,90 @@
+import {
+    genFuncType,
+    genUserFuncArgsType,
+    genUserFuncRetType
+} from "../codegen/LoadedScriptsWriter.js"
+import { ChildArtifactWriter } from "./ChildArtifactWriter.js"
+
+/**
+ * @import { UserFuncProps } from "../index.js"
+ * @import { Artifact } from "./Artifact.js"
+ * @import { FunctionDetails } from "./symbols.js"
+ */
+
+/**
+ * @param {Artifact} parent
+ * @param {string} name
+ * @param {FunctionDetails} details
+ */
+export function writeFunctionArtifact(parent, name, details) {
+    const artifact = new FunctionArtifact(parent, name)
+
+    const program = details.uplc
+    const props = details.props
+
+    artifact.writeProgram("$program", program)
+    artifact.writeProps(props)
+    artifact.writeEvals(props)
+
+    artifact.save()
+
+    parent.writeAggregateExport(name)
+}
+
+/**
+ * @implements {Artifact}
+ */
+class FunctionArtifact extends ChildArtifactWriter {
+    /**
+     * @param {UserFuncProps} props
+     */
+    writeProps(props) {
+        this.addImport("UserFuncProps", "@helios-lang/contract-utils", true)
+
+        this.writeDeclLine(`export const $props: UserFuncProps`)
+            .writeDefLine(`/**
+ * @type {import("@helios-lang/contract-utils").UserFuncProps}
+ */
+export const $props = ${JSON.stringify(props, undefined, 4)}`)
+    }
+
+    /**
+     * @param {UserFuncProps} props
+     */
+    writeEvals(props) {
+        const safeArgsType = genUserFuncArgsType(props)
+        const unsafeArgsType = genUserFuncArgsType(props, true)
+        const retType = genUserFuncRetType(props)
+        const unsafeRetType = genUserFuncRetType(props, true)
+
+        this.addImport("UplcLogger", "@helios-lang/uplc", true)
+        this.addImport("UplcData", "@helios-lang/uplc", true)
+        this.addImport("CekResult", "@helios-lang/uplc", true)
+
+        this.addImport("evalUserFunc", "@helios-lang/contract-utils")
+            .writeDeclLine(
+                `export function $eval(args${safeArgsType == "{}" ? "?" : ""}: ${safeArgsType}, logOptions?: UplcLogger | undefined): ${retType}`
+            )
+            .writeDefLine(
+                `export function $eval(args${safeArgsType == "{}" ? " = {}" : ""}, logOptions = undefined) {
+    return evalUserFunc($program, $props, args, logOptions)
+}`
+            )
+            .addImport("evalUserFuncUnsafe", "@helios-lang/contract-utils")
+            .writeDeclLine(
+                `export function $evalUnsafe(args${unsafeArgsType == "{}" ? "?" : ""}: ${unsafeArgsType}, logOptions?: UplcLogger | undefined): ${unsafeRetType}`
+            )
+            .writeDefLine(
+                `export function $evalUnsafe(args${unsafeArgsType == "{}" ? " = {}" : ""}, logOptions = undefined) {
+    return evalUserFuncUnsafe($program, $props, args, logOptions)
+}`
+            )
+            .addImport("profileUserFunc", "@helios-lang/contract-utils")
+            .writeDeclLine(
+                `export function $profile(args${unsafeArgsType == "{}" ? "?" : ""}: ${unsafeArgsType}, logOptions?: UplcLogger | undefined): CekResult`
+            )
+            .writeDefLine(`export function $profile(args${unsafeArgsType == "{}" ? " = {}" : ""}, logOptions = undefined) {
+    return profileUserFunc($program, $props, args, logOptions)
+}`)
+    }
+}

package/src/artifacts/ModuleArtifact.js

@@ -0,0 +1,83 @@
+import { ArtifactWriter } from "./ArtifactWriter.js"
+import { ChildArtifactWriter } from "./ChildArtifactWriter.js"
+import { writeFunctionArtifact } from "./FunctionArtifact.js"
+import { writeTypeArtifact } from "./TypeArtifact.js"
+
+/**
+ * @import { FunctionDetails, ModuleSymbols, TypeDetails } from "./symbols.js"
+ */
+
+/**
+ * Re-export Artifact to avoid issues with typescript private symbol errors
+ * @typedef {import("./Artifact.js").Artifact} Artifact
+ */
+
+/**
+ * @param {Artifact} parent
+ * @param {string} name
+ * @param {ModuleSymbols} symbols
+ */
+export function writeModuleArtifact(parent, name, symbols) {
+    const artifact = new ModuleArtifact(parent, name)
+
+    artifact.writeSymbols(symbols)
+
+    artifact.save()
+
+    parent.writeAggregateExport(name)
+}
+
+/**
+ * @implements {Artifact}
+ */
+export class ModuleArtifact extends ChildArtifactWriter {
+    /**
+     * @param {Artifact} parent
+     * @param {string} name
+     */
+    constructor(parent, name) {
+        super(parent, name)
+    }
+
+    /**
+     * @param {ModuleSymbols} symbols
+     */
+    writeSymbols(symbols) {
+        for (let symbolName in symbols) {
+            if (symbolName.startsWith("$") || symbolName.includes("::")) {
+                continue
+            }
+
+            // either function or type
+            const symbolDetails = symbols[symbolName]
+
+            console.log(symbolName)
+            if ("schema" in symbolDetails) {
+                // collect members
+                const members = /** @type {Record<string, FunctionDetails>} */ (
+                    Object.fromEntries(
+                        Object.entries(symbols)
+                            .filter(([key, value]) => {
+                                return (
+                                    key.startsWith(`${symbolName}::`) &&
+                                    value["kind"] != "Cast"
+                                )
+                            })
+                            .map(([key, value]) => [
+                                key.slice(`${symbolName}::`.length),
+                                value
+                            ])
+                    )
+                )
+
+                writeTypeArtifact(this, symbolName, symbolDetails, members)
+            } else {
+                writeFunctionArtifact(
+                    this,
+                    symbolName,
+                    /** @type {FunctionDetails} */ (symbolDetails)
+                )
+            }
+        }
+    }
+}

package/src/artifacts/RootArtifact.js

@@ -0,0 +1,105 @@
+import { ArtifactWriter } from "./ArtifactWriter.js"
+import { writeModuleArtifact } from "./ModuleArtifact.js"
+import { writeValidatorArtifact } from "./ValidatorArtifact.js"
+
+/**
+ * @import { ContractContext, ContractModuleContexts, ContractValidatorContexts, FileSystem, LoadedValidator, WriteContractContextArtifactsOptions } from "../index.js"
+ * @import { Artifact } from "./Artifact.js"
+ */
+
+/**
+ * @param {any} context - TODO: make this typesafe (`ContractContext<any, any>` or `ContractContext` doesn't seem to work)
+ * @param {WriteContractContextArtifactsOptions} options - not optional, at least the fs and outDir must be specified
+ */
+export function writeContractContextArtifacts(context, options) {
+    const isMainnet = extractIsMainnet(context)
+
+    const root = new RootArtifact(options.fs, options.outDir, isMainnet)
+
+    for (let moduleName in context) {
+        if (moduleName.startsWith("$")) {
+            continue
+        }
+
+        const moduleDetails = context[moduleName]
+
+        if (moduleDetails.$hash) {
+            writeValidatorArtifact(
+                root,
+                moduleName,
+                moduleDetails.$hash,
+                moduleDetails
+            )
+        } else {
+            writeModuleArtifact(root, moduleName, moduleDetails)
+        }
+    }
+
+    root.save()
+}
+
+/**
+ * @implements {Artifact}
+ */
+class RootArtifact extends ArtifactWriter {
+    /**
+     * @readonly
+     * @type {boolean}
+     */
+    isMainnet
+
+    /**
+     * @param {FileSystem} fs
+     * @param {string} dir
+     * @param {boolean} isMainnet
+     */
+    constructor(fs, dir, isMainnet) {
+        super(fs, dir)
+
+        this.isMainnet = isMainnet
+    }
+}
+
+/**
+ * @param {any} context
+ * @returns {boolean}
+ */
+function extractIsMainnet(context) {
+    /**
+     * @type {boolean | undefined}
+     */
+    let isMainnet = undefined
+
+    /**
+     * @param {boolean} b
+     */
+    const setIsMainnet = (b) => {
+        if (isMainnet === undefined) {
+            isMainnet = b
+        } else if (isMainnet != b) {
+            throw new Error("isMainnet inconsistent in contract context")
+        }
+    }
+
+    let stack = [context]
+
+    let obj = stack.pop()
+
+    while (obj) {
+        if ("isMainnet" in obj && typeof obj.isMainnet == "boolean") {
+            setIsMainnet(obj.isMainnet)
+        } else if ("$isMainnet" in obj && typeof obj.$isMainnet == "boolean") {
+            setIsMainnet(obj.$isMainnet)
+        }
+
+        for (let key in obj) {
+            if (typeof obj[key] === "object" && obj[key] !== null) {
+                stack.push(obj[key])
+            }
+        }
+
+        obj = stack.pop()
+    }
+
+    return isMainnet ?? false
+}