Struct ResourceCommitment 

#[non_exhaustive]
pub struct ResourceCommitment {
    pub layout: ChunkLayout,
    pub total_length: u64,
    pub root: Option<String>,
    pub inclusion_proof: Option<String>,
}

The trusted per-resource metadata a download verifies every range against: the chunk boundaries, the total length, the chain-anchored generation root, and (for a resource, not a capsule) the whole-resource inclusion_proof.

Established from the first frame of the first fetched range (or an availability answer + the first frame). Immutable for the life of the download: a range whose first-frame metadata disagrees with this commitment is rejected as a different/forged generation.

Adoption is NOT verification

Every gate available when a layout is adopted — the root match against the caller’s content id, and the chunk_lens-sums-to-total_length consistency check — is satisfiable by a holder that lies consistently, because both compare fields the SAME untrusted holder supplied. Only Verifier::verify_resource_leaf binds the layout to the chain, and it cannot run until the whole resource has been fetched against that layout. So a commitment is a HYPOTHESIS about the resource’s shape, and a holder positioned first in the provider order can therefore deny a read by declaring a short but self-consistent layout for the correct root (#1670, OPEN).

That denial is not fixable from here. Attributing the later refutation to the holder that supplied the layout requires distinguishing “the shape was wrong” from “the bytes were wrong”, and nothing in the system can: per-range verification is length and alignment only, with no per-chunk hash. Three successive attempts to stand a vote over peer DECLARATIONS in for that missing evidence each produced a cheaper denial than the one they replaced, because those declarations are optional wire fields that cost an attacker a keypair to forge and that honest holders legitimately omit. #1670 is re-scoped onto per-chunk attribution, which is the only thing that can name a bad holder.

#[non_exhaustive]: the adoption path is expected to gain provenance once that evidence exists. Build one with from_first_frame or from_first_frame_bounded.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

layout: ChunkLayout

The chunk boundaries (chunk_lens → offsets).

total_length: u64

The full resource ciphertext length.

root: Option<String>

The chain-anchored generation root (64-hex) every range verifies against. None only for a self-verifying capsule fetch that carries no per-resource root.

inclusion_proof: Option<String>

The whole-resource merkle inclusion proof (base64), relayed verbatim from the first frame; None for a capsule: true fetch (the capsule self-verifies on install).

Implementations

impl ResourceCommitment

pub fn from_first_frame( total_length: u64, chunk_lens: Vec<u64>, root: Option<String>, inclusion_proof: Option<String>, ) -> Result<Self, VerifyError>

Build a commitment from first-frame verification metadata, bounded by DEFAULT_MAX_RESOURCE_SIZE.

Equivalent to from_first_frame_bounded with the default ceiling — see it for what the bound defends against.

pub fn from_first_frame_bounded( total_length: u64, chunk_lens: Vec<u64>, root: Option<String>, inclusion_proof: Option<String>, max_resource_size: u64, ) -> Result<Self, VerifyError>

Build a commitment from first-frame verification metadata, refusing a declared total_length above max_resource_size.

Validates that chunk_lens sums to total_length with CHECKED arithmetic (a peer reporting inconsistent metadata is rejected up front) — and, BEFORE that, that the declared length is within the ceiling.

The ceiling is load-bearing, not hygiene. total_length and the individual chunk_lens come from the first frame of a peer that has not proven anything yet, and they SIZE the download: a single chunk becomes at least one whole Range regardless of the window, and the range assembler then buffers up to that length. So an unbounded declared length is a one-frame memory-exhaustion primitive: a peer answering the metadata probe with total_length: 2^40, chunk_lens: [2^40] makes the client try to buffer a terabyte. Bounding it here — before any layout or plan exists — is what keeps that a rejection instead of an allocation. (The range assembler’s own reservation is additionally FALLIBLE, so even a within-ceiling length that this host cannot hold is a recoverable error rather than an uncatchable abort.)

pub fn check_consistent( &self, total_length: Option<u64>, chunk_lens: Option<&[u64]>, root: Option<&str>, ) -> Result<(), VerifyError>

Check that a range’s declared first-frame metadata is consistent with this commitment (same chunk_lens, total_length, and root). Used when a later range’s first frame arrives to reject a source serving a different generation.

Trait Implementations

impl Clone for ResourceCommitment

fn clone(&self) -> ResourceCommitment

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ResourceCommitment

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

Formats the value using the given formatter.

impl Eq for ResourceCommitment

impl PartialEq for ResourceCommitment

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

Equality operator ==.

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

Inequality operator !=.

impl StructuralPartialEq for ResourceCommitment