Add determinism support and enhance error handling in PVM runtime

- Introduced `DeterminismOptions` to the `ExecutionOptions` struct for improved execution control. - Added new error types: `DeterministicValidationError`, `NonDeterministicError`, and `OutOfGasError` to enhance error reporting. - Updated `execute_tx_with_options` to handle determinism settings and associated error handling. - Enhanced demo scripts to showcase determinism features and provide clearer usage instructions. - Refactored exception mapping to include determinism-related errors for better debugging and user feedback.
yusufyian · Dec 18, 2025 · Dec 18, 2025 · Dec 19, 2025 · Dec 19, 2025 · Dec 19, 2025
commit 072c0ccba9e154317cd3c9d92aaa75c56f203f4a
diff --git a/Lib/pvm_sdk/__init__.py b/Lib/pvm_sdk/__init__.py
@@ -0,0 +1,5 @@
+from . import pvm_random
+from . import pvm_sys
+from . import pvm_time
+
+__all__ = ["pvm_random", "pvm_sys", "pvm_time"]
diff --git a/Lib/pvm_sdk/pvm_random.py b/Lib/pvm_sdk/pvm_random.py
@@ -0,0 +1,23 @@
+import pvm_host
+
+_counter = 0
+
+
+def _next_block():
+    global _counter
+    domain = b"random" + _counter.to_bytes(8, "little")
+    _counter += 1
+    return pvm_host.randomness(domain)
+
+
+def random():
+    block = _next_block()
+    value = int.from_bytes(block[:8], "little") >> 11
+    return value / (1 << 53)
+
+
+def randbytes(n):
+    out = bytearray()
+    while len(out) < n:
+        out.extend(_next_block())
+    return bytes(out[:n])
diff --git a/Lib/pvm_sdk/pvm_sys.py b/Lib/pvm_sdk/pvm_sys.py
@@ -0,0 +1,7 @@
+import pvm_host
+
+_ctx = pvm_host.context()
+
+chain_id = _ctx.get("chain_id")
+pvm_version = _ctx.get("pvm_version")
+stdlib_hash = _ctx.get("stdlib_hash")
diff --git a/Lib/pvm_sdk/pvm_time.py b/Lib/pvm_sdk/pvm_time.py
@@ -0,0 +1,9 @@
+import pvm_host
+
+
+def time():
+    return pvm_host.context()["timestamp_ms"] / 1000.0
+
+
+def time_ns():
+    return pvm_host.context()["timestamp_ms"] * 1_000_000
diff --git a/crates/pvm-runtime/src/determinism.rs b/crates/pvm-runtime/src/determinism.rs
@@ -0,0 +1,134 @@
+#[derive(Clone, Debug)]
+pub struct DeterminismOptions {
+    pub enabled: bool,
+    pub hash_seed: u32,
+    pub stdlib_whitelist: Vec<String>,
+    pub stdlib_blacklist: Vec<String>,
+    pub stdlib_hash: Option<String>,
+    pub enable_softfloat: bool,
+    pub enable_gas: bool,
+}
+
+impl DeterminismOptions {
+    pub fn deterministic(hash_seed: Option<u32>) -> Self {
+        let mut options = Self::default();
+        options.enabled = true;
+        options.hash_seed = hash_seed.unwrap_or(0);
+        options
+    }
+
+    pub fn default_whitelist() -> Vec<String> {
+        vec![
+            "builtins",
+            "types",
+            "collections",
+            "collections.abc",
+            "abc",
+            "enum",
+            "dataclasses",
+            "typing",
+            "functools",
+            "itertools",
+            "operator",
+            "re",
+            "sre_compile",
+            "sre_parse",
+            "sre_constants",
+            "_sre",
+            "string",
+            "codecs",
+            "encodings",
+            "unicodedata",
+            "math",
+            "keyword",
+            "reprlib",
+            "json",
+            "copyreg",
+            "base64",
+            "binascii",
+            "struct",
+            "hashlib",
+            "hmac",
+            "warnings",
+            "heapq",
+            "bisect",
+            "_collections",
+            "_collections_abc",
+            "_functools",
+            "_abc",
+            "_py_abc",
+            "_struct",
+            "_weakrefset",
+            "_weakref",
+            "_thread",
+            "_json",
+            "_hashlib",
+            "_md5",
+            "_sha1",
+            "_sha256",
+            "_sha512",
+            "_sha3",
+            "_blake2",
+            "_bisect",
+            "_heapq",
+            "_warnings",
+            "_operator",
+            "pvm_host",
+            "pvm_sdk",
+            "pvm_sdk.pvm_time",
+            "pvm_sdk.pvm_random",
+            "pvm_sdk.pvm_sys",
+            "pvm_time",
+            "pvm_random",
+            "pvm_sys",
+        ]
+        .into_iter()
+        .map(|item| item.to_owned())
+        .collect()
+    }
+
+    pub fn default_blacklist() -> Vec<String> {
+        vec![
+            "time",
+            "datetime",
+            "random",
+            "secrets",
+            "uuid",
+            "os",
+            "sys",
+            "socket",
+            "ssl",
+            "subprocess",
+            "ctypes",
+            "threading",
+            "multiprocessing",
+            "signal",
+            "select",
+            "asyncio",
+            "pathlib",
+            "glob",
+            "tempfile",
+            "shutil",
+            "zipfile",
+            "inspect",
+            "traceback",
+        ]
+        .into_iter()
+        .map(|item| item.to_owned())
+        .collect()
+    }
+}
+
+impl Default for DeterminismOptions {
+    fn default() -> Self {
+        Self {
+            enabled: false,
+            hash_seed: 0,
+            stdlib_whitelist: Self::default_whitelist(),
+            stdlib_blacklist: Self::default_blacklist(),
+            stdlib_hash: None,
+            enable_softfloat: false,
+            enable_gas: false,
+        }
+    }
+}
diff --git a/crates/pvm-runtime/src/guard.rs b/crates/pvm-runtime/src/guard.rs
@@ -0,0 +1,191 @@
+use crate::determinism::DeterminismOptions;
+use rustpython_vm::{
+    PyObjectRef, PyResult, VirtualMachine,
+    builtins::PyListRef,
+    compiler::Mode,
+};
+
+const GUARD_SOURCE: &str = r#"
+import builtins
+import sys
+
+_ALLOW = set(PVM_WHITELIST)
+_DENY = set(PVM_BLACKLIST)
+_REAL_IMPORT = builtins.__import__
+_HOST = _REAL_IMPORT(PVM_HOST_MODULE, None, None, (), 0)
+
+_ALIAS = {
+    "time": "pvm_sdk.pvm_time",
+    "random": "pvm_sdk.pvm_random",
+    "pvm_time": "pvm_sdk.pvm_time",
+    "pvm_random": "pvm_sdk.pvm_random",
+    "pvm_sys": "pvm_sdk.pvm_sys",
+}
+
+
+def _resolve_name(name, globals, level):
+    if level and globals:
+        pkg = globals.get("__package__") or globals.get("__name__")
+        if pkg:
+            parts = pkg.split(".")
+            if level <= len(parts):
+                base = ".".join(parts[: len(parts) - level + 1])
+                return base + ("." + name if name else "")
+    return name
+
+
+def _is_allowed(name, globals=None, level=0):
+    resolved = _resolve_name(name, globals, level)
+    if resolved == "sys" and globals:
+        importer = globals.get("__package__") or globals.get("__name__")
+        if importer and _allowed_by_whitelist(importer):
+            return True
+    parts = resolved.split(".") if resolved else []
+    for i in range(1, len(parts) + 1):
+        prefix = ".".join(parts[:i])
+        if prefix in _DENY:
+            return False
+    if resolved in _DENY:
+        return False
+    if resolved in _ALLOW:
+        return True
+    for i in range(1, len(parts) + 1):
+        prefix = ".".join(parts[:i])
+        if prefix in _ALLOW:
+            return True
+    if resolved:
+        prefix = resolved + "."
+        for item in _ALLOW:
+            if item.startswith(prefix):
+                return True
+    return False
+
+
+def _allowed_by_whitelist(name):
+    parts = name.split(".") if name else []
+    if name in _ALLOW:
+        return True
+    for i in range(1, len(parts) + 1):
+        prefix = ".".join(parts[:i])
+        if prefix in _ALLOW:
+            return True
+    if name:
+        prefix = name + "."
+        for item in _ALLOW:
+            if item.startswith(prefix):
+                return True
+    return False
+
+
+def _alias(name, target):
+    try:
+        if "." in target:
+            leaf = target.rsplit(".", 1)[-1]
+            mod = _REAL_IMPORT(target, None, None, (leaf,), 0)
+        else:
+            mod = _REAL_IMPORT(target, None, None, (), 0)
+    except Exception:
+        return
+    sys.modules[name] = mod
+
+
+if PVM_SYS_PATH is not None:
+    sys.path[:] = PVM_SYS_PATH
+    try:
+        sys.path_importer_cache.clear()
+    except Exception:
+        sys.path_importer_cache = {}
+
+for _name, _target in _ALIAS.items():
+    _alias(_name, _target)
+
+
+def _pvm_import(name, globals=None, locals=None, fromlist=(), level=0):
+    resolved = _resolve_name(name, globals, level)
+    if resolved in _ALIAS:
+        mod = sys.modules.get(resolved)
+        if mod is None:
+            raise _HOST.DeterministicValidationError("alias module missing: " + resolved)
+        return mod
+    if not _is_allowed(name, globals, level):
+        raise _HOST.NonDeterministicError("module not allowed: " + name)
+    return _REAL_IMPORT(name, globals, locals, fromlist, level)
+
+
+builtins.__import__ = _pvm_import
+
+
+class _PvmImportGuard:
+    def find_spec(self, fullname, path=None,>
+        if not _is_allowed(fullname):
+            raise _HOST.NonDeterministicError("module not allowed: " + fullname)
+        return None
+
+
+sys.meta_path.insert(0, _PvmImportGuard())
+
+
+def _blocked_open(*_args, **_kwargs):
+    raise _HOST.DeterministicValidationError(
+        "file IO is disabled in deterministic mode"
+    )
+
+
+builtins.open = _blocked_open
+try:
+    import io as _io
+    _io.open = _blocked_open
+except Exception:
+    pass
+
+if hasattr(builtins, "execfile"):
+    builtins.execfile = _blocked_open
+"#;
+
+pub(crate) fn install(
+    vm: &VirtualMachine,
+    options: &DeterminismOptions,
+    host_module_name: &str,
+) -> PyResult<()> {
+    if !options.enabled {
+        return Ok(());
+    }
+
+    let scope = vm.new_scope_with_builtins();
+    let mut whitelist_items = options.stdlib_whitelist.clone();
+    if !whitelist_items.iter().any(|item| item == host_module_name) {
+        whitelist_items.push(host_module_name.to_owned());
+    }
+    let whitelist = to_pylist(vm, &whitelist_items);
+    scope
+        .globals
+        .set_item("PVM_WHITELIST", whitelist.into(), vm)?;
+    let blacklist = to_pylist(vm, &options.stdlib_blacklist);
+    scope
+        .globals
+        .set_item("PVM_BLACKLIST", blacklist.into(), vm)?;
+    let sys_paths = vm.state.config.paths.module_search_paths.clone();
+    let sys_paths_list = to_pylist(vm, &sys_paths);
+    scope
+        .globals
+        .set_item("PVM_SYS_PATH", sys_paths_list.into(), vm)?;
+    scope.globals.set_item(
+        "PVM_HOST_MODULE",
+        vm.ctx.new_str(host_module_name).into(),
+        vm,
+    )?;
+
+    let code = vm
+        .compile(GUARD_SOURCE, Mode::Exec, "<pvm_guard>".to_owned())
+        .map_err(|err| vm.new_syntax_error(&err, Some(GUARD_SOURCE)))?;
+    vm.run_code_obj(code, scope)?;
+    Ok(())
+}
+
+fn to_pylist(vm: &VirtualMachine, items: &[String]) -> PyListRef {
+    let entries: Vec<PyObjectRef> = items
+        .iter()
+        .map(|item| vm.ctx.new_str(item.as_str()).into())
+        .collect();
+    vm.ctx.new_list(entries)
+}