@helios-lang/contract-utils 0.1.1 → 0.1.6

package/examples/spending/app.js

@@ -0,0 +1,13 @@
+import { Program } from "@hyperionbt/helios"
+import { utils, match_string } from "./unspecialized.js"
+
+const modules = [utils, ...]
+
+export class App {
+    /**
+     * @param {typeof utils} specializedUtils 
+     */
+    constructor(specializedUtils) {
+        this.program = Program.new(match_string, modules.replace("utils", specializedUtils))
+    }
+}

package/examples/spending/output.d.ts

@@ -0,0 +1,18 @@
+
+export const utils: {
+    $name: string
+    $purpose: string
+    $sourceCode: string
+    $dependencies: []
+}
+export const match_string: {
+    $name: string
+    $purpose: string
+    $sourceCode: string
+    $dependencies: [typeof utils]
+    $hashDependencies: []
+    $dependsOnOwnHash: boolean
+    $Redeemer: Cast<string, string>
+    $Datum: Cast<{message: string}, {message: string}>
+}
+

package/examples/spending/output2.d.ts

@@ -0,0 +1,24 @@
+
+
+export const utils: {
+    $name: string
+    $purpose: string
+    $sourceCode: string
+    $dependencies: []
+}
+export const match_string: {
+    $name: string
+    $purpose: string
+    $sourceCode: string
+    $dependencies: [typeof utils]
+    $hashDependencies: []
+    $dependsOnOwnHash: boolean
+    $Redeemer: Cast<string, string>
+    $Datum: Cast<
+      {One: {message: string}} | 
+      {Two: {code: bigint}}, 
+      {One: {message: string}} | 
+      {Two: {code: bigint | number | string}}
+    >
+}
+

package/examples/spending/output2.js

@@ -0,0 +1,34 @@
+export const utils = {
+    $name: "utils",
+    $purpose: "module",
+    $sourceCode: "module utils\n\nfunc compare(a: String, b: String) -> Bool {\n    a == b\n}",
+    $dependencies: [],
+}
+export const match_string = {
+    $name: "match_string",
+    $purpose: "spending",
+    $sourceCode: "spending match_string\n\nimport { compare } from utils\n\nenum Datum {\n One {\n  message: String\n }\n\n Two {\n  message: String\n }\n}\n\nfunc main(datum: Datum, redeemer: String, _) -> Bool {\n compare(datum.switch{d: One => d.message, d: Two => d.message}, redeemer)\n}",
+    $dependencies: [utils],
+    $hashDependencies: [],
+    $dependsOnOwnHash: false,
+    $Redeemer: new Cast({"primitiveType":"String"}),
+    $Datum: new Cast({"enumVariantTypes":[{"name":"One","fieldTypes":[{"name":"message","type":{"primitiveType":"String"}}]},{"name":"Two","fieldTypes":[{"name":"message","type":{"primitiveType":"String"}}]}]})
+}
+
+export const utils: {
+    $name: string
+    $purpose: string
+    $sourceCode: string
+    $dependencies: []
+}
+export const match_string: {
+    $name: string
+    $purpose: string
+    $sourceCode: string
+    $dependencies: [typeof utils]
+    $hashDependencies: []
+    $dependsOnOwnHash: boolean
+    $Redeemer: Cast<string, string>
+    $Datum: Cast<{One: {message: string}} | {Two: {message: string}}, {One: {message: string}} | {Two: {message: string}}>
+}
+

package/examples/spending/package-lock.json

@@ -0,0 +1,39 @@
+{
+  "name": "spending_example",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "spending_example",
+      "dependencies": {
+        "@helios-lang/contract-utils": "file:../..",
+        "@hyperionbt/helios": "^0.16.7"
+      }
+    },
+    "../..": {
+      "name": "@helios-lang/contract-utils",
+      "version": "0.1.1",
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "@helios-lang/compiler-utils": "^0.1.2"
+      },
+      "bin": {
+        "hl2ts": "src/hl2ts.js"
+      },
+      "devDependencies": {
+        "@types/node": "^20.11.24",
+        "prettier": "^3.1.0",
+        "typescript": "^5.3.2"
+      }
+    },
+    "node_modules/@helios-lang/contract-utils": {
+      "resolved": "../..",
+      "link": true
+    },
+    "node_modules/@hyperionbt/helios": {
+      "version": "0.16.7",
+      "resolved": "https://registry.npmjs.org/@hyperionbt/helios/-/helios-0.16.7.tgz",
+      "integrity": "sha512-ysPaF0OCY0NJa1mc+LXERjH71VDNGUbYrrovKUHJv1v+eS1WJhKmxSHWh9sVa6b+sYoXdKwoCR20UQhzCF5jzA=="
+    }
+  }
+}

package/examples/spending/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "spending_example",
+  "dependencies": {
+    "@helios-lang/contract-utils": "file:../..",
+    "@hyperionbt/helios": "^0.16.7"
+  }
+}

package/examples/spending/specialized.js

@@ -0,0 +1,6 @@
+export const utils = {
+    $name: "utils",
+    $purpose: "module",
+    $sourceCode: "module utils\n\nfunc compare(a: String, b: String) -> Bool {\n    a == b\n}",
+    $dependencies: [],
+}

package/examples/spending/spending.hl

@@ -0,0 +1,17 @@
+spending match_string
+
+import { compare } from "./utils.hl"
+
+enum Datum {
+	One {
+		message: String
+	}
+
+	Two {
+		code: Int
+	}
+}
+
+func main(datum: Datum, redeemer: String, _) -> Bool {
+	compare(datum.switch{d: One => d.message, d: Two => d.code.show()}, redeemer)
+}

package/examples/spending/unspecialized.js

@@ -0,0 +1,18 @@
+import { Cast } from "@helios-lang/contract-utils"
+
+export const utils = {
+    $name: "utils",
+    $purpose: "module",
+    $sourceCode: "module utils\n\nfunc compare(a: String, b: String) -> Bool {\n    a == b\n}",
+    $dependencies: [],
+}
+export const match_string = {
+    $name: "match_string",
+    $purpose: "spending",
+    $sourceCode: "spending match_string\n\nimport { compare } from utils\n\nstruct Datum {\n message: String\n}\n\nfunc main(datum: Datum, redeemer: String, _) -> Bool {\n compare(datum.message, redeemer)\n}",
+    $dependencies: [utils],
+    $hashDependencies: [],
+    $dependsOnOwnHash: false,
+    $Redeemer: new Cast({"primitiveType":"String"}),
+    $Datum: new Cast({"structFieldTypes":[{"name":"message","type":{"primitiveType":"String"}}]})
+}

package/examples/spending/utils.hl

@@ -0,0 +1,5 @@
+module utils
+
+func compare(a: String, b: String) -> Bool {
+    a == b
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@helios-lang/contract-utils",
-    "version": "0.1.1",
+    "version": "0.1.6",
     "description": "Convenience and type-safety utilities for using Helios validators from within Typescript",
     "main": "src/index.js",
     "type": "module",
@@ -28,5 +28,12 @@
         "tabWidth": 4,
         "semi": false,
         "singleQuote": false
+    },
+    "dependencies": {
+        "@helios-lang/codec-utils": "^0.1.26",
+        "@helios-lang/compiler-utils": "^0.1.20",
+        "@helios-lang/ledger": "^0.1.10",
+        "@helios-lang/type-utils": "^0.1.8",
+        "@helios-lang/uplc": "^0.1.21"
     }
 }

package/src/codegen/Module.js

@@ -0,0 +1,15 @@
+/**
+ * @typedef {import("./TypeSchema.js").TypeSchema} TypeSchema
+ */
+
+/**
+ * @typedef {{
+ *   name: string
+ *   purpose: string
+ *   sourceCode: string
+ *   moduleDepedencies: string[]
+ *   types: {[name: string]: TypeSchema}
+ * }} Module
+ */
+
+export const _ = {}

package/src/codegen/TypeSchema.js

@@ -0,0 +1,151 @@
+/**
+ * @typedef {{
+ *     primitiveType: string
+ * } | {
+ *     listItemType: TypeSchema
+ * } | {
+ *     mapKeyType: TypeSchema
+ *     mapValueType: TypeSchema
+ * } | {
+ *     optionSomeType: TypeSchema
+ * } | {
+ *     structFieldTypes: {
+ *         name: string
+ *         type: TypeSchema
+ *     }[]
+ * } | {
+ *     enumVariantTypes: {
+ *          name: string,
+ *          fieldTypes: {
+ *              name: string
+ *              type: TypeSchema
+ *          }[]
+ *     }[]
+ * }} TypeSchema
+ */
+
+/**
+ * @param {TypeSchema} schema
+ * @returns {[string, string]} - the first entry is the canonical type, the second is the permissive type
+ */
+export function genTypes(schema) {
+    if ("primitiveType" in schema) {
+        switch (schema.primitiveType) {
+            case "Address":
+                return ["Address", "Address | string"]
+            case "Any":
+                return ["never", "any"]
+            case "AssetClass":
+                return [
+                    "AssetClass",
+                    "AssetClass | string | [string | MintingPolicyHash | number[], string | number[]] | {mph: MintingPolicyHash | string | number[], tokenName: string | number[]}"
+                ]
+            case "Bool":
+                return ["boolean", "boolean"]
+            case "ByteArray":
+                return ["number[]", "number[]"]
+            case "Credential":
+                return ["Credential", "Credential | PubKeyHash | ValidatorHash"]
+            case "Data":
+                return ["UplcData", "UplcData"]
+            case "Duration":
+                return ["bigint", "bigint | number"]
+            case "Int":
+                return ["bigint", "bigint | number | string"]
+            case "MintingPolicyHash":
+                return [
+                    "MintingPolicyHash",
+                    "MintingPolicyHash | string | number[]"
+                ]
+            case "PubKey":
+                return ["string", "string | number[]"]
+            case "PubKeyHash":
+                return ["PubKeyHash", "PubKeyHash | string | number[]"]
+            case "Real":
+                return ["number", "numer"]
+            case "StakingCredential":
+                return [
+                    "StakingCredential",
+                    "StakingCredential | StakingHash | PubKeyHash | StakingValidatorHash"
+                ]
+            case "StakingHash":
+                return [
+                    "StakingHash",
+                    "StakingHash | PubKeyHash | StakingValidatorHash"
+                ]
+            case "StakingValidatorHash":
+                return [
+                    "StakingValidatorHash",
+                    "StakingValidatorHash | string | number[]"
+                ]
+            case "String":
+                return ["string", "string"]
+            case "Time":
+                return ["Date", "Date | bigint | number"]
+            case "TimeRange":
+                return [
+                    "TimeRange",
+                    "TimeRange | [Date | number | bigint, Date | number | bigint] | {start?: Date | number | bigint, excludeStart?: boolean, end?: Date | number | bigint, excludeEnd?: boolean}"
+                ]
+            case "TxId":
+                return ["TxId", "TxId | string | number[]"]
+            case "TxOutputDatum":
+                return [
+                    "TxOutputDatum | null",
+                    "TxOutputDatum | null | undefined | DatumHash | UplcData"
+                ]
+            case "TxOutputId":
+                return ["TxOutputId", "TxOutputId | string"]
+            case "ValidatorHash":
+                return ["ValidatorHash", "ValidatorHash | string | number[]"]
+            case "Value":
+                return [
+                    "Value",
+                    "Value | [MintingPolicyHash | string | number[], [number[] | string, bigint | number | string][]][] | {mph: MintingPolicyHash | string | number[], tokens: {name: number[] | string, qty: bigint | number | string}[]}[]"
+                ]
+            default:
+                throw new Error(
+                    `unhandled primitive ${schema.primitiveType} in hl2ts`
+                )
+        }
+    } else if ("listItemType" in schema) {
+        const [c, p] = genTypes(schema.listItemType)
+        return [`${c}[]`, `${p}[]`]
+    } else if ("optionSomeType" in schema) {
+        const [c, p] = genTypes(schema.optionSomeType)
+        return [`${c} | null`, `${p} | null | undefined`]
+    } else if ("mapKeyType" in schema) {
+        const [ck, pk] = genTypes(schema.mapKeyType)
+        const [cv, pv] = genTypes(schema.mapValueType)
+
+        return [`Map<${ck}, ${cv}>`, `Map<${pk}, ${pv}> | [${pk}, ${pv}][]`]
+    } else if ("structFieldTypes" in schema) {
+        const fieldTypes = schema.structFieldTypes.map(({ name, type }) => ({
+            name: name,
+            types: genTypes(type)
+        }))
+
+        return [
+            `{${fieldTypes.map(({ name, types: [c, p] }) => `${name}: ${c}`).join(", ")}}`,
+            `{${fieldTypes.map(({ name, types: [c, p] }) => `${name}: ${p}`).join(", ")}}`
+        ]
+    } else if ("enumVariantTypes" in schema) {
+        const variantTypes = schema.enumVariantTypes.map(
+            ({ name, fieldTypes }) => ({
+                name: name,
+                types: genTypes({ structFieldTypes: fieldTypes })
+            })
+        )
+
+        return [
+            variantTypes
+                .map(({ name, types: [c, p] }) => `{${name}: ${c}}`)
+                .join(" | "),
+            variantTypes
+                .map(({ name, types: [c, p] }) => `{${name}: ${p}}`)
+                .join(" | ")
+        ]
+    } else {
+        throw new Error(`unhandled TypeSchema ${JSON.stringify(schema)}`)
+    }
+}

package/src/codegen/TypescriptWriter.js

@@ -0,0 +1,184 @@
+import { genTypes } from "./TypeSchema.js"
+import { Writer } from "./Writer.js"
+
+/**
+ * @typedef {import("./Module.js").Module} Module
+ * @typedef {import("./Validator.js").Validator} Validator
+ */
+
+export class TypescriptWriter {
+    constructor() {
+        this.wjs = new Writer()
+        this.wdts = new Writer()
+    }
+
+    /**
+     * @param {string} js
+     * @param {string} dts
+     * @returns {TypescriptWriter}
+     */
+    write(js, dts = "") {
+        this.wjs.write(js)
+        this.wdts.write(dts)
+        return this
+    }
+
+    /**
+     * @param {string} js
+     * @param {string} dts
+     * @returns {TypescriptWriter}
+     */
+    writeLine(js, dts = "") {
+        if (js != "") {
+            this.wjs.writeLine(js)
+        }
+
+        if (dts != "") {
+            this.wdts.writeLine(dts)
+        }
+
+        return this
+    }
+
+    /**
+     * @param {Module} m
+     */
+    writeModule(m) {
+        this.write(
+            `export const ${m.name} = {
+    $name: "${m.name}",
+    $purpose: "${m.purpose}",
+    $sourceCode: ${JSON.stringify(m.sourceCode)},
+    $dependencies: [${m.moduleDepedencies.join(", ")}],
+}
+`,
+            `export const ${m.name}: {
+    $name: string
+    $purpose: string
+    $sourceCode: string
+    $dependencies: [${m.moduleDepedencies.map((d) => `typeof ${d}`).join(", ")}]
+}
+`
+        )
+    }
+
+    /**
+     * @param {Validator} v
+     */
+    writeValidator(v) {
+        const redeemerTypes = genTypes(v.Redeemer)
+        const datumTypes = v.Datum ? genTypes(v.Datum) : undefined
+
+        this.write(
+            `export const ${v.name} = {
+    $name: "${v.name}",
+    $purpose: "${v.purpose}",
+    $sourceCode: ${JSON.stringify(v.sourceCode)},
+    $dependencies: [${v.moduleDepedencies.join(", ")}],
+    $hashDependencies: [${v.hashDependencies.filter((d) => d != v.name).join(", ")}],
+    $dependsOnOwnHash: ${v.hashDependencies.some((d) => d == v.name)},
+    $Redeemer: new Cast(${JSON.stringify(v.Redeemer)}),
+    ${datumTypes ? `$Datum: new Cast(${JSON.stringify(v.Datum)})` : ""}
+}
+`,
+            `export const ${v.name}: {
+    $name: string
+    $purpose: string
+    $sourceCode: string
+    $dependencies: [${v.moduleDepedencies.map((d) => `typeof ${d}`).join(", ")}]
+    $hashDependencies: [${v.hashDependencies
+        .filter((d) => d != v.name)
+        .map((d) => `typeof ${d}`)
+        .join(", ")}]
+    $dependsOnOwnHash: boolean
+    $Redeemer: Cast<${redeemerTypes[0]}, ${redeemerTypes[1]}>
+    ${datumTypes ? `$Datum: Cast<${datumTypes[0]}, ${datumTypes[1]}>` : ""}
+}
+`
+        )
+    }
+
+    writeHeaders() {
+        this.wjs.writeLine("import { Cast } from \"@helios-lang/contract-utils\";")
+
+        this.wdts.writeLine("import type {UplcData} from \"@helios-lang/ledger\";")
+        this.wdts.writeLine("import { Address, AssetClass, Credential, DatumHash, MintingPolicyHash, PubKeyHash, StakingCredential, StakingHash, StakingValidatorHash, TimeRange, TxId, TxOutputDatum, ValidatorHash, Value} from \"@helios-lang/ledger\";")
+        this.wdts.writeLine("import { Cast } from \"@helios-lang/contract-utils\";")
+    }
+
+    /**
+     * @param {{[name: string]: Module}} ms
+     */
+    writeModules(ms) {
+        /**
+         * @type {Set<string>}
+         */
+        const done = new Set()
+
+        let todo = Object.values(ms)
+
+        while (todo.length > 0) {
+            /**
+             * @type {Module[]}
+             */
+            let todoNext = []
+
+            for (let i = 0; i < todo.length; i++) {
+                const m = todo[i]
+
+                if (m.moduleDepedencies.every((d) => done.has(d))) {
+                    this.writeModule(m)
+
+                    done.add(m.name)
+                } else {
+                    todoNext.push(m)
+                }
+            }
+
+            todo = todoNext
+        }
+    }
+
+    /**
+     *
+     * @param {{[name: string]: Validator}} validators
+     */
+    writeValidators(validators) {
+        /**
+         * @type {Set<string>}
+         */
+        const done = new Set()
+
+        let todo = Object.values(validators)
+
+        while (todo.length > 0) {
+            /**
+             * @type {Validator[]}
+             */
+            let todoNext = []
+
+            for (let i = 0; i < todo.length; i++) {
+                const v = todo[i]
+
+                if (
+                    v.hashDependencies.every((d) => done.has(d) || d == v.name)
+                ) {
+                    this.writeValidator(v)
+
+                    done.add(v.name)
+                } else {
+                    todoNext.push(v)
+                }
+            }
+
+            todo = todoNext
+        }
+    }
+
+    /**
+     * @returns {[string, string]}
+     */
+    finalize() {
+        return [this.wjs.finalize(), this.wdts.finalize()]
+    }
+}

package/src/codegen/Validator.js

@@ -0,0 +1,17 @@
+/**
+ * @typedef {import("./TypeSchema.js").TypeSchema} TypeSchema
+ */
+
+/**
+ * @typedef {import("./Module.js").Module} Module
+ */
+
+/**
+ * @typedef {Module & {
+ *   hashDependencies: string[]
+ *   Redeemer: TypeSchema
+ *   Datum?: TypeSchema
+ * }} Validator
+ */
+
+export const _ = {}

package/src/codegen/Writer.js

@@ -0,0 +1,37 @@
+export class Writer {
+    /**
+     * @private
+     * @readonly
+     * @type {string[]}
+     */
+    parts
+
+    constructor() {
+        this.parts = []
+    }
+
+    /**
+     * @param {string} part
+     * @returns {Writer}
+     */
+    write(part) {
+        this.parts.push(part)
+        return this
+    }
+
+    /**
+     * @param {string} line
+     * @returns {Writer}
+     */
+    writeLine(line) {
+        this.parts.push(`${line}\n`)
+        return this
+    }
+
+    /**
+     * @returns {string}
+     */
+    finalize() {
+        return this.parts.join("")
+    }
+}

package/src/codegen/index.js

@@ -0,0 +1,8 @@
+export { TypescriptWriter } from "./TypescriptWriter.js"
+export { Writer } from "./Writer.js"
+
+/**
+ * @typedef {import("./Module.js").Module} Module
+ * @typedef {import("./TypeSchema.js").TypeSchema} TypeSchema
+ * @typedef {import("./Validator.js").Validator} Validator
+ */