Warning
This open source code is provided for research, experimentation, and developer education only. This code has not been audited, is actively experimental, and may contain bugs, vulnerabilities, or incomplete features. Use at your own risk and obtain legal advice as appropriate - DYOR.
Parity doesn’t deploy the code but may update it based on community feedback.
If you experience problems with any product or service that was built on or deployed from this code, you should contact the third party who deployed the code in its amended form, not Parity.
Experimental, host-neutral PolkaVM application runtime code developed and published by Parity for native and browser Hosts.
The repository owns one implementation of the App Manifest v2 PolkaVM execution contract across native Rust, browser WebAssembly, framebuffer, Tri2D, WebGPU Raster, and expanded WebGPU presentation. Runtime limits, GPU records, browser workers, and distributable assets are built and reviewed together.
rust/crates/polkavm-host-runtime: execution, hostcalls, lifecycle, bounds, and native/wasm backends.rust/crates/polkavm-wasm-compiler: host-independent bytecode-to-Wasm translation with explicit caller-supplied limits.rust/crates/polkavm-gpu-wire: bounded Tri2D and WebGPU wire protocol.rust/crates/polkavm-motion-wire: bounded motion-sample wire protocol.rust/crates/polkavm-ui-wire: bounded cursor, clipboard, navigation, and IME output protocol.rust/crates/polkavm-host-runtime-assets: source-identified browser assets exposed as static Rust data.rust/crates/polkavm-assets-export: exports those assets for Android, iOS, and browser packaging.js/packages/polkavm-browser-runtime: source-built@parity/polkavm-browser-runtimepackage.docs/runtime/polkavm-app-abi-v1.md: application ABI contract.docs/runtime/tri2d-v1.md: Tri2D frame, command, retained-resource, and limit contract.
The engine is pinned to immutable upstream revision
642fa95a6f1df85612bdbd0a7e4353a2aa4dc9b5 (0.37.0), which includes the
interpreter stack-residency fix: resident stack length is bounded by the
declared stack size, independently of allocation capacity. Native and browser
interpreter builds use that same upstream crate; no local engine fork is needed.
Native Hosts can consume polkavm-host-runtime directly. TrUAPI-based native
Hosts may instead use the optional truapi-polkavm-host composition crate in
paritytech/host-rust-core, which
owns its runtime pin and TrUAPI routing. Do not add a second independent runtime
version underneath that bridge. The base TrUAPI implementation is PolkaVM-free.
Browser Hosts consume @parity/polkavm-browser-runtime directly; browser workers
and assets come from this repository, not host-rust-core. In either integration,
the Host owns product verification, identity, permissions, transport, persistent
storage, presentation, and device/UI resource cleanup. The runtime does not
grant permissions or interpret opaque TrUAPI requests on the Host's behalf.
Native UniFFI hosts mediate opaque TrUAPI frames through
take_host_frame_request() and send_host_frame_response(); the runtime keeps
the guest-facing host_frame_send / host_frame_poll queues bounded.
Native callers terminate execution explicitly with NativePolkaVmRuntime.stop().
Guest execution and host-transport failures also stop the runtime; subsequent
input, output, GPU, audio, and host-frame operations return
NativePolkaVmError::Stopped, while is_exited() reports true. Consumers
must regenerate their UniFFI bindings when updating to this API surface.
Large browser guests use bounded groups of Wasm functions instead of one function per basic block, avoiding browser function-count limits while preserving gas accounting and hostcall resumption. Long PolkaVM blocks split after 64 instructions, amortizing translated tail dispatch while keeping generated function bodies bounded. Compilation first uses one module to keep calls local. If the browser exhausts native compilation capacity, the runtime retries with bounded code modules sharing guest memory, registers, and dispatch state before falling back to the interpreter. Cached compiled programs include the root and every code module; instantiation creates fresh guest state.
File handlers are runtime registrations on the mediated-input lifecycle
(ABI v1 §File input). A Host declares the deliveries it serves with
set_file_input_support (browser start option fileInput), reads the
registrations with file_registrations (file-registrations messages), and
delivers a selected file with send_file_input (file-input). The runtime
enforces descriptor rules and maxBytes before any byte reaches the guest. A
relaunch delivery stops the execution and returns the file, which the Host
mounts in a fresh execution with set_file_relaunch (fileRelaunch).
Registrations stay readable after an execution stops or fails.
Application hosts may pause through ApplicationRuntime::set_paused(bool).
Updates do not execute while paused, execution-scoped monotonic clocks freeze,
and resume excludes paused wall time. Wall-clock imports remain real time.
Release held controls before pausing and suspend/clear the host audio device;
the runtime discards pending gameplay actions and audio while retaining input
releases and viewport state for the next update.
The browser endpoint accepts { type: "pause", paused: boolean } and acknowledges
every valid request with { type: "pause-state", paused: boolean }. This is a hard
pause: no updates or external-event wakes execute. Pause is retained before and
during asynchronous startup: initialization completes, but updates wait for resume.
For menu/visibility inactivity without interrupting host-response delivery, use
{ type: "background", backgrounded: boolean, seq?: number }, acknowledged with
{ type: "background-state", backgrounded: boolean, seq?: number }. An optional
nonnegative safe-integer sequence is echoed before any resumed framebuffer.
Hosts combine menu and visibility reasons before sending the effective state.
Background mode freezes elapsed update time and discards gameplay input, motion,
and audio, but services host responses with coalesced bounded update work for
both legacy and demand-driven guests. Queue-full retries also wake servicing;
there are no periodic background frames. Hard pause takes precedence, and
overlapping inactive reasons exclude their combined duration exactly once.
This is not simulation suspension: service updates execute guest code;
wall-clock reads, host requests, saves, and other external side effects remain
possible. Subscriptions are not interrupted or their responses coalesced.
The runtime retains only the latest complete framebuffer while inactive and
delivers it on resume, even if the guest is idle. Tri2D streams are not standalone
snapshots: they include retained texture mutations. Hosts must apply every stream
in order offscreen, retaining only the latest completed presentation for resume.
GPU batches and protocol events likewise remain ordered and lossless; Hosts
suppress new surface presentation rather than discard commands. Already
submitted GPU work may complete at the transition. Hosts also suppress inactive
clipboard/navigation actions, defer pointer-capture acquisition, and cancel
new mediated-input prompts, including file pickers, while retaining current
cursor/IME state. File deliveries accepted while inactive wait for the next
executed update.
Resume does not replay missed ticks or buffered audio, and stopping clears held
presentation and cannot be reversed by queued work or asynchronous compilation.
The worker and Wasm runtime must be rebuilt together:
polkavm_browser_pause_input enforces the same input boundary as translation,
and polkavm_browser_pending_host_frame_responses reports actual queued work
when entering background mode instead of assuming foreground updates polled it.
Browser and native render passes accept registered texture views as offscreen color attachments; zero still selects the surface. Offscreen passes preserve the surface and retain generation and resource-handle validation. These changes remain within application runtime ABI 1, as required by ADR 0001.
Native GPU descriptors are checked before backend creation, and validation, out-of-memory, and internal backend errors are captured at the runtime boundary. Resource quotas include objects retained transitively by views, bindings, and pipelines, plus resources referenced by an in-flight batch. A rejected batch is not transactional: earlier successful commands and their charges remain. These checks do not isolate the Host from native graphics-driver faults.
The Rust and browser computer supervisors share one 8,192-resumption budget across foreground, background, and nested workspace processes per Host turn. Budget exhaustion yields without discarding output, queued input, child state, or pending package resolution. Repeated child faults consume that same budget.
Native and translated CoreVM vectored I/O preserve completed bytes when a later
vector faults. A descriptor fault before any progress returns EFAULT rather
than terminating the guest; short reads and writes stop before later vectors.
The native framebuffer example uses only public APIs, selects the interpreter explicitly, disables audio and external services, captures a real frame, and stops/releases the VM before writing its output:
cargo run -p polkavm-host-runtime --example native_framebuffer -- \
rust/crates/polkavm-host-runtime/tests/fixtures/framebuffer-test.polkavm \
/tmp/framebuffer.ppmIt accepts an asset-free guest path and output path, not a product identifier.
A production launcher must first verify the manifest and archive, choose the
presentation profile, supply bounded assets, and mediate requested services.
native-gpu enables the native renderer; ffi enables UniFFI bindings. Neither
feature is required for this headless example.
Import startSession and its types from @parity/polkavm-browser-runtime.
Provide runtime bytes or a compiled WebAssembly.Module, guest bytes, an asset
array, the selected graphicsProfile, and an ordered onOutput callback.
The session owns one Worker; the Host owns all presentation and permissions.
- Await
session.readybeforesession.send(input). Startup failure rejects it. RuntimeInputandRuntimeOutputcover input, pause/background, graphics, audio, host frames, mediated input, runtime file registrations and delivery, and compiler-cache messages.- Frame pixels are RGBA bytes; audio samples are signed-16-bit bytes. GPU and Tri2D outputs require their corresponding Host renderers.
- Binary inputs are cloned rather than transferred; callers retain ownership.
await session.stop()is idempotent and terminal. It requests cancellation, then forcibly releases an unresponsive Worker after one second of Host scheduling.session.terminalalways resolves after Worker/listener/timer cleanup. Release outstanding Host prompts, audio, graphics, and other resources on every terminal outcome, including startup/callback failure. Stopping before ready rejectsreadywithAbortError; queued startup work cannot resurrect the session.- A runtime error marked
fatal: falsereports a recoverable file-delivery failure; it does not terminate the session. Fatal errors and output-callback failures request runtime shutdown before the Worker is released. - With private file caching enabled, inspect
terminal.cleanupFailed: it is set if cleanup failed or a forced Worker termination left cleanup unconfirmed. Worker termination alone is not proof that private disk files were removed.
Run the browser framebuffer example
after npm run build, serving the repository root over HTTP:
python3 -m http.server 8765 --bind 127.0.0.1Open http://127.0.0.1:8765/js/packages/polkavm-browser-runtime/examples/framebuffer.html.
It loads the real fixture, renders its pixels, and exposes pause, background,
and stop controls. Deployments must serve the Worker and Wasm URLs allowed by
their CSP; do not mix files from different runtime revisions.
The typed ./file-input-router subpath routes selected-file metadata to the
active runtime's file-registrations output, not manifest declarations.
Products supply their ID, entrypoint and current { handle, descriptor }
registrations. The runtime validates handler bounds when the guest registers;
the router rejects malformed or stale metadata rather than mounting files itself.
Host consent precedes reading or delivering a selected file. The router passes
file-input messages through the Host's sendToRuntime callback: stream
handlers receive a Blob, while inline and relaunch handlers receive bounded
bytes. The runtime owns readiness, cancellation and relaunch outcomes.
The file-input prototype
demonstrates routing and consent; it simulates delivery, not an emulator.
polkavm-wasm-compiler exposes translate(program, limits) and
translate_partitioned(program, limits). Its Limits require maximum program
bytes, read-write data, stack, and heap sizes. It contains no Host policy,
application manifest parsing, Worker lifecycle, graphics renderer, or native
engine dependency in production. The native runtime does not pull in the
translator: it is a wasm32 production dependency and a native test dependency.
Both outputs retain the existing guest register/memory/gas/resumption contract.
Partitioned output embeds epoca.pvm.code-part modules: instantiate the root,
then every part importing the root under pvm, before execution. The browser
runtime handles this ordering and caches the complete set. Browser Wasm tail
calls are required by the compiled backend; unsupported compilation falls back
to the interpreter. Compiler tests use the pinned native engine only as an oracle.
The load-helper optimization emits address mapping directly inside each shared load helper, avoiding a second Wasm call on every dynamic load. It retains the general guest-address mapping, including heap-backed fiber stacks; SP is not assumed to point into the reserved stack segment. In a local hardware-WebGPU OpenHV menu comparison, this change alone moved 8.85 to 9.37 FPS while adding 294 bytes to the 204,709,713-byte translated module.
The compiler caches the 13 guest registers in block-local Wasm locals. Dirty registers are published at control transfers, hostcalls, explicit traps, and before potentially trapping memory operations. RV32 writes remain zero-normalized; host register mutations are observed on resumption. Direct forward transfers within a 128-block group branch to the existing Wasm labels instead of re-entering the dispatcher; backward and cross-group transfers still tail-call. Block-entry gas checks are emitted inline to avoid a shared call obscuring register globals from the Wasm optimizer. Gas accounting, the exported register ABI, memory layout, heap limits, and partitioned-module contract are unchanged. All 24 compiler regressions pass, including interpreter comparisons at hostcalls, traps, float intrinsics, and gas resumption.
With the same integer-audio/input-before-render OpenHV guest, matched local
60-second menu captures improved 13.15 → 22.40 FPS (70%). The preserved
published guest/runtime measured 10.15 FPS in the same comparison. Chromium 153
used a non-fallback NVIDIA Ampere WebGPU adapter at 1304×1088 with music enabled.
The final core compiled the guest normally in-browser, without supplied
precompiled guest Wasm: translation took 3,998 ms and the backend was compiler.
A fresh Cold Rage/Rogue AI match exercised construction, placement, and return
to the menu. An earlier long session hit a guest OutOfMemoryException during
map loading. Guest-side diagnostics showed contiguous GC reservation pressure;
OpenHV now uses 4 MiB rather than 16 MiB small-object segments within the same
128 MiB heap ceiling. The uninstrumented guest on rc.8 measured 22.13 FPS,
or 21.52 FPS with browser audio playback active, and passed 21,854 frames including
a 12,800-frame menu soak, construction, world teardown, and a second map with
three AI opponents. The intermittent original terminal failure was not
deterministically reproduced; the guest change mitigates the observed pressure,
not every possible OOM. These are local qualification results, not a general
frame-rate or unlimited-session stability guarantee.
Version numbers describe different boundaries; they are not interchangeable:
| Boundary | Current contract |
|---|---|
| Application manifest | $v: 2, kind: "app" |
| Guest application imports | runtime.abiVersion: 1 |
| Presentation records | Graphics ABI 1, with the selected profile and required limits |
| Browser bootstrap exports | Browser runtime ABI 2; ship Wasm and JS from the same build |
| Engine and blob encoding | Exact revision 642fa95a6f1df85612bdbd0a7e4353a2aa4dc9b5 |
| Conformance guest toolchain | nightly-2025-10-09; polkatool 0.31.0 for 32-bit fixtures and the exact engine revision above for 64-bit fixtures |
The pinned engine passed Linux and Apple M1 qualification,
including forced native JIT execution and an ad-hoc signed hardened macOS host
with allow-jit. This maintenance revision preserves the previous Latest64
blob encoding; see engine maintenance.
For PolkaVM App Kit, match the
guest's linker/blob format, imported host functions, graphics profile, and limits
to this runtime. The conformance fixtures exercise the toolchain above; this is
not a promise that every App Kit application or moving branch is compatible.
Older capabilities.deviceInput declarations are rejected; current device
availability is negotiated by the runtime, not restored through that obsolete
manifest field. Rebuild guests, compiler caches, and Host assets as one reviewed
compatibility change when the engine's blob encoding changes. PolkaVM 0.37.0
alone is insufficient to identify that encoding.
Rust crates are consumed from a reviewed full Git revision or local workspace paths; this repository does not publish them to crates.io. Direct consumers pin the same revision for runtime, wire crates, compiler, and asset crate. Bridge consumers use their bridge's pin instead.
Browser releases are immutable GitHub release tarballs, not npm publications
from this repository (ADR 0002).
Download the reviewed release's parity-polkavm-browser-runtime-<version>.tgz,
check its runtime release manifest/artifact hashes, and install that local tarball
with npm. Registry distribution is owned separately by paritytech/useragent-kit;
its versioning must not be assumed to match this repository.
For local development, npm ci && npm run build && npm run pack:browser
creates the tarball in the repository root. Install that file in the consuming
project, or serve the complete dist/ directory. Native/mobile packaging can use
polkavm-assets-export; it exports the same checked-in files, checksums, and
license notices. A runtime source update requires regenerating those embedded
files before the exporter represents the new build.
cargo +nightly fmt --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-features
npm ci
npm testBuild and export browser assets:
npm run build
cargo run -p polkavm-assets-export -- --output ./out/polkavm-host-runtimeA release is identified by one source commit and records:
- Rust workspace version.
@parity/polkavm-browser-runtimeversion.- native and wasm PolkaVM revisions.
- SHA-256 digest of every browser artifact.
Release tags use v<version>. Moving branch references are not release inputs.
The workspace, Rust crates, and browser package are aligned at 0.3.2-rc.9.
This candidate combines the released rc.8 optimizations with foreground event
wakes and the initial demand-driven update, monotonic clocks for 32-bit and
64-bit guests, and WebGPU device-recovery retries. Recovery retains pending
surface resizes, validates against the replacement device's current limits,
and does not announce success after a failed surface configuration.
Translated hostcall yields retain the remaining complete-call gas budget,
scheduling requests, and per-call service bounds.
It preserves rc.8's block-local register caching, forward dispatch, and inline gas checks described above, and rc.7's exact binary32 add/multiply intrinsics, accepting and returning raw IEEE-754 bits. Native execution, browser fallback and translated Wasm preserve round-to-nearest-even, subnormals, signed zero, and the documented NaN payload/sign rules. The bounded intrinsics consume guest gas without consuming Host I/O quotas. Translated float calls continue directly into the next block when it belongs to the same generated function; gas checks and real Host-call suspension are retained. The application measurements above are local observations, not a general FPS guarantee.
The candidate retains 0.3.2-rc.6's correction for heap-backed fiber stacks:
SP-relative loads and stores use the same guest-address mapping as other dynamic
accesses, rather than assuming SP always points into the reserved stack segment.
The 32-bit and 64-bit regression compares heap-backed and reserved-stack accesses
with the interpreter.
The candidate retains the surface-resize fix: offscreen passes retain their
resources across resize, stale default-surface passes report error 4 with
the offending command index, and offscreen/resource-only work does not count
as a presented frame. It retains PolkaVM engine
642fa95a6f1df85612bdbd0a7e4353a2aa4dc9b5 and the prior translated-dispatch
optimization, without adding the unfinished checkpoint changes.
It remains a prerelease, not a stable compatibility promise. The release generator
deliberately refuses inconsistent versions, dirty or untagged source, stale embedded
files, or mismatched compiler/engine provenance.
See CONTRIBUTING.md for preparation and integrity checks.
Local rc.9 integration qualification passed 344 browser tests, 34 release-integrity tests, the all-feature Rust workspace suite, and all seven opt-in native GPU regressions. The rebuilt 32-bit and 64-bit clock fixtures matched their checked-in bytes; both browser backends produced monotonic samples over real MessageChannels. Chromium on a non-fallback NVIDIA Ampere adapter recovered from device loss and an injected acquisition failure, applied a pending resize using replacement limits, and completed a real GPU submission. An injected surface-configuration failure remained terminal without announcing restoration. Actual compiler and interpreter Workers also preserved hard-pause, background-idle, foreground-resume, and terminal stop behavior. These local results do not replace the candidate's required CI or qualify every graphics driver.
See SECURITY.md and the Parity security policy. Report unpatched vulnerabilities privately.
MPL-2.0. See LICENSE. Third-party source exceptions retain their original licenses; see THIRD_PARTY_NOTICES.md and the generated license bundle for exact notices, provenance, evidence limitations, and redistribution obligations.