CAR Files (Content Addressable Archive)

A CAR (Content Addressable Archive) file is a container format for storing and transferring IPLD (InterPlanetary Linked Data) blocks. It's the standard format for packaging content-addressed data in IPFS ecosystems.

What is a CAR File?

A CAR file contains:

Header - Encoded in DAG-CBOR, specifies version and root CIDs
Blocks - Raw IPLD data blocks, each prefixed with length and CID
Optional metadata - Additional information about the archive

Structure

┌─────────────────────────────────────┐
│  Header (DAG-CBOR encoded)          │
│  - version: 1 or 2                  │
│  - roots: Array of root CIDs        │
├─────────────────────────────────────┤
│  Block 1                            │
│  - length (varint)                  │
│  - CID (content identifier)         │
│  - block data (raw bytes)           │
├─────────────────────────────────────┤
│  Block 2                            │
│  - ...                              │
├─────────────────────────────────────┤
│  ... more blocks ...                │
└─────────────────────────────────────┘

Why CAR Files Matter

CAR files are essential for:

Bulk uploads - Efficiently upload many blocks at once
Data portability - Bundle IPLD data for transfer or storage
Streaming support - Read/write incrementally without loading entire files
Partial reads - CARv2 includes offset/size fields for random access
Directory preservation - Maintain IPLD graph structure (UnixFS, DAGs)

How Pinner Uses CARs

When you upload content through Pinner, the SDK packages your data into CAR format for efficient storage on IPFS. This ensures:

Content is addressed by its cryptographic hash (CID)
Blocks are deduplicated across the network
Data can be retrieved from any IPFS node

Pre-Calculable Root CID

A critical advantage of CAR format is IPFS-nativity. Since CAR contains raw IPLD blocks with their CIDs pre-computed, you can know the root CID of your data before uploading:

import { Pinner } from "@lumeweb/pinner";
 
const pinner = new Pinner({ jwt: "YOUR_API_TOKEN" });
 
// Upload a directory - root CID is calculated locally from IPFS block structure
const files = [
  new File(["Hello, Pinner!"], "hello.txt"),
  new File([JSON.stringify({ name: "config" })], "config.json"),
];
const operation = await pinner.uploadDirectory(files);
 
// Get the root CID - calculated client-side, no server round-trip needed
const rootCid = operation.result.cid;
console.log("Root CID:", rootCid); // e.g., bafybeiemxf5abjwjbikoz4mc3a3dla6ual3jsgpdr4cjr3oz3evfyavhwq

This is impossible with non-IPFS-native formats like ZIP. A ZIP file's checksum is based on raw bytes, not IPFS block hashes. To get the IPFS CID from a ZIP, you'd need to upload it and wait for the server to re-chunk and re-encode the data - introducing trust dependencies and latency.

With CARs, the CID is deterministic and locally verifiable. You're guaranteed the content will resolve to the same CID once pinned.

Uploading CAR Files

npm install @lumeweb/pinner

import { Pinner } from "@lumeweb/pinner";
 
const pinner = new Pinner({ jwt: "YOUR_API_TOKEN" });
 
// Upload a CAR file
const response = await fetch("/path/to/data.car");
const carData = response.body;
const operation = await pinner.uploadCar(carData);
const result = await operation.result;
 
console.log("Root CID:", result.cid);