Crate nub_kernel 

Nub: the JAR v3 microkernel.

This crate defines the Arch substrate trait and the generic Kernel over it. The kernel is a general VM that invokes JAVM programs (see ~/docs/minimum-v3). It is not block-apply specific — block-apply is layered on top in a separate crate.

Layering

    callers (chain runtime / tests / RPC)
                 │
        jar-apply  (block-apply, gas, quota — separate crate, later)
                 │
            javm  (JAVM entrypoint: Javm personality, typed Cap
                 │  surface, guest blob + Hyperlight singleton)
                 │
             nub  (generic Nub<P: Personality> handle over backends)
                 │
    ┌────────────┼────────────────┐
    │                             │
nub-arch-local        nub-arch-x86
(in-process,         (generic bare-metal guest-kernel lib;
 std)                 javm-guest-x86 supplies the personality
    │                 + binaries, no_std + no_main)
    │                             │
    └────────────┬────────────────┘
                 │
             nub-kernel  ← this crate
             (Arch trait, Kernel<A: Arch>, types)

State

The kernel “owns the state”: the invoking Cap::Instance and everything reachable from it. Concretely the Arch impl holds the storage (in-process structures for nub-arch-local, guest-resident structures for nub-arch-x86); the Kernel is a thin generic wrapper that delegates to the Arch.

no_std

This crate is no_std by default with an optional std feature (currently enabled by default for ergonomics on host targets). The Hyperlight Arch impl will pull the no_std build path; in-process consumers use the std build.

Structs

InstanceRef

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

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.

Kernel

The kernel: a thin wrapper over an Arch impl that owns the state. nub is the microkernel that this represents; callers use it via the uniform Nub handle in the nub crate, which selects the backend (local interpreter vs hyperlight RPC) at construction time.

Traits

Arch

Low-level CPU/MMU substrate trait. An Arch impl runs in the same address space as the Kernel that calls it — it owns the kernel’s state and provides the primitives (page mapping, ring transitions, exception handling, …) needed to execute JAVM programs. The skeleton trait only exposes invoke and state_root; the substrate-specific primitives that the kernel will eventually drive (map_pages, install_handler, …) are intentionally not part of the public surface yet — they’re encapsulated inside Arch::invoke for now.

Type Aliases

CapHash

Legacy alias for ObjHash from when the only personality was the JAVM capability system. Prefer ObjHash in new code.

ObjHash

32-byte content hash of a published state object. The personality defines the hash function (JAVM: SSZ hash_tree_root); nub treats the value as an opaque content-addressed key.