From: Brian Warner <warner@allmydata.com>
Date: Fri, 8 Jun 2007 04:50:58 +0000 (-0700)
Subject: docs/thingA.txt: describe what this does, even if it doesn't yet have a name
X-Git-Tag: allmydata-tahoe-0.3.0~11
X-Git-Url: https://git.rkrishnan.org/frontends/wapi.txt?a=commitdiff_plain;h=243300f84361e5510c513eb1f4bf09585fc2afa5;p=tahoe-lafs%2Ftahoe-lafs.git

docs/thingA.txt: describe what this does, even if it doesn't yet have a name
---

diff --git a/docs/thingA.txt b/docs/thingA.txt
new file mode 100644
index 00000000..895de8a2
--- /dev/null
+++ b/docs/thingA.txt
@@ -0,0 +1,45 @@
+
+We need a new name for this intentionally-vague block of data.
+
+This block is a bencoded dictionary. All buckets hold an identical copy. The
+hash of the serialized data is kept in the URI.
+
+The download process must obtain a valid copy of this data before any
+decoding can take place. The download process must also obtain other data
+before incremental validation can be performed. Full-file validation (for
+clients who do not wish to do incremental validation) can be performed solely
+with the data from this block.
+
+At the moment, this data block contains the following keys:
+
+ size
+ segment_size
+ num_segments
+ needed_shares
+ total_shares
+
+ codec_name
+ codec_params
+ tail_codec_params
+
+ share_root_hash
+ fileid
+ plaintext_root_hash
+ verifierid
+ crypttext_root_hash
+
+
+Some pieces are needed elsewhere (size should be visible without pulling the
+block, the Tahoe3 algorithm needs total_shares to find the right peers, all
+peer selection algorithms need needed_shares to ask a minimal set of peers).
+Some pieces are arguably redundant but are convenient to have present
+(test_encode.py makes use of num_segments).
+
+fileid/verifierid need to be renamed 'plaintext_hash' and 'crypttext_hash'
+respectively.
+
+The rule for this data block is that it should be a constant size for all
+files, regardless of file size. Therefore hash trees (which have a size that
+depends linearly upon the number of segments) are stored elsewhere in the
+bucket, with only the hash tree root stored in this data block.
+