Skip to content

Commit 3db70ce

Browse files
author
Robin Berjon
committed
block vs data
1 parent d44b37b commit 3db70ce

File tree

2 files changed

+32
-42
lines changed

2 files changed

+32
-42
lines changed

‎car.html‎

Lines changed: 16 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -46,16 +46,17 @@ <h2>Introduction</h2>
4646
<section>
4747
<h2>Parsing CAR</h2>
4848
<p>
49-
The CAR format comprises a sequence of length-prefixed block data, where the first
50-
block in the CAR is the Header encoded as [<a href="#ref-drisl" class="ref">drisl</a>], and the remaining blocks form
51-
the Data component of the CAR and are each additionally prefixed with their CIDs ([<a href="#ref-drisl" class="ref">drisl</a>], [<a href="#ref-cid" class="ref">cid</a>]).
49+
The CAR format is made of a Header followed by a Body. The Header is a length-prefixed
50+
chunk of DRISL ([<a href="#ref-drisl" class="ref">drisl</a>]) and the Body is a sequence of zero or more length-prefixed
51+
blocks that contain a tuple of a DASL CID ([<a href="#ref-cid" class="ref">cid</a>]) which is always 36 bytes long and
52+
the data addressed by that CID.
5253
The length prefix of each block in a CAR is encoded as an unsigned variable-length
5354
integer ([<a href="#ref-varint" class="ref">varint</a>], a variant of <a href="https://en.wikipedia.org/wiki/LEB128">LEB128</a>).
5455
This integer specifies the number of remaining bytes for that block entry, excluding
55-
the bytes used to encode the integer, but including the CID for non-header blocks.
56+
the bytes used to encode the integer, but including the CID for non-Header blocks.
5657
</p>
57-
<pre><code>|------- Header -------| |------------------- Data -------------------|
58-
[ int | DAG-CBOR block ] [ int | CID | block ] [ int | CID | block ] …
58+
<pre><code>|------- Header -------| |------------------- Body -------------------|
59+
[ int | DAG-CBOR block ] [ int | CID | data ] [ int | CID | data ] …
5960
</code></pre>
6061
<p>
6162
The steps to <dfn id="dfn-parse-a-car">parse a CAR</dfn> are:
@@ -75,15 +76,15 @@ <h2>Parsing CAR</h2>
7576
<li>If <var>bytes</var> is empty, terminate these substeps.</li>
7677
<li>
7778
Run the steps to <a href="#dfn-parse-a-car-block-header" class="dfn-ref">parse a CAR block header</a> with <var>bytes</var>
78-
to obtain <var>cid</var> and <var>block size</var>.
79+
to obtain <var>cid</var> and <var>data size</var>.
7980
</li>
8081
<li>
81-
Read <var>block size</var> bytes from <var>bytes</var> and store the
82-
result in <var>block</var>.
82+
Read <var>data size</var> bytes from <var>bytes</var> and store the
83+
result in <var>data</var>.
8384
</li>
8485
<li>
8586
Push an entry onto <var>blocks</var> containing <var>cid</var>,
86-
<var>block size</var>, and <var>block</var>.
87+
<var>data size</var>, and <var>data</var>.
8788
</li>
8889
<li>Return to the beginning of these substeps.</li>
8990
</ol>
@@ -100,7 +101,7 @@ <h2>Parsing CAR</h2>
100101
<ul>
101102
<li>
102103
The object MUST contain a <code>version</code> map entry, the value of which
103-
is always integer-type <code>1</code>. Version numbers is data formats are
104+
is always integer-type <code>1</code>. Version numbers in data formats are
104105
an anti-pattern, and as a result this number is guaranteed never to change.
105106
</li>
106107
<li>
@@ -161,17 +162,11 @@ <h2>Parsing CAR</h2>
161162
<li>If <var>length</var> is 0, throw an error.</li>
162163
<li>
163164
Read a CID ([<a href="#ref-cid" class="ref">cid</a>]) from <var>bytes</var> and store it in <var>cid</var>.
164-
Note: the length of the CID can be inferred by reading its metadata
165-
step by step until the <code>hash size</code> part, which is then used
166-
to consume that many bytes from <var>bytes</var>.
165+
Note: the length of the CID is always 36 bytes.
167166
</li>
167+
<li>Set <var>data size</var> to <var>length</var> minus 36 (the CID length).</li>
168168
<li>
169-
Set <var>CID length</var> to the number of bytes that were required to
170-
read the CID.
171-
</li>
172-
<li>Set <var>block size</var> to <var>length</var> minus <var>CID length</var>.</li>
173-
<li>
174-
Return <var>block size</var> and <var>cid</var>.
169+
Return <var>data size</var> and <var>cid</var>.
175170
</li>
176171
</ol>
177172
</section>
@@ -214,7 +209,7 @@ <h3>Determinism</h3>
214209
<section>
215210
<h3>Security &amp; Verifiability</h3>
216211
<p>
217-
The <code>roots</code> specified by the Header of a CAR is expected to appear somewhere in its Data section,
212+
The <code>roots</code> specified by the Header of a CAR is expected to appear somewhere in its Body section,
218213
however there is no requirement that the roots define entire DAGs, nor that all blocks
219214
in a CAR must be part of DAGs described by the root CIDs in the Header. Therefore, the
220215
<code>roots</code> must not be used alone to determine or differentiate the contents of a CAR.

‎car.src.html‎

Lines changed: 16 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -32,16 +32,17 @@ <h2>Introduction</h2>
3232
<section>
3333
<h2>Parsing CAR</h2>
3434
<p>
35-
The CAR format comprises a sequence of length-prefixed block data, where the first
36-
block in the CAR is the Header encoded as [[drisl]], and the remaining blocks form
37-
the Data component of the CAR and are each additionally prefixed with their CIDs ([[drisl]], [[cid]]).
35+
The CAR format is made of a Header followed by a Body. The Header is a length-prefixed
36+
chunk of DRISL ([[drisl]]) and the Body is a sequence of zero or more length-prefixed
37+
blocks that contain a tuple of a DASL CID ([[cid]]) which is always 36 bytes long and
38+
the data addressed by that CID.
3839
The length prefix of each block in a CAR is encoded as an unsigned variable-length
3940
integer ([[varint]], a variant of <a href="https://en.wikipedia.org/wiki/LEB128">LEB128</a>).
4041
This integer specifies the number of remaining bytes for that block entry, excluding
41-
the bytes used to encode the integer, but including the CID for non-header blocks.
42+
the bytes used to encode the integer, but including the CID for non-Header blocks.
4243
</p>
43-
<pre><code>|------- Header -------| |------------------- Data -------------------|
44-
[ int | DAG-CBOR block ] [ int | CID | block ] [ int | CID | block ] …
44+
<pre><code>|------- Header -------| |------------------- Body -------------------|
45+
[ int | DAG-CBOR block ] [ int | CID | data ] [ int | CID | data ] …
4546
</code></pre>
4647
<p>
4748
The steps to <dfn>parse a CAR</dfn> are:
@@ -61,15 +62,15 @@ <h2>Parsing CAR</h2>
6162
<li>If <var>bytes</var> is empty, terminate these substeps.</li>
6263
<li>
6364
Run the steps to <a>parse a CAR block header</a> with <var>bytes</var>
64-
to obtain <var>cid</var> and <var>block size</var>.
65+
to obtain <var>cid</var> and <var>data size</var>.
6566
</li>
6667
<li>
67-
Read <var>block size</var> bytes from <var>bytes</var> and store the
68-
result in <var>block</var>.
68+
Read <var>data size</var> bytes from <var>bytes</var> and store the
69+
result in <var>data</var>.
6970
</li>
7071
<li>
7172
Push an entry onto <var>blocks</var> containing <var>cid</var>,
72-
<var>block size</var>, and <var>block</var>.
73+
<var>data size</var>, and <var>data</var>.
7374
</li>
7475
<li>Return to the beginning of these substeps.</li>
7576
</ol>
@@ -86,7 +87,7 @@ <h2>Parsing CAR</h2>
8687
<ul>
8788
<li>
8889
The object MUST contain a <code>version</code> map entry, the value of which
89-
is always integer-type <code>1</code>. Version numbers is data formats are
90+
is always integer-type <code>1</code>. Version numbers in data formats are
9091
an anti-pattern, and as a result this number is guaranteed never to change.
9192
</li>
9293
<li>
@@ -147,17 +148,11 @@ <h2>Parsing CAR</h2>
147148
<li>If <var>length</var> is 0, throw an error.</li>
148149
<li>
149150
Read a CID ([[cid]]) from <var>bytes</var> and store it in <var>cid</var>.
150-
Note: the length of the CID can be inferred by reading its metadata
151-
step by step until the <code>hash size</code> part, which is then used
152-
to consume that many bytes from <var>bytes</var>.
151+
Note: the length of the CID is always 36 bytes.
153152
</li>
153+
<li>Set <var>data size</var> to <var>length</var> minus 36 (the CID length).</li>
154154
<li>
155-
Set <var>CID length</var> to the number of bytes that were required to
156-
read the CID.
157-
</li>
158-
<li>Set <var>block size</var> to <var>length</var> minus <var>CID length</var>.</li>
159-
<li>
160-
Return <var>block size</var> and <var>cid</var>.
155+
Return <var>data size</var> and <var>cid</var>.
161156
</li>
162157
</ol>
163158
</section>
@@ -200,7 +195,7 @@ <h3>Determinism</h3>
200195
<section>
201196
<h3>Security &amp; Verifiability</h3>
202197
<p>
203-
The <code>roots</code> specified by the Header of a CAR is expected to appear somewhere in its Data section,
198+
The <code>roots</code> specified by the Header of a CAR is expected to appear somewhere in its Body section,
204199
however there is no requirement that the roots define entire DAGs, nor that all blocks
205200
in a CAR must be part of DAGs described by the root CIDs in the Header. Therefore, the
206201
<code>roots</code> must not be used alone to determine or differentiate the contents of a CAR.

0 commit comments

Comments
 (0)