How wnfs-wg/rs-wnfs works
Project Type and Purpose
• This is a multi‐crate Rust library (an open‐source tool) implementing the WebNative FileSystem (WNFS) spec.
• It provides both a native Rust API (crate “wnfs”) and WebAssembly bindings (“wnfs‐wasm”), plus related core libraries (“wnfs‐common”, “wnfs‐hamt”, “wnfs‐nameaccumulator”, “wnfs‐unixfs‐file”).
• It’s content‐addressable, versioned, supports private (encrypted) and public (unencrypted) filesystems, with pluggable BlockStore backends and collaborative editing.
High‐Level File/Crate Structure
Top-level crates and folders:
– wnfs : main Rust crate exposing public/private FS APIs
– wnfs‐wasm : wasm‐bindgen wrapper for browser/JS usage
– wnfs‐common : shared traits & utilities (BlockStore trait, encoding, errors)
– wnfs‐hamt : Hash Array Mapped Trie implementation for private forests
– wnfs‐nameaccumulator : name‐accumulator logic for proof generation
– wnfs‐unixfs‐file : UnixFS file chunking & balanced‐tree builder
– wnfs‐bench : benchmarking harness
– scripts, examples, tests, CI config
Core Architectural Components
• “BlockStore” trait (wnfs‐common) – abstract storage interface (in‐memory, IPFS, etc.)
• PublicDirectory / PublicFile (wnfs) – unencrypted filesystem tree, serializes to IPLD
• PrivateDirectory / PrivateFile (wnfs) – encrypted, stored inside a PrivateForest (HAMT)
• HamtForest (wnfs‐hamt) – HAMT‐based key→CID map for private FS nodes
• NameAccumulator (wnfs‐nameaccumulator) – per‐node naming & proof metadata
• UnixFsFileBuilder (wnfs‐unixfs‐file) – chunker, balanced tree, codecs for file contents
• Wasm glue (wnfs‐wasm) – binds PublicDirectory, PrivateDirectory, BlockStore to JS/TS
Relationships & Data Flow
– User code (Rust or JS) uses PublicDirectory / PrivateDirectory APIs.
– On write/mkdir: FS API calls into directory node modules, which:
• public: builds IPLD DAG nodes → BlockStore.put()
• private: encrypts data → HamtForest.insert(key, cid) → BlockStore.put()
– Directory ls/read: retrieves CIDs via HAMT or links, decodes from BlockStore.
– NameAccumulator tracks node names through edits for proof generation.
– UnixFS file operations use chunkers to split data, then store chunks in BlockStore.
Architectural Patterns & Principles
– Clean separation by crate: core traits (wnfs‐common) → data structures (hamt, nameacc) → high‐level API (wnfs) → language binding (wnfs‐wasm)
– Trait‐based abstractions (BlockStore, PrivateForest) for pluggable backends
– Content‐addressable design: CIDs as keys in HAMT and public links
– Functional, immutable‐style edits via Rc<…> wrappers for easy rollback & collaboration
– Modular UnixFS chunking and codecs for file content