Skip to content

Commit 38077b0

Browse files
committed
Refine iroh collections
1 parent 8f93195 commit 38077b0

1 file changed

Lines changed: 3 additions & 3 deletions

File tree

β€Ždocs/how-to/content-addressed-folders.mdβ€Ž

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -110,13 +110,13 @@ Because DRISL and MASL build on CBOR β€” a widely supported serialization format
110110

111111
## iroh collections
112112

113-
An iroh `Collection` is a flat list of `(String, blake3::Hash)` pairs. Filenames are mapped to 32-byte BLAKE3 content hashes. Directory structure is encoded in the name strings as relative paths (e.g. `"assets/style.css"`, `"js/app.js"`), keeping the format flat while representing arbitrary directory trees.
113+
An iroh `Collection` is a way to represent a directory of files as a single content hash, designed for efficient verification and distribution with [iroh-blobs](https://docs.iroh.computer/protocols/blobs). The format is simple by design: a flat list of `(String, blake3::Hash)` pairs. Filenames are mapped to 32-byte BLAKE3 content hashes. Directory structure is encoded in the name strings as relative paths (e.g. `"assets/style.css"`, `"js/app.js"`), keeping the format flat while representing arbitrary directory trees.
114114

115115
On the wire, a collection splits into two blobs:
116116

117117
### The metadata blob (`CollectionMeta`)
118118

119-
Serialized with [postcard](https://docs.rs/postcard) (a compact, no_std-friendly binary format):
119+
Serialized with [postcard](https://docs.rs/postcard):
120120

121121
```
122122
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
@@ -165,7 +165,7 @@ These are standard BLAKE3 hashes, but they can be encoded as CIDs for interopera
165165
- **Compact.** The overhead per file is a varint-prefixed filename in the metadata blob and a 32-byte hash in the root blob.
166166
- **O(1) file lookup.** The root blob is a flat array of fixed-size 32-byte hashes, so finding the Nth file is a constant-time offset (`N * 32` bytes) with no parsing required.
167167
- **Streaming verification.** The root blob is a hash sequence, so a verifier can check individual files incrementally as they arrive.
168-
- **Ready-made distribution.** Collections can be distributed directly over iroh's peer-to-peer network without conversion.
168+
- **Ready-made distribution.** Collections can be distributed in a peer-to-peer fashion with iroh-blobs.
169169
- **BLAKE3.** Fast (parallelizable, SIMD-accelerated), 256-bit digests, and adopted by the [BDASL](https://dasl.ing/bdasl.html) spec.
170170
- **File-level subsetting only.** Individual files can be fetched and verified by their BLAKE3 hash, but there is no way to address a subdirectory as a unit. Fetching a subset means filtering the path list and requesting files one by one.
171171
- **Rust only (for now).** The reference implementation is in Rust. The format is simple enough to implement in other languages β€” it's just postcard-encoded strings and a flat array of BLAKE3 hashes β€” but no other implementations exist yet.

0 commit comments

Comments
Β (0)