@lucid-evolution/uplc 0.3.0 → 0.4.0

package/README.md

@@ -28,7 +28,44 @@ pnpm build
 
 The package ships two builds of the evaluator:
 
-- **speed** (`-O3`, ~1.77 MB wasm): faster script evaluation.
-- **size** (`-Oz`, ~0.94 MB wasm): smaller download.
+- **speed** (`-O3`, ~1.93 MB wasm): faster script evaluation.
+- **size** (`-Oz`, ~1.03 MB wasm): smaller download.
 
 `@lucid-evolution/uplc` resolves to the speed build on Node, Bun and Deno, and to the size build in browser bundles and edge runtimes (`browser`, `worker`, `workerd` and `edge-light` export conditions). To pick a variant explicitly, import `@lucid-evolution/uplc/speed` or `@lucid-evolution/uplc/size`.
+
+## Evaluating a program
+
+`eval_program_raw` evaluates a UPLC program applied to `Data` arguments, outside of any transaction. The caller builds whatever arguments the program expects, including its script context.
+
+```ts
+import { eval_program_raw } from "@lucid-evolution/uplc";
+
+const result = eval_program_raw(
+  programFlat, // Uint8Array: the program, flat-encoded without a CBOR wrapper
+  [datum, redeemer, context], // Uint8Array[]: each argument as CBOR-encoded Data
+  3, // Plutus version: 1, 2 or 3
+  11, // protocol major version: 5 to 11
+  costModel, // BigInt64Array: every cost model parameter for this Plutus version
+  10_000_000_000n, // CPU budget
+  14_000_000n, // memory budget
+  true, // charge every step, and stop as soon as the budget runs out
+);
+
+result.ok; // whether the program succeeded (for Plutus V3, returned unit)
+result.error_kind; // 0 ok, 1 over budget, 2 failed, 3 Plutus V3 result not unit
+result.cpu; // bigint
+result.mem; // bigint
+result.logs; // string[]: the program's traces
+```
+
+With `false` as the last argument, steps are charged and the budget is checked every 200 steps as the ledger does. That only changes the cost reported for a program that fails, as the ledger does not charge the steps it took since the budget was last checked; the Haskell evaluator reports the same cost. It throws only when the inputs are malformed or unsupported.
+
+`uplc_build_info()` returns JSON that describes the build: the uplc crate it was built from, the latest protocol version it supports, each Plutus version's cost model length, a digest of what a fixed set of programs evaluate to, and whether those programs give the expected results (`"selfTest": "pass"`).
+
+## Tests
+
+```bash
+pnpm test
+```
+
+`test/fixtures/programs.json` holds programs with their outcome and cost under Plutus V3 and protocol version 11, as given by the Haskell evaluator (plutus-core 1.71).

package/dist/size/browser/uplc_tx.d.ts

@@ -16,3 +16,74 @@ export function apply_params_to_script(
   params_bytes: Uint8Array,
   plutus_script_bytes: Uint8Array,
 ): Uint8Array;
+/**
+ * Evaluates a UPLC program applied to Data arguments, outside of any
+ * transaction: the caller builds whatever arguments the program expects,
+ * including its script context.
+ *
+ * - `program_flat`: the program, flat-encoded without a CBOR wrapper.
+ * - `args_cbor`: the arguments, each one CBOR-encoded Data, applied in order.
+ * - `language`: the Plutus version to evaluate as, 1, 2 or 3.
+ * - `protocol_major_version`: the protocol version whose semantics to use,
+ *   from 5 (Alonzo) to 12 (Dijkstra).
+ * - `cost_model`: the cost model parameters, every one the evaluator knows
+ *   for this Plutus version (350 for Plutus V3), in the ledger's order.
+ * - `budget_cpu`, `budget_mem`: the budget.
+ * - `strict_budget`: charge every step as the machine takes it, and stop the
+ *   program as soon as it goes over budget, instead of charging steps and
+ *   checking the budget every 200 steps as the ledger does. Only the cost of a
+ *   program that fails differs: the ledger does not charge the steps it took
+ *   since the budget was last checked.
+ *
+ * Fails only when the inputs are malformed or unsupported. A program that fails
+ * is an [`EvalProgramResult`] that is not `ok`.
+ */
+export function eval_program_raw(
+  program_flat: Uint8Array,
+  args_cbor: Uint8Array[],
+  language: number,
+  protocol_major_version: number,
+  cost_model: BigInt64Array,
+  budget_cpu: bigint,
+  budget_mem: bigint,
+  strict_budget: boolean,
+): EvalProgramResult;
+/**
+ * Describes this build of the evaluator as JSON: the uplc crate it was built
+ * from, the length of each Plutus version's cost model, and a digest of what a
+ * fixed set of programs evaluate to, with their costs, under Plutus V3 and the
+ * latest protocol version. Two builds with the same digest agree on those
+ * programs; `selfTest` says whether this one gives the expected results.
+ */
+export function uplc_build_info(): string;
+/**
+ * The outcome of [`eval_program_raw`].
+ */
+export class EvalProgramResult {
+  private constructor();
+  free(): void;
+  /**
+   * Whether the program succeeded: it did not fail and, for Plutus V3, it
+   * returned unit.
+   */
+  ok: boolean;
+  /**
+   * The CPU the program used. A program that went over budget is charged
+   * what it used up to the point where the machine stopped it.
+   */
+  cpu: bigint;
+  /**
+   * The memory the program used.
+   */
+  mem: bigint;
+  /**
+   * Why the program did not succeed: 0 when it did, 1 when it went over
+   * budget, 2 when it failed in any other way and 3 when a Plutus V3 program
+   * returned something other than unit.
+   */
+  error_kind: number;
+  /**
+   * The messages the program traced, in order.
+   */
+  logs: string[];
+}

package/dist/size/browser/uplc_tx_bg.js

@@ -4,11 +4,7 @@ export function __wbg_set_wasm(val) {
 }
 
 
-const lTextDecoder = typeof TextDecoder === 'undefined' ? (0, module.require)('util').TextDecoder : TextDecoder;
-
-let cachedTextDecoder = new lTextDecoder('utf-8', { ignoreBOM: true, fatal: true });
-
-cachedTextDecoder.decode();
+let WASM_VECTOR_LEN = 0;
 
 let cachedUint8ArrayMemory0 = null;
 
@@ -19,20 +15,66 @@ function getUint8ArrayMemory0() {
     return cachedUint8ArrayMemory0;
 }
 
-function getStringFromWasm0(ptr, len) {
-    ptr = ptr >>> 0;
-    return cachedTextDecoder.decode(getUint8ArrayMemory0().subarray(ptr, ptr + len));
+const lTextEncoder = typeof TextEncoder === 'undefined' ? (0, module.require)('util').TextEncoder : TextEncoder;
+
+let cachedTextEncoder = new lTextEncoder('utf-8');
+
+const encodeString = (typeof cachedTextEncoder.encodeInto === 'function'
+    ? function (arg, view) {
+    return cachedTextEncoder.encodeInto(arg, view);
 }
+    : function (arg, view) {
+    const buf = cachedTextEncoder.encode(arg);
+    view.set(buf);
+    return {
+        read: arg.length,
+        written: buf.length
+    };
+});
 
-let WASM_VECTOR_LEN = 0;
+function passStringToWasm0(arg, malloc, realloc) {
 
-function passArray8ToWasm0(arg, malloc) {
-    const ptr = malloc(arg.length * 1, 1) >>> 0;
-    getUint8ArrayMemory0().set(arg, ptr / 1);
-    WASM_VECTOR_LEN = arg.length;
+    if (realloc === undefined) {
+        const buf = cachedTextEncoder.encode(arg);
+        const ptr = malloc(buf.length, 1) >>> 0;
+        getUint8ArrayMemory0().subarray(ptr, ptr + buf.length).set(buf);
+        WASM_VECTOR_LEN = buf.length;
+        return ptr;
+    }
+
+    let len = arg.length;
+    let ptr = malloc(len, 1) >>> 0;
+
+    const mem = getUint8ArrayMemory0();
+
+    let offset = 0;
+
+    for (; offset < len; offset++) {
+        const code = arg.charCodeAt(offset);
+        if (code > 0x7F) break;
+        mem[ptr + offset] = code;
+    }
+
+    if (offset !== len) {
+        if (offset !== 0) {
+            arg = arg.slice(offset);
+        }
+        ptr = realloc(ptr, len, len = offset + arg.length * 3, 1) >>> 0;
+        const view = getUint8ArrayMemory0().subarray(ptr + offset, ptr + len);
+        const ret = encodeString(arg, view);
+
+        offset += ret.written;
+        ptr = realloc(ptr, len, offset, 1) >>> 0;
+    }
+
+    WASM_VECTOR_LEN = offset;
     return ptr;
 }
 
+function isLikeNone(x) {
+    return x === undefined || x === null;
+}
+
 let cachedDataViewMemory0 = null;
 
 function getDataViewMemory0() {
@@ -42,6 +84,24 @@ function getDataViewMemory0() {
     return cachedDataViewMemory0;
 }
 
+const lTextDecoder = typeof TextDecoder === 'undefined' ? (0, module.require)('util').TextDecoder : TextDecoder;
+
+let cachedTextDecoder = new lTextDecoder('utf-8', { ignoreBOM: true, fatal: true });
+
+cachedTextDecoder.decode();
+
+function getStringFromWasm0(ptr, len) {
+    ptr = ptr >>> 0;
+    return cachedTextDecoder.decode(getUint8ArrayMemory0().subarray(ptr, ptr + len));
+}
+
+function passArray8ToWasm0(arg, malloc) {
+    const ptr = malloc(arg.length * 1, 1) >>> 0;
+    getUint8ArrayMemory0().set(arg, ptr / 1);
+    WASM_VECTOR_LEN = arg.length;
+    return ptr;
+}
+
 function addToExternrefTable0(obj) {
     const idx = wasm.__externref_table_alloc();
     wasm.__wbindgen_export_0.set(idx, obj);
@@ -58,10 +118,6 @@ function passArrayJsValueToWasm0(array, malloc) {
     return ptr;
 }
 
-function isLikeNone(x) {
-    return x === undefined || x === null;
-}
-
 function takeFromExternrefTable0(idx) {
     const value = wasm.__wbindgen_export_0.get(idx);
     wasm.__externref_table_dealloc(idx);
@@ -132,6 +188,203 @@ export function apply_params_to_script(params_bytes, plutus_script_bytes) {
     return v3;
 }
 
+let cachedBigUint64ArrayMemory0 = null;
+
+function getBigUint64ArrayMemory0() {
+    if (cachedBigUint64ArrayMemory0 === null || cachedBigUint64ArrayMemory0.byteLength === 0) {
+        cachedBigUint64ArrayMemory0 = new BigUint64Array(wasm.memory.buffer);
+    }
+    return cachedBigUint64ArrayMemory0;
+}
+
+function passArray64ToWasm0(arg, malloc) {
+    const ptr = malloc(arg.length * 8, 8) >>> 0;
+    getBigUint64ArrayMemory0().set(arg, ptr / 8);
+    WASM_VECTOR_LEN = arg.length;
+    return ptr;
+}
+/**
+ * Evaluates a UPLC program applied to Data arguments, outside of any
+ * transaction: the caller builds whatever arguments the program expects,
+ * including its script context.
+ *
+ * - `program_flat`: the program, flat-encoded without a CBOR wrapper.
+ * - `args_cbor`: the arguments, each one CBOR-encoded Data, applied in order.
+ * - `language`: the Plutus version to evaluate as, 1, 2 or 3.
+ * - `protocol_major_version`: the protocol version whose semantics to use,
+ *   from 5 (Alonzo) to 12 (Dijkstra).
+ * - `cost_model`: the cost model parameters, every one the evaluator knows
+ *   for this Plutus version (350 for Plutus V3), in the ledger's order.
+ * - `budget_cpu`, `budget_mem`: the budget.
+ * - `strict_budget`: charge every step as the machine takes it, and stop the
+ *   program as soon as it goes over budget, instead of charging steps and
+ *   checking the budget every 200 steps as the ledger does. Only the cost of a
+ *   program that fails differs: the ledger does not charge the steps it took
+ *   since the budget was last checked.
+ *
+ * Fails only when the inputs are malformed or unsupported. A program that fails
+ * is an [`EvalProgramResult`] that is not `ok`.
+ * @param {Uint8Array} program_flat
+ * @param {Uint8Array[]} args_cbor
+ * @param {number} language
+ * @param {number} protocol_major_version
+ * @param {BigInt64Array} cost_model
+ * @param {bigint} budget_cpu
+ * @param {bigint} budget_mem
+ * @param {boolean} strict_budget
+ * @returns {EvalProgramResult}
+ */
+export function eval_program_raw(program_flat, args_cbor, language, protocol_major_version, cost_model, budget_cpu, budget_mem, strict_budget) {
+    const ptr0 = passArray8ToWasm0(program_flat, wasm.__wbindgen_malloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ptr1 = passArrayJsValueToWasm0(args_cbor, wasm.__wbindgen_malloc);
+    const len1 = WASM_VECTOR_LEN;
+    const ptr2 = passArray64ToWasm0(cost_model, wasm.__wbindgen_malloc);
+    const len2 = WASM_VECTOR_LEN;
+    const ret = wasm.eval_program_raw(ptr0, len0, ptr1, len1, language, protocol_major_version, ptr2, len2, budget_cpu, budget_mem, strict_budget);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return EvalProgramResult.__wrap(ret[0]);
+}
+
+/**
+ * Describes this build of the evaluator as JSON: the uplc crate it was built
+ * from, the length of each Plutus version's cost model, and a digest of what a
+ * fixed set of programs evaluate to, with their costs, under Plutus V3 and the
+ * latest protocol version. Two builds with the same digest agree on those
+ * programs; `selfTest` says whether this one gives the expected results.
+ * @returns {string}
+ */
+export function uplc_build_info() {
+    let deferred1_0;
+    let deferred1_1;
+    try {
+        const ret = wasm.uplc_build_info();
+        deferred1_0 = ret[0];
+        deferred1_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
+    }
+}
+
+const EvalProgramResultFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_evalprogramresult_free(ptr >>> 0, 1));
+/**
+ * The outcome of [`eval_program_raw`].
+ */
+export class EvalProgramResult {
+
+    static __wrap(ptr) {
+        ptr = ptr >>> 0;
+        const obj = Object.create(EvalProgramResult.prototype);
+        obj.__wbg_ptr = ptr;
+        EvalProgramResultFinalization.register(obj, obj.__wbg_ptr, obj);
+        return obj;
+    }
+
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        EvalProgramResultFinalization.unregister(this);
+        return ptr;
+    }
+
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_evalprogramresult_free(ptr, 0);
+    }
+    /**
+     * Whether the program succeeded: it did not fail and, for Plutus V3, it
+     * returned unit.
+     * @returns {boolean}
+     */
+    get ok() {
+        const ret = wasm.__wbg_get_evalprogramresult_ok(this.__wbg_ptr);
+        return ret !== 0;
+    }
+    /**
+     * Whether the program succeeded: it did not fail and, for Plutus V3, it
+     * returned unit.
+     * @param {boolean} arg0
+     */
+    set ok(arg0) {
+        wasm.__wbg_set_evalprogramresult_ok(this.__wbg_ptr, arg0);
+    }
+    /**
+     * The CPU the program used. A program that went over budget is charged
+     * what it used up to the point where the machine stopped it.
+     * @returns {bigint}
+     */
+    get cpu() {
+        const ret = wasm.__wbg_get_evalprogramresult_cpu(this.__wbg_ptr);
+        return BigInt.asUintN(64, ret);
+    }
+    /**
+     * The CPU the program used. A program that went over budget is charged
+     * what it used up to the point where the machine stopped it.
+     * @param {bigint} arg0
+     */
+    set cpu(arg0) {
+        wasm.__wbg_set_evalprogramresult_cpu(this.__wbg_ptr, arg0);
+    }
+    /**
+     * The memory the program used.
+     * @returns {bigint}
+     */
+    get mem() {
+        const ret = wasm.__wbg_get_evalprogramresult_mem(this.__wbg_ptr);
+        return BigInt.asUintN(64, ret);
+    }
+    /**
+     * The memory the program used.
+     * @param {bigint} arg0
+     */
+    set mem(arg0) {
+        wasm.__wbg_set_evalprogramresult_mem(this.__wbg_ptr, arg0);
+    }
+    /**
+     * Why the program did not succeed: 0 when it did, 1 when it went over
+     * budget, 2 when it failed in any other way and 3 when a Plutus V3 program
+     * returned something other than unit.
+     * @returns {number}
+     */
+    get error_kind() {
+        const ret = wasm.__wbg_get_evalprogramresult_error_kind(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * Why the program did not succeed: 0 when it did, 1 when it went over
+     * budget, 2 when it failed in any other way and 3 when a Plutus V3 program
+     * returned something other than unit.
+     * @param {number} arg0
+     */
+    set error_kind(arg0) {
+        wasm.__wbg_set_evalprogramresult_error_kind(this.__wbg_ptr, arg0);
+    }
+    /**
+     * The messages the program traced, in order.
+     * @returns {string[]}
+     */
+    get logs() {
+        const ret = wasm.__wbg_get_evalprogramresult_logs(this.__wbg_ptr);
+        var v1 = getArrayJsValueFromWasm0(ret[0], ret[1]).slice();
+        wasm.__wbindgen_free(ret[0], ret[1] * 4, 4);
+        return v1;
+    }
+    /**
+     * The messages the program traced, in order.
+     * @param {string[]} arg0
+     */
+    set logs(arg0) {
+        const ptr0 = passArrayJsValueToWasm0(arg0, wasm.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        wasm.__wbg_set_evalprogramresult_logs(this.__wbg_ptr, ptr0, len0);
+    }
+}
+
 export function __wbg_buffer_609cc3eee51ed158(arg0) {
     const ret = arg0.buffer;
     return ret;
@@ -172,6 +425,15 @@ export function __wbindgen_memory() {
     return ret;
 };
 
+export function __wbindgen_string_get(arg0, arg1) {
+    const obj = arg1;
+    const ret = typeof(obj) === 'string' ? obj : undefined;
+    var ptr1 = isLikeNone(ret) ? 0 : passStringToWasm0(ret, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    var len1 = WASM_VECTOR_LEN;
+    getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
+    getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
+};
+
 export function __wbindgen_string_new(arg0, arg1) {
     const ret = getStringFromWasm0(arg0, arg1);
     return ret;

package/dist/size/browser/uplc_tx_bg.wasm.d.ts

@@ -1,6 +1,24 @@
 /* tslint:disable */
 /* eslint-disable */
 export const memory: WebAssembly.Memory;
+export const __wbg_evalprogramresult_free: (a: number, b: number) => void;
+export const __wbg_get_evalprogramresult_cpu: (a: number) => bigint;
+export const __wbg_get_evalprogramresult_error_kind: (a: number) => number;
+export const __wbg_get_evalprogramresult_logs: (a: number) => [number, number];
+export const __wbg_get_evalprogramresult_mem: (a: number) => bigint;
+export const __wbg_get_evalprogramresult_ok: (a: number) => number;
+export const __wbg_set_evalprogramresult_cpu: (a: number, b: bigint) => void;
+export const __wbg_set_evalprogramresult_error_kind: (
+  a: number,
+  b: number,
+) => void;
+export const __wbg_set_evalprogramresult_logs: (
+  a: number,
+  b: number,
+  c: number,
+) => void;
+export const __wbg_set_evalprogramresult_mem: (a: number, b: bigint) => void;
+export const __wbg_set_evalprogramresult_ok: (a: number, b: number) => void;
 export const apply_params_to_script: (
   a: number,
   b: number,
@@ -24,8 +42,28 @@ export const eval_phase_two_raw: (
   n: number,
   o: number,
 ) => [number, number, number, number];
+export const eval_program_raw: (
+  a: number,
+  b: number,
+  c: number,
+  d: number,
+  e: number,
+  f: number,
+  g: number,
+  h: number,
+  i: bigint,
+  j: bigint,
+  k: number,
+) => [number, number, number];
+export const uplc_build_info: () => [number, number];
 export const __wbindgen_export_0: WebAssembly.Table;
 export const __wbindgen_malloc: (a: number, b: number) => number;
+export const __wbindgen_realloc: (
+  a: number,
+  b: number,
+  c: number,
+  d: number,
+) => number;
 export const __externref_table_alloc: () => number;
 export const __externref_table_dealloc: (a: number) => void;
 export const __externref_drop_slice: (a: number, b: number) => void;

package/dist/size/node/uplc_tx.d.ts

@@ -16,3 +16,74 @@ export function apply_params_to_script(
   params_bytes: Uint8Array,
   plutus_script_bytes: Uint8Array,
 ): Uint8Array;
+/**
+ * Evaluates a UPLC program applied to Data arguments, outside of any
+ * transaction: the caller builds whatever arguments the program expects,
+ * including its script context.
+ *
+ * - `program_flat`: the program, flat-encoded without a CBOR wrapper.
+ * - `args_cbor`: the arguments, each one CBOR-encoded Data, applied in order.
+ * - `language`: the Plutus version to evaluate as, 1, 2 or 3.
+ * - `protocol_major_version`: the protocol version whose semantics to use,
+ *   from 5 (Alonzo) to 12 (Dijkstra).
+ * - `cost_model`: the cost model parameters, every one the evaluator knows
+ *   for this Plutus version (350 for Plutus V3), in the ledger's order.
+ * - `budget_cpu`, `budget_mem`: the budget.
+ * - `strict_budget`: charge every step as the machine takes it, and stop the
+ *   program as soon as it goes over budget, instead of charging steps and
+ *   checking the budget every 200 steps as the ledger does. Only the cost of a
+ *   program that fails differs: the ledger does not charge the steps it took
+ *   since the budget was last checked.
+ *
+ * Fails only when the inputs are malformed or unsupported. A program that fails
+ * is an [`EvalProgramResult`] that is not `ok`.
+ */
+export function eval_program_raw(
+  program_flat: Uint8Array,
+  args_cbor: Uint8Array[],
+  language: number,
+  protocol_major_version: number,
+  cost_model: BigInt64Array,
+  budget_cpu: bigint,
+  budget_mem: bigint,
+  strict_budget: boolean,
+): EvalProgramResult;
+/**
+ * Describes this build of the evaluator as JSON: the uplc crate it was built
+ * from, the length of each Plutus version's cost model, and a digest of what a
+ * fixed set of programs evaluate to, with their costs, under Plutus V3 and the
+ * latest protocol version. Two builds with the same digest agree on those
+ * programs; `selfTest` says whether this one gives the expected results.
+ */
+export function uplc_build_info(): string;
+/**
+ * The outcome of [`eval_program_raw`].
+ */
+export class EvalProgramResult {
+  private constructor();
+  free(): void;
+  /**
+   * Whether the program succeeded: it did not fail and, for Plutus V3, it
+   * returned unit.
+   */
+  ok: boolean;
+  /**
+   * The CPU the program used. A program that went over budget is charged
+   * what it used up to the point where the machine stopped it.
+   */
+  cpu: bigint;
+  /**
+   * The memory the program used.
+   */
+  mem: bigint;
+  /**
+   * Why the program did not succeed: 0 when it did, 1 when it went over
+   * budget, 2 when it failed in any other way and 3 when a Plutus V3 program
+   * returned something other than unit.
+   */
+  error_kind: number;
+  /**
+   * The messages the program traced, in order.
+   */
+  logs: string[];
+}