Implement PVM host and runtime modules with initial configurations

- Added `pvm-host` crate for Host API definitions and error types. - Introduced `pvm-runtime` crate for PVM runtime encapsulation, including new features and modules. - Updated Cargo.lock to reflect the addition of `pvm-host` and `pvm-runtime` dependencies.
RustPython · yusufyian · Dec 18, 2025 · Dec 18, 2025 · Dec 19, 2025 · Dec 19, 2025
commit 5f547a577b7eb21adebe2c56d1e7c1a4ef6587c0
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/crates/pvm-host/Cargo.toml b/crates/pvm-host/Cargo.toml
@@ -0,0 +1,10 @@
+[package]
+name = "pvm-host"
+version.workspace = true
+authors.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+repository.workspace = true
+license.workspace = true
+
+[dependencies]
diff --git a/crates/pvm-host/src/lib.rs b/crates/pvm-host/src/lib.rs
@@ -0,0 +1,54 @@
+use core::fmt;
+
+pub type Bytes = Vec<u8>;
+
+#[derive(Clone, Debug)]
+pub struct HostContext {
+    pub block_height: u64,
+    pub block_hash: [u8; 32],
+    pub tx_hash: [u8; 32],
+    pub sender: Bytes,
+    pub timestamp_ms: u64,
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub enum HostError {
+    OutOfGas,
+    InvalidInput,
+    NotFound,
+    StorageError,
+    Forbidden,
+    Internal,
+}
+
+impl fmt::Display for HostError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let msg = match self {
+            HostError::OutOfGas => "out of gas",
+            HostError::InvalidInput => "invalid input",
+            HostError::NotFound => "not found",
+            HostError::StorageError => "storage error",
+            HostError::Forbidden => "forbidden",
+            HostError::Internal => "internal error",
+        };
+        f.write_str(msg)
+    }
+}
+
+impl std::error::Error for HostError {}
+
+pub type HostResult<T> = Result<T, HostError>;
+
+pub trait HostApi {
+    fn state_get(&self, key: &[u8]) -> HostResult<Option<Bytes>>;
+    fn state_set(&mut self, key: &[u8], value: &[u8]) -> HostResult<()>;
+    fn state_delete(&mut self, key: &[u8]) -> HostResult<()>;
+
+    fn emit_event(&mut self, topic: &str, data: &[u8]) -> HostResult<()>;
+
+    fn charge_gas(&mut self, amount: u64) -> HostResult<()>;
+    fn gas_left(&self) -> u64;
+
+    fn context(&self) -> HostContext;
+    fn randomness(&self, domain: &[u8]) -> HostResult<[u8; 32]>;
+}
diff --git a/crates/pvm-runtime/Cargo.toml b/crates/pvm-runtime/Cargo.toml
@@ -0,0 +1,17 @@
+[package]
+name = "pvm-runtime"
+version.workspace = true
+authors.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+repository.workspace = true
+license.workspace = true
+
+[features]
+default = ["stdlib"]
+stdlib = ["rustpython/stdlib"]
+
+[dependencies]
+pvm-host = { path = "../pvm-host" }
+rustpython = { path = "../.." }
+rustpython-vm = { workspace = true }
diff --git a/crates/pvm-runtime/src/host.rs b/crates/pvm-runtime/src/host.rs
@@ -0,0 +1,40 @@
+use pvm_host::HostApi;
+use std::cell::Cell;
+use std::marker::PhantomData;
+use std::mem;
+
+type HostPtr = *mut (dyn HostApi + 'static);
+
+thread_local! {
+    static HOST: Cell<Option<HostPtr>> = Cell::new(None);
+}
+
+pub struct HostGuard<'a> {
+    _marker: PhantomData<&'a mut dyn HostApi>,
+}
+
+impl<'a> HostGuard<'a> {
+    pub fn install(host: &'a mut dyn HostApi) -> Self {
+        let ptr = host as *mut dyn HostApi;
+        // Erase the lifetime; the guard ensures the pointer is only used in-scope.
+        let ptr = unsafe { mem::transmute::<*mut dyn HostApi, HostPtr>(ptr) };
+        HOST.with(|cell| cell.set(Some(ptr)));
+        Self {
+            _marker: PhantomData,
+        }
+    }
+}
+
+impl Drop for HostGuard<'_> {
+    fn drop(&mut self) {
+        HOST.with(|cell| cell.set(None));
+    }
+}
+
+pub(crate) fn with_host<R>(f: impl FnOnce(&mut dyn HostApi) -> R) -> Option<R> {
+    HOST.with(|cell| {
+        let ptr = cell.get()?;
+        // Safety: host pointer is installed for the duration of an execution.
+        Some(unsafe { f(&mut *ptr) })
+    })
+}
diff --git a/crates/pvm-runtime/src/lib.rs b/crates/pvm-runtime/src/lib.rs
@@ -0,0 +1,85 @@
+mod host;
+mod module;
+
+use pvm_host::{Bytes, HostApi, HostError};
+use rustpython::InterpreterConfig;
+use rustpython_vm::{
+    PyResult, Settings, VirtualMachine,
+    builtins::PyNone,
+    compiler::Mode,
+    scope::Scope,
+};
+
+pub fn execute_tx(host: &mut dyn HostApi, code: &[u8], input: &[u8]) -> Result<Bytes, HostError> {
+    let source = std::str::from_utf8(code).map_err(|_| HostError::InvalidInput)?;
+    let mut settings = Settings::default();
+    settings.argv = vec!["<pvm>".to_owned()];
+
+    let _host_guard = host::HostGuard::install(host);
+
+    let mut config = InterpreterConfig::new().settings(settings);
+    #[cfg(feature = "stdlib")]
+    {
+        config = config.init_stdlib();
+    }
+    config = config.add_native_module("pvm_host".to_owned(), module::make_module);
+    let interpreter = config.interpreter();
+
+    let result = interpreter.enter(|vm| {
+        let res = run_source(vm, source, input);
+        if let Err(err) = &res {
+            vm.print_exception(err.clone());
+        }
+        res
+    });
+
+    match result {
+        Ok(bytes) => Ok(bytes),
+        Err(_) => Err(HostError::Internal),
+    }
+}
+
+fn run_source(vm: &VirtualMachine, source: &str, input: &[u8]) -> PyResult<Bytes> {
+    let scope = setup_main_module(vm)?;
+    scope
+        .globals
+        .set_item("__pvm_input__", vm.ctx.new_bytes(input.to_vec()).into(), vm)?;
+
+    let code_obj = vm
+        .compile(source, Mode::Exec, "<pvm>".to_owned())
+        .map_err(|err| vm.new_syntax_error(&err, Some(source)))?;
+    vm.run_code_obj(code_obj, scope.clone())?;
+
+    extract_output(vm, &scope)
+}
+
+fn setup_main_module(vm: &VirtualMachine) -> PyResult<Scope> {
+    let scope = vm.new_scope_with_builtins();
+    let main_module = vm.new_module("__main__", scope.globals.clone(), None);
+    main_module
+        .dict()
+        .set_item("__annotations__", vm.ctx.new_dict().into(), vm)
+        .expect("Failed to initialize __main__.__annotations__");
+
+    vm.sys_module
+        .get_attr("modules", vm)?
+        .set_item("__main__", main_module.into(), vm)?;
+
+    Ok(scope)
+}
+
+fn extract_output(vm: &VirtualMachine, scope: &Scope) -> PyResult<Bytes> {
+    let output = scope
+        .globals
+        .get_item_opt("__pvm_output__", vm)?;
+
+    let Some(output) = output else {
+        return Ok(Vec::new());
+    };
+
+    if output.downcast_ref::<PyNone>().is_some() {
+        return Ok(Vec::new());
+    }
+
+    output.try_bytes_like(vm, |bytes| bytes.to_vec())
+}
diff --git a/crates/pvm-runtime/src/module.rs b/crates/pvm-runtime/src/module.rs
@@ -0,0 +1,99 @@
+pub(crate) use pvm_host_module::make_module;
+
+#[rustpython_vm::pymodule]
+mod pvm_host_module {
+    use crate::host;
+    use ::pvm_host::{HostApi, HostContext, HostError};
+    use rustpython_vm::{
+        PyObjectRef, PyResult, VirtualMachine,
+        builtins::{PyBaseExceptionRef, PyStrRef},
+        function::ArgBytesLike,
+    };
+
+    fn host_error(vm: &VirtualMachine, err: HostError) -> PyBaseExceptionRef {
+        vm.new_runtime_error(format!("pvm host error: {err}"))
+    }
+
+    fn with_host<R>(
+        vm: &VirtualMachine,
+        f: impl FnOnce(&mut dyn HostApi) -> Result<R, HostError>,
+    ) -> PyResult<R> {
+        let result = host::with_host(f)
+            .ok_or_else(|| vm.new_runtime_error("pvm host is not initialized".to_owned()))?;
+        result.map_err(|err| host_error(vm, err))
+    }
+
+    #[pyfunction]
+    fn get_state(key: ArgBytesLike, vm: &VirtualMachine) -> PyResult<PyObjectRef> {
+        let value = with_host(vm, |host| key.with_ref(|bytes| host.state_get(bytes)))?;
+        Ok(match value {
+            Some(data) => vm.ctx.new_bytes(data).into(),
+            None => vm.ctx.none(),
+        })
+    }
+
+    #[pyfunction]
+    fn set_state(key: ArgBytesLike, value: ArgBytesLike, vm: &VirtualMachine) -> PyResult<()> {
+        with_host(vm, |host| {
+            key.with_ref(|k| value.with_ref(|v| host.state_set(k, v)))
+        })?;
+        Ok(())
+    }
+
+    #[pyfunction]
+    fn delete_state(key: ArgBytesLike, vm: &VirtualMachine) -> PyResult<()> {
+        with_host(vm, |host| key.with_ref(|bytes| host.state_delete(bytes)))?;
+        Ok(())
+    }
+
+    #[pyfunction]
+    fn emit_event(topic: PyStrRef, data: ArgBytesLike, vm: &VirtualMachine) -> PyResult<()> {
+        with_host(vm, |host| data.with_ref(|bytes| host.emit_event(topic.as_str(), bytes)))?;
+        Ok(())
+    }
+
+    #[pyfunction]
+    fn charge_gas(amount: u64, vm: &VirtualMachine) -> PyResult<()> {
+        with_host(vm, |host| host.charge_gas(amount))?;
+        Ok(())
+    }
+
+    #[pyfunction]
+    fn gas_left(vm: &VirtualMachine) -> PyResult<u64> {
+        with_host(vm, |host| Ok(host.gas_left()))
+    }
+
+    #[pyfunction]
+    fn context(vm: &VirtualMachine) -> PyResult<PyObjectRef> {
+        let ctx = with_host(vm, |host| Ok(host.context()))?;
+        Ok(host_context_to_dict(vm, ctx)?.into())
+    }
+
+    #[pyfunction]
+    fn randomness(domain: ArgBytesLike, vm: &VirtualMachine) -> PyResult<PyObjectRef> {
+        let bytes = with_host(vm, |host| domain.with_ref(|d| host.randomness(d)))?;
+        Ok(vm.ctx.new_bytes(bytes.to_vec()).into())
+    }
+
+    fn host_context_to_dict(
+        vm: &VirtualMachine,
+        ctx: HostContext,
+    ) -> PyResult<rustpython_vm::builtins::PyDictRef> {
+        let dict = vm.ctx.new_dict();
+        dict.set_item("block_height", vm.new_pyobj(ctx.block_height), vm)?;
+        dict.set_item(
+            "block_hash",
+            vm.ctx.new_bytes(ctx.block_hash.to_vec()).into(),
+            vm,
+        )?;
+        dict.set_item(
+            "tx_hash",
+            vm.ctx.new_bytes(ctx.tx_hash.to_vec()).into(),
+            vm,
+        )?;
+        dict.set_item("sender", vm.ctx.new_bytes(ctx.sender).into(), vm)?;
+        dict.set_item("timestamp_ms", vm.new_pyobj(ctx.timestamp_ms), vm)?;
+        Ok(dict)
+    }
+
+}
diff --git a/refs/PVM_CHAIN_INTEGRATION_CN.md b/refs/PVM_CHAIN_INTEGRATION_CN.md
@@ -361,3 +361,21 @@ flowchart LR
         N -->|No| P[Rollback State Overlay]
     end
 ```
+
+## 11. 本次方案落地的实际改动（仓库内）
+
+以下是已按本方案落地的具体代码变更点（与 Alto 适配层解耦）：
+
+- 新增 `crates/pvm-host`：Host API 定义与错误类型
+  - `crates/pvm-host/Cargo.toml`
+  - `crates/pvm-host/src/lib.rs`（`HostApi`/`HostContext`/`HostError`）
+- 新增 `crates/pvm-runtime`：PVM 运行时封装与 `pvm_host` 原生模块
+  - `crates/pvm-runtime/Cargo.toml`（新增 `stdlib` feature 与默认开启）
+  - `crates/pvm-runtime/src/lib.rs`（`execute_tx` + VM 初始化 + 结果提取）
+  - `crates/pvm-runtime/src/module.rs`（`pvm_host` 模块：state/event/gas/context/randomness）
+  - `crates/pvm-runtime/src/host.rs`（Host 句柄安装/卸载与线程本地桥接）
+
+说明：
+- 当前 `execute_tx` 接口采用源代码字节串执行（`code: &[u8]`，UTF-8），输出通过 `__pvm_output__` 约定返回 bytes。
+- Host 句柄为每次执行安装的线程本地指针，生命周期由 `HostGuard` 控制，避免 PVM 与链对象硬耦合。
+- VM 初始化使用 `rustpython::InterpreterConfig`，避免直接侵入 `rustpython-vm` 内部构建路径。