WASM Runtime
Understand Paxeer’s in-tree CosmWasm virtual machine, Go and Rust boundary, native library builds, and gas accounting.
paxeer-network/wasm-runtime/, especially lib.go, internal/api/, and libwasmvm/.Runtime responsibilities
The in-tree CosmWasm runtime connects the Go node to a Rust virtual machine through a C interface. It stores and compiles WebAssembly modules, caches them, and executes contract entry points with host callbacks for storage, addresses, queries, and gas.
A contract developer compiles Rust into a .wasm artifact separately. The runtime's StoreCode compiles that WebAssembly into its execution representation; it does not accept Rust source.
Package layout
| Path | Responsibility |
|---|---|
lib.go | CGO-enabled VM, cache lifetime, code storage, and contract entry points. |
lib_no_cgo.go | Shared types, Wasm checksum creation, and version API available without a VM execution build. |
internal/api/ | C bindings, callbacks, memory ownership, iterators, and platform linker settings. |
libwasmvm/ | Rust library and generated C header. |
types/ | Environment, messages, query results, gas, storage, and IBC types shared across the boundary. |
builders/ | Containerized native-library build definitions. |
testdata/ | Compiled contracts used by runtime tests. |
The node imports github.com/sidiora-labs/paxeer-network/wasm-runtime. Use the version in the Paxeer tree with its matching native library and generated bindings.
CGO and native libraries
lib.go is guarded by the cgo build tag. Without CGO, checksum and shared-type utilities remain available, but the VM execution API is not compiled. LibwasmvmVersion explicitly returns an unavailable error when CGO is disabled.
Linker files cover Linux glibc, Linux musl, macOS, Windows, and a system-library mode. Install the native library matching the node's operating system and architecture.
| Build path | Relevant files or targets |
|---|---|
| Linux glibc | link_glibclinux_x86_64.go, link_glibclinux_aarch64.go, release-build-linux |
| Linux musl | link_muslc.go, release-build-alpine |
| macOS | link_mac.go, link_mac_static.go, macOS release targets |
| Windows | link_windows.go, release-build-windows |
| System library | link_system.go and its sys_wasmvm build selection |
Building the runtime
Use the node's installation guide to build Paxeer. When changing the runtime itself, its local Makefile has separate Rust and Go targets. Run these from the repository root:
# Build the native release library and refresh the generated C bindings.
make -C wasm-runtime build-rust-release
# Build the Go packages and demo against the native library.
make -C wasm-runtime build-go
# Run the runtime's Go test suite with the actual native library.
make -C wasm-runtime testThe Rust target copies the compiled library into internal/api/ and updates bindings.h. It requires a working Rust and C toolchain. Containerized release targets build specific distribution artifacts; choose the target matching the node you will run.
VM lifecycle and caching
NewVM creates a cache using a data directory, supported capabilities, a per-execution memory limit, a debug-output setting, and a cache size. Call Cleanup when releasing a VM. StoreCode returns the checksum used for later instantiation and execution; Pin and Unpin control retention in the memory cache.
Code upload, contract instantiation, storage updates, and message dispatch are coordinated by the CosmWasm module. Upload or instantiation permissions are module parameters, not a statement that the VM implementation is absent.
Execution and gas
The VM receives an environment, contract message bytes, storage and query callbacks, and gas limits. Its result carries contract data, emitted messages, and execution gas information back to the module. Host work also consumes gas through the supplied meter.
When an EVM contract calls the wasmd precompile, the adapter maps the supplied EVM gas into the native execution meter and reports remaining gas. A read-only call made from another on-chain contract still consumes execution gas. Measure the complete call with its real payload and state instead of assuming a fixed gas cost for all CosmWasm operations.
Runtime integration
WASM bindings add Paxeer-specific query and message handlers. EVM precompiles expose selected runtime and native-module operations to Solidity. Their ABI and execution-context checks are part of the integration contract.