Crate nub 

Nub: the JAR v3 microkernel — uniform caller-facing handle.

The Nub handle is the API callers (chain runtime, tests, RPC, jar-apply) link against. It hides the choice of substrate behind a single invoke surface, dispatching to one of two backends:

• Local: runs the PVM2 (RISC-V) interpreter directly in-process via nub_arch_local::run_instance. Used for tests, deterministic replay, and any host that doesn’t need real ring-0 isolation.
• Hyperlight: ships the invocation as an RPC into a nub-arch-x86 guest binary running inside a Hyperlight sandbox. The actual Kernel<HyperlightArch> lives guest-side; the host holds only the sandbox + a state cache.

Both backends share the same typed publish/invoke surface — the caller publishes a Cap::Image (and optionally a Cap::CNode), publishes a Cap::Instance referencing them, and then invokes by the resulting instance hash.

Structs

InstanceRef

Opaque, 32-byte handle to an Instance held by an Arch.

InvocationResult

Invocation result. Both backends produce this shape on completion; rkyv-archived on the wire from the cached path’s response.

InvokeJob

InvokeJobId

InvokeOptions

Per-invocation knobs. Empty for the skeleton; fields will land as the kernel grows (gas budget overrides, quota budget, tracing, reentrancy depth limits, …).

InvokeOutcome

Result of a successful invocation. Extensible — fields land as needed (gas remaining, post-invocation cap hash, host-call trace, …). For the skeleton we expose only the JAVM HALT return value and gas used.

InvokeRequest

Nub

Uniform handle to the nub microkernel.

NubOptions

Options used when constructing the process-wide Hyperlight Nub singleton.

Constants

MAX_HYPERLIGHT_VCPUS

SCRATCHPAD_HEAD_LEN

Bytes of the running Instance’s scratchpad (slot[0]) region surfaced at the top-level HALT — a fixed-size head of the returned DataCap’s effective content. The guest writes its result into the scratchpad-mapped memory region during the run (CoW into the cap); at top HALT the engine reads the region’s effective bytes back out here, so the host observes the full, uncompressed result without a separate data-flow event.

Type Aliases

AbiCapHash

32-byte Cap::Instance identity hash. Matches javm_cap::CapHash byte-wise (kept as a local alias here so nub-arch-x86-abi stays free of the javm-cap dependency, which pulls in alloc::collections etc.).

CapHash

32-byte content hash. Same shape as javm_cap::CapHash; defined here locally so this crate stays no_std. A future unification pass will share the type once javm-cap becomes no_std-clean.

HyperlightNubGuard

Compatibility alias for older tests/benches that named the returned Hyperlight singleton borrow. Nub is now a cloneable handle; synchronization lives inside the handle instead of in an outer mutex guard.