Enum Cap 

pub enum Cap {
    Instance(InstanceCap),
    Image(ImageCap),
    Data(DataCap),
    CNode(CNodeCap),
}

One of the four v3 cap kinds.

SSZ note: the HashTreeRoot derive treats Cap as an SSZ Union over the four variants. Each variant’s selector provides the domain separation that the legacy byte-protocol kind tags (0x10..0x50) provided; the per-variant root is computed by that variant’s own HashTreeRoot impl. We do not derive Encode + Decode on Cap itself; caps move through the cache by direct allocation and aren’t wire-transmitted at this SSZ-encoded layer.

rkyv note: the Archive/Serialize/Deserialize derives provide the I/O-boundary wire form. Serialization errors out (no panic) if any slot target is an inline CapHashOrRef::Owned cap — see the module docs.

Clone: the derived Clone recursively clones field-by-field. An inline Owned(Box<Cap>) slot deep-clones the boxed cap. Drop is symmetric.

Variants

Instance(InstanceCap)

Image(ImageCap)

Data(DataCap)

CNode(CNodeCap)

Implementations

impl Cap

pub fn cap_hash(&self) -> CapHash

32-byte content hash. Walks the cap tree via SSZ HashTreeRoot with SHA-256 as the digest; the four variants get their domain separation from the SSZ Union selector.

Substitution invariants preserved by hand-written HashTreeRoot impls on page::PageSlot, page::PageBytes, and super::cache::CapHashOrRef:

• PageSlot::Loaded(p) hashes identically to PageSlot::Missing(p.hash) — a freshly-loaded page substitutes for a missing page without changing the enclosing cap’s hash.
• CapHashOrRef::Hash(h) hashes to h exactly — a freshly- published cap blob substitutes for a content reference without changing the enclosing cap’s hash.

In-flight Owned caps panic: hashing a Cap whose graph still contains an inline CapHashOrRef::Owned(_) target will panic in the SSZ path. Callers must settle the cap graph first. (The rkyv serialise path is fallible for the same case — see the module docs.)

Image hash distinction: Cap::Image(_).cap_hash() and crate::image::image_content_hash hash different types — the cap-resident ImageCap has a flatter layout than the SSZ Image. The cache publishes by cap_hash; the image-hash chain protocol uses image_content_hash.

pub fn data_inline(bytes: &[u8]) -> Self

Build a heap Cap::Data whose content is bytes padded up to the next PAGE_SIZE boundary with zeros. The backing allocation is page-aligned so the kernel can later map the cap’s pages directly into a ring-3 PT.

DataCap.content_len() returns the padded length (always a 4 KiB-multiple). There is no separate logical-size field; callers needing a shorter logical payload (e.g. variable-length args) interpret the meaningful prefix themselves.

pub fn data_inline_with_size(bytes: &[u8], target_size: u64) -> Self

Build a heap Cap::Data whose logical size is at least target_size bytes (rounded up to the next page boundary). bytes fills the low bytes; the remainder is zero (sparse).

pub fn data_from_desc(arena: &[u8], desc: &DataDesc) -> Self

Build a heap Cap::Data from a page-granular crate::image::DataDesc over an Image arena: each named page is materialized from its PAGE_SIZE arena window, omitted pages are the canonical zero page. The single materialization point for Image data slots; the resulting cap hash equals data_inline_with_size(equivalent_contiguous_content, size). The caller must have validated the descriptor (crate::image::DataDesc::validate) against arena.len().

pub fn empty_cnode() -> Self

Build an empty heap Cap::CNode. A CNode is an unbounded hash-keyed map (bounded by storage quota), so there is no size_log to declare.

pub fn image_with_slots( image: &Image, pinned_hashes: &[(Key, CapHash)], initial_hashes: &[(Key, CapHash)], ) -> Result<Self, ImageConvertError>

Build a heap Cap::Image from an SSZ Image plus the caller-resolved pinned/initial slot CapHash pairs.

pub fn instance_with_mem( image_hash_chain: CapHash, image_hash: CapHash, root_cnode: CapHash, mem: DataCap, regs: [u64; 13], pc: u64, gas_remaining: u64, ) -> Self

Build a heap Cap::Instance directly from field values.

mem is the Instance’s read-write memory image (a dense DataCap covering the data extent; pinned read-only mappings are not part of it — see instance::InstanceCap::mem).

Trait Implementations

impl Archive for Cap

where InstanceCap: Archive, ImageCap: Archive, DataCap: Archive, CNodeCap: Archive,

type Archived = ArchivedCap

The archived representation of this type.

type Resolver = CapResolver

The resolver for this type. It must contain all the additional information from serializing needed to make the archived type from the normal type.

fn resolve( &self, resolver: <Self as Archive>::Resolver, out: Place<<Self as Archive>::Archived>, )

Creates the archived version of this value at the given position and writes it to the given output.

const COPY_OPTIMIZATION: CopyOptimization<Self> = _

An optimization flag that allows the bytes of this type to be copied directly to a writer instead of calling serialize.

impl Clone for Cap

fn clone(&self) -> Cap

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Cap

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<__D: Fallible + ?Sized> Deserialize<Cap, __D> for Archived<Cap>

where InstanceCap: Archive, <InstanceCap as Archive>::Archived: Deserialize<InstanceCap, __D>, ImageCap: Archive, <ImageCap as Archive>::Archived: Deserialize<ImageCap, __D>, DataCap: Archive, <DataCap as Archive>::Archived: Deserialize<DataCap, __D>, CNodeCap: Archive, <CNodeCap as Archive>::Archived: Deserialize<CNodeCap, __D>,

fn deserialize( &self, deserializer: &mut __D, ) -> Result<Cap, <__D as Fallible>::Error>

Deserializes using the given deserializer

impl HashTreeRoot for Cap

fn hash_tree_root<__D: Digest<OutputSize = U32>>(&self) -> [u8; 32]

Compute the hash tree root using D as the underlying hash.

impl ResidentCap for Cap

fn from_cap(cap: Cap) -> Self

Wrap a public wire cap for resident storage.

fn as_cap(&self) -> &Cap

Borrow the public wire cap.

fn into_cap(self) -> Cap

Consume the resident payload back into its wire cap.

impl<__S: Fallible + ?Sized> Serialize<__S> for Cap

where InstanceCap: Serialize<__S>, ImageCap: Serialize<__S>, DataCap: Serialize<__S>, CNodeCap: Serialize<__S>,

fn serialize( &self, serializer: &mut __S, ) -> Result<<Self as Archive>::Resolver, <__S as Fallible>::Error>

Writes the dependencies for the object and returns a resolver that can create the archived type.

impl WireOwned for Box<Cap>