Filecoin web3.storage Tutorial Advanced: CAR Files, UCAN Auth, and Filecoin Deals Explained

• Key Takeaway 1: web3.storage has evolved into Storacha — all new projects should use @storacha/client or the storacha CLI instead of the old package.
• Key Takeaway 2: Building CAR files client-side gives you a verified Content Identifier (CID) before any data leaves your machine — zero trust required.
• Key Takeaway 3: CAR sharding lets you upload datasets larger than 4 GB by splitting them into smaller pieces, each under the per-shard size limit.
• Key Takeaway 4: UCAN authorization lets apps delegate storage rights to users or services without ever sharing a private key.
• Key Takeaway 5: Filecoin’s Proof of Replication and Proof of Spacetime proofs cryptographically confirm your data is stored — and stays stored — over time.

This filecoin web3.storage tutorial advanced guide walks you through the full production pipeline: building CAR files programmatically, sharding large datasets, managing authorization with UCAN tokens, tracking Filecoin storage deals, and designing multi-tenant app architectures — all using the current Storacha platform that powers web3.storage today.📋 Prerequisite: Before reading this guide, make sure you have completed the beginner article Filecoin web3.storage Tutorial: Store & Retrieve Files on Web3 (2025 Guide). This advanced article assumes you already know how to create a Space, log in via the CLI, and run a basic storacha up command.

What Changed — web3.storage Is Now Storacha

If you used the old web3.storage npm package, there is one critical update to know right away. As of early 2024, web3.storage was rebranded and rebuilt as Storacha. The legacy Web3Storage client and its api.web3.storage endpoint were sunset in January 2024 and no longer accept new uploads.^[1] The new platform lives at storacha.network, and the CLI you now install is @storacha/cli, not the old w3 tool.

The good news is that the core ideas are the same — your data still goes to IPFS hot storage and then into Filecoin deals with multiple storage providers. What changed is the underlying protocol. Storacha now uses the w3up platform, which is built around UCAN (User Controlled Authorization Networks) instead of API tokens. Under this model, your data is tied to a Space (a namespace with a unique Decentralized Identifier, or DID), and permissions are passed as cryptographically signed tokens — not stored in a database somewhere.^[2] This shift is important for advanced usage because it unlocks delegation patterns that simply were not possible before.

For the rest of this guide, all code examples use @storacha/client and @web3-storage/upload-client (the low-level package for manual CAR operations). If you see old examples using client.put() from web3.storage, they are outdated and should not be used for new projects.

Understanding the Full Filecoin Storage Pipeline

Before diving into code, it helps to see exactly what happens when you push data through the Storacha/Filecoin pipeline. Most beginner tutorials hide this detail, but knowing it is what separates someone who uploads files from someone who understands how decentralized storage actually works.

When you upload a file, it does not go straight to Filecoin. First, it gets encoded into an IPLD DAG (InterPlanetary Linked Data Directed Acyclic Graph) — a tree-like structure where each node is a content-addressed block. This DAG is then serialized into a CAR file (Content Archive), which is a portable container format designed for IPFS data. That CAR file is uploaded to Storacha’s hot storage layer, where it becomes instantly retrievable via IPFS gateways. In the background, Storacha batches your data and pushes it into Filecoin storage deals with multiple independent storage providers.^[3] Those providers then periodically submit cryptographic proofs to the Filecoin blockchain confirming they still hold your data. This entire chain — from client-side encoding to on-chain proof — is what makes Filecoin different from a normal cloud storage bucket.

The key insight: your CID is computed locally before any data is sent. This means you can verify, with certainty, that what the service stored is exactly what you uploaded — without trusting Storacha at all.

Building a CAR File Upload Pipeline with filecoin web3.storage

The simplest way to use Storacha is to call a high-level method and let the library do everything for you. But for production systems, you often want direct control over the CAR file itself. This lets you compute CIDs deterministically, parallelize uploads, and retry failed shards without re-encoding your entire dataset.^[4] Here is how to do it using the low-level @web3-storage/upload-client package.

Step 1 — Encode Your File Into a DAG

The first step turns your raw file bytes into a UnixFS DAG and returns a root CID along with all the blocks that make up that DAG. This happens entirely in your local environment — nothing is sent to the network yet.

import { UnixFS, CAR, Blob, Index, Upload } from '@web3-storage/upload-client'
import * as BlobIndexUtil from '@web3-storage/blob-index/util'
import * as Link from 'multiformats/link'

// file is a Blob/File/Uint8Array of your content
const { cid, blocks } = await UnixFS.encodeFile(file)

The variable cid is now your root Content Identifier — a unique, deterministic fingerprint of your data computed using a cryptographic hash. Write this value down or store it in your database. Every other step refers back to it. If the CID you compute here matches the CID returned by the Storacha service later, you have mathematical proof that the service stored exactly what you sent.

Step 2 — Serialize the DAG Into a CAR File

Next, you pack those blocks into a CAR file. A CAR file is essentially a portable zip of all the IPLD blocks in your DAG, with a header pointing to the root CID.

// Serialize the DAG into a single CAR file
const car = await CAR.encode(blocks, cid)

// Create an index so Storacha can find individual blocks inside the CAR
const index = await BlobIndexUtil.fromShardArchives(cid, [
  new Uint8Array(await car.arrayBuffer())
])

You can inspect the CAR file locally at this point, pass it to any IPFS tool, or store a local copy as a backup. This portability is one of CAR’s biggest advantages — your data is not locked into Storacha’s format. Any IPFS node in the world can read a CAR file.

Step 3 — Upload the CAR and Register the Upload

Once your CAR file is ready, you push it to Storacha in three sub-steps: store the blob, store the index, and register the upload. The “upload” registration is what tells Storacha that a specific root CID lives inside one or more CAR shards — this is how the service knows how to reassemble your data when someone requests it.

// conf: your invocation config with issuer, space DID, and proofs
const carDigest  = await Blob.add(conf, car)
const indexDigest = await Blob.add(conf, (await index.archive()).ok)

await Index.add(conf, Link.create(CAR.code, indexDigest))
await Upload.add(conf, cid, [Link.create(CAR.code, carDigest)])

The conf object contains your UCAN authorization context — we cover how to build that in the authorization section below. Once Upload.add returns successfully, your file is live on the IPFS network and queued for Filecoin deals.

How to Handle Large Data — CAR Sharding

One of the most practical skills in this filecoin web3.storage tutorial advanced guide is knowing how to deal with large datasets. Storacha has a maximum upload size of approximately 4 GB per individual CAR shard.^[5] For datasets bigger than that, you need to split your data into multiple smaller CARs, upload each one separately, and then tie them together under a single root CID when registering the upload.

Why Files Need to Be Split

The reason for sharding goes beyond just file size limits. When you split a large CAR into smaller pieces, each piece becomes an independently verifiable unit. If one shard fails to upload, you retry just that shard — not the entire multi-gigabyte dataset. This is a huge advantage for unstable or slow network connections. The @web3-storage/upload-client library supports streaming DAG generation, which means you can send CAR shards to Storacha as the DAG is being built, rather than waiting for the entire encoding to finish first.^[4] For very large archives, this can cut upload times significantly.

Uploading Shards and Registering One Root CID

The process for multi-shard uploads follows the same three steps as a single-file upload, but you loop over each shard and collect all the CAR digests before making a single call to Upload.add. Here is the pattern:

const carDigests = []

for (const shard of carShards) {
  const digest = await Blob.add(conf, shard)
  carDigests.push(Link.create(CAR.code, digest))
}

// One registration call covers all shards
await Upload.add(conf, rootCid, carDigests)

The key rule is that all shards must share the same root CID — this is what lets Storacha reassemble the full DAG accurately when someone retrieves your data. If you use a command-line tool to pre-split CARs, make sure you use the treewalk strategy so that the root CID is preserved across shards.

Advanced Authorization with UCAN — No More Shared API Keys

Traditional web services use API keys for authorization. You generate a token, store it in your app, and include it in every request. The problem is that the token grants access to everything in your account — there is no easy way to give a single user or service just the permissions they need, and no more. UCAN solves this problem in a fundamentally different way.

Spaces, Agents, and Delegations

UCAN (User Controlled Authorization Networks) lets you share storage access without sharing your private key. In the w3up model, your data lives in a Space — a namespace identified by a DID (Decentralized Identifier). Your local Agent holds the private signing key for that Space. When you want to give another device, user, or service the ability to upload to your Space, you issue a UCAN delegation — a signed token that grants specific capabilities (like space/blob/add or upload/add) to a specific audience DID, with an optional expiration time.^[6]

Because delegations are cryptographically signed, the Storacha service can verify them without needing to call back to any central authority. And because they expire, a compromised delegation token automatically becomes worthless after the set time window — unlike a leaked API key, which stays valid until someone manually revokes it.

Delegating Storage Rights in a Multi-Tenant App

Here is a practical example. Suppose you are building a dApp where users upload profile images. You own one Space. You want each user to be able to upload directly from their browser, without you proxying the data through your own server. With UCAN delegation, you can do this cleanly. Your backend creates a short-lived delegation that grants the user’s session DID just the abilities it needs — space/blob/add, space/index/add, filecoin/offer, and upload/add — expiring in 24 hours. The user’s browser receives this delegation and uses it to upload directly to Storacha.^[7] Your server never touches the upload bytes. You keep one Space. Billing stays centralized. It is a clean separation that was difficult to achieve with the old API-key model.

const abilities = ['space/blob/add', 'space/index/add', 'filecoin/offer', 'upload/add']
const expiration = Math.floor(Date.now() / 1000) + (60 * 60 * 24) // 24 hours
const delegation  = await client.createDelegation(audienceDID, abilities, { expiration })

How Filecoin Proves Your Files Are Actually Stored

One of the most common questions developers have after uploading to Storacha is: how do I know Filecoin is actually holding my data? This is where Filecoin’s cryptographic proof system does something no traditional cloud provider can match.

“Proof of Replication is ultimately a proving system to verify that a storage miner actually has the content they are storing and are not cheating.”— Juan Benet, Founder of Protocol Labs and IPFS, speaking on the Zero Knowledge podcast^[8]

Filecoin uses two interlocking proof mechanisms to make this work, and they are both recorded directly on the blockchain. Understanding them will change how you think about decentralized storage.

Proof of Replication (PoRep)

When a Filecoin storage provider agrees to store your data, it goes through a process called sealing. The provider takes the raw data, encodes it into a unique replica using a slow, cryptographically intense process, and then submits a commitment hash (CommR) to the Filecoin blockchain.^[9] This hash is tied to both the provider’s identity and the data itself — no two providers produce the same CommR for the same data. This proves, publicly and verifiably, that the provider made and stored a physically unique copy. They cannot fake it by pointing at someone else’s copy, because the encoding process uses their own identity as an input.

Proof of Spacetime (PoSt)

Sealing proves storage happened once. Proof of Spacetime proves it keeps happening. Every 24 hours, the Filecoin network divides into 48 non-overlapping 30-minute windows. In each window, storage providers must respond to cryptographic challenges that can only be answered by reading from their sealed sectors directly.^[10] If a provider fails to submit a valid WindowPoSt proof within the 30-minute window, they are slashed — a portion of their staked collateral is burned and their storage power is reduced. This financial penalty is what makes the proof system credible. Providers have a strong economic reason to keep your data intact and accessible at all times.

For you as a developer, this means your data on Filecoin comes with a built-in audit trail. You do not have to trust that Storacha is managing your storage well — you can verify it yourself by checking the on-chain deal records associated with your root CID.

Tracking Filecoin Storage Status and Retrieval

After uploading, the next practical skill is knowing how to track what happened to your data. Storacha’s console at console.storacha.network gives you a visual dashboard showing all your uploads, their CIDs, and IPFS availability status. Programmatically, you can list uploads and their associated CAR shards using the client library.

// List all uploads in your current Space (paginated)
const result = await client.capability.upload.list({ cursor: '', size: 25 })

// To list CAR shards for a specific upload:
const shards = await client.capability.store.list({ cursor: '', size: 25 })

For retrieval, any file stored via Storacha is accessible through public IPFS gateways using its CID. The standard pattern is https://<cid>.ipfs.dweb.link/<filename> or via the Storacha gateway at https://storacha.link/ipfs/<cid>. Keep in mind that IPFS hot storage availability is typically fast, while Filecoin deal creation runs in the background as data is batched into deal proposals across multiple providers. For mission-critical applications, it is good practice to verify that your data is pinned in hot storage before treating the upload as complete.

How This Connects to Chia Network’s Proof of Space and Time

If you come from the Chia Network side of crypto, Filecoin’s proof system will feel very familiar — and for good reason. Both Chia and Filecoin are built on the idea that consensus should require useful work. In Chia’s case, that means dedicating real hard drive space to store plot files. In Filecoin’s case, it means dedicating real storage to hold client data. Both networks then require ongoing cryptographic proofs that the storage is still there — Chia uses Proof of Space and Time, while Filecoin uses Proof of Spacetime.^[11]

The UCAN authorization model in Storacha also has a conceptual parallel in Chialisp. In Chialisp, a coin can only be spent if it produces a valid solution to its puzzle — and complex puzzles can encode fine-grained permissions, delegation chains, and time locks directly in the script. UCAN takes a similar approach at the API layer: permissions are encoded in signed tokens with explicit capabilities and expiration, rather than being checked against a central database. Both models share the same philosophy — trust the math, not the middleman. For Chia farmers exploring decentralized storage infrastructure, Filecoin via Storacha represents a natural extension of the same values that drive Chia’s design. You can learn more about how scalable, verifiable web3 infrastructure fits together in our article on Polyhedra Network’s sustainable, scalable Web3 solutions.

Case Study: elizaOS Integrates Storacha for AI Agent Memory

elizaOS — a popular framework for building autonomous AI agents — has integrated Storacha’s decentralized storage layer to give AI agents persistent, verifiable memory. Agents store and retrieve data across the decentralized web using the same UCAN-based pipeline described in this guide, ensuring that their stored knowledge is cryptographically verified and not dependent on any single centralized service. This real-world integration shows that the patterns covered in this advanced tutorial are production-ready today, not experimental — and that they extend far beyond simple file storage into dynamic, programmable data workflows.

Conclusion

Moving from basic file uploads to a production-grade Filecoin storage pipeline is a big step, but every piece covered in this filecoin web3.storage tutorial advanced guide is something you can start using today. The migration from the old web3.storage client to Storacha is straightforward once you understand that Spaces replace accounts and UCAN tokens replace API keys. Building CAR files manually gives you a level of control and verifiability that no centralized storage provider can match. And Filecoin’s PoRep and PoSt proof system means that for the first time, you can mathematically verify your data is stored — not just hope that a cloud vendor is telling the truth. Whether you are a Chia farmer exploring decentralized infrastructure, a dApp developer, or a backend engineer building production systems on web3, the patterns in this guide are the foundation for anything serious you build on Filecoin. Start with the CAR pipeline, wire in UCAN delegation for your users, and let Filecoin handle the rest. Your data — and the proof it is safe — will be on-chain.

filecoin web3.storage tutorial advanced FAQs

What is the main difference between a filecoin web3.storage tutorial advanced guide and a beginner guide?

A filecoin web3.storage tutorial advanced guide goes beyond simple uploads to cover building CAR file pipelines manually, managing UCAN authorization and delegation, handling large datasets through sharding, and designing production-ready multi-tenant architectures — skills that beginner guides skip entirely. The beginner guide teaches you to use storacha up; this guide teaches you to understand and control every step underneath it.

How do I use a filecoin web3.storage tutorial advanced approach to upload files larger than 4 GB?

To upload files larger than 4 GB using the filecoin web3.storage tutorial advanced pipeline, you split your data into multiple CAR shards, each under the per-shard size limit, upload each shard separately using Blob.add, and then call Upload.add once with all the shard digests and a single root CID. This keeps one root CID as the canonical identifier for the full dataset regardless of how many pieces it was split into.

What is UCAN and why does Storacha use it instead of API keys?

UCAN stands for User Controlled Authorization Networks — a capability-based authorization system where permissions are encoded as cryptographically signed tokens that can be delegated to other users or services without sharing private keys. Storacha uses UCAN because it lets developers give users or services only the exact permissions they need, with expiration times, without any central server needing to verify the permission at runtime.

How does Filecoin prove my data is still being stored over time?

Filecoin uses Proof of Spacetime (PoSt), which requires storage providers to respond to cryptographic challenges every 30 minutes that can only be correctly answered by reading from the actual sealed data on disk. If a provider fails to submit a valid proof within that window, they are penalized financially through slashing — which creates a strong economic incentive to keep your data intact continuously.

Can I verify my CID locally before uploading to Filecoin through Storacha?

Yes — and this is one of the biggest advantages of the CAR-based pipeline. When you call UnixFS.encodeFile(file) using the @web3-storage/upload-client library, the root CID is computed entirely on your machine before any data is transmitted. You can compare this locally computed CID against the CID returned by the Storacha service to confirm the service stored exactly what you sent, with no trust required.

filecoin web3.storage tutorial advanced Citations

1. Storacha Network — Documentation Home. https://docs.storacha.network/
2. Storacha Docs — How to Upload Data. https://docs.storacha.network/how-to/upload/
3. Storacha Docs — Working with Content Archive (CAR) Files. https://docs.storacha.network/concepts/car/
4. npm — @web3-storage/upload-client. https://www.npmjs.com/package/@web3-storage/upload-client
5. Storacha Docs — Go Client (Guppy): CAR Shard Size Limits. https://docs.storacha.network/go-client/
6. web3.storage Blog — Intro to UCAN. https://blog.web3.storage/posts/intro-to-ucan
7. Storacha Docs — Architecture Options: Possible Architectures. https://docs.storacha.network/concepts/architecture-options/
8. Filecoin Blog — What Sets Us Apart: Filecoin’s Proof System (Juan Benet, Zero Knowledge Podcast). https://filecoin.io/blog/posts/what-sets-us-apart-filecoin-s-proof-system/
9. Filecoin Blog — Filecoin Features: Verifiable Storage. https://filecoin.io/blog/posts/filecoin-features-verifiable-storage/
10. Filecoin Docs — Storage Proving. https://docs.filecoin.io/storage-providers/filecoin-economics/storage-proving
11. Filecoin Docs — Proofs (PoRep and PoSt). https://docs.filecoin.io/basics/the-blockchain/proofs
12. web3.storage Blog — UCAN Delegation with w3up. https://blog.web3.storage/posts/ucan-delegation-with-w3up