IPFS to Swarm

August 4, 2025 · View on GitHub

1. Introduction
1.1 Why choose Swarm over IPFS
1.2 Comparison of Swarm to IPFS
1.3 Further reading about Swarm – official documentation
1.4 Setting up the infrastructure
1.5 Building the Migration Tool and Usage

2. Determining Swarm Stamp Capacity Before Initial Purchase
2.1 Estimating the Size of Data to Upload
2.1.1 Using IPFS Desktop
2.1.2 Using the Migration Tool for Size Estimation
2.1.3 Using the Bash Script (Alternative)
2.1.4 Alternative: IPFS Desktop UI
2.2 Swarm Stamp Depth and Amount
2.3 Buying Swarm Stamps
2.4 Monitoring Stamp Validity and Capacity
2.5 Extending stamps in time or capacity

3. Migrating Data from IPFS to Swarm
3.1 Prerequisites
3.2 Migration Steps
3.2.1 Single File Migration
3.2.2 Bulk Migration (All IPFS MFS Content)
3.3 How It Works (Code Overview)
3.3.1 Single File Migration
3.3.2 Bulk Migration
3.4 Troubleshooting

4. Advanced Configuration and Troubleshooting
4.1 Advanced Configuration
4.2 Common Issues & Solutions
4.3 Debugging Tips

5. Keeping Up to Date with Bee Node Versions

6. Getting started as a Developer
6.1 Community & Support

1. Introduction

Swarm is a fully decentralized, censorship-resistant peer-to-peer storage network powered by Bee nodes. Unlike IPFS, it doesn't rely on any centralized third-party infrastructure. Swarm's mission is to empower a self-sovereign global society and open, permissionless markets by offering scalable decentralized storage for Web3. Its incentive system runs on smart contracts on the Gnosis Chain and is fueled by the xBZZ token, ensuring economic sustainability.

1.1 Why choose Swarm over IPFS

Swarm offers several advantages over IPFS, especially in decentralized storage and content distribution.

Atomic Unit: Swarm uses 4 kB chunks (compared to IPFS's 256 kB), enabling more efficient storage and faster retrieval of small files.
Mutable pointers: Feeds allow dynamic content updates without changing the content address.
Download speed: Unlike IPFS, even rarely accessed files download quickly; popular files are even faster.
Censorship Resistance: Content is nearly impossible to remove, protecting against internal or external censorship.
DDOS Resistance: The architecture resists DDoS attacks, ensuring content availability under stress.
Privacy/Anonymity: Strong privacy and anonymity features make it ideal for sensitive data.
Storage Payment: Integrated BZZ token system enables decentralized storage payments.
Incentives: BZZ token rewards motivate users to contribute storage resources to the network.

1.2 Comparison of Swarm to IPFS

Feature	Swarm	IPFS
Data Availability	Guaranteed via incentivized storage and retrieval	No guarantees – relies on external pinning services.
Retrievability	Native bandwidth market ensures persistent delivery	No native incentives for retrieval
Persistence Guarantees	Long-term through economic incentives	Ephemeral unless actively pinned
Privacy & Access Control	Built-in encryption and on-chain ACT permissions.	No native encryption or access management.
Censorship Resistance	High – fully decentralized with autonomous guarantees	Limited – centralized services can be pressure points
Architecture	Decentralized storage service	Decentralized protocol
Infrastructure Dependencies	Self-sustaining network	Typically needs third-party infrastructure
Target Use Case	Production-grade dApps with long-term requirements	File sharing and prototypes, not production storage.

1.3 Further reading about Swarm – official documentation

For a comprehensive understanding of Swarm, start with the following official resources:

Book of Swarm – Foundational document covering Swarm's architecture, vision, and core concepts.
Swarm Documentation Hub – Main entry point for users, developers, and node operators.
Swarm Gateway – Public interface for accessing content on the Swarm network.
Bee Node Manual – For installing and configuring Bee nodes.
Swarm Blog – News, release notes, and deep technical insights.
Migrating from IPFS to Swarm: Your Guide to a More Resilient & Empowering Decentralized Web
Swarm GitHub Repositories – Source code, SDKs, and developer tools.

1.4 Setting up the infrastructure

Swarm Desktop App The simplest way to get started is by installing the Swarm Desktop App, available for macOS, Linux, and Windows. It installs both the Bee node and a user-friendly interface in one step, allowing you to easily manage your node and access the network.
Command-line Access For command-line interface (CLI) access to your Bee node, use the npm package @ethersphere/swarm-cli.
Bee-JS The Bee-JS provides a JavaScript/TypeScript library for interacting with Bee nodes, making it easy to integrate Swarm into your applications.
Manual Bee Node Setup For advanced users, the Bee node can be installed manually. See the official Bee Node Manual for OS-specific setup instructions.

1.5 Building the Migration Tool and Usage

Requirements Before you start, ensure you have the following prerequisites:
- git installed
- Node.js v16 or newer
- pnpm
- A running Bee node
- A valid Swarm postage batch ID (see section 2 for details on buying stamps)
- A running IPFS node

Clone the Repository To get started, clone this repository to your local machine:

git clone git@github.com:Solar-Punk-Ltd/ipfs-to-swarm.git
cd ipfs-to-swarm

Installation
```
pnpm install
```
Build
```
pnpm build
```
Usage

The migration tool supports two modes:

Single File Migration: Replace <ipfs-cid> with the actual CID of the file you want to download from IPFS.
```
node dist/index.js <ipfs-cid> <swarm-batch-id>
```
Bulk Migration (All IPFS MFS Content): Downloads all files and directories from your IPFS MFS root directory, preserving the original structure.
```
node dist/index.js --all <swarm-batch-id>
```
Configuration
- src/bee.ts: Set your Bee node URL (default: http://localhost:1633)
- src/ipfs.ts: Set your IPFS node URL (default: http://127.0.0.1:5001/api/v0)

2. Determining Swarm Stamp Capacity Before Initial Purchase

Postage stamps are used to pay for storing data on Swarm. They are purchased in batches, granting a prepaid right to store data on Swarm, similar to how real-world postage stamps pay for mail delivery. To select the appropriate stamp size, you first need to estimate the total amount of data you plan to upload. This data volume will determine the required capacity of the postage stamp.

2.1 Estimating the Size of Data to Upload

2.1.1 Using IPFS Desktop

Start the IPFS Desktop application.
You can list the pinned files and their CIDs either via the application interface or using the command line:
```
  ipfs pin ls --type=recursive
```
Note: This command lists both files and directories. To identify which items are actual files, you need to inspect each pinned CID individually. You can determine whether a given CID points to a file or a directory by using the ipfs cat <CID> command:
- If the CID points to a file, ipfs cat will output the file's contents (binary files may produce unreadable output).
- If the CID points to a directory, the command will return an error like:
```
Error: this dag node is a directory
```

Based on this behavior, the following shell script filters and lists only the files:

for cid in $(ipfs pin ls --type recursive --quiet); do
  if ipfs cat -l 10 "$cid" >/dev/null 2>&1; then
    echo "$cid"
  fi
done

This script is located in examples/cli/list-ipfs-files.sh and can run with:

bash examples/cli/list-ipfs-files.sh

It's often easier to copy file CIDs directly from the IPFS Desktop app, where the content type is already clear.

IPFS CID Copy

2.1.2 Using the Migration Tool for Size Estimation

You can use the built-in TypeScript/JavaScript migration tool to download all your IPFS MFS content and calculate the total size:

pnpm build
node dist/index.js --all dummy-batch-id

This will download all files and directories from your IPFS MFS root to tmp_ipfs_download/ and display the total size.

2.1.3 Using the Bash Script (Alternative)

To download all files from IPFS (including directories and files) while preserving the directory structure and calculating the total size of the pinned files, you can use the following Bash script located in examples/cli/download-from-ipfs.sh:

  bash examples/cli/download-from-ipfs.sh

This script:

Downloads the pinned files and directories to a temporary folder
Saves them in a directory named tmp_ipfs_download
Prints the total size of all downloaded files, along with the recommended stamp depth and amount values for storing these files for one year

Example output:

Download IPFS files to: ./tmp_ipfs_download

Downloading directory: folder1 (CID: QmPj5k5sYq8aQ65KrtQzxhPD8nsMkQA7FJAFUb4sRbpfsC)
Saving file(s) to ./tmp_ipfs_download/folder1
  2.12 KiB / 2.12 KiB [====================================================================================================] 100.00% 0s
Downloading file: solarpunk.jpg (CID: QmNevLJmACaaJ9PXNH6fgApsEEyC4KS6toQyjv6U811bFT)
Saving file(s) to ./tmp_ipfs_download/solarpunk.jpg
  47.68 KiB / 47.68 KiB [==================================================================================================] 100.00% 0s
All files and directories downloaded to ./tmp_ipfs_download

Size: 1M, Batch Depth: 18, Amount: 235283788800 for 1 year

The script clears the temporary download folder before each run to ensure fresh and accurate size calculations.

2.1.4 Alternative: IPFS Desktop UI

Alternatively, you can estimate the data volume by checking the file sizes directly in the IPFS Desktop UI (see screenshot example).

IPFS Desktop Pinned Files

2.2 Swarm Stamp Depth and Amount

Each stamp batch has two key parameters — depth and amount — which are recorded on the Gnosis Chain at the time of issuance.

Batch Depth Reference The depth determines how much data a batch can store. A batch can hold 2^batch_depth chunks, with each chunk being 4 kB. Total capacity = 2^batch_depth × 4 kB.
Batch Amount Reference This is the amount of xBZZ (in PLUR, where 1 xBZZ = 10¹⁶ PLUR) assigned per chunk.
Calculating the Required Amount for a Desired TTL Reference To calculate the required amount for a given storage time:
```
(stamp_price ÷ block_time_in_seconds) × storage_duration_in_seconds
```
For example, with a stamp price of 24,000 PLUR/chunk/block and a block time of 5 seconds:

$ \text{text} (24000 ÷ 5) \times \text{desired\_seconds} $

Note: Stamp price is dynamic and depends on overall network utilization. See the utilization tables for guidance on expected storage capacity and efficiency.

2.3 Buying Swarm Stamps

You can buy Swarm stamps using either the Swarm Desktop app or the command-line interface (CLI).

Swarm Desktop App - Buy Stamp Or you can use swarm-cli to buy stamps directly from the command line:

swarm-cli stamp buy --depth <depth value> --amount <amount value>

2.4 Monitoring Stamp Validity and Capacity

You can monitor your Swarm stamps using the Swarm Desktop app or via the CLI:

swarm-cli stamp list

Example output:

Stamp ID: f0a8788256368f5ca323905163d924981edf17f1b26954c9aae2d62fae341c12
Label: test22
Usage: 6%
Capacity (immutable): 589.603 MB remaining out of 628.910 MB
TTL: 7 days (2025-07-04)

This command lists all your stamps, including their ID, label, usage, remaining capacity, and time-to-live (TTL).

Note: This command only works on the Bee node that originally issued (stamped) the batch.

You can also check the status of a specific stamp on the Gnosis Chain using the script in examples/typescript/contract.ts.

Note: Smart contracts cannot provide information about remaining capacity — only on-chain data such as ownership and amount.

2.5 Extending stamps in time or capacity

To extend the time or capacity of a stamp, use the Swarm Desktop app or the CLI:

swarm-cli stamp dilute – Increases the depth of an existing stamp (adds capacity)
swarm-cli stamp topup – Increases the amount of an existing stamp (extends TTL)

3. Migrating Data from IPFS to Swarm

This section explains how to migrate files from IPFS to Swarm using the provided CLI tool. The process downloads a file from IPFS (using its CID) and uploads it to Swarm, returning the new Swarm reference.

3.1 Prerequisites

Ensure your Bee node is running and accessible (default: http://localhost:1633).
You have a valid Swarm postage batch ID (see previous sections on buying stamps).
IPFS node is running locally (default: http://127.0.0.1:5001).
Project dependencies are installed and the code is built.

3.2 Migration Steps

First, install dependencies and build the project (see Building the Migration Tool and Usage)

3.2.1 Single File Migration

For migrating individual files by their CID:

Obtain the IPFS CID of the file you want to migrate (e.g., from ipfs pin ls). Run the migration CLI with the CID and batchId as arguments:

node dist/index.js <ipfs-cid> <batch-id>

Replace <ipfs-cid> with your actual IPFS content ID and <batch-id> with your Swarm postage batch ID.

Important: Please use the correct CID! You can copy the CID for a file from IPFS Desktop.

Example:

node dist/index.js QmYwAPJzv5CZsnAzt8auVTL3nA3XgkHcVqZ9QZQZQZQZQZ 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

Expected output:

IPFS : QmYwAPJzv5CZsnAzt8auVTL3nA3XgkHcVqZ9QZQZQZQZQZ
SWARM: 3c7b8e0f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d

3.2.2 Bulk Migration (All IPFS MFS Content)

If you have folders and files stored on IPFS and want to migrate everything at once, you can use the bulk migration feature.

For migrating all files and directories from your IPFS MFS root directory:

node dist/index.js --all <batch-id>

Example:

node dist/index.js --all 7db8086638ecb1691857b22b3d050eed8758fa27605ff27dcdc684e537cbc34f

Expected output:

node dist/index.js --all 7db8086638ecb1691857b22b3d050eed8758fa27605ff27dcdc684e537cbc34f
Starting download of all IPFS content...

File  folder1/folder2/stamps_response.json - CID: QmYtKeGP66WqYXzT9Qxkmj6r68Db2cH2WSjmChk7SHsBpm
File  folder1/folder3/folder4/download-from-ipfs.sh - CID: QmP85GANSTFma76TTC9SgvqTauKYeBd2K6S68Kn77eSWDP
File  folder1/folder3/folder4/ipfs-text.txt - CID: QmVjXDgsBwHaKSjKftQ8jY1fqQ3qpnq4QoAzY1WH71DBka
File  folder1/ipfs-text.txt - CID: QmVjXDgsBwHaKSjKftQ8jY1fqQ3qpnq4QoAzY1WH71DBka
File  solarpunk.jpg - CID: QmNevLJmACaaJ9PXNH6fgApsEEyC4KS6toQyjv6U811bFT

 All content downloaded to: /Users/ferencsarai/Work/ipfs-to-swarm/SPDV-392-ipfs-cid/tmp_ipfs_download

 Download completed successfully!
 Location: /Users/ferencsarai/Work/ipfs-to-swarm/SPDV-392-ipfs-cid/tmp_ipfs_download
 BatchId: 7db8086638ecb1691857b22b3d050eed8758fa27605ff27dcdc684e537cbc34f

Migration completed!
 Swarm REF: ec290ad77c52e9198db44ded9d28004c4c99f5970067430aa97857a58e1c586a
Closing Helia instance...

The Swarm reference (ec290ad77c52e9198db44ded9d28004c4c99f5970067430aa97857a58e1c586a) is printed at the end of the migration process. You can use this reference to access the migrated content on Swarm. To download the folder structure, use the swarm-cli command as shown below.

swarm-cli download ec290ad77c52e9198db44ded9d28004c4c99f5970067430aa97857a58e1c586a

This creates a directory structure like:

└── ec290ad77c52e9198db44ded9d28004c4c99f5970067430aa97857a58e1c586a
    ├── folder1
    │   ├── folder2
    │   │   └── stamps_response.json
    │   ├── folder3
    │   │   └── folder4
    │   │       ├── download-from-ipfs.sh
    │   │       └── ipfs-text.txt
    │   └── ipfs-text.txt
    └── solarpunk.jpg

3.3 How It Works (Code Overview)

The migration tool performs two main steps:

3.3.1 Single File Migration

Download from IPFS: The function downloadFromIpfs(cid) in src/ipfs.ts fetches the file using the provided CID and saves it locally.
```
const tempPath = await downloadFromIpfs(cid)
```
Upload to Swarm: The function uploadFileToBee(filePath, batchId) in src/bee.ts uploads the downloaded file to the Swarm network using the specified postage batch ID.
```
const ref = await uploadFileToBee(tempPath, batchId)
```

3.3.2 Bulk Migration

Download All IPFS MFS Content: The function downloadAllPinnedContent() in src/ipfs.ts downloads all files and directories from the IPFS MFS root directory, preserving the original structure.
```
const downloadDir = await downloadAllPinnedContent()
```
Upload to Swarm: The function uploadDirectoryToBee(directoryPath, batchId) in src/bee.ts uploads the entire directory structure to Swarm, creating a new reference for the uploaded content.
```
const ref = await uploadDirectoryToBee(downloadDir, batchId)
```

3.4 Troubleshooting

Ensure both IPFS and Bee nodes are running and accessible.
Make sure your batch ID is valid and has enough capacity/TTL.
If you encounter errors, check the logs for more details and verify your network configuration.

4. Advanced Configuration and Troubleshooting

This section covers advanced configuration options and common troubleshooting tips to help you get the most out of your IPFS-to-Swarm migration workflow.

4.1 Advanced Configuration

Custom Bee Node URL: By default, the Bee node URL is set to http://localhost:1633 in src/bee.ts. To use a remote Bee node, edit the URL in src/bee.ts:
```
const bee = new Bee('http://your-remote-node:1633')
```
Postage Batch ID: The batch ID is provided via the CLI when running the migration tool, allowing you to specify it dynamically for each operation.
Temporary File Handling: The migration tool downloads files from IPFS to a temporary path. Update the logic in src/ipfs.ts if you want to change the output location or handle multiple files in parallel.
IPFS Node Endpoint: The IPFS HTTP API endpoint is set to http://127.0.0.1:5001 in src/ipfs.ts. Change this if your IPFS node runs elsewhere.

4.2 Common Issues & Solutions

Error: Invalid batch ID or insufficient funds/capacity Make sure your postage batch is valid, funded, and not expired. Use swarm-cli stamp list to check status.
IPFS connection refused or timeout Ensure your IPFS daemon is running and accessible at the configured address.
Bee node connection refused or timeout Make sure your Bee node is running and reachable from your CLI environment.
File not found or empty after migration Double-check the CID and ensure the file is pinned and available on your IPFS node.
Permission errors (EACCES) on file operations Run the CLI with appropriate permissions or change the download directory in the code.
Check stamp status from CLI You can verify the status of a specific stamp using:
```
swarm-cli stamp check <stamp-id>
```
This command provides details about the stamp's validity, usage, and remaining capacity.

4.3 Debugging Tips

Add console.log statements in src/index.ts, src/ipfs.ts, or src/bee.ts to trace execution and variable values.
Use the Bee node and IPFS node logs for deeper diagnostics.
For network issues, verify connectivity with curl or similar tools.

5. Keeping Up to Date with Bee Node Versions

Easiest option: If you use Swarm Desktop, it includes an auto-update feature making it the simplest way to always stay up to date with the latest Bee releases.

It's important to keep your Bee node up to date for security, compatibility, and optimal performance. Here's how you can stay current:

Check Official Releases: Visit the Bee Releases page on GitHub to see the latest versions, release notes, and changelogs.
Read the Upgrade Guide:
- Follow the Upgrading Bee guide for best practices and step-by-step instructions.
- Before upgrading, always back up your keys and cash out your cheques to protect your xBZZ. See the cashing out guide.
- Avoid updating during an active round to prevent loss of rewards or node issues. For advanced users, check your node's round status via the /redistributionstate endpoint.
Community Updates: Join the Swarm Discord and follow the #node-operators channel for announcements, tips, and support from other node operators.

Useful Links:

6. Getting started as a Developer

For using Swarm in your applications, you can use the Bee-JS library, which provides a JavaScript/TypeScript interface for interacting with Bee nodes. An example app in the src directory demonstrates a simple CLI tool that downloads files from IPFS and uploads them to Swarm.

6.1 Community & Support

Official Swarm Website: ethswarm.org
Join the Community: Swarm Discord
Professional Consultancy: Solarpunk.Buzz

If you have questions, need help, or want to connect with other users and developers, join the Swarm Discord. For professional consulting or custom migration solutions, reach out to solarpunk.buzz.