@helios-lang/contract-utils 0.2.72 → 0.2.74

package/package.json

@@ -1,9 +1,15 @@
 {
   "name": "@helios-lang/contract-utils",
-  "version": "0.2.72",
+  "version": "0.2.74",
   "description": "Convenience and type-safety utilities for using Helios validators from within Typescript",
   "main": "src/index.js",
   "types": "types/index.d.ts",
+  "exports": {
+    "./set-fs-build-cache": "./src/context/set-fs-build-cache.js"
+  },
+  "sideEffects": [
+    "./src/context/set-fs-build-cache.js"
+  ],
   "type": "module",
   "bin": {
     "hl2ts": "src/hl2ts.js"
@@ -28,6 +34,7 @@
     "@helios-lang/cli-utils": "^0.1.10",
     "@helios-lang/codec-utils": "^0.2.1",
     "@helios-lang/compiler-utils": "^0.2.1",
+    "@helios-lang/crypto": "0.1.17",
     "@helios-lang/ledger": "^0.5.8",
     "@helios-lang/type-utils": "^0.1.25",
     "@helios-lang/uplc": "^0.6.1"

package/src/context/CacheEntry.js

@@ -0,0 +1,310 @@
+import { bytesToHex } from "@helios-lang/codec-utils"
+import {
+    MintingPolicyHash,
+    ScriptHash,
+    StakingValidatorHash,
+    ValidatorHash
+} from "@helios-lang/ledger"
+import { None, expectSome } from "@helios-lang/type-utils"
+import { UplcProgramV1, UplcProgramV2, UplcSourceMap } from "@helios-lang/uplc"
+import { Cast } from "../cast/Cast.js"
+
+/**
+ * @typedef {import("@helios-lang/type-utils").TypeSchema} TypeSchema
+ * @typedef {import("@helios-lang/uplc").UplcData} UplcData
+ * @typedef {import("@helios-lang/uplc").PlutusVersion} PlutusVersion
+ * @typedef {import("@helios-lang/uplc").UplcProgram} UplcProgram
+ * @typedef {import("@helios-lang/uplc").UplcProgramV1I} UplcProgramV1I
+ * @typedef {import("@helios-lang/uplc").UplcProgramV2I} UplcProgramV2I
+ * @typedef {import("@helios-lang/uplc").UplcSourceMapJsonSafe} UplcSourceMapJsonSafe
+ * @typedef {import("../cast/index.js").CastConfig} CastConfig
+ * @typedef {import("../codegen/LoadedModule.js").LoadedModule} LoadedModule
+ * @typedef {import("../codegen/LoadedValidator.js").LoadedValidator} LoadedValidator
+ * @typedef {import("./ContractContext.js").AnyContractValidatorContext} AnyContractValidatorContext
+ */
+
+/**
+ * @typedef {{
+ *   debug?: boolean
+ *   validators: {[name: string]: AnyContractValidatorContext}
+ *   userFuncs: {[name: string]: UplcProgram}
+ * }} CacheEntry
+ */
+
+/**
+ * @typedef {{[name: string]: {
+ *     purpose: "minting" | "spending" | "staking" | "mixed"
+ *     bytes: number[]
+ *     unoptimizedCborHex?: string
+ *     unoptimizedIr?: string
+ *     unoptimizedSourceMap?: UplcSourceMapJsonSafe
+ *     optimizedCborHex: string
+ *     optimizedIr?: string
+ *     optimizedSourceMap?: UplcSourceMapJsonSafe
+ *     plutusVersion: PlutusVersion
+ *     castConfig: CastConfig
+ *     datum?: TypeSchema
+ *     redeemer: TypeSchema
+ *   }}} CacheEntryValidatorsJson
+ */
+
+/**
+ * @typedef {{[name: string]: {
+ *   unoptimizedCborHex?: string
+ *   unoptimizedIr?: string
+ *   unoptimizedSourceMap?: UplcSourceMapJsonSafe
+ *   optimizedCborHex: string
+ *   optimizedIr?: string
+ *   optimizedSourceMap?: UplcSourceMapJsonSafe
+ *   plutusVersion: PlutusVersion
+ * }}} CacheEntryUserFuncsJson
+ */
+
+/**
+ * @typedef {{
+ *   debug?: boolean
+ *   validators: CacheEntryValidatorsJson
+ *   userFuncs: CacheEntryUserFuncsJson
+ * }} CacheEntryJson
+ */
+
+/**
+ * @param {CacheEntry} entry
+ * @returns {CacheEntryJson}
+ */
+export function cacheEntryToJsonSafe(entry) {
+    /**
+     * @type {CacheEntryValidatorsJson}
+     */
+    const resValidators = {}
+
+    /**
+     * @type {CacheEntryUserFuncsJson}
+     */
+    const resUserFuncs = {}
+
+    for (let name in entry.validators) {
+        const hash = entry.validators[name]
+
+        const purpose =
+            hash instanceof ValidatorHash
+                ? "spending"
+                : hash instanceof MintingPolicyHash
+                  ? "minting"
+                  : hash instanceof StakingValidatorHash
+                    ? "staking"
+                    : hash instanceof ScriptHash
+                      ? "mixed"
+                      : "unknown"
+        if (purpose == "unknown") {
+            throw new Error("unhandled hash type")
+        }
+
+        const redeemer =
+            hash.context.redeemer instanceof Cast ? hash.context.redeemer : None
+
+        if (!redeemer) {
+            throw new Error("Redeemer is not a Cast type")
+        }
+
+        /**
+         * @type {Option<Cast>}
+         */
+        let datum = None
+
+        if (hash.context.datum && hash.context.datum instanceof Cast) {
+            datum = hash.context.datum
+        }
+
+        if (["spending", "mixed"].includes(purpose) && !datum) {
+            throw new Error("Datum is not a Cast type")
+        }
+
+        /**
+         * @type {UplcProgramV1I | UplcProgramV2I}
+         */
+        const program = hash.context.program
+
+        resValidators[name] = {
+            purpose: purpose,
+            bytes: hash.bytes,
+            optimizedCborHex: bytesToHex(program.toCbor()),
+            unoptimizedCborHex: program.alt
+                ? bytesToHex(program.alt.toCbor())
+                : undefined,
+            optimizedIr:
+                /** @type {UplcProgramV2I} */ (program).ir ?? undefined,
+            unoptimizedIr:
+                /** @type {UplcProgramV2I} */ (program).alt?.ir ?? undefined,
+            optimizedSourceMap: UplcSourceMap.fromUplcTerm(
+                program.root
+            ).toJsonSafe(),
+            unoptimizedSourceMap: program.alt
+                ? UplcSourceMap.fromUplcTerm(program.alt.root).toJsonSafe()
+                : undefined,
+            plutusVersion: hash.context.program.plutusVersion,
+            castConfig: redeemer.config,
+            redeemer: redeemer.schema,
+            datum: datum?.schema
+        }
+    }
+
+    for (let name in entry.userFuncs) {
+        const userFunc = entry.userFuncs[name]
+
+        resUserFuncs[name] = {
+            optimizedCborHex: bytesToHex(userFunc.toCbor()),
+            unoptimizedCborHex: /** @type {UplcProgramV2I} */ (userFunc).alt
+                ? bytesToHex(
+                      /** @type {UplcProgramV2I} */ (userFunc).alt.toCbor()
+                  )
+                : undefined,
+            optimizedIr: userFunc.ir ?? undefined,
+            unoptimizedIr: userFunc.alt?.ir ?? undefined,
+            optimizedSourceMap: UplcSourceMap.fromUplcTerm(
+                userFunc.root
+            ).toJsonSafe(),
+            unoptimizedSourceMap: userFunc.alt
+                ? UplcSourceMap.fromUplcTerm(userFunc.alt.root).toJsonSafe()
+                : undefined,
+            plutusVersion: userFunc.plutusVersion
+        }
+    }
+
+    return {
+        debug: entry.debug ?? false,
+        validators: resValidators,
+        userFuncs: resUserFuncs
+    }
+}
+
+/**
+ * @param {CacheEntryJson} entry
+ * @returns {CacheEntry}
+ */
+export function cacheEntryFromJson(entry) {
+    /**
+     * @type {CacheEntry}
+     */
+    const res = {
+        debug: entry.debug ?? false,
+        validators: {},
+        userFuncs: {}
+    }
+
+    for (let name in entry.validators) {
+        const props = entry.validators[name]
+
+        /**
+         * @type {UplcProgram}
+         */
+        let program =
+            props.plutusVersion == "PlutusScriptV1"
+                ? UplcProgramV1.fromCbor(props.optimizedCborHex, {
+                      ir: props.optimizedIr,
+                      sourceMap: props.optimizedSourceMap
+                  })
+                : UplcProgramV2.fromCbor(props.optimizedCborHex, {
+                      ir: props.optimizedIr,
+                      sourceMap: props.optimizedSourceMap
+                  })
+
+        if (props.unoptimizedCborHex) {
+            if (program.plutusVersion == "PlutusScriptV1") {
+                program = program.withAlt(
+                    UplcProgramV1.fromCbor(props.unoptimizedCborHex, {
+                        ir: props.unoptimizedIr,
+                        sourceMap: props.unoptimizedSourceMap
+                    })
+                )
+            } else if (program.plutusVersion == "PlutusScriptV2") {
+                program = program.withAlt(
+                    UplcProgramV2.fromCbor(props.unoptimizedCborHex, {
+                        ir: props.unoptimizedIr,
+                        sourceMap: props.unoptimizedSourceMap
+                    })
+                )
+            } else {
+                throw new Error("unhandled Plutus version")
+            }
+        }
+
+        let redeemer = new Cast(props.redeemer, props.castConfig)
+
+        switch (props.purpose) {
+            case "spending": {
+                res.validators[name] = new ValidatorHash(props.bytes, {
+                    datum: new Cast(expectSome(props.datum), props.castConfig),
+                    redeemer: redeemer,
+                    program: program
+                })
+                break
+            }
+            case "minting": {
+                res.validators[name] = new MintingPolicyHash(props.bytes, {
+                    redeemer: redeemer,
+                    program: program
+                })
+                break
+            }
+            case "staking": {
+                res.validators[name] = new StakingValidatorHash(props.bytes, {
+                    redeemer: redeemer,
+                    program: program
+                })
+                break
+            }
+            case "mixed": {
+                res.validators[name] = new ScriptHash(props.bytes, {
+                    datum: new Cast(expectSome(props.datum), props.castConfig),
+                    redeemer: redeemer,
+                    program: program
+                })
+                break
+            }
+            default:
+                throw new Error("unhandled purpose")
+        }
+    }
+
+    for (let name in entry.userFuncs) {
+        const props = entry.userFuncs[name]
+
+        /**
+         * @type {UplcProgram}
+         */
+        let program =
+            props.plutusVersion == "PlutusScriptV1"
+                ? UplcProgramV1.fromCbor(props.optimizedCborHex, {
+                      ir: props.optimizedIr,
+                      sourceMap: props.optimizedSourceMap
+                  })
+                : UplcProgramV2.fromCbor(props.optimizedCborHex, {
+                      ir: props.optimizedIr,
+                      sourceMap: props.optimizedSourceMap
+                  })
+
+        if (props.unoptimizedCborHex) {
+            if (program.plutusVersion == "PlutusScriptV1") {
+                program = program.withAlt(
+                    UplcProgramV1.fromCbor(props.unoptimizedCborHex, {
+                        ir: props.unoptimizedIr,
+                        sourceMap: props.unoptimizedSourceMap
+                    })
+                )
+            } else if (program.plutusVersion == "PlutusScriptV2") {
+                program = program.withAlt(
+                    UplcProgramV2.fromCbor(props.unoptimizedCborHex, {
+                        ir: props.unoptimizedIr,
+                        sourceMap: props.unoptimizedSourceMap
+                    })
+                )
+            } else {
+                throw new Error("unhandled Plutus version")
+            }
+        }
+        res.userFuncs[name] = program
+    }
+
+    return res
+}

package/src/context/ContractContextBuilder.js

@@ -47,6 +47,7 @@ export class ContractContextBuilder {
     validators
 
     /**
+     * @private
      * @readonly
      * @type {Ms}
      */
@@ -118,12 +119,22 @@ export class ContractContextBuilder {
         const castConfig = { isMainnet: props.isMainnet }
         const lib = loadCompilerLib()
 
+        // generate a cache key
+        const key = contractContextCache.genCacheKey({
+            version: lib.version,
+            debug: !!props.debug,
+            isMainnet: props.isMainnet,
+            validators: this.validators,
+            modules: this.modules,
+            parameters: props.parameters ?? {}
+        })
+
         const dagCompiler = new DagCompiler(lib, {
             debug: props.debug ?? false,
             ...castConfig
         })
 
-        const cached = contractContextCache.shift()
+        const cached = contractContextCache.get(key)
 
         const compiled =
             cached ||
@@ -134,8 +145,7 @@ export class ContractContextBuilder {
                 props.expectedHashes
             )
 
-        // TODO: adapt to use generic cache interface
-        contractContextCache.push(compiled)
+        contractContextCache.set(key, compiled)
 
         if (props.dumpHashes) {
             for (let name in compiled.validators) {

package/src/context/ContractContextCache.js

@@ -1,89 +1,57 @@
-import { bytesToHex } from "@helios-lang/codec-utils"
-import {
-    MintingPolicyHash,
-    ScriptHash,
-    StakingValidatorHash,
-    ValidatorHash
-} from "@helios-lang/ledger"
-import { None, expectSome } from "@helios-lang/type-utils"
-import { UplcProgramV1, UplcProgramV2, UplcSourceMap } from "@helios-lang/uplc"
-import { Cast } from "../cast/Cast.js"
+import { bytesToHex, encodeUtf8 } from "@helios-lang/codec-utils"
+import { blake2b } from "@helios-lang/crypto"
+import { JSON, None } from "@helios-lang/type-utils"
+import { cacheEntryFromJson, cacheEntryToJsonSafe } from "./CacheEntry.js"
 
 /**
- * @typedef {import("@helios-lang/uplc").PlutusVersion} PlutusVersion
+ * @typedef {import("@helios-lang/uplc").UplcData} UplcData
  * @typedef {import("@helios-lang/uplc").UplcProgram} UplcProgram
- * @typedef {import("@helios-lang/uplc").UplcProgramV1I} UplcProgramV1I
- * @typedef {import("@helios-lang/uplc").UplcProgramV2I} UplcProgramV2I
- * @typedef {import("@helios-lang/uplc").UplcSourceMapJsonSafe} UplcSourceMapJsonSafe
- * @typedef {import("../cast/index.js").CastConfig} CastConfig
- * @typedef {import("../codegen/index.js").TypeSchema} TypeSchema
- * @typedef {import("./ContractContext.js").AnyContractValidatorContext} AnyContractValidatorContext
+ * @typedef {import("../codegen/LoadedModule.js").LoadedModule} LoadedModule
+ * @typedef {import("../codegen/LoadedValidator.js").LoadedValidator} LoadedValidator
+ * @typedef {import("./CacheEntry.js").CacheEntry} CacheEntry
+ * @typedef {import("./CacheEntry.js").CacheEntryJson} CacheEntryJson
+ * @typedef {import("./CacheEntry.js").CacheEntryUserFuncsJson} CacheEntryUserFuncsJson
+ * @typedef {import("./CacheEntry.js").CacheEntryValidatorsJson} CacheEntryValidatorsJson
  */
 
 /**
  * @typedef {{
- *   debug?: boolean
- *   validators: {[name: string]: AnyContractValidatorContext}
- *   userFuncs: {[name: string]: UplcProgram}
- * }} CacheEntry
- */
-
-/**
- * @typedef {{[name: string]: {
- *     purpose: "minting" | "spending" | "staking" | "mixed"
- *     bytes: number[]
- *     unoptimizedCborHex?: string
- *     unoptimizedIr?: string
- *     unoptimizedSourceMap?: UplcSourceMapJsonSafe
- *     optimizedCborHex: string
- *     optimizedIr?: string
- *     optimizedSourceMap?: UplcSourceMapJsonSafe
- *     plutusVersion: PlutusVersion
- *     castConfig: CastConfig
- *     datum?: TypeSchema
- *     redeemer: TypeSchema
- *   }}} CacheEntryValidatorsJson
- */
-
-/**
- * @typedef {{[name: string]: {
- *   unoptimizedCborHex?: string
- *   unoptimizedIr?: string
- *   unoptimizedSourceMap?: UplcSourceMapJsonSafe
- *   optimizedCborHex: string
- *   optimizedIr?: string
- *   optimizedSourceMap?: UplcSourceMapJsonSafe
- *   plutusVersion: PlutusVersion
- * }}} CacheEntryUserFuncsJson
- */
-
-/**
- * @typedef {{
- *   debug?: boolean
- *   validators: CacheEntryValidatorsJson
- *   userFuncs: CacheEntryUserFuncsJson
- * }} CacheEntryJson
+ *   has(key: string): boolean
+ *   get(key: string): JsonSafe
+ *   set(key: string, entry: JsonSafe): void
+ * }} ExplicitCache
  */
 
 class ContractContextCache {
     /**
+     * Used by esbuild-plugin
+     * @private
      * @type {CacheEntry[]}
      */
-    cache
+    positionalCache
+
+    /**
+     * Explicitly specified by user by calling setBuildCache()
+     * @readwrite
+     * @type {Option<ExplicitCache>}
+     */
+    explicitCache
 
     /**
      * Load count
+     * @private
      * @type {number}
      */
     i
 
     /**
+     * @private
      * @type {boolean}
      */
     enabled
 
     constructor() {
-        this.cache = []
+        this.positionalCache = []
         this.enabled = false
         this.i = 0
     }
@@ -93,292 +61,94 @@ class ContractContextCache {
     }
 
     /**
-     * @param {CacheEntryJson[]} json
+     * Key is only generated if the explicitCache is set
+     * @param {{
+     *   version: string
+     *   debug: boolean
+     *   isMainnet: boolean
+     *   validators: Record<string, LoadedValidator>
+     *   modules: Record<string, LoadedModule>
+     *   parameters: Record<string, UplcData>
+     * }} props
+     * @returns {string}
      */
-    load(json) {
-        this.cache = json.map((entry) => {
-            /**
-             * @type {CacheEntry}
-             */
-            const res = {
-                debug: entry.debug ?? false,
-                validators: {},
-                userFuncs: {}
+    genCacheKey(props) {
+        if (this.explicitCache) {
+            const obj = {
+                version: props.version,
+                debug: props.debug,
+                isMainnet: props.isMainnet,
+                validators: Object.keys(props.validators)
+                    .sort()
+                    .map((k) => props.validators[k].$sourceCode),
+                modules: Object.keys(props.modules)
+                    .sort()
+                    .map((k) => props.modules[k].$sourceCode),
+                parameters: Object.keys(props.parameters)
+                    .sort()
+                    .map((k) => props.parameters[k].toSchemaJson())
             }
 
-            for (let name in entry.validators) {
-                const props = entry.validators[name]
-
-                /**
-                 * @type {UplcProgram}
-                 */
-                let program =
-                    props.plutusVersion == "PlutusScriptV1"
-                        ? UplcProgramV1.fromCbor(props.optimizedCborHex, {
-                              ir: props.optimizedIr,
-                              sourceMap: props.optimizedSourceMap
-                          })
-                        : UplcProgramV2.fromCbor(props.optimizedCborHex, {
-                              ir: props.optimizedIr,
-                              sourceMap: props.optimizedSourceMap
-                          })
-
-                if (props.unoptimizedCborHex) {
-                    if (program.plutusVersion == "PlutusScriptV1") {
-                        program = program.withAlt(
-                            UplcProgramV1.fromCbor(props.unoptimizedCborHex, {
-                                ir: props.unoptimizedIr,
-                                sourceMap: props.unoptimizedSourceMap
-                            })
-                        )
-                    } else if (program.plutusVersion == "PlutusScriptV2") {
-                        program = program.withAlt(
-                            UplcProgramV2.fromCbor(props.unoptimizedCborHex, {
-                                ir: props.unoptimizedIr,
-                                sourceMap: props.unoptimizedSourceMap
-                            })
-                        )
-                    } else {
-                        throw new Error("unhandled Plutus version")
-                    }
-                }
-
-                let redeemer = new Cast(props.redeemer, props.castConfig)
-
-                switch (props.purpose) {
-                    case "spending": {
-                        res.validators[name] = new ValidatorHash(props.bytes, {
-                            datum: new Cast(
-                                expectSome(props.datum),
-                                props.castConfig
-                            ),
-                            redeemer: redeemer,
-                            program: program
-                        })
-                        break
-                    }
-                    case "minting": {
-                        res.validators[name] = new MintingPolicyHash(
-                            props.bytes,
-                            {
-                                redeemer: redeemer,
-                                program: program
-                            }
-                        )
-                        break
-                    }
-                    case "staking": {
-                        res.validators[name] = new StakingValidatorHash(
-                            props.bytes,
-                            {
-                                redeemer: redeemer,
-                                program: program
-                            }
-                        )
-                        break
-                    }
-                    case "mixed": {
-                        res.validators[name] = new ScriptHash(props.bytes, {
-                            datum: new Cast(
-                                expectSome(props.datum),
-                                props.castConfig
-                            ),
-                            redeemer: redeemer,
-                            program: program
-                        })
-                        break
-                    }
-                    default:
-                        throw new Error("unhandled purpose")
-                }
-            }
+            // TODO: if this hashing method is slow fall back to system defined hashing
+            const digest = blake2b(encodeUtf8(JSON.stringify(obj)))
 
-            for (let name in entry.userFuncs) {
-                const props = entry.userFuncs[name]
-
-                /**
-                 * @type {UplcProgram}
-                 */
-                let program =
-                    props.plutusVersion == "PlutusScriptV1"
-                        ? UplcProgramV1.fromCbor(props.optimizedCborHex, {
-                              ir: props.optimizedIr,
-                              sourceMap: props.optimizedSourceMap
-                          })
-                        : UplcProgramV2.fromCbor(props.optimizedCborHex, {
-                              ir: props.optimizedIr,
-                              sourceMap: props.optimizedSourceMap
-                          })
-
-                if (props.unoptimizedCborHex) {
-                    if (program.plutusVersion == "PlutusScriptV1") {
-                        program = program.withAlt(
-                            UplcProgramV1.fromCbor(props.unoptimizedCborHex, {
-                                ir: props.unoptimizedIr,
-                                sourceMap: props.unoptimizedSourceMap
-                            })
-                        )
-                    } else if (program.plutusVersion == "PlutusScriptV2") {
-                        program = program.withAlt(
-                            UplcProgramV2.fromCbor(props.unoptimizedCborHex, {
-                                ir: props.unoptimizedIr,
-                                sourceMap: props.unoptimizedSourceMap
-                            })
-                        )
-                    } else {
-                        throw new Error("unhandled Plutus version")
-                    }
-                }
-                res.userFuncs[name] = program
-            }
+            return bytesToHex(digest)
+        } else {
+            return ""
+        }
+    }
 
-            return res
-        })
+    /**
+     * @param {CacheEntryJson[]} json
+     */
+    load(json) {
+        this.positionalCache = json.map(cacheEntryFromJson)
     }
 
     /**
-     * @param {CacheEntry} hashes
+     * @param {string} key - empty string is used to set positional cache (eg. for esbuild-plugn)
+     * @param {CacheEntry} entry
      */
-    push(hashes) {
-        if (this.enabled) {
-            this.cache.push(hashes)
+    set(key, entry) {
+        if (key != "" && this.explicitCache) {
+            this.explicitCache.set(key, cacheEntryToJsonSafe(entry))
+        } else if (this.enabled) {
+            this.positionalCache.push(entry)
         }
     }
 
     /**
+     * @param {string} key - empty string is used to access positional cache (eg. for esbuild-plugn)
      * @returns {Option<CacheEntry>}
      */
-    shift() {
-        if (this.i >= this.cache.length) {
+    get(key) {
+        if (key != "") {
+            if (this.explicitCache && this.explicitCache.has(key)) {
+                return cacheEntryFromJson(
+                    /** @type {CacheEntryJson} */ (this.explicitCache.get(key))
+                )
+            }
+
             return None
-        }
+        } else {
+            if (this.i >= this.positionalCache.length) {
+                // TODO: lookup in explicitCache
+                return None
+            }
 
-        const res = this.cache[this.i]
+            const res = this.positionalCache[this.i]
 
-        this.i += 1
+            this.i += 1
 
-        return res
+            return res
+        }
     }
 
     /**
      * @return {CacheEntryJson[]}
      */
     toJson() {
-        return this.cache.map((entry) => {
-            /**
-             * @type {CacheEntryValidatorsJson}
-             */
-            const resValidators = {}
-
-            /**
-             * @type {CacheEntryUserFuncsJson}
-             */
-            const resUserFuncs = {}
-
-            for (let name in entry.validators) {
-                const hash = entry.validators[name]
-
-                const purpose =
-                    hash instanceof ValidatorHash
-                        ? "spending"
-                        : hash instanceof MintingPolicyHash
-                          ? "minting"
-                          : hash instanceof StakingValidatorHash
-                            ? "staking"
-                            : hash instanceof ScriptHash
-                              ? "mixed"
-                              : "unknown"
-                if (purpose == "unknown") {
-                    throw new Error("unhandled hash type")
-                }
-
-                const redeemer =
-                    hash.context.redeemer instanceof Cast
-                        ? hash.context.redeemer
-                        : None
-
-                if (!redeemer) {
-                    throw new Error("Redeemer is not a Cast type")
-                }
-
-                /**
-                 * @type {Option<Cast>}
-                 */
-                let datum = None
-
-                if (hash.context.datum && hash.context.datum instanceof Cast) {
-                    datum = hash.context.datum
-                }
-
-                if (["spending", "mixed"].includes(purpose) && !datum) {
-                    throw new Error("Datum is not a Cast type")
-                }
-
-                /**
-                 * @type {UplcProgramV1I | UplcProgramV2I}
-                 */
-                const program = hash.context.program
-
-                resValidators[name] = {
-                    purpose: purpose,
-                    bytes: hash.bytes,
-                    optimizedCborHex: bytesToHex(program.toCbor()),
-                    unoptimizedCborHex: program.alt
-                        ? bytesToHex(program.alt.toCbor())
-                        : undefined,
-                    optimizedIr:
-                        /** @type {UplcProgramV2I} */ (program).ir ?? undefined,
-                    unoptimizedIr:
-                        /** @type {UplcProgramV2I} */ (program).alt?.ir ??
-                        undefined,
-                    optimizedSourceMap: UplcSourceMap.fromUplcTerm(
-                        program.root
-                    ).toJsonSafe(),
-                    unoptimizedSourceMap: program.alt
-                        ? UplcSourceMap.fromUplcTerm(
-                              program.alt.root
-                          ).toJsonSafe()
-                        : undefined,
-                    plutusVersion: hash.context.program.plutusVersion,
-                    castConfig: redeemer.config,
-                    redeemer: redeemer.schema,
-                    datum: datum?.schema
-                }
-            }
-
-            for (let name in entry.userFuncs) {
-                const userFunc = entry.userFuncs[name]
-
-                resUserFuncs[name] = {
-                    optimizedCborHex: bytesToHex(userFunc.toCbor()),
-                    unoptimizedCborHex: /** @type {UplcProgramV2I} */ (userFunc)
-                        .alt
-                        ? bytesToHex(
-                              /** @type {UplcProgramV2I} */ (
-                                  userFunc
-                              ).alt.toCbor()
-                          )
-                        : undefined,
-                    optimizedIr: userFunc.ir ?? undefined,
-                    unoptimizedIr: userFunc.alt?.ir ?? undefined,
-                    optimizedSourceMap: UplcSourceMap.fromUplcTerm(
-                        userFunc.root
-                    ).toJsonSafe(),
-                    unoptimizedSourceMap: userFunc.alt
-                        ? UplcSourceMap.fromUplcTerm(
-                              userFunc.alt.root
-                          ).toJsonSafe()
-                        : undefined,
-                    plutusVersion: userFunc.plutusVersion
-                }
-            }
-
-            return {
-                debug: entry.debug ?? false,
-                validators: resValidators,
-                userFuncs: resUserFuncs
-            }
-        })
+        return this.positionalCache.map(cacheEntryToJsonSafe)
     }
 }
 

package/src/context/set-fs-build-cache.js

@@ -0,0 +1,81 @@
+import { contractContextCache } from "./ContractContextCache.js"
+
+/**
+ * @typedef {import("./ContractContextCache.js").ExplicitCache} ExplicitCache
+ */
+
+// uses same storage strategy as esbuild-plugin
+/**
+ * @implements {ExplicitCache}
+ */
+class FileSystemCache {
+    /**
+     * @private
+     * @type {typeof import("node:fs")}
+     */
+    fs
+
+    /**
+     * @private
+     * @type {typeof import("node:os")}
+     */
+    os
+
+    /**
+     * @private
+     * @type {typeof import("node:path")}
+     */
+    path
+
+    /**
+     * @private
+     * @type {string}
+     */
+    cacheDir
+
+    constructor() {
+        this.fs = require("node:fs")
+        this.os = require("node:os")
+        this.path = require("node:path")
+        this.cacheDir = this.path.join(this.os.tmpdir(), "helios-cache")
+
+        if (!this.fs.existsSync(this.cacheDir)) {
+            this.fs.mkdirSync(this.cacheDir, {
+                recursive: true
+            })
+        }
+    }
+
+    /**
+     * @private
+     * @param {string} key
+     */
+    genPath(key) {
+        return this.path.join(this.cacheDir, key + ".json")
+    }
+
+    /**
+     * @param {string} key
+     */
+    has(key) {
+        return this.fs.existsSync(this.genPath(key))
+    }
+
+    /**
+     * @param {string} key
+     * @returns {JsonSafe}
+     */
+    get(key) {
+        return JSON.parse(this.fs.readFileSync(this.genPath(key)).toString())
+    }
+
+    /**
+     * @param {string} key
+     * @param {JsonSafe} obj
+     */
+    set(key, obj) {
+        this.fs.writeFileSync(this.genPath(key), JSON.stringify(obj))
+    }
+}
+
+contractContextCache.explicitCache = new FileSystemCache()

package/src/index.js

@@ -3,3 +3,8 @@ export * from "./context/index.js"
 export { typeCheckFiles, typeCheckScripts } from "./compiler/ops.js"
 export { LoadedScriptsWriter } from "./codegen/LoadedScriptsWriter.js"
 export { loadCompilerLib } from "./compiler/ops.js"
+
+/**
+ * @typedef {import("./codegen/index.js").LoadedValidator} LoadedValidator
+ * @typedef {import("./codegen/index.js").LoadedModule} LoadedModule
+ */

package/types/context/CacheEntry.d.ts

@@ -0,0 +1,117 @@
+/**
+ * @typedef {import("@helios-lang/type-utils").TypeSchema} TypeSchema
+ * @typedef {import("@helios-lang/uplc").UplcData} UplcData
+ * @typedef {import("@helios-lang/uplc").PlutusVersion} PlutusVersion
+ * @typedef {import("@helios-lang/uplc").UplcProgram} UplcProgram
+ * @typedef {import("@helios-lang/uplc").UplcProgramV1I} UplcProgramV1I
+ * @typedef {import("@helios-lang/uplc").UplcProgramV2I} UplcProgramV2I
+ * @typedef {import("@helios-lang/uplc").UplcSourceMapJsonSafe} UplcSourceMapJsonSafe
+ * @typedef {import("../cast/index.js").CastConfig} CastConfig
+ * @typedef {import("../codegen/LoadedModule.js").LoadedModule} LoadedModule
+ * @typedef {import("../codegen/LoadedValidator.js").LoadedValidator} LoadedValidator
+ * @typedef {import("./ContractContext.js").AnyContractValidatorContext} AnyContractValidatorContext
+ */
+/**
+ * @typedef {{
+ *   debug?: boolean
+ *   validators: {[name: string]: AnyContractValidatorContext}
+ *   userFuncs: {[name: string]: UplcProgram}
+ * }} CacheEntry
+ */
+/**
+ * @typedef {{[name: string]: {
+ *     purpose: "minting" | "spending" | "staking" | "mixed"
+ *     bytes: number[]
+ *     unoptimizedCborHex?: string
+ *     unoptimizedIr?: string
+ *     unoptimizedSourceMap?: UplcSourceMapJsonSafe
+ *     optimizedCborHex: string
+ *     optimizedIr?: string
+ *     optimizedSourceMap?: UplcSourceMapJsonSafe
+ *     plutusVersion: PlutusVersion
+ *     castConfig: CastConfig
+ *     datum?: TypeSchema
+ *     redeemer: TypeSchema
+ *   }}} CacheEntryValidatorsJson
+ */
+/**
+ * @typedef {{[name: string]: {
+ *   unoptimizedCborHex?: string
+ *   unoptimizedIr?: string
+ *   unoptimizedSourceMap?: UplcSourceMapJsonSafe
+ *   optimizedCborHex: string
+ *   optimizedIr?: string
+ *   optimizedSourceMap?: UplcSourceMapJsonSafe
+ *   plutusVersion: PlutusVersion
+ * }}} CacheEntryUserFuncsJson
+ */
+/**
+ * @typedef {{
+ *   debug?: boolean
+ *   validators: CacheEntryValidatorsJson
+ *   userFuncs: CacheEntryUserFuncsJson
+ * }} CacheEntryJson
+ */
+/**
+ * @param {CacheEntry} entry
+ * @returns {CacheEntryJson}
+ */
+export function cacheEntryToJsonSafe(entry: CacheEntry): CacheEntryJson;
+/**
+ * @param {CacheEntryJson} entry
+ * @returns {CacheEntry}
+ */
+export function cacheEntryFromJson(entry: CacheEntryJson): CacheEntry;
+export type TypeSchema = import("@helios-lang/type-utils").TypeSchema;
+export type UplcData = import("@helios-lang/uplc").UplcData;
+export type PlutusVersion = import("@helios-lang/uplc").PlutusVersion;
+export type UplcProgram = import("@helios-lang/uplc").UplcProgram;
+export type UplcProgramV1I = import("@helios-lang/uplc").UplcProgramV1I;
+export type UplcProgramV2I = import("@helios-lang/uplc").UplcProgramV2I;
+export type UplcSourceMapJsonSafe = import("@helios-lang/uplc").UplcSourceMapJsonSafe;
+export type CastConfig = import("../cast/index.js").CastConfig;
+export type LoadedModule = import("../codegen/LoadedModule.js").LoadedModule;
+export type LoadedValidator = import("../codegen/LoadedValidator.js").LoadedValidator;
+export type AnyContractValidatorContext = import("./ContractContext.js").AnyContractValidatorContext;
+export type CacheEntry = {
+    debug?: boolean;
+    validators: {
+        [name: string]: AnyContractValidatorContext;
+    };
+    userFuncs: {
+        [name: string]: UplcProgram;
+    };
+};
+export type CacheEntryValidatorsJson = {
+    [name: string]: {
+        purpose: "minting" | "spending" | "staking" | "mixed";
+        bytes: number[];
+        unoptimizedCborHex?: string;
+        unoptimizedIr?: string;
+        unoptimizedSourceMap?: UplcSourceMapJsonSafe;
+        optimizedCborHex: string;
+        optimizedIr?: string;
+        optimizedSourceMap?: UplcSourceMapJsonSafe;
+        plutusVersion: PlutusVersion;
+        castConfig: CastConfig;
+        datum?: TypeSchema;
+        redeemer: TypeSchema;
+    };
+};
+export type CacheEntryUserFuncsJson = {
+    [name: string]: {
+        unoptimizedCborHex?: string;
+        unoptimizedIr?: string;
+        unoptimizedSourceMap?: UplcSourceMapJsonSafe;
+        optimizedCborHex: string;
+        optimizedIr?: string;
+        optimizedSourceMap?: UplcSourceMapJsonSafe;
+        plutusVersion: PlutusVersion;
+    };
+};
+export type CacheEntryJson = {
+    debug?: boolean;
+    validators: CacheEntryValidatorsJson;
+    userFuncs: CacheEntryUserFuncsJson;
+};
+//# sourceMappingURL=CacheEntry.d.ts.map

package/types/context/CacheEntry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CacheEntry.d.ts","sourceRoot":"","sources":["../../src/context/CacheEntry.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;GAYG;AAEH;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;;;;;GAUG;AAEH;;;;;;GAMG;AAEH;;;GAGG;AACH,4CAHW,UAAU,GACR,cAAc,CA0G1B;AAED;;;GAGG;AACH,0CAHW,cAAc,GACZ,UAAU,CA+HtB;yBAzSY,OAAO,yBAAyB,EAAE,UAAU;uBAC5C,OAAO,mBAAmB,EAAE,QAAQ;4BACpC,OAAO,mBAAmB,EAAE,aAAa;0BACzC,OAAO,mBAAmB,EAAE,WAAW;6BACvC,OAAO,mBAAmB,EAAE,cAAc;6BAC1C,OAAO,mBAAmB,EAAE,cAAc;oCAC1C,OAAO,mBAAmB,EAAE,qBAAqB;yBACjD,OAAO,kBAAkB,EAAE,UAAU;2BACrC,OAAO,4BAA4B,EAAE,YAAY;8BACjD,OAAO,+BAA+B,EAAE,eAAe;0CACvD,OAAO,sBAAsB,EAAE,2BAA2B;yBAI1D;IACR,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,UAAU,EAAE;QAAC,CAAC,IAAI,EAAE,MAAM,GAAG,2BAA2B,CAAA;KAAC,CAAA;IACzD,SAAS,EAAE;QAAC,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAAA;KAAC,CAAA;CACzC;uCAIS;IAAC,CAAC,IAAI,EAAE,MAAM,GAAG;QACvB,OAAO,EAAE,SAAS,GAAG,UAAU,GAAG,SAAS,GAAG,OAAO,CAAA;QACrD,KAAK,EAAE,MAAM,EAAE,CAAA;QACf,kBAAkB,CAAC,EAAE,MAAM,CAAA;QAC3B,aAAa,CAAC,EAAE,MAAM,CAAA;QACtB,oBAAoB,CAAC,EAAE,qBAAqB,CAAA;QAC5C,gBAAgB,EAAE,MAAM,CAAA;QACxB,WAAW,CAAC,EAAE,MAAM,CAAA;QACpB,kBAAkB,CAAC,EAAE,qBAAqB,CAAA;QAC1C,aAAa,EAAE,aAAa,CAAA;QAC5B,UAAU,EAAE,UAAU,CAAA;QACtB,KAAK,CAAC,EAAE,UAAU,CAAA;QAClB,QAAQ,EAAE,UAAU,CAAA;KACrB,CAAA;CAAC;sCAIM;IAAC,CAAC,IAAI,EAAE,MAAM,GAAG;QACzB,kBAAkB,CAAC,EAAE,MAAM,CAAA;QAC3B,aAAa,CAAC,EAAE,MAAM,CAAA;QACtB,oBAAoB,CAAC,EAAE,qBAAqB,CAAA;QAC5C,gBAAgB,EAAE,MAAM,CAAA;QACxB,WAAW,CAAC,EAAE,MAAM,CAAA;QACpB,kBAAkB,CAAC,EAAE,qBAAqB,CAAA;QAC1C,aAAa,EAAE,aAAa,CAAA;KAC7B,CAAA;CAAC;6BAIQ;IACR,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,UAAU,EAAE,wBAAwB,CAAA;IACpC,SAAS,EAAE,uBAAuB,CAAA;CACnC"}

package/types/context/ContractContextBuilder.d.ts

@@ -50,10 +50,11 @@ export class ContractContextBuilder<Vs extends {
      */
     private readonly validators;
     /**
+     * @private
      * @readonly
      * @type {Ms}
      */
-    readonly modules: Ms;
+    private readonly modules;
     /**
      * @template {LoadedValidator} V
      * @param {V} validator

package/types/context/ContractContextBuilder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ContractContextBuilder.d.ts","sourceRoot":"","sources":["../../src/context/ContractContextBuilder.js"],"names":[],"mappings":"AAMA;;;;;;GAMG;AAEH;;;GAGG;AAEH;;;;GAIG;AAEH;;;;;;;;;GASG;AAEH;;;GAGG;AACH,oCAHiD,EAAE,SAAtC;IAAE,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAAA;CAAE,EACF,EAAE,SAAnC;IAAE,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAAA;CAAE;IA0BzC;;OAEG;IACH,gBAFa,sBAAsB,CAAC,EAAE,EAAE,EAAE,CAAC,CAI1C;IAfD;;;;OAIG;IACH,sBAGC;IArBD;;;;OAIG;IACH,4BAAU;IAEV;;;OAGG;IACH,kBAFU,EAAE,CAEL;IAmBP;;;;;;;OAOG;IACH,KAP+B,CAAC,SAAlB,eAAgB,aACnB,CAAC,GACC,sBAAsB,CAC9B,EAAE,GAAG,GAAE,CAAe,IAAV,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,GAAC,EAC3B,EAAE,GAAG,mBAAmB,CAAC,CAAC,CAAC,CAC5B,CAeH;IAED;;;;;;;OAOG;IACH,WAP4B,CAAC,SAAf,YAAa,KAChB,CAAC,GACC,sBAAsB,CAC9B,EAAE,EACF,EAAE,GAAG,GAAE,CAAe,IAAV,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,GAAC,CAC5B,CAUH;IAED;;;OAGG;IACH,aAHW,yBAAyB,GACvB,eAAe,CAAC,EAAE,EAAE,EAAE,CAAC,CA6GnC;CACJ;uBAzNY,OAAO,mBAAmB,EAAE,QAAQ;yBACpC,OAAO,kBAAkB,EAAE,UAAU;2BACrC,OAAO,4BAA4B,EAAE,YAAY;8BACjD,OAAO,+BAA+B,EAAE,eAAe;0BACvD,OAAO,sBAAsB,EAAE,WAAW;gCAIxB,CAAC,SAAlB,eAAgB,IACjB,OAAO,+BAA+B,EAAE,mBAAmB,CAAC,CAAC,CAAC;4BAI1B,EAAE,SAAtC;IAAE,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAAA;CAAE,EACF,EAAE,SAAnC;IAAE,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAAA;CAAE,IAChC,OAAO,sBAAsB,EAAE,eAAe,CAAC,EAAE,EAAE,EAAE,CAAC;;;;wCAKtD;IACR,SAAS,EAAE,OAAO,CAAA;IAClB,cAAc,CAAC,EAAE;QAAC,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;KAAC,CAAA;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;IACrC,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB"}
+{"version":3,"file":"ContractContextBuilder.d.ts","sourceRoot":"","sources":["../../src/context/ContractContextBuilder.js"],"names":[],"mappings":"AAMA;;;;;;GAMG;AAEH;;;GAGG;AAEH;;;;GAIG;AAEH;;;;;;;;;GASG;AAEH;;;GAGG;AACH,oCAHiD,EAAE,SAAtC;IAAE,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAAA;CAAE,EACF,EAAE,SAAnC;IAAE,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAAA;CAAE;IA2BzC;;OAEG;IACH,gBAFa,sBAAsB,CAAC,EAAE,EAAE,EAAE,CAAC,CAI1C;IAfD;;;;OAIG;IACH,sBAGC;IAtBD;;;;OAIG;IACH,4BAAU;IAEV;;;;OAIG;IACH,yBAAO;IAmBP;;;;;;;OAOG;IACH,KAP+B,CAAC,SAAlB,eAAgB,aACnB,CAAC,GACC,sBAAsB,CAC9B,EAAE,GAAG,GAAE,CAAe,IAAV,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,GAAC,EAC3B,EAAE,GAAG,mBAAmB,CAAC,CAAC,CAAC,CAC5B,CAeH;IAED;;;;;;;OAOG;IACH,WAP4B,CAAC,SAAf,YAAa,KAChB,CAAC,GACC,sBAAsB,CAC9B,EAAE,EACF,EAAE,GAAG,GAAE,CAAe,IAAV,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,GAAC,CAC5B,CAUH;IAED;;;OAGG;IACH,aAHW,yBAAyB,GACvB,eAAe,CAAC,EAAE,EAAE,EAAE,CAAC,CAsHnC;CACJ;uBAnOY,OAAO,mBAAmB,EAAE,QAAQ;yBACpC,OAAO,kBAAkB,EAAE,UAAU;2BACrC,OAAO,4BAA4B,EAAE,YAAY;8BACjD,OAAO,+BAA+B,EAAE,eAAe;0BACvD,OAAO,sBAAsB,EAAE,WAAW;gCAIxB,CAAC,SAAlB,eAAgB,IACjB,OAAO,+BAA+B,EAAE,mBAAmB,CAAC,CAAC,CAAC;4BAI1B,EAAE,SAAtC;IAAE,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAAA;CAAE,EACF,EAAE,SAAnC;IAAE,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAAA;CAAE,IAChC,OAAO,sBAAsB,EAAE,eAAe,CAAC,EAAE,EAAE,EAAE,CAAC;;;;wCAKtD;IACR,SAAS,EAAE,OAAO,CAAA;IAClB,cAAc,CAAC,EAAE;QAAC,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;KAAC,CAAA;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;IACrC,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB"}

package/types/context/ContractContextCache.d.ts

@@ -1,131 +1,93 @@
 export const contractContextCache: ContractContextCache;
-export type PlutusVersion = import("@helios-lang/uplc").PlutusVersion;
+export type UplcData = import("@helios-lang/uplc").UplcData;
 export type UplcProgram = import("@helios-lang/uplc").UplcProgram;
-export type UplcProgramV1I = import("@helios-lang/uplc").UplcProgramV1I;
-export type UplcProgramV2I = import("@helios-lang/uplc").UplcProgramV2I;
-export type UplcSourceMapJsonSafe = import("@helios-lang/uplc").UplcSourceMapJsonSafe;
-export type CastConfig = import("../cast/index.js").CastConfig;
-export type TypeSchema = import("../codegen/index.js").TypeSchema;
-export type AnyContractValidatorContext = import("./ContractContext.js").AnyContractValidatorContext;
-export type CacheEntry = {
-    debug?: boolean;
-    validators: {
-        [name: string]: AnyContractValidatorContext;
-    };
-    userFuncs: {
-        [name: string]: UplcProgram;
-    };
-};
-export type CacheEntryValidatorsJson = {
-    [name: string]: {
-        purpose: "minting" | "spending" | "staking" | "mixed";
-        bytes: number[];
-        unoptimizedCborHex?: string;
-        unoptimizedIr?: string;
-        unoptimizedSourceMap?: UplcSourceMapJsonSafe;
-        optimizedCborHex: string;
-        optimizedIr?: string;
-        optimizedSourceMap?: UplcSourceMapJsonSafe;
-        plutusVersion: PlutusVersion;
-        castConfig: CastConfig;
-        datum?: TypeSchema;
-        redeemer: TypeSchema;
-    };
-};
-export type CacheEntryUserFuncsJson = {
-    [name: string]: {
-        unoptimizedCborHex?: string;
-        unoptimizedIr?: string;
-        unoptimizedSourceMap?: UplcSourceMapJsonSafe;
-        optimizedCborHex: string;
-        optimizedIr?: string;
-        optimizedSourceMap?: UplcSourceMapJsonSafe;
-        plutusVersion: PlutusVersion;
-    };
-};
-export type CacheEntryJson = {
-    debug?: boolean;
-    validators: CacheEntryValidatorsJson;
-    userFuncs: CacheEntryUserFuncsJson;
+export type LoadedModule = import("../codegen/LoadedModule.js").LoadedModule;
+export type LoadedValidator = import("../codegen/LoadedValidator.js").LoadedValidator;
+export type CacheEntry = import("./CacheEntry.js").CacheEntry;
+export type CacheEntryJson = import("./CacheEntry.js").CacheEntryJson;
+export type CacheEntryUserFuncsJson = import("./CacheEntry.js").CacheEntryUserFuncsJson;
+export type CacheEntryValidatorsJson = import("./CacheEntry.js").CacheEntryValidatorsJson;
+export type ExplicitCache = {
+    has(key: string): boolean;
+    get(key: string): JsonSafe;
+    set(key: string, entry: JsonSafe): void;
 };
 /**
- * @typedef {import("@helios-lang/uplc").PlutusVersion} PlutusVersion
+ * @typedef {import("@helios-lang/uplc").UplcData} UplcData
  * @typedef {import("@helios-lang/uplc").UplcProgram} UplcProgram
- * @typedef {import("@helios-lang/uplc").UplcProgramV1I} UplcProgramV1I
- * @typedef {import("@helios-lang/uplc").UplcProgramV2I} UplcProgramV2I
- * @typedef {import("@helios-lang/uplc").UplcSourceMapJsonSafe} UplcSourceMapJsonSafe
- * @typedef {import("../cast/index.js").CastConfig} CastConfig
- * @typedef {import("../codegen/index.js").TypeSchema} TypeSchema
- * @typedef {import("./ContractContext.js").AnyContractValidatorContext} AnyContractValidatorContext
- */
-/**
- * @typedef {{
- *   debug?: boolean
- *   validators: {[name: string]: AnyContractValidatorContext}
- *   userFuncs: {[name: string]: UplcProgram}
- * }} CacheEntry
- */
-/**
- * @typedef {{[name: string]: {
- *     purpose: "minting" | "spending" | "staking" | "mixed"
- *     bytes: number[]
- *     unoptimizedCborHex?: string
- *     unoptimizedIr?: string
- *     unoptimizedSourceMap?: UplcSourceMapJsonSafe
- *     optimizedCborHex: string
- *     optimizedIr?: string
- *     optimizedSourceMap?: UplcSourceMapJsonSafe
- *     plutusVersion: PlutusVersion
- *     castConfig: CastConfig
- *     datum?: TypeSchema
- *     redeemer: TypeSchema
- *   }}} CacheEntryValidatorsJson
- */
-/**
- * @typedef {{[name: string]: {
- *   unoptimizedCborHex?: string
- *   unoptimizedIr?: string
- *   unoptimizedSourceMap?: UplcSourceMapJsonSafe
- *   optimizedCborHex: string
- *   optimizedIr?: string
- *   optimizedSourceMap?: UplcSourceMapJsonSafe
- *   plutusVersion: PlutusVersion
- * }}} CacheEntryUserFuncsJson
+ * @typedef {import("../codegen/LoadedModule.js").LoadedModule} LoadedModule
+ * @typedef {import("../codegen/LoadedValidator.js").LoadedValidator} LoadedValidator
+ * @typedef {import("./CacheEntry.js").CacheEntry} CacheEntry
+ * @typedef {import("./CacheEntry.js").CacheEntryJson} CacheEntryJson
+ * @typedef {import("./CacheEntry.js").CacheEntryUserFuncsJson} CacheEntryUserFuncsJson
+ * @typedef {import("./CacheEntry.js").CacheEntryValidatorsJson} CacheEntryValidatorsJson
  */
 /**
  * @typedef {{
- *   debug?: boolean
- *   validators: CacheEntryValidatorsJson
- *   userFuncs: CacheEntryUserFuncsJson
- * }} CacheEntryJson
+ *   has(key: string): boolean
+ *   get(key: string): JsonSafe
+ *   set(key: string, entry: JsonSafe): void
+ * }} ExplicitCache
  */
 declare class ContractContextCache {
     /**
+     * Used by esbuild-plugin
+     * @private
      * @type {CacheEntry[]}
      */
-    cache: CacheEntry[];
+    private positionalCache;
+    /**
+     * Explicitly specified by user by calling setBuildCache()
+     * @readwrite
+     * @type {Option<ExplicitCache>}
+     */
+    explicitCache: Option<ExplicitCache>;
     /**
      * Load count
+     * @private
      * @type {number}
      */
-    i: number;
+    private i;
     /**
+     * @private
      * @type {boolean}
      */
-    enabled: boolean;
+    private enabled;
     enable(): void;
+    /**
+     * Key is only generated if the explicitCache is set
+     * @param {{
+     *   version: string
+     *   debug: boolean
+     *   isMainnet: boolean
+     *   validators: Record<string, LoadedValidator>
+     *   modules: Record<string, LoadedModule>
+     *   parameters: Record<string, UplcData>
+     * }} props
+     * @returns {string}
+     */
+    genCacheKey(props: {
+        version: string;
+        debug: boolean;
+        isMainnet: boolean;
+        validators: Record<string, LoadedValidator>;
+        modules: Record<string, LoadedModule>;
+        parameters: Record<string, UplcData>;
+    }): string;
     /**
      * @param {CacheEntryJson[]} json
      */
     load(json: CacheEntryJson[]): void;
     /**
-     * @param {CacheEntry} hashes
+     * @param {string} key - empty string is used to set positional cache (eg. for esbuild-plugn)
+     * @param {CacheEntry} entry
      */
-    push(hashes: CacheEntry): void;
+    set(key: string, entry: CacheEntry): void;
     /**
+     * @param {string} key - empty string is used to access positional cache (eg. for esbuild-plugn)
      * @returns {Option<CacheEntry>}
      */
-    shift(): Option<CacheEntry>;
+    get(key: string): Option<CacheEntry>;
     /**
      * @return {CacheEntryJson[]}
      */

package/types/context/ContractContextCache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ContractContextCache.d.ts","sourceRoot":"","sources":["../../src/context/ContractContextCache.js"],"names":[],"mappings":"AAgYA,wDAA8D;4BApXjD,OAAO,mBAAmB,EAAE,aAAa;0BACzC,OAAO,mBAAmB,EAAE,WAAW;6BACvC,OAAO,mBAAmB,EAAE,cAAc;6BAC1C,OAAO,mBAAmB,EAAE,cAAc;oCAC1C,OAAO,mBAAmB,EAAE,qBAAqB;yBACjD,OAAO,kBAAkB,EAAE,UAAU;yBACrC,OAAO,qBAAqB,EAAE,UAAU;0CACxC,OAAO,sBAAsB,EAAE,2BAA2B;yBAI1D;IACR,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,UAAU,EAAE;QAAC,CAAC,IAAI,EAAE,MAAM,GAAG,2BAA2B,CAAA;KAAC,CAAA;IACzD,SAAS,EAAE;QAAC,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAAA;KAAC,CAAA;CACzC;uCAIS;IAAC,CAAC,IAAI,EAAE,MAAM,GAAG;QACvB,OAAO,EAAE,SAAS,GAAG,UAAU,GAAG,SAAS,GAAG,OAAO,CAAA;QACrD,KAAK,EAAE,MAAM,EAAE,CAAA;QACf,kBAAkB,CAAC,EAAE,MAAM,CAAA;QAC3B,aAAa,CAAC,EAAE,MAAM,CAAA;QACtB,oBAAoB,CAAC,EAAE,qBAAqB,CAAA;QAC5C,gBAAgB,EAAE,MAAM,CAAA;QACxB,WAAW,CAAC,EAAE,MAAM,CAAA;QACpB,kBAAkB,CAAC,EAAE,qBAAqB,CAAA;QAC1C,aAAa,EAAE,aAAa,CAAA;QAC5B,UAAU,EAAE,UAAU,CAAA;QACtB,KAAK,CAAC,EAAE,UAAU,CAAA;QAClB,QAAQ,EAAE,UAAU,CAAA;KACrB,CAAA;CAAC;sCAIM;IAAC,CAAC,IAAI,EAAE,MAAM,GAAG;QACzB,kBAAkB,CAAC,EAAE,MAAM,CAAA;QAC3B,aAAa,CAAC,EAAE,MAAM,CAAA;QACtB,oBAAoB,CAAC,EAAE,qBAAqB,CAAA;QAC5C,gBAAgB,EAAE,MAAM,CAAA;QACxB,WAAW,CAAC,EAAE,MAAM,CAAA;QACpB,kBAAkB,CAAC,EAAE,qBAAqB,CAAA;QAC1C,aAAa,EAAE,aAAa,CAAA;KAC7B,CAAA;CAAC;6BAIQ;IACR,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,UAAU,EAAE,wBAAwB,CAAA;IACpC,SAAS,EAAE,uBAAuB,CAAA;CACnC;AArDJ;;;;;;;;;GASG;AAEH;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;;;;;GAUG;AAEH;;;;;;GAMG;AAEH;IACI;;OAEG;IACH,OAFU,UAAU,EAAE,CAEjB;IAEL;;;OAGG;IACH,GAFU,MAAM,CAEf;IAED;;OAEG;IACH,SAFU,OAAO,CAEV;IAQP,eAEC;IAED;;OAEG;IACH,WAFW,cAAc,EAAE,QA6I1B;IAED;;OAEG;IACH,aAFW,UAAU,QAMpB;IAED;;OAEG;IACH,SAFa,MAAM,CAAC,UAAU,CAAC,CAY9B;IAED;;OAEG;IACH,UAFY,cAAc,EAAE,CAsH3B;CACJ"}
+{"version":3,"file":"ContractContextCache.d.ts","sourceRoot":"","sources":["../../src/context/ContractContextCache.js"],"names":[],"mappings":"AA0JA,wDAA8D;uBApJjD,OAAO,mBAAmB,EAAE,QAAQ;0BACpC,OAAO,mBAAmB,EAAE,WAAW;2BACvC,OAAO,4BAA4B,EAAE,YAAY;8BACjD,OAAO,+BAA+B,EAAE,eAAe;yBACvD,OAAO,iBAAiB,EAAE,UAAU;6BACpC,OAAO,iBAAiB,EAAE,cAAc;sCACxC,OAAO,iBAAiB,EAAE,uBAAuB;uCACjD,OAAO,iBAAiB,EAAE,wBAAwB;4BAIlD;IACR,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;IACzB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAAA;IAC1B,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,IAAI,CAAA;CACxC;AAhBJ;;;;;;;;;GASG;AAEH;;;;;;GAMG;AAEH;IACI;;;;OAIG;IACH,wBAAe;IAEf;;;;OAIG;IACH,eAFU,MAAM,CAAC,aAAa,CAAC,CAElB;IAEb;;;;OAIG;IACH,UAAC;IAED;;;OAGG;IACH,gBAAO;IAQP,eAEC;IAED;;;;;;;;;;;OAWG;IACH,mBAVW;QACN,OAAO,EAAE,MAAM,CAAA;QACf,KAAK,EAAE,OAAO,CAAA;QACd,SAAS,EAAE,OAAO,CAAA;QAClB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAA;QAC3C,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;QACrC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;KACrC,GACS,MAAM,CA0BlB;IAED;;OAEG;IACH,WAFW,cAAc,EAAE,QAI1B;IAED;;;OAGG;IACH,SAHW,MAAM,SACN,UAAU,QAQpB;IAED;;;OAGG;IACH,SAHW,MAAM,GACJ,MAAM,CAAC,UAAU,CAAC,CAuB9B;IAED;;OAEG;IACH,UAFY,cAAc,EAAE,CAI3B;CACJ"}

package/types/context/set-fs-build-cache.d.ts

@@ -0,0 +1,2 @@
+export type ExplicitCache = import("./ContractContextCache.js").ExplicitCache;
+//# sourceMappingURL=set-fs-build-cache.d.ts.map

package/types/context/set-fs-build-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"set-fs-build-cache.d.ts","sourceRoot":"","sources":["../../src/context/set-fs-build-cache.js"],"names":[],"mappings":"4BAGa,OAAO,2BAA2B,EAAE,aAAa"}

package/types/index.d.ts

@@ -1,5 +1,7 @@
 export * from "./cast/index.js";
 export * from "./context/index.js";
 export { LoadedScriptsWriter } from "./codegen/LoadedScriptsWriter.js";
+export type LoadedValidator = import("./codegen/index.js").LoadedValidator;
+export type LoadedModule = import("./codegen/index.js").LoadedModule;
 export { typeCheckFiles, typeCheckScripts, loadCompilerLib } from "./compiler/ops.js";
 //# sourceMappingURL=index.d.ts.map

package/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.js"],"names":[],"mappings":""}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.js"],"names":[],"mappings":";;;8BAOa,OAAO,oBAAoB,EAAE,eAAe;2BAC5C,OAAO,oBAAoB,EAAE,YAAY"}