Enum BlobRef 

pub enum BlobRef {
    Small {
        version: u8,
        uri: String,
        hash: [u8; 32],
        size: u64,
    },
    Manifest {
        version: u8,
        uri: String,
        encoding: Encoding,
        chunks: Vec<ChunkRef>,
        total_size: u64,
    },
    Tree {
        version: u8,
        uri: String,
        encoding: Encoding,
        root_hash: [u8; 32],
        total_size: u64,
        depth: u8,
    },
}

Pointer to content stored out-of-band. Round-trips through every binding as a typed value via the public fields; the substrate uses Self::encode / Self::decode for the wire form.

Two variants:

• BlobRef::Small — payload ≤ BLOB_CHUNK_SIZE_BYTES; a single content-addressed blob. Wire-compatible with v0.15.
• BlobRef::Manifest — payload > BLOB_CHUNK_SIZE_BYTES; carries an ordered ChunkRef list plus an Encoding discriminant. Each chunk is itself a content-addressed Small blob stored independently via the adapter; the manifest exists only as the routing structure that ties them together.

Variants

Small

Single-blob path. Wire-compatible with v0.15.

Fields

version: u8

Encoding version byte. Always BLOB_REF_VERSION_V1 on fresh constructions; decode preserves the on-wire value so upstream code can detect forward-compat scenarios.

uri: String

Adapter-routed URI — e.g. s3://bucket/key, ipfs://<cid>, file:///abs/path, mesh://<hex>. The scheme picks the adapter; the rest is passed through opaque.

hash: [u8; 32]

BLAKE3-256 hash of the canonical bytes the URI resolves to. The substrate verifies this on every successful fetch; an adversarial adapter cannot fake-verify because the check runs in the substrate, not the adapter.

size: u64

Size of the resolved content in bytes. Range-fetch callers use this to bound their reads; the verification path uses it to short-circuit obviously-wrong payloads.

Manifest

Chunked-blob path (v0.2). Wire version BLOB_REF_VERSION_V2_MANIFEST; body schema version BLOB_MANIFEST_BODY_VERSION.

Fields

version: u8

Outer wire discriminator (always BLOB_REF_VERSION_V2_MANIFEST on fresh constructions).

uri: String

Adapter-routed URI.

encoding: Encoding

Replication / erasure encoding for the chunks.

chunks: Vec<ChunkRef>

Ordered chunk list. Empty manifests are rejected on decode (use BlobRef::Small for zero-byte payloads).

total_size: u64

Total payload size = sum of every chunk’s size. Cached for cheap BlobRef::size; validated on decode against the iterated sum.

Tree

Tree-manifest path (v0.3). Wire version BLOB_REF_VERSION_V3_TREE; body schema version BLOB_TREE_BODY_VERSION. Lifts the addressable size from the v0.2 16 GiB cap to 128 PiB at fanout 128 + depth 4 + 4 MiB chunks. The blob’s actual chunk references live at the TreeNode leaves, reachable via the tree walk starting from root_hash.

Fields

version: u8

Outer wire discriminator (always BLOB_REF_VERSION_V3_TREE on fresh constructions).

uri: String

Adapter-routed URI. For the mesh-native path this is mesh://<hex-of-root_hash>; external adapters use their own scheme.

encoding: Encoding

Replication / erasure encoding (inherits the same enum surface as Manifest).

root_hash: [u8; 32]

BLAKE3 hash of the root TreeNode body — the substrate fetches this hash to start the tree walk.

total_size: u64

Total payload size in bytes (sum of every leaf chunk’s size across the whole tree). Cached for cheap Self::size.

depth: u8

Tree depth — 1 for root-as-leaf, up to super::blob_tree::MAX_TREE_DEPTH.

Implementations

impl BlobRef

pub fn small(uri: impl Into<String>, hash: [u8; 32], size: u64) -> BlobRef

Construct a v1 BlobRef::Small. The caller is responsible for the hash matching the content at uri — the substrate verifies on fetch, not on construction.

pub fn new(uri: impl Into<String>, hash: [u8; 32], size: u64) -> BlobRef

👎Deprecated since 0.18.0:

use BlobRef::small for explicit-variant construction

Backwards-compatible alias for Self::small. Pre-v0.2 callers used BlobRef::new(uri, hash, size) which produced the single-blob shape; the new enum surface uses Self::small for the same shape.

pub fn manifest( uri: impl Into<String>, encoding: Encoding, chunks: Vec<ChunkRef>, ) -> Result<BlobRef, BlobError>

Construct a v2 BlobRef::Manifest from a chunk list. The caller is responsible for each chunk’s hash matching the stored chunk; the substrate verifies on fetch.

pub fn tree( uri: impl Into<String>, encoding: Encoding, root_hash: [u8; 32], total_size: u64, depth: u8, ) -> Result<BlobRef, BlobError>

Construct a v3 BlobRef::Tree. The caller is responsible for root_hash matching the BLAKE3 of the root TreeNode’s encoded bytes, and for total_size matching the sum of every leaf chunk’s size across the tree — the substrate verifies the hash on tree-walk descent and cross-checks total_size at the leaves.

Validates:

• total_size > 0 (use BlobRef::Small for zero-byte payloads).
• total_size <= BLOB_TREE_MAX_TOTAL_SIZE (~128 PiB ceiling).
• depth in 1..=MAX_TREE_DEPTH.

pub fn version(&self) -> u8

Outer wire version discriminator — BLOB_REF_VERSION_V1 for Small, BLOB_REF_VERSION_V2_MANIFEST for Manifest, BLOB_REF_VERSION_V3_TREE for Tree.

pub fn uri(&self) -> &str

Adapter-routed URI. The scheme picks the adapter; the rest is passed through opaque.

pub fn size(&self) -> u64

Total payload size in bytes — size for Small, total_size for Manifest, total_size for Tree.

pub fn is_chunked(&self) -> bool

true if this is a chunked-blob manifest (flat Self::Manifest or hierarchical Self::Tree).

pub fn is_tree(&self) -> bool

true if this is a hierarchical-manifest tree.

pub fn small_hash(&self) -> Option<&[u8; 32]>

The single content hash for a Small blob; None for a Manifest or Tree (manifests reference many chunks, each with its own hash — use Self::chunks for Manifest or Self::tree_root_hash for Tree).

pub fn tree_root_hash(&self) -> Option<&[u8; 32]>

The root TreeNode hash for a Self::Tree; None for Self::Small or Self::Manifest.

pub fn tree_depth(&self) -> Option<u8>

The tree depth for a Self::Tree; None for Self::Small or Self::Manifest.

pub fn chunks(&self) -> &[ChunkRef]

The chunk list for a Manifest; empty slice for a Small or Tree (Tree chunks live at the leaf TreeNodes, reachable via tree walk — not flattened here).

pub fn encoding(&self) -> Option<Encoding>

The encoding tag for a Manifest or Tree; None for a Small (Small has no encoding because the bytes are stored directly).

pub fn encoded_len(&self) -> usize

Encoded length in bytes. The Small variant is O(1) — header size plus URI length. The Manifest / Tree variants now use postcard::experimental::serialized_size to measure without allocating, per dataforts perf #174.

Pre-fix these variants called self.encode().len() — a full postcard alloc-encode of the entire body just to read .len() off the temporary and drop it. For a 1000-chunk Manifest, that was 64 KB+ allocated and thrown away per encoded_len call. Workloads that pair encoded_len + encode (typical sizing-then-emit pattern) paid 2× the encode cost.

Post-fix encoded_len walks the structure measuring without allocating the output buffer — same byte count, no Vec churn.

pub fn encode(&self) -> Vec<u8>

Emit the wire form. See the module-level table for the byte layout per variant.

pub fn decode(bytes: &[u8]) -> Result<Option<BlobRef>, BlobError>

Decode a wire form. Returns Ok(None) when the first four bytes are not BLOB_REF_MAGIC (caller should treat the payload as inline). Returns Err only when the magic matches but the rest of the frame is malformed.

pub fn verify(&self, bytes: &[u8]) -> Result<(), BlobError>

Verify bytes resolves to this BlobRef’s hash. Only defined for BlobRef::Small — call sites holding a Manifest verify chunk-by-chunk via Self::chunks; call sites holding a Tree verify via tree-walk descent (each TreeNode’s bytes hash to the parent’s stored child-hash entry). Returns Ok(()) on match, Err(BlobError::HashMismatch) otherwise, Err(BlobError::Decode) on a Manifest / Tree. Runs inside the substrate, not the adapter, so an adversarial adapter cannot fake-verify.

Trait Implementations

impl Clone for BlobRef

fn clone(&self) -> BlobRef

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for BlobRef

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

Formats the value using the given formatter.

impl Eq for BlobRef

impl Hash for BlobRef

fn hash<__H>(&self, state: &mut __H)

where __H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for BlobRef

fn eq(&self, other: &BlobRef) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for BlobRef