@lucid-evolution/uplc 0.5.0 → 0.5.1

package/README.md

@@ -16,6 +16,8 @@ Before continuing, please note that this step is not part of the CI process. You
 pnpm build-local
 ```
 
+The browser builds are made with wasm-pack. The Node.js builds need wasm-bindgen's `--experimental-reset-state-function`, which wasm-pack cannot pass, so `scripts/build-node.sh` runs cargo, the `wasm-bindgen` CLI and `wasm-opt` itself: both must be on the `PATH`, with the `wasm-bindgen` CLI at the version of `wasm-bindgen` in `rust/Cargo.lock` (`cargo install wasm-bindgen-cli --version <version>`).
+
 ## 3. Build the UPLC Package
 
 Once you've completed the previous step, you can build the UPLC package by running:
@@ -33,6 +35,12 @@ The package ships two builds of the evaluator:
 
 `@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`.
 
+## Recovering from a wasm trap
+
+On Node.js (the `default` export condition), the bindings recover from a wasm trap. A trap or a stack overflow inside wasm leaves the instance unable to run anything after it, so after any binding throws, the next call first replaces the instance with a fresh one, and the error itself is rethrown unchanged. A result returned before the replacement throws when read afterwards, and freeing it, explicitly or by garbage collection, does not touch the new instance.
+
+The browser, worker, workerd and edge-light builds do not recover: a bundler instantiates their wasm once, and wasm-bindgen cannot replace that instance. After a trap there, load the package again (for example in a new worker).
+
 ## 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.

package/dist/recover-from-trap.js

@@ -0,0 +1,44 @@
+"use strict";
+
+// Recovers the Node.js bindings from a wasm trap. A trap or a stack overflow
+// inside wasm unwinds without restoring the instance's stack pointer or
+// releasing the state it was using, so every later call on that instance can
+// fail. After a binding throws, the next call first replaces the instance with
+// a fresh one (wasm-bindgen's `__wbg_reset_state`); the error itself is
+// rethrown unchanged. Results that came from a replaced instance throw when
+// read, and freeing them, explicitly or by garbage collection, leaves the
+// current instance alone.
+//
+// Returns a function that wraps one binding of `bindings`.
+module.exports = (bindings) => {
+  let replaceInstance = false;
+  // The results the current instance returned: only these are freed in it.
+  let current = new WeakSet();
+
+  for (const value of Object.values(bindings)) {
+    const free = value?.prototype?.free;
+    if (typeof free !== "function") continue;
+    value.prototype.free = function () {
+      if (current.has(this)) free.call(this);
+    };
+    if (Symbol.dispose) value.prototype[Symbol.dispose] = value.prototype.free;
+  }
+
+  return (binding) =>
+    function (...args) {
+      if (replaceInstance) {
+        bindings.__wbg_reset_state();
+        current = new WeakSet();
+        replaceInstance = false;
+      }
+      let result;
+      try {
+        result = binding.apply(this, args);
+      } catch (error) {
+        replaceInstance = true;
+        throw error;
+      }
+      if (typeof result === "object" && result !== null) current.add(result);
+      return result;
+    };
+};

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

@@ -1,98 +1,6 @@
 /* tslint:disable */
 /* eslint-disable */
-export function eval_phase_two_raw(
-  tx_bytes: Uint8Array,
-  utxos_bytes_x: Uint8Array[],
-  utxos_bytes_y: Uint8Array[],
-  cost_mdls_bytes: Uint8Array,
-  initial_budget_n: bigint,
-  initial_budget_d: bigint,
-  slot_config_x: bigint,
-  slot_config_y: bigint,
-  slot_config_z: number,
-  protocol_major_version?: number | null,
-): Uint8Array[];
-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;
-/**
- * Evaluates the builtin `tag` applied to `args` as a Plutus V3 script
- * evaluates it at a protocol version, without any program around it: the
- * result, or how it fails, is what the machine gives for the saturated
- * application.
- *
- * - `tag`: the builtin's flat tag (0 for addInteger to 100 for scaleValue).
- *   The Miller-loop builtins (68 to 70) are not supported, since their
- *   results cannot be returned.
- * - `args`: exactly the builtin's arguments, in order, each encoded as the
- *   matching entry of `arg_kinds` says, a [`BuiltinValueKind`]: 0 for a
- *   flat-encoded `(program 1.1.0 (con …))`, 1 for a compressed G1 point, 2
- *   for a compressed G2 point, 3 for a list of G1 points, 4 for a list of G2
- *   points, 5 for an array of G1 points and 6 for an array of G2 points, each
- *   list or array as the compressed points one after the other. Flat cannot
- *   encode BLS12-381 points, so they cross as their compressed bytes.
- * - `protocol_major_version`: from 9 (Chang, which introduced Plutus V3) to
- *   12 (Dijkstra). It decides which builtins are available and the semantics
- *   they have.
- *
- * The result's `cpu` and `mem` are the builtin's charge for the application
- * under Plutus' default Plutus V3 cost model (not the ledger's protocol
- * parameters), excluding the machine's per-step costs.
- *
- * Fails only when the inputs are malformed or unsupported: an unknown or
- * Miller-loop tag, a number of arguments other than the builtin's arity, an
- * argument that does not decode as its kind says or is not a constant, an
- * invalid compressed point, a protocol version out of range, or a result that
- * none of the kinds can encode. A builtin that fails is an
- * [`EvalBuiltinResult`] that is not `ok`.
- */
-export function eval_builtin_raw(
-  tag: number,
-  args: Uint8Array[],
-  arg_kinds: Uint8Array,
-  protocol_major_version: number,
-): EvalBuiltinResult;
+
 /**
  * Why the builtin given to [`eval_builtin_raw`] did not return a value: the
  * codes of the result's `error_kind`.
@@ -116,6 +24,7 @@ export enum BuiltinErrorKind {
    */
   Failed = 3,
 }
+
 /**
  * How a value of [`eval_builtin_raw`] is encoded: the codes of its
  * `arg_kinds` and of the result's `result_kind`.
@@ -156,16 +65,22 @@ export enum BuiltinValueKind {
    */
   G2Array = 6,
 }
+
 /**
  * The outcome of [`eval_builtin_raw`].
  */
 export class EvalBuiltinResult {
   private constructor();
   free(): void;
+  [Symbol.dispose](): void;
   /**
-   * Whether the builtin returned a value.
+   * The CPU the builtin's cost model charges for this application, under
+   * Plutus' default cost model for Plutus V3 at the protocol version; 0
+   * when the builtin was not costed (error kinds 1 and 2). It leaves out the
+   * machine's own step costs for evaluating the application (the builtin,
+   * each force and each apply).
    */
-  ok: boolean;
+  cpu: bigint;
   /**
    * Why the builtin did not return a value, a [`BuiltinErrorKind`]: 0 when
    * it did, 1 when it is not available to Plutus V3 at the protocol version,
@@ -174,53 +89,42 @@ export class EvalBuiltinResult {
    */
   error_kind: number;
   /**
-   * How `result` encodes the value, a [`BuiltinValueKind`] as for the
-   * arguments of [`eval_builtin_raw`]; 0 when there is no value.
+   * The evaluator's description of why the builtin did not return a value;
+   * empty when it did.
    */
-  result_kind: number;
+  error: string;
   /**
-   * The value the builtin returned; empty when there is none.
+   * The memory the builtin's cost model charges for this application; see
+   * `cpu`.
    */
-  result: Uint8Array;
+  mem: bigint;
   /**
-   * The CPU the builtin's cost model charges for this application, under
-   * Plutus' default cost model for Plutus V3 at the protocol version; 0
-   * when the builtin was not costed (error kinds 1 and 2). It leaves out the
-   * machine's own step costs for evaluating the application (the builtin,
-   * each force and each apply).
+   * Whether the builtin returned a value.
    */
-  cpu: bigint;
+  ok: boolean;
   /**
-   * The memory the builtin's cost model charges for this application; see
-   * `cpu`.
+   * How `result` encodes the value, a [`BuiltinValueKind`] as for the
+   * arguments of [`eval_builtin_raw`]; 0 when there is no value.
    */
-  mem: bigint;
+  result_kind: number;
   /**
-   * The evaluator's description of why the builtin did not return a value;
-   * empty when it did.
+   * The value the builtin returned; empty when there is none.
    */
-  error: string;
+  result: Uint8Array;
 }
+
 /**
  * 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;
+  [Symbol.dispose](): void;
   /**
    * 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
@@ -231,4 +135,111 @@ export class EvalProgramResult {
    * The messages the program traced, in order.
    */
   logs: string[];
+  /**
+   * The memory the program used.
+   */
+  mem: bigint;
+  /**
+   * Whether the program succeeded: it did not fail and, for Plutus V3, it
+   * returned unit.
+   */
+  ok: boolean;
 }
+
+export function apply_params_to_script(
+  params_bytes: Uint8Array,
+  plutus_script_bytes: Uint8Array,
+): Uint8Array;
+
+/**
+ * Evaluates the builtin `tag` applied to `args` as a Plutus V3 script
+ * evaluates it at a protocol version, without any program around it: the
+ * result, or how it fails, is what the machine gives for the saturated
+ * application.
+ *
+ * - `tag`: the builtin's flat tag (0 for addInteger to 100 for scaleValue).
+ *   The Miller-loop builtins (68 to 70) are not supported, since their
+ *   results cannot be returned.
+ * - `args`: exactly the builtin's arguments, in order, each encoded as the
+ *   matching entry of `arg_kinds` says, a [`BuiltinValueKind`]: 0 for a
+ *   flat-encoded `(program 1.1.0 (con …))`, 1 for a compressed G1 point, 2
+ *   for a compressed G2 point, 3 for a list of G1 points, 4 for a list of G2
+ *   points, 5 for an array of G1 points and 6 for an array of G2 points, each
+ *   list or array as the compressed points one after the other. Flat cannot
+ *   encode BLS12-381 points, so they cross as their compressed bytes.
+ * - `protocol_major_version`: from 9 (Chang, which introduced Plutus V3) to
+ *   12 (Dijkstra). It decides which builtins are available and the semantics
+ *   they have.
+ *
+ * The result's `cpu` and `mem` are the builtin's charge for the application
+ * under Plutus' default Plutus V3 cost model (not the ledger's protocol
+ * parameters), excluding the machine's per-step costs.
+ *
+ * Fails only when the inputs are malformed or unsupported: an unknown or
+ * Miller-loop tag, a number of arguments other than the builtin's arity, an
+ * argument that does not decode as its kind says or is not a constant, an
+ * invalid compressed point, a protocol version out of range, or a result that
+ * none of the kinds can encode. A builtin that fails is an
+ * [`EvalBuiltinResult`] that is not `ok`.
+ */
+export function eval_builtin_raw(
+  tag: number,
+  args: Uint8Array[],
+  arg_kinds: Uint8Array,
+  protocol_major_version: number,
+): EvalBuiltinResult;
+
+export function eval_phase_two_raw(
+  tx_bytes: Uint8Array,
+  utxos_bytes_x: Uint8Array[],
+  utxos_bytes_y: Uint8Array[],
+  cost_mdls_bytes: Uint8Array,
+  initial_budget_n: bigint,
+  initial_budget_d: bigint,
+  slot_config_x: bigint,
+  slot_config_y: bigint,
+  slot_config_z: number,
+  protocol_major_version?: number | null,
+): 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;

package/dist/size/browser/uplc_tx.js

@@ -1,5 +1,9 @@
+/* @ts-self-types="./uplc_tx.d.ts" */
 import * as wasm from "./uplc_tx_bg.wasm";
-export * from "./uplc_tx_bg.js";
 import { __wbg_set_wasm } from "./uplc_tx_bg.js";
+
 __wbg_set_wasm(wasm);
 wasm.__wbindgen_start();
+export {
+    BuiltinErrorKind, BuiltinValueKind, EvalBuiltinResult, EvalProgramResult, apply_params_to_script, eval_builtin_raw, eval_phase_two_raw, eval_program_raw, uplc_build_info
+} from "./uplc_tx_bg.js";