A centralized manager of vats and distributed objects. See the Kernel class.
A unit of compute managed by the kernel. See the VatHandle and VatSupervisor classes.
Persistent key-value storage for a vat's durable state. Baggage survives vat
restarts (resuscitation) and is the primary mechanism for vat state persistence. Baggage
is provided as the third argument to buildRootObject.
The initialization method called on the bootstrap vat's root object when a subcluster is first launched. The bootstrap method receives references to other vats and kernel services and is called exactly once — it is not called again after a vat restart.
See subcluster.
A remotable object created with makeDefaultExo() from @metamask/kernel-utils/exo. Exos
are the standard way to create objects that can be passed between vats, stored in
baggage, and invoked via E(). Do not use Far() from @endo/far.
A persistent object residing in a vat and asynchronously accessible to other vats. See the implementation in the kernel's storage methods.
An object registered with the kernel that vats can invoke via E().
Kernel services run in the kernel's own context (not in a vat) and are registered using
kernel.registerKernelServiceObject(). Because service implementations do not participate
in the kernel's reference management, they cannot return exos. Services marked
systemOnly can only be accessed by system subclusters. See the
KernelServiceManager.
A kernel-space component that manages the lifecycle and communication of a vat. The VatSupervisor handles message delivery, syscalls, and vat initialization.
A host/Web API value — setTimeout, Date, crypto, URL, etc. — that is installed in
a vat's SES Compartment at initialization. Compartments do not expose these
APIs by default; vats request them by name via the globals field in their VatConfig.
Many endowments are attenuated for security or isolation (e.g., per-vat timer queues
so one vat cannot clear another's timers, monotonically-clamped Date.now()) — they
are callable but deliberately differ from host semantics. See Vat
Endowments and the default factory in
endowments.ts.
A framework for managing object lifecycles within vats. Liveslots provides the runtime environment for vat code and handles object persistence, distributed promise management, and syscall coordination.
A single execution cycle of the kernel's run loop. Each crank processes one
item: a control operation such as reset, a message from a remote peer, or an item off
the run queue, such as a message or notification for a vat. The
first two wait in memory until their crank comes. Cranks can be aborted and rolled back if
errors occur. See the
KernelQueue for the run loop implementation.
A system call made by a vat to request kernel services. Syscalls include operations like sending messages, resolving kernel promises, and accessing persistent storage. See VatSyscall and the syscall service.
The process of sending a message or notification to a vat in a crank. Deliveries can be of type 'message', 'notify', 'dropExports', 'retireExports', 'retireImports', or 'bringOutYourDead'. See the kernel router (KernelRouter) for delivery logic.
The process of serializing and deserializing data for transmission between vats.
The kernel uses marshaling to convert object references and data structures into a format
suitable for cross-vat communication. See the kernel marshal
service for kser and kunser
functions.
A persistent record in the kernel store that tracks the state of a promise across vat
boundaries. A kernel promise has a state (unresolved, fulfilled, or rejected), a
decider, a list of subscribers, and (once settled) a value. Kernel promises
survive vat restarts and crank rollbacks.
Kernel promises are distinct from JavaScript promises. Vat code works with JS promises
and E() calls; liveslots translates between the vat's JS promises and
kernel promise IDs (krefs) via syscalls. Kernel-space code (e.g.,
enqueueMessage) may create both a kernel
promise (for routing) and a JS promise (for the caller to await), bridged by a
subscription callback. See the
promise store methods.
The endpoint authorized to settle (fulfill or reject) a kernel promise.
Analogous to a function call: when vat A sends E(obj).foo() to vat B, vat A is the
caller waiting for a result, and vat B is the callee that computes it. B becomes the
decider of the result's kernel promise at delivery time, just as a callee
determines the return value of a function call. Only the decider can resolve the kernel
promise — attempts by other endpoints are rejected. After crank rollback, the
decider reverts to its pre-delivery value, which matters for error handling (e.g.,
rejecting the kernel promise of a message sent to a terminated vat). See
setPromiseDecider and the
authorization check in
resolvePromises.
The process of fulfilling or rejecting a kernel promise. Promise resolutions are delivered as notifications to vats and can trigger cascading resolutions of dependent kernel promises. See the promise store methods for implementation details.
The process of identifying and cleaning up unreachable objects. The kernel performs GC by tracking reference counts and delivering appropriate notifications to vats. Important: the garbage collection systems of the kernel, liveslots, and javascript are all mutually independent. See the GC methods and GC service for implementation details.
The process of invalidating an object reference, preventing further access to the object. Revoked objects return errors when accessed. See the revocation methods for implementation.
A form of attenuation in which every method of the derived exo is an unaltered forward to the same method of the exo it narrows, admitting a subset of that method's arguments. Narrowings of a common capability form a lattice whose join is computable syntactically, which is what separates narrowing from attenuations that rewrite arguments or add behavior. See Attenuation by narrowing.
A communication pathway between different components, such as between a vat and the kernel, or between different clusters. Channels use streams for message passing. See the BaseDuplexStream for the core channel implementation.
A remote asynchronous iterator that provides bidirectional communication between
components. Streams implement the Reader interface from @endo/stream and can be used
for message passing between vats, kernel components, and external systems. See the
BaseDuplexStream for bidirectional
streams.
A logically related group of vats, intended to be operated together. Defined by a
ClusterConfig. When a subcluster is launched, all its vats start and the
bootstrap vat receives references to the other vats. See the ClusterConfig
type in packages/ocap-kernel/src/types.ts.
A subcluster declared at kernel initialization that can access
privileged (systemOnly) kernel services. System subclusters persist
across kernel restarts and are identified by a unique name. See the
SubclusterManager.
The kernel's main execution queue that processes messages, notifications, and garbage collection actions. See the KernelQueue class and queue methods for implementation details.
The loop in KernelQueue that takes items one
at a time, each in a crank of its own, and sleeps when none are waiting. It takes
a control operation (clearStorage, reset or terminateAllVats) ahead of everything
else, then any garbage collection action or reap, then the run queue and the
messages remote peers have sent, in turns, so a peer that sends faster than cranks finish
cannot crowd out the run queue. It is the one writer meant to change the kernel store: work
asked for from outside it, such as a vat restart or termination, or a peer's message or
change of incarnation (but not the acknowledgement a message carries), is queued for it to
carry out rather than written into whichever crank happens to be open. stop ends the run
loop between cranks, once the control operations asked for before it have run. A crank that
throws kills the run loop for the life of the kernel instance; callers still waiting on
queued work, control operations included, are then rejected.
The component responsible for routing messages to the correct vat based on target references and kernel promise states. The router handles delivery logic. See the KernelRouter for routing logic.
A clist (short for "capability list") is a bidirectional mapping between short, channel-specific identifiers and actual object references. The clist is unique to a channel-runtime pair, and translates between the javascript runtime which holds the object references and the channel which communicates about them.
An ERef (short for "endpoint reference") is a generic term for a ref which is either a vref or an rref.
A KRef (short for "kernel reference") designates an Object within the scope of the Kernel itself. It is used in the translation of References between one Vat and another. A KRef is generated and assigned by the Kernel whenever an Object reference is imported into or exported from a Vat for the first time.
An RRef (short for "remote reference") designates an object within the scope of an established point-to-point communications Channel between two Clusters. An RRef does not survive the Channel it is associated with. An RRef is generated when the Kernel for one Cluster exports an Object Reference into the Channel connecting it to another Cluster's Kernel.
A VRef (short for "vat reference") designates an Object within the scope of the Objects known to a particular Vat. It is used across the Kernel/Vat boundary in the marshaling of messages delivered into or sent by that Vat. A VRef is generated and assigned by the Kernel when importing an Object Reference into a Vat for the first time and by the Vat when exporting an Object Reference from it for the first time.