> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bitfield.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Content-addressed storage

> What content addresses are and why they matter for speed, integrity, and reuse.

<div className="bf-article">
  <p className="bf-lead">
    A content address is a name for bytes that comes from the bytes themselves.
  </p>

  Your product stores the same help text, image bytes, or package-owned file more than once. A normal name tells you where somebody put it. A content address tells you what the bytes are.

  <div className="bf-flow" aria-label="Content address flow">
    <div className="bf-flow-step">
      <span>Bytes</span>
      <strong>Content exists</strong>
      <p>The product has bytes it wants to store or reuse.</p>
    </div>

    <div className="bf-flow-arrow">→</div>

    <div className="bf-flow-step">
      <span>Identity</span>
      <strong>Address from content</strong>
      <p>The address changes when the bytes change.</p>
    </div>

    <div className="bf-flow-arrow">→</div>

    <div className="bf-flow-step">
      <span>Use</span>
      <strong>Lookup or read</strong>
      <p>Bitfield can use the identity as part of the local storage path.</p>
    </div>
  </div>

  The important distinction is an exact warm local read versus a content address lookup. They are useful for different jobs.

  ## What this means

  Content-addressed storage = storing bytes so the content can be found by a fingerprint of the content.

  Fingerprint = a short identity made from the bytes. If the bytes change, the fingerprint changes.

  That gives Bitfield a useful rule. The same bytes have the same identity. Different bytes have a different identity.

  ## Why this matters

  Most app code thinks in names that people made up. A record might be called `user_123`, `invoice_9`, or `project-settings`. Those names are useful, but they do not prove what bytes are inside.

  A content address points at the bytes by what they are. That makes identity, reuse, and integrity easier to explain:

  <div className="bf-grid">
    <div className="bf-card">
      <strong>Identity.</strong>
      The address points at the content, not at a random storage location.
    </div>

    <div className="bf-card">
      <strong>Reuse.</strong>
      The same content can share the same identity instead of being treated like a totally new file.
    </div>

    <div className="bf-card">
      <strong>Integrity.</strong>
      If the bytes change, the identity changes, so silent changes are easier to catch.
    </div>
  </div>

  ## How this connects to speed

  Content addresses do not make every job instant. They remove a kind of searching when the system already knows which content it needs.

  That is why the benchmark ledger separates `warm-local-read` from `content-address-lookup`. A warm local read means Bitfield already knows the local bytes to read and the needed pages are warm. A content address lookup means Bitfield first resolves the content identity, then reads.

  Those are both local jobs. They are not the same job.

  ## What stays private

  Public docs can explain that content addresses exist and what they do.

  Public docs do not expose private byte layouts, private hash framing, private record encoding, or raw benchmark logs.

  That boundary is not a lack of proof. It is the difference between explaining how the product works and handing out proprietary implementation details.

  <div className="bf-callout">
    Content address = a name made from the bytes. That is the public idea. The private layout stays private.
  </div>

  ## Common mistakes

  | Mistake                                           | Why it hurts                                                        | Better path                                                           |
  | ------------------------------------------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------- |
  | Treating content address lookup as exact read     | Lookup work is included                                             | Use the claim category in [Benchmark ledger](/proof/benchmark-ledger) |
  | Treating human names as proof of content          | A name can point at changed bytes                                   | Use content identity for byte identity                                |
  | Asking public docs for private hash framing       | It crosses the disclosure boundary                                  | Stay with the public concept and proof rows                           |
  | Saying content addressing makes every job instant | Network, cold storage, writes, and runtime calls are different jobs | Use [Measurement methodology](/proof/methodology)                     |

  ## Next

  * Learn callable pieces: [Slots](/concepts/slots)
  * Build with package-owned bytes: [Package-owned file](/runtime-kit/cookbook/package-owned-file)
  * Compare proof rows: [Benchmark ledger](/proof/benchmark-ledger)
</div>