Added more comments to the main structs.

crates/node/src/main.rs

@@ -12,7 +12,7 @@ enum VersionedBlock {
 /// verify and decrypt it.
 #[allow(dead_code)]
 struct Block {
-    /// A block is identified by this field, which defines its location in the tree.
+    /// Identifies this block and defines its location in the tree.
     path: Path,
     /// This field contains a collection of `ReadCap`s indexed by the principal who holds them.
     /// `ReadCap`s are envelopments of the key used to encrypt this block.
@@ -22,27 +22,18 @@ struct Block {
     /// is part of.
     write_cap: WriteCap,
     /// The encrypted data contained in this block.
-    body: SymCiphertext<Vec<u8>>,
+    body: Ciphertext<Vec<u8>>,
     /// The contents of the block are covered by a digital signature contained in this field.  
     signature: Signature
 }
 
-/// The body of every non-leaf node in a tree contains this data structure.
-#[allow(dead_code)]
-struct Directory {
-    /// The nodes that are attached to this block tree at this block.
-    nodes: Vec<Principal>,
-    /// The blocks that are descended from this one.
-    children: HashMap<String, FragmentRecord>,
-}
-
 /// An envelopment of a key, which is tagged with the principal who the key is meant for.
 #[allow(dead_code)]
 struct ReadCap {
     /// The principal this `ReadCap` was issued to.
     issued_to: Principal,
     /// An encipherment of a block key using the public key of the principal.
-    key: AsymCiphertext<Key>,
+    key: Ciphertext<Key>,
 }
 
 /// Verifies that a principal is authorized to write blocks in a tree.
@@ -50,55 +41,77 @@ struct ReadCap {
 struct WriteCap {
     /// The principal this `WriteCap` was issued to.
     issued_to: Principal,
+    /// The principal that issued this write cap.
+    issued_by: Principal,
+    /// The path where this write caps's validity begins.
     path: Path,
-    chain: Vec<Certificate>,
+    /// The point in time after which this write cap is no longer valid.
+    expires: Epoch,
+    /// A digital signature which covers all of the fields in the write cap except for next.
     signature: Signature,
+    /// The next write cap in the chain leading back to the root.
+    next: Box<Option<WriteCap>>,
 }
 
+/// Fragments are created from blocks using Erasure Encoding and stored with other nodes in the
+/// network to provide availability and redundancy of data.
 #[allow(dead_code)]
-struct Certificate {
-    issued_to: Principal,
-    issued_by: Principal,
-    signature: Signature,
-    // TODO: Add expiration.
+struct Fragment {
+    /// The path to the block this fragment is from.
+    path: Path,
+    /// The serial number of this fragment.
+    serial: FragmentSerial,
+    /// The actual data.
+    body: Vec<u8>,
 }
 
+/// The body of every non-leaf node in a tree contains this data structure.
 #[allow(dead_code)]
-struct FragmentRecord {
-    stored_by: Hash,
-    serial: u32,
+struct Directory {
+    /// The nodes that are attached to the tree at this block.
+    nodes: Vec<Principal>,
+    /// This block's descendants.
+    children: HashMap<String, HashMap<FragmentSerial, FragmentRecord>>,
 }
 
+/// Keeps track of which principal is storing a fragment.
 #[allow(dead_code)]
-struct Fragment {
-    path: String,
-    serial: u32,
-    body: Vec<u8>,
+struct FragmentRecord {
+    /// The fragment serial number this record is for.
+    serial: FragmentSerial,
+    /// The principal who is storing this fragment.
+    stored_by: Principal,
 }
 
 /// An identifier for a security principal, which is any entity that can be authenticated.
 struct Principal(Hash);
 
-/// Ciphertext which was produced using a symmetric algorithm.
-struct SymCiphertext<T>(T);
-
-/// Ciphertext that was produced using an asymmetric algorithm.
-struct AsymCiphertext<T>(T);
+/// Encrypted data.
+struct Ciphertext<T>(T);
 
 /// An identifier for a block in a tree.
 struct Path(Vec<String>);
 
+/// An instant in time represented by the number of seconds since January 1st 1970, 00:00:00 UTC.
+struct Epoch(u64);
+
+/// The serial number of a block fragment.
+struct FragmentSerial(u32);
+
+/// A cryptographic hash.
 #[allow(dead_code)]
 enum Hash {
     Sha2_256([u8; 32]),
     Sha2_512([u8; 64]),
 }
 
+/// A cryptographic signature.
 #[allow(dead_code)]
 enum Signature {
     Ed25519([u8; 64]),
 }
 
+/// A cryptographic key.
 #[allow(dead_code)]
 enum Key {
     Xsalsa20Poly1305([u8; 32]),