Multi-file uploads

The three strategies

Decision table

Pick the strategy that says "yes" to the most of your needs:

Each file separately (default)

How it works: the wizard's upload loop runs once per file. Each file gets its own Walrus blob, its own SHA-256 hash, its own register_blob Sui transaction. The progress bar restarts between files; you'll see "File 2 of 3 · cat.png" under the bar.

When to pick it:

• You don't know what fetch pattern you'll need (safe default)
• Files will be shared with different viewer sets
• You expect to delete individual files later
• Mixed file sizes (some big, some small)

The cost: N wallet popups (one per file) and N register transactions worth of gas. For small batches (2-5 files) this is fine. For 50 files, look at quilt.

Bundle as tar

How it works: the browser packs all selected files into a tar archive locally, then uploads the tar as a single blob. The original filenames are preserved inside the tar, but Walrus sees one blob with one content hash.

When to pick it:

• All files are related (e.g. a dataset that's always retrieved together)
• You want the lowest possible gas
• Total size is reasonable (the browser has to hold the whole tar in memory)
• You don't need to share individual inner files

What you give up:

• No way to fetch one file from the tar without downloading the whole thing
• Sharing applies to the whole bundle, not per-file
• Deletion is whole-bundle
• The on-chain original_name is the tar archive's name (e.g. waldrop-bundle-20260520-1342.tar)

Walrus quilt

How it works: Walrus has a native multi-file container called a "quilt." The publisher packs your files into one blob with a directory structure, and each inner file gets its own retrievable "patch id." You upload once, sign one register transaction, but the Walrus aggregator can serve each inner file by its patch id.

When to pick it:

• All files are small (under ~10 MiB each)
• You'll fetch them individually later
• You want one transaction's worth of gas
• The 10-MiB-per-file ceiling isn't a problem

The dapp auto-picks quilt when all selected files are ≤10 MiB. You can override to separate or bundle from the strategy chooser if you need to.

How "separate" handles renaming

Multi-file separate is the only strategy where the rename inputs in Step 2 actually do something meaningful. Each file gets its own input — edit any to override what's recorded on-chain. Empty inputs fall back to the OS filename.

RENAME FILES (3)
1. [photo-vacation.jpg     ]   ← OS name
2. [winter-2025-cover.png  ]   ← edited by user
3. [                       ]   ← left blank, falls back to "img003.png"

Bundle and quilt have a single "bundle name" input instead (one name for the whole archive).

Memory + size limits

For a 100-file batch of small images: quilt. For a 5-GB dataset that's always retrieved together: bundle (but watch browser memory — close other tabs). For mixed sizes: separate.

What sharing looks like per strategy

If you need different viewer sets for different files, separate is the only option that supports that natively.

Where to go next