@helios-lang/contract-utils 0.1.20 → 0.1.24

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"