@helios-lang/contract-utils 0.1.20 → 0.1.23

package/src/compiler/ops.js

@@ -0,0 +1,137 @@
+import * as unsafeLib from "@helios-lang/compiler"
+import {
+    translateImportPaths as translateImportPathsInternal,
+    readHeader
+} from "@helios-lang/compiler-utils"
+import { CompilerLib_v0_16 } from "./CompilerLib_v0_16.js"
+
+/**
+ * @typedef {import("./CompilerLib.js").CompilerLib} CompilerLib
+ * @typedef {import("./CompilerLib.js").TypeCheckOutput} TypeCheckOutput
+ */
+
+/**
+ * @param {{VERSION: string}} lib
+ * @returns {number[]}
+ */
+function getVersion(lib) {
+    return lib.VERSION.split(".").map((v) => Number(v))
+}
+
+/**
+ * The compiler library is passed as an argument instead of loading locally, so any optional configuration of the library can be done externally
+ * @returns {CompilerLib}
+ */
+export function loadCompilerLib() {
+    const [major, minor] = getVersion(unsafeLib)
+
+    switch (major) {
+        case 0:
+            switch (minor) {
+                case 16:
+                    return new CompilerLib_v0_16(unsafeLib)
+            }
+        default:
+            throw new Error(
+                `compiler version ${unsafeLib.VERSION} not supported`
+            )
+    }
+}
+
+/**
+ * The compiler library is passed as an argument instead of loading locally, so any optional configuration of the library can be done externally
+ * @param {CompilerLib} lib
+ * @param {{[path: string]: string}} files
+ * @param {(current: string, rel: string) => string} relToAbs
+ * @returns {TypeCheckOutput}
+ */
+export function typeCheckFiles(lib, files, relToAbs) {
+    const scripts = translateImportPaths(files, relToAbs)
+
+    return typeCheckScripts(lib, scripts)
+}
+
+/**
+ * @param {CompilerLib} lib
+ * @param {string[]} scripts
+ * @returns {TypeCheckOutput}
+ */
+export function typeCheckScripts(lib, scripts) {
+    const [validators, modules] = splitValidatorsAndModules(scripts)
+
+    return lib.typeCheck(validators, modules)
+}
+
+/**
+ * Filters out duplicates
+ * @param {string[]} scripts
+ * @returns {[string[], string[]]} - [validators, modules]
+ */
+function splitValidatorsAndModules(scripts) {
+    /**
+     * @type {Map<string, string>}
+     */
+    const validators = new Map()
+
+    /**
+     * @type {Map<string, string>}
+     */
+    const modules = new Map()
+
+    scripts.forEach((s) => {
+        const [purpose, name] = readHeader(s)
+
+        switch (purpose) {
+            case "module":
+                modules.set(name, s)
+                break
+            case "minting":
+            case "spending":
+            case "certifying":
+            case "rewarding":
+            case "staking":
+                validators.set(name, s)
+                break
+            default:
+                throw new Error(
+                    `unhandled script purpose ${purpose} in script ${name}`
+                )
+        }
+    })
+
+    return [Array.from(validators.values()), Array.from(modules.values())]
+}
+
+/**
+ *
+ * @param {{[path: string]: string}} files
+ * @param {(current: string, rel: string) => string} relToAbs
+ * @returns {string[]}
+ */
+function translateImportPaths(files, relToAbs) {
+    const partialSources = {}
+
+    for (let path in files) {
+        const [purpose, name] = readHeader(files[path])
+
+        partialSources[path] = {
+            name: name,
+            purpose: purpose,
+            sourceCode: files[path]
+        }
+    }
+
+    return Object.entries(files).map(([path, file]) =>
+        translateImportPathsInternal(file, (relPath) => {
+            const absPath = relToAbs(path, relPath)
+
+            const d = partialSources[absPath] ?? partialSources[absPath + ".hl"]
+
+            if (!d) {
+                throw new Error(`'${relPath}' not found`)
+            }
+
+            return d.name
+        })
+    )
+}

package/src/context/ContractContext.js

@@ -0,0 +1,78 @@
+import {
+    StakingValidatorHash,
+    ValidatorHash,
+    MintingPolicyHash
+} from "@helios-lang/ledger"
+import { Cast } from "../cast/index.js"
+
+/**
+ * @typedef {import("../codegen/index.js").LoadedValidator} LoadedValidator
+ */
+
+/**
+ * @template TRedeemerStrict
+ * @template TRedeemerPermissive
+ * @typedef {import("@helios-lang/ledger").MintingContext<TRedeemerStrict, TRedeemerPermissive>} MintingContext
+ */
+
+/**
+ * @template TDatumStrict
+ * @template TDatumPermissive
+ * @template TRedeemerStrict
+ * @template TRedeemerPermissive
+ * @typedef {import("@helios-lang/ledger").SpendingContext<TDatumStrict, TDatumPermissive, TRedeemerStrict, TRedeemerPermissive>} SpendingContext
+ */
+
+/**
+ * @template TRedeemerStrict
+ * @template TRedeemerPermissive
+ * @typedef {import("@helios-lang/ledger").StakingContext<TRedeemerStrict, TRedeemerPermissive>} StakingContext
+ */
+
+/**
+ * @template {Cast} C
+ * @typedef {import("../cast/index.js").PermissiveType<C>} PermissiveType
+ */
+
+/**
+ * @template {Cast} C
+ * @typedef {import("../cast/index.js").StrictType<C>} StrictType
+ */
+
+/**
+ * @typedef {(
+ *   ValidatorHash<SpendingContext<any, any, any, any>> |
+ *   MintingPolicyHash<MintingContext<any, any>> |
+ *   StakingValidatorHash<StakingContext<any, any>>
+ * )} AnyContractValidatorHash
+ */
+
+/**
+ * @template {LoadedValidator} V
+ * @typedef {V extends {"$purpose": "spending", "$Datum": Cast} ? ValidatorHash<
+ *       SpendingContext<
+ *         StrictType<V["$Datum"]>,
+ *         PermissiveType<V["$Datum"]>,
+ *         StrictType<V["$Redeemer"]>,
+ *         PermissiveType<V["$Redeemer"]>
+ *       >
+ *     > :
+ *     V extends {"$purpose": "minting"} ? MintingPolicyHash<
+ *       MintingContext<
+ *         StrictType<V["$Redeemer"]>,
+ *         PermissiveType<V["$Redeemer"]>
+ *       >
+ *     > :
+ *     V extends {"$purpose": ("certifying" | "rewarding")} ? StakingValidatorHash<
+ *       StakingContext<
+ *         StrictType<V["$Redeemer"]>,
+ *         PermissiveType<V["$Redeemer"]>
+ *       >
+ *     > : never
+ * } ContractValidatorHash
+ */
+
+/**
+ * @template {{[name: string]: LoadedValidator}} T
+ * @typedef {{[K in keyof T]: ContractValidatorHash<T[K]>}} ContractContext
+ */

package/src/context/ContractContextBuilder.js

@@ -0,0 +1,69 @@
+import { None } from "@helios-lang/type-utils"
+import { loadCompilerLib } from "../compiler/index.js"
+import { DagCompiler } from "./DagCompiler.js"
+
+/**
+ * @typedef {import("../codegen/LoadedModule.js").LoadedModule} LoadedModule
+ * @typedef {import("../codegen/LoadedValidator.js").LoadedValidator} LoadedValidator
+ * @typedef {import("../compiler/index.js").CompilerLib} CompilerLib
+ */
+
+/**
+ * @template {{[name: string]: LoadedValidator}} T
+ * @typedef {import("./ContractContext.js").ContractContext<T>} ContractContext
+ */
+
+/**
+ * @template {{[name: string]: LoadedValidator}} T
+ */
+export class ContractContextBuilder {
+    /**
+     * @private
+     * @readonly
+     * @type {T}
+     */
+    validators
+
+    /**
+     * @private
+     * @param {T} validators
+     */
+    constructor(validators) {
+        this.validators = validators
+    }
+
+    /**
+     * @returns {ContractContextBuilder<{}>}
+     */
+    static new() {
+        return new ContractContextBuilder({})
+    }
+
+    /**
+     * @template {LoadedValidator} V
+     * @param {V} validator
+     * @returns {ContractContextBuilder<T & {
+     *   [K in V["$name"]]: V
+     * }>}
+     */
+    with(validator) {
+        return new ContractContextBuilder({
+            ...this.validators,
+            [validator.$name]: validator
+        })
+    }
+
+    /**
+     * @param {Option<{[name: string]: string}>} expectedHashes
+     * @returns {ContractContext<T>}
+     */
+    build(expectedHashes = None) {
+        const lib = loadCompilerLib()
+
+        const dagCompiler = new DagCompiler(lib)
+
+        return /** @type {any} */ (
+            dagCompiler.build(Object.values(this.validators), expectedHashes)
+        )
+    }
+}

package/src/context/DagCompiler.js

@@ -0,0 +1,229 @@
+import { bytesToHex } from "@helios-lang/codec-utils"
+import {
+    MintingPolicyHash,
+    StakingValidatorHash,
+    ValidatorHash
+} from "@helios-lang/ledger"
+import { None } from "@helios-lang/type-utils"
+import { UplcProgramV2 } from "@helios-lang/uplc"
+
+/**
+ * @typedef {import("../codegen/LoadedValidator.js").LoadedValidator} LoadedValidator
+ * @typedef {import("../compiler/index.js").CompilerLib} CompilerLib
+ * @typedef {import("./ContractContext.js").AnyContractValidatorHash} AnyContractValidatorHash
+ */
+
+/**
+ * Compiles a set of validators that depend on eachothers hashes (forming a Directed Acyclical Graph)
+ */
+export class DagCompiler {
+    /**
+     * @private
+     * @readonly
+     * @type {CompilerLib}
+     */
+    lib
+
+    /**
+     * @private
+     * @readonly
+     * @type {{[name: string]: AnyContractValidatorHash}}
+     */
+    cache
+
+    /**
+     * @param {CompilerLib} lib
+     */
+    constructor(lib) {
+        this.lib = lib
+        this.cache = {}
+    }
+
+    /**
+     * @param {LoadedValidator[]} validators
+     * @param {Option<{[name: string]: string}>} expectedHashes
+     * @returns {{[name: string]: AnyContractValidatorHash}}
+     */
+    build(validators, expectedHashes = None) {
+        const hashTypes = this.getHashTypes(validators)
+
+        /**
+         * `buildValidator()` is a closure instead of a member method of DagCompiler
+         *    because this way we have easy access to `hashTypes` and `expectedHashes`
+         * @param {LoadedValidator} validator
+         */
+        const buildValidator = (validator) => {
+            const name = validator.$name
+            const sourceCode = validator.$sourceCode
+
+            // if already built before, return immediately
+            if (name in this.cache) {
+                return
+            }
+
+            // make sure all the hash dependencies are built first
+            validator.$hashDependencies.forEach((v) => buildValidator(v))
+
+            // get the dependencies
+            const hashDeps = this.getHashDependencies(validator)
+            const moduleDeps = getModuleDependencies(validator)
+
+            // optimized compilation
+            const { cborHex: optimizedCborHex, prettyIR } = this.lib.compile(
+                sourceCode,
+                moduleDeps,
+                {
+                    optimize: true,
+                    hashDependencies: hashDeps,
+                    allValidatorHashTypes: hashTypes,
+                    dependsOnOwnHash: validator.$dependsOnOwnHash
+                }
+            )
+
+            const optimizedProgram = UplcProgramV2.fromCbor(optimizedCborHex)
+
+            // calculate the hash
+            const ownHash = bytesToHex(optimizedProgram.hash())
+
+            // optionally assert the own hash is equal to a given hash
+            if (expectedHashes && name in expectedHashes) {
+                if (expectedHashes[name] != ownHash) {
+                    console.log(prettyIR)
+
+                    throw new Error(
+                        `expected hash ${expectedHashes[name]} for validator ${name}, got ${ownHash}`
+                    )
+                }
+            }
+
+            // unoptimized compilation (so traces are untouched)
+            const { cborHex: unoptimizedCborHex } = this.lib.compile(
+                validator.$sourceCode,
+                Array.from(moduleDeps.values()),
+                {
+                    optimize: false,
+                    hashDependencies: hashDeps,
+                    allValidatorHashTypes: hashTypes,
+                    ownHash: validator.$dependsOnOwnHash ? ownHash : undefined
+                }
+            )
+
+            const unoptimizedProgram =
+                UplcProgramV2.fromCbor(unoptimizedCborHex)
+
+            // add result to cache (unoptimizedProgram is attached to optimizedProgram)
+            this.addToCache(
+                validator,
+                optimizedProgram.withAlt(unoptimizedProgram),
+                ownHash
+            )
+        }
+
+        validators.forEach((v) => buildValidator(v))
+
+        return this.cache
+    }
+
+    /**
+     * @private
+     * @param {LoadedValidator} validator
+     * @param {UplcProgramV2} program
+     * @param {string} hash - although this can be derived from `program`, reuse this to save some effort
+     */
+    addToCache(validator, program, hash) {
+        const name = validator.$name
+        const redeemer = validator.$Redeemer
+
+        switch (validator.$purpose) {
+            case "spending":
+                this.cache[name] = new ValidatorHash(hash, {
+                    program,
+                    redeemer,
+                    datum: validator.$Datum
+                })
+                break
+            case "minting":
+                this.cache[name] = new MintingPolicyHash(hash, {
+                    program,
+                    redeemer
+                })
+                break
+            case "certifying":
+            case "rewarding":
+            case "staking":
+                this.cache[name] = new StakingValidatorHash(hash, {
+                    program,
+                    redeemer
+                })
+                break
+            default:
+                throw new Error("unhandled purpose")
+        }
+    }
+
+    /**
+     * @private
+     * @param {LoadedValidator} validator
+     * @returns {{[name: string]: string}} - TODO: do we really need the purpose?
+     */
+    getHashDependencies(validator) {
+        /**
+         * @type {{[name: string]: string}}
+         */
+        const deps = {}
+
+        validator.$hashDependencies.forEach((dep) => {
+            const k = dep.$name
+            const v = this.cache[k]
+
+            if (!v) {
+                throw new Error(
+                    `${k} should've been built before ${validator.$name}`
+                )
+            }
+
+            deps[k] = v.toHex()
+        })
+
+        return deps
+    }
+
+    /**
+     * @private
+     * @param {LoadedValidator[]} validators
+     * @returns {{[name: string]: any}}
+     */
+    getHashTypes(validators) {
+        return Object.fromEntries(
+            validators.map((v) => {
+                return [v.$name, this.lib.getScriptHashType(v.$purpose)]
+            })
+        )
+    }
+}
+
+/**
+ * @param {LoadedValidator} validator
+ * @returns {string[]}
+ */
+export function getModuleDependencies(validator) {
+    /**
+     * @type {Map<string, string>}
+     */
+    const deps = new Map()
+
+    let stack = validator.$dependencies.slice()
+    let m = stack.pop()
+
+    while (m) {
+        if (!deps.has(m.$name)) {
+            deps.set(m.$name, m.$sourceCode)
+
+            stack = stack.concat(m.$dependencies)
+        }
+
+        m = stack.pop()
+    }
+
+    return Array.from(deps.values())
+}

package/src/context/index.js

@@ -0,0 +1 @@
+export { ContractContextBuilder } from "./ContractContextBuilder.js"

package/src/hl2ts.js

@@ -3,40 +3,54 @@
 import { promises, readFileSync, writeFileSync } from "node:fs"
 import { dirname, join, resolve } from "node:path"
 import { readHeader, translateImportPaths } from "@helios-lang/compiler-utils"
-import { TypescriptWriter } from "./codegen/index.js"
-import { loadLibrary } from "./lib/index.js"
+import { LoadedScriptsWriter } from "./codegen/index.js"
+import { loadCompilerLib } from "./compiler/index.js"
+import { typeCheckFiles, typeCheckScripts } from "./compiler/ops.js"
 
 /**
- * @typedef {import("./lib/Lib.js").Lib} Lib
- * @typedef {import("./lib/Lib.js").SourceDetails} SourceDetails
- * @typedef {import("./lib/Lib.js").ModuleDetails} ModuleDetails
- * @typedef {import("./lib/Lib.js").ValidatorDetails} ValidatorDetails
+ * @typedef {import("./compiler/CompilerLib.js").CompilerLib} CompilerLib
+ * @typedef {import("./compiler/CompilerLib.js").TypeCheckedModule} ModuleDetails
+ * @typedef {import("./compiler/CompilerLib.js").TypeCheckedValidator} ValidatorDetails
+ */
+
+/**
+ * @typedef {{
+ *   name: string
+ *   purpose: string
+ *   sourceCode: string
+ * }} SourceDetails
  */
 
 async function main() {
-    console.log("hl2ts")
+    const lib = loadCompilerLib()
 
     const { outDir } = parseArgs(process.argv)
 
-    const lib = await loadLibrary()
     const filePaths = await listFiles(process.cwd(), ".hl")
     const files = readFiles(filePaths)
-    const sources = preparseFiles(files)
-    const { modules, validators } = typeCheck(lib, sources)
 
-    const w = new TypescriptWriter()
+    console.log(`hl2ts using Helios compiler v${lib.version}`)
+    console.log(`  Transpiling ${Object.keys(files).length} inputs:`)
+    filePaths.forEach((p) => console.log(`    ${p}`))
 
-    w.writeHeaders()
-    w.writeModules(modules)
-    w.writeValidators(validators)
+    const { modules, validators } = typeCheckFiles(lib, files, (current, rel) =>
+        resolve(join(dirname(current), rel))
+    )
 
-    const [js, dts] = w.finalize()
+    const [js, dts] = LoadedScriptsWriter.new()
+        .writeModules(modules)
+        .writeValidators(validators)
+        .finalize()
 
     const jsPath = join(outDir, "index.js")
     const dtsPath = join(outDir, "index.d.ts")
 
     writeFileSync(jsPath, js)
     writeFileSync(dtsPath, dts)
+
+    console.log(`  Output:`)
+    console.log(`    ${jsPath}`)
+    console.log(`    ${dtsPath}`)
 }
 
 main()
@@ -100,7 +114,7 @@ function readFiles(filePaths) {
 /**
  *
  * @param {{[path: string]: string}} files
- * @returns {{[name: string]: SourceDetails}}
+ * @returns {string[]}
  */
 function preparseFiles(files) {
     const partialSources = {}
@@ -139,47 +153,5 @@ function preparseFiles(files) {
         }
     }
 
-    return sources
-}
-
-/**
- * @param {{[name: string]: SourceDetails}} sources
- * @returns {[{[name: string]: SourceDetails}, {[name: string]: SourceDetails}]}
- */
-function splitValidatorsAndModules(sources) {
-    /**
-     * @type {{[name: string]: SourceDetails}}
-     */
-    const validators = {}
-
-    /**
-     * @type {{[name: string]: SourceDetails}}
-     */
-    const modules = {}
-
-    for (let key in sources) {
-        const v = sources[key]
-        if (v.purpose == "module") {
-            modules[key] = v
-        } else if (
-            v.purpose == "spending" ||
-            v.purpose == "minting" ||
-            v.purpose == "staking"
-        ) {
-            validators[key] = v
-        }
-    }
-
-    return [validators, modules]
-}
-
-/**
- * @param {Lib} lib
- * @param {{[name: string]: SourceDetails}} sources
- * @returns {{modules: {[name: string]: ModuleDetails}, validators: {[name: string]: ValidatorDetails}}}
- */
-function typeCheck(lib, sources) {
-    const [validators, modules] = splitValidatorsAndModules(sources)
-
-    return lib.typeCheck(validators, modules)
+    return Object.values(sources).map((s) => s.sourceCode)
 }

package/src/index.js

@@ -1 +1,12 @@
-export { Cast, ContractContextBuilder } from "./runtime/index.js"
+export { Cast } from "./cast/index.js"
+export { ContractContextBuilder } from "./context/index.js"
+
+/**
+ * @template {import("./cast/index.js").Cast} C
+ * @typedef {import("./cast/index.js").StrictType<C>} StrictType
+ */
+
+/**
+ * @template {import("./cast/index.js").Cast} C
+ * @typedef {import("./cast/index.js").PermissiveType<C>} PermissiveType
+ */

package/types/cast/Cast.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @typedef {import("@helios-lang/uplc").UplcData} UplcData
+ * @typedef {import("../codegen/index.js").TypeSchema} TypeSchema
+ */
+/**
+ * @template [TStrict=any]
+ * @template [TPermissive=any]
+ */
+export class Cast<TStrict = any, TPermissive = any> {
+    /**
+     * @param {TypeSchema} schema
+     */
+    constructor(schema: TypeSchema);
+    /**
+     * @readonly
+     * @type {TypeSchema}
+     */
+    readonly schema: TypeSchema;
+    /**
+     * @param {UplcData} data
+     * @returns {TStrict}
+     */
+    fromUplcData(data: UplcData): TStrict;
+    /**
+     * @param {TPermissive} x
+     * @returns {UplcData}
+     */
+    toUplcData(x: TPermissive): UplcData;
+}
+export type UplcData = import("@helios-lang/uplc").UplcData;
+export type TypeSchema = import("../codegen/index.js").TypeSchema;
+//# sourceMappingURL=Cast.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Cast.d.ts","sourceRoot":"","sources":["../../src/cast/Cast.js"],"names":[],"mappings":"AAiCA;;;GAGG;AAEH;;;GAGG;AACH;IAOI;;OAEG;IACH,oBAFW,UAAU,EAIpB;IAXD;;;OAGG;IACH,iBAFU,UAAU,CAEd;IASN;;;OAGG;IACH,mBAHW,QAAQ,GACN,OAAO,CAInB;IAED;;;OAGG;IACH,cAHW,WAAW,GACT,QAAQ,CAIpB;CACJ;uBArCY,OAAO,mBAAmB,EAAE,QAAQ;yBACpC,OAAO,qBAAqB,EAAE,UAAU"}

package/types/cast/PermissiveType.d.ts

@@ -0,0 +1,3 @@
+export type PermissiveType<C extends Cast<any, any>> = C extends Cast<any, infer TPermissive> ? TPermissive : never;
+import { Cast } from "./Cast.js";
+//# sourceMappingURL=PermissiveType.d.ts.map