Struct VsfBuilder 

pub struct VsfBuilder { /* private fields */ }

Builder for complete VSF files with headers and sections

All VSF files automatically include a BLAKE3 hash for integrity verification.

Implementations

impl VsfBuilder

pub fn new() -> Self

Create a new VSF file builder

Note: Every VSF file automatically includes:

• Creation timestamp (current time as ef5, ~2min precision)
• BLAKE3 hash for integrity verification (computed during build())

Examples found in repository

examples/demo_creation_time.rs (line 7)

fn main() {
    println!("=== VSF Creation Timestamp Demo ===\n");

    // Build a simple VSF file
    let result = VsfBuilder::new()
        .add_section(
            "metadata",
            vec![
                ("width".to_string(), VsfType::u(1920, false)),
                ("height".to_string(), VsfType::u(1080, false)),
                ("format".to_string(), VsfType::x("RAW".to_string())),
            ],
        )
        .build();

    match result {
        Ok(bytes) => {
            println!("✓ Successfully built VSF file: {} bytes\n", bytes.len());

            // Write to file
            std::fs::write("/tmp/demo.vsf", &bytes).expect("Failed to write file");
            println!("✓ Written to /tmp/demo.vsf");
            println!("\nRun: cargo run --bin vsfinfo /tmp/demo.vsf");
            println!("\nYou should see the creation timestamp in the header!");
        }
        Err(e) => {
            eprintln!("✗ Build error: {}", e);
            std::process::exit(1);
        }
    }
}

pub fn creation_time_nanos(self, eagle_time: f64) -> Self

Set creation time with nanosecond precision (ef6) Use this for protocols that need unique timestamps for replay protection

pub fn provenance_hash(self, hash: [u8; 32]) -> Self

Set a custom provenance hash (immutable content identity)

Use this when the provenance hash has specific meaning in your protocol, such as linking a response to a challenge. The provenance hash will NOT be recomputed during build() - it stays exactly as you set it.

pub fn signature_ed25519(self, pubkey: [u8; 32], signature: [u8; 64]) -> Self

Add an Ed25519 signature to the header (replaces rolling hash)

The signature should sign the provenance hash. When a signature is present, no rolling hash (hb) is included - the signature provides integrity verification.

Both pubkey (ke) and signature (ge) are included in the header for verification.

pub fn avatar_hash(self, hash: [u8; 32]) -> Self

Add an avatar provenance hash as a header field (davatar_id:hp[hash])

This is the BLAKE3 provenance hash of the sender’s avatar VSF file. Used in ping/pong messages to sync avatar state between peers. Stored as a metadata-only header field with name “avatar_id”.

pub fn provenance_only(self) -> Self

Disable rolling hash - use provenance hash only

Use this for files that don’t need mutable state tracking or signatures. The provenance hash (hp) will still be computed for content identity.

pub fn add_inline_field( self, name: impl Into<String>, values: Vec<VsfType>, ) -> Self

Add an inline metadata field (header-only, no section body)

Creates a field like (d#{name}:value1,value2,...) in the header. Unlike sections, inline fields have no offset/size/count - just name + values.

Use for lightweight control packets (e.g., PT acks) where provenance hash provides integrity and inline values carry the metadata.

Example

VsfBuilder::new()
    .provenance_hash(chunk_hash)
    .provenance_only()
    .add_inline_field("pt_ack", vec![VsfType::u3(seq), VsfType::u3(buf)])
    .build()

pub fn version(self, version: usize, backward_compat: usize) -> Self

Set version numbers

pub fn add_section( self, name: impl Into<String>, fields: Vec<(String, VsfType)>, ) -> Self

Add a structured section with name and items

Examples found in repository

examples/demo_creation_time.rs (lines 8-15)

fn main() {
    println!("=== VSF Creation Timestamp Demo ===\n");

    // Build a simple VSF file
    let result = VsfBuilder::new()
        .add_section(
            "metadata",
            vec![
                ("width".to_string(), VsfType::u(1920, false)),
                ("height".to_string(), VsfType::u(1080, false)),
                ("format".to_string(), VsfType::x("RAW".to_string())),
            ],
        )
        .build();

    match result {
        Ok(bytes) => {
            println!("✓ Successfully built VSF file: {} bytes\n", bytes.len());

            // Write to file
            std::fs::write("/tmp/demo.vsf", &bytes).expect("Failed to write file");
            println!("✓ Written to /tmp/demo.vsf");
            println!("\nRun: cargo run --bin vsfinfo /tmp/demo.vsf");
            println!("\nYou should see the creation timestamp in the header!");
        }
        Err(e) => {
            eprintln!("✗ Build error: {}", e);
            std::process::exit(1);
        }
    }
}

pub fn add_section_with_meta( self, name: impl Into<String>, fields: Vec<(String, VsfType)>, meta: SectionMeta, ) -> Self

Add a structured section with cryptographic metadata (key)

Use this for sections where the header field needs to indicate:

• key: The cryptographic key (ke for Ed25519, kx for X25519)

Example

let builder = VsfBuilder::new()
    .add_section_with_meta(
        "encrypted_data",
        vec![("payload".to_string(), VsfType::v(b'e', encrypted_bytes))],
        SectionMeta::new(VsfType::ke(pubkey.to_vec())),
    );

pub fn add_section_direct(self, section: VsfSection) -> Self

Add a pre-built VsfSection directly Use this when you need fields with multiple values (Vec)

pub fn add_section_direct_with_meta( self, section: VsfSection, meta: SectionMeta, ) -> Self

Add a pre-built VsfSection with cryptographic metadata

pub fn add_unboxed(self, name: impl Into<String>, data: Vec<u8>) -> Self

Add an unboxed data blob (zero-copy section)

pub fn add_unboxed_with_meta( self, name: impl Into<String>, data: Vec<u8>, meta: SectionMeta, ) -> Self

Add an unboxed data blob with cryptographic metadata

Use this for encrypted sections where the header field needs to indicate the encryption key and wrapper type, but the section body is raw bytes.

pub fn build(self) -> Result<Vec<u8>, String>

Build complete VSF file using Vec<Vec> pattern with stabilization loop

Examples found in repository

examples/demo_creation_time.rs (line 16)

fn main() {
    println!("=== VSF Creation Timestamp Demo ===\n");

    // Build a simple VSF file
    let result = VsfBuilder::new()
        .add_section(
            "metadata",
            vec![
                ("width".to_string(), VsfType::u(1920, false)),
                ("height".to_string(), VsfType::u(1080, false)),
                ("format".to_string(), VsfType::x("RAW".to_string())),
            ],
        )
        .build();

    match result {
        Ok(bytes) => {
            println!("✓ Successfully built VSF file: {} bytes\n", bytes.len());

            // Write to file
            std::fs::write("/tmp/demo.vsf", &bytes).expect("Failed to write file");
            println!("✓ Written to /tmp/demo.vsf");
            println!("\nRun: cargo run --bin vsfinfo /tmp/demo.vsf");
            println!("\nYou should see the creation timestamp in the header!");
        }
        Err(e) => {
            eprintln!("✗ Build error: {}", e);
            std::process::exit(1);
        }
    }
}

Trait Implementations

impl Default for VsfBuilder

fn default() -> Self

Returns the “default value” for a type.