cid.html

<!DOCTYPE html><html lang="en"><head>

<!--

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!!!!!   GENERATED SPEC — DO NOT EDIT. Look for the .src.html instead   !!!!
!!!!!                                                                  !!!!
!!!!!   HEY YOU                                                        !!!!
!!!!!   YES ***YOU****!                                                !!!!
!!!!!                                                                  !!!!
!!!!!   You're about to edit a generated document.                     !!!!
!!!!!   Don't do that! Why would you do that.                          !!!!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

-->


    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Content IDs (CIDs)</title>
  <link rel="stylesheet" href="spec.css"><link rel="icon" href="data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 100 100%22><rect x=%220%22 y=%220%22 width=%22100%22 height=%22100%22 fill=%22%2300ff75%22></rect></svg>"><link rel="alternate" type="text/markdown" href="https://dasl.ing/cid.md"><meta name="twitter:card" content="summary_large_image"><meta name="twitter:title" property="og:title" content="DASL: Content IDs (CIDs)"><meta name="twitter:description" property="og:description" content="DASL CIDs are a simple structured identifier format for content addressing. They encapsulate a hash         with enough metadata to be extensible (to add new hash types in the future) and to indicate whether         they are pointing to raw bytes or to structured data."><meta name="twitter:image" property="og:image" content="https://dasl.ing/cid.png"><meta name="twitter:image:alt" content="Very colourful stripes, so colourful it hurts"><meta name="twitter:url" property="og:url" content="https://dasl.ing/"><meta property="og:site_name" content="DASL"><meta property="og:locale" content="en"><meta name="theme-color" content="#00ff75"></head>
  <body><div class="nav-back">A specification of the <a href="/">DASL Project</a>.</div><main><header><h1>Content IDs (CIDs)</h1><table><tbody><tr><th>date</th><td>2026-08-06</td></tr><tr><th>editors</th><td><a href="https://berjon.com/">Robin Berjon</a> &lt;<a href="mailto:robin@berjon.com">robin@berjon.com</a>&gt;<br><a href="https://bumblefudge.com/">Juan Caballero</a> &lt;<a href="mailto:bumblefudge@learningproof.xyz">bumblefudge@learningproof.xyz</a>&gt;</td></tr><tr><th>issues</th><td><a href="https://github.com/darobin/dasl.ing/issues">list</a>, <a href="https://github.com/darobin/dasl.ing/issues/new">new</a></td></tr><tr><th>abstract</th><td><div id="abstract">
      <p>
        DASL CIDs are a simple structured identifier format for content addressing. They encapsulate a hash
        with enough metadata to be extensible (to add new hash types in the future) and to indicate whether
        they are pointing to raw bytes or to structured data.
      </p>
    </div></td></tr></tbody></table></header>
    
    <section>
      <h2>Introduction</h2>
      <p>
        DASL CIDs are a simple structured identifier format for content addressing. They encapsulate a hash
        with enough metadata to be extensible (to add new hash types in the future) and to indicate whether
        they are pointing to raw bytes or to structured data. If you're simply using DASL CIDs as identifiers, you
        can almost certainly just use the string as an opaque ID and worry no further.
      </p>
      <p>
        A DASL CID can be represented as a string or as an array of bytes. If you wish to understand the
        internals of a CID, it has the following structure:
      </p>
      <ol>
        <li>
          A <code>b</code> prefix (only in string form). This is an extensibility point for future
          CID encodings other than the current base32 to be supported. (Currently this is the only one.)
        </li>
        <li>
          A version number, which is currently always 1.
        </li>
        <li>
          A content codec, which is a flag indicating whether it is pointing to structured or raw
          data.
        </li>
        <li>
          A hash type, that is always SHA-256 ([<a href="#ref-sha256" class="ref">sha256</a>]).
        </li>
        <li>
          A hash size, that is always 32 (<code>0x20</code>).
        </li>
        <li>
          A digest, which is the hash of the content being identified.
        </li>
      </ol>
    </section>
    <section>
      <h2>Parsing CIDs</h2>
      <p>
        Use the following steps to <dfn id="dfn-parse-a-string-encoded-cid">parse a string-encoded CID</dfn>, i.e. translate it to a bytestring:
      </p>
      <ol>
        <li>Accept a string <var>CID</var>.</li>
        <li>Remove the first character from <var>CID</var> and store it in <var>prefix</var>.</li>
        <li>If <var>prefix</var> is not equal to <code>b</code>, throw an error.</li>
        <li>
          Decode the rest of <var>CID</var> using
          <a href="https://datatracker.ietf.org/doc/html/rfc4648#section-6">the base32 algorithm from
          RFC4648</a> with a lowercase alphabet and store the result in <var>CID bytes</var> ([<a href="#ref-rfc4648" class="ref">rfc4648</a>]).
        </li>
        <li>This results in <var>CID bytes</var>, which can be used to <a href="#dfn-decode-a-cid" class="dfn-ref">decode a CID</a>.</li>
      </ol>
      <p>
        Use the following steps to <dfn id="dfn-decode-a-cid">decode a CID</dfn>:
      </p>
      <ol>
        <li>Accept an array of bytes <var>CID bytes</var>.</li>
        <li>
          Remove the first byte in <var>CID bytes</var> and store it in <var>version</var>.
        </li>
        <li>If <var>version</var> is not equal to <code>1</code>, throw an error.</li>
        <li>
          Remove the next byte in <var>CID bytes</var> and store it in <var>codec</var>.
        </li>
        <li>
          If <var>codec</var> is not equal to <code>0x55</code> (raw) or <code>0x71</code> (DRISL),
          throw an error ([<a href="#ref-drisl" class="ref">drisl</a>]).
        </li>
        <li>
          Remove the next byte in <var>CID bytes</var> and store it in <var>hash type</var>.
        </li>
        <li>
          If <var>hash type</var> is not equal to <code>0x12</code> (SHA-256), throw an error ([<a href="#ref-sha256" class="ref">sha256</a>]).
        </li>
        <li>
          Read one byte from <var>CID bytes</var> and store it in <var>hash size</var>. If <var>hash size</var>
          is any value other than 32 (<code>0x20</code>) , throw an error.
        </li>
        <li>
          Read 32 bytes from <var>CID bytes</var> and store them in <var>digest</var>. If there were
          fewer than 32 bytes left in <var>CID bytes</var>, throw an error.
        </li>
        <li>
          Return <var>version</var>, <var>codec</var>, <var>hash type</var>, <var>hash size</var>,
          and <var>digest</var>.
        </li>
      </ol>
    </section>
    <section>
      <h2>Relationship to IPFS</h2>
      <p>
        You don't need to understand IPFS in order to use DASL. This section is for informational
        purposes only.
      </p>
      <p>
        DASL CIDs are a strict subset of <a href="https://docs.ipfs.tech/concepts/content-addressing/">IPFS CIDs</a>
        with the following properties:
      </p>
      <ul>
        <li>Only modern CIDv1 CIDs are used, not legacy CIDv0.</li>
        <li>
          Only the lowercase base32 multibase encoding (the <code>b</code> prefix) is used for human-readable
          (and subdomain-usable) string encoding.
        </li>
        <li>
          Only the <code>raw</code> binary multicodec (0x55) and <code>dag-cbor</code> multicodec (0x71), with the
          latter used only for [<a href="#ref-drisl" class="ref">drisl</a>]-conformant DAGs of CBOR objects.
        </li>
        <li>Only SHA-256 (0x12) for the hash function .</li>
        <li>
          The CID isn't the boss of anyone, but the expectation is that, regardless of size, resources
          <em>should not</em> be "chunked" into a DAG or Merkle tree (as historically done with UnixFS canonicalization
          in IPFS systems) but rather hashed in their entirety and content-addressed directly. That being
          said, a DASL CID can point to a piece of [<a href="#ref-drisl" class="ref">drisl</a>] metadata that describes this kind of
          chunking, if needed. (A separate specification may be added for that.)
        </li>
        <li>
          This set of options has the added advantage that all the aforementioned single-byte prefixes require no
          additional varint processing or byte-fiddling.
        </li>
      </ul>
    </section>
  

<section><h2>References</h2><dl><dt id="ref-drisl">[drisl]</dt><dd>Robin Berjon &amp; Juan Caballero. <a href="https://dasl.ing/drisl.html"><cite>DRISL — Deterministic Representation for Interoperable Structures &amp; Links</cite></a>. 2026-08-06. URL:&nbsp;<a href="https://dasl.ing/drisl.html">https://dasl.ing/drisl.html</a></dd><dt id="ref-rfc4648">[rfc4648]</dt><dd>S. Josefsson. <a href="https://www.rfc-editor.org/rfc/rfc4648"><cite>The Base16, Base32, and Base64 Data Encodings</cite></a>. October 2006. URL:&nbsp;<a href="https://www.rfc-editor.org/rfc/rfc4648">https://www.rfc-editor.org/rfc/rfc4648</a></dd><dt id="ref-sha256">[sha256]</dt><dd>National Institute of Standards and Technology, <cite>Secure Hash Algorithm. NIST FIPS 180-2</cite>. August 2002.</dd></dl></section></main></body></html>