How to Convert Swarm Hashes to Content Identifiers (CIDs) Using the Swarm CID Converter

TLDR: The Swarm CID Converter is a lightweight Node.js utility that translates Swarm hashes (bzz:/…) into standard IPFS Content Identifiers (CIDs) and back, enabling seamless interoperability between the Swarm and IPFS ecosystems.

While Swarm stores data using its native addressing scheme (the Swarm hash), modern decentralized applications commonly rely on the IPFS Content Identifier (CID) format. The Swarm CID Converter, referenced in the ethersphere/awesome-swarm repository, bridges this gap by providing bidirectional translation between these addressing systems. This standalone tool parses Swarm's multihash format and constructs CID v1 strings using the appropriate multicodec and multibase encodings.

What Is the Swarm CID Converter?

The Swarm CID Converter is a lightweight utility that understands both Swarm and CID encoding rules, enabling developers to convert Swarm hashes or links to CID format and vice versa. According to the awesome-swarm source code, the tool is listed in README.md at line 66 with the description: "Convert Swarm hashes or links to CID and vice versa".

The converter performs three core operations:

• Swarm hash parsing – Recognizes raw multihash formats used by Swarm (bzz:/… or bzz-raw:/…) and extracts the underlying SHA-256 digest.
• CID construction – Builds a CID v1 using the extracted digest, selecting the appropriate multicodec (ethash for Swarm) and multibase (base58btc or base32).
• Reverse conversion – Re-creates original Swarm URLs from CIDs that were derived from Swarm hashes, allowing seamless round-tripping between ecosystems.

The tool is maintained in its own repository at agazso/swarm-cid-converter and does not form part of the awesome-swarm source code itself.

Installation and Setup

Because the conversion logic is pure data transformation, the tool runs on any platform with a recent Node.js runtime. You can also compile it to a tiny WebAssembly module for browser usage.

Install the CLI globally using npm:

npm install -g swarm-cid-converter

Converting Swarm Hashes to CIDs

To convert a Swarm hash to a CID, use the to-cid command followed by the Swarm URL or hash:

swarm-cid-converter to-cid bzz:/b5d5f0c9...

This command takes a Swarm hash (such as bzz:/…) and prints a CID v1 string (such as bafy...).

For programmatic use in Node.js applications, import the toCid function from the library:

const { toCid } = require('swarm-cid-converter');

const cid = toCid('bzz:/...');
console.log(cid);

Converting CIDs Back to Swarm Hashes

The converter also supports reverse conversion from CIDs back to Swarm URLs using the to-swarm command:

swarm-cid-converter to-swarm bafy2bz...

This decodes the CID, restores the original Swarm multihash, and outputs a Swarm URL (bzz:/…).

In JavaScript, use the toSwarm function:

const { toSwarm } = require('swarm-cid-converter');

const swarmUrl = toSwarm('bafy...');
console.log(swarmUrl);

Batch Processing Multiple Hashes

To process multiple hashes efficiently, you can pipe a file of Swarm hashes through the converter using standard Unix utilities:

cat hashes.txt | xargs -n1 swarm-cid-converter to-cid

This batch-converts each line in hashes.txt to its corresponding CID representation.

Technical Implementation Details

The Swarm CID Converter implements industry-standard multiformat specifications to ensure compatibility. When converting Swarm hashes to CIDs, the tool:

1. Extracts the SHA-256 digest from the Swarm multihash
2. Constructs a CID v1 with the ethash multicodec (indicating Swarm content)
3. Encodes the result using base58btc or base32 multibase

This approach ensures that the resulting CIDs are valid IPFS Content Identifiers that reference the same underlying content as the original Swarm hashes.

Summary

• The Swarm CID Converter enables bidirectional conversion between Swarm hashes and IPFS Content Identifiers (CIDs).
• The tool is listed in ethersphere/awesome-swarm at README.md line 66 and maintained separately at agazso/swarm-cid-converter.
• Use swarm-cid-converter to-cid or the toCid() function to convert Swarm hashes to CIDs.
• Use swarm-cid-converter to-swarm or the toSwarm() function for reverse conversion.
• The converter supports CID v1 with the ethash multicodec and works as both a CLI tool and a Node.js library.

Frequently Asked Questions

What is the difference between a Swarm hash and a CID?

A Swarm hash uses Swarm's native multihash format (typically prefixed with bzz:/ or bzz-raw:/) to address content in the Swarm decentralized storage network. A CID (Content Identifier) is the addressing format used by IPFS and other systems in the multiformat ecosystem. While both represent cryptographic hashes of content, they use different encoding schemes and multicodec identifiers.

Can I use the Swarm CID Converter in a browser?

Yes. Although the primary distribution is a Node.js CLI tool and library, the conversion logic is pure data transformation that can be compiled to a tiny WebAssembly module for browser usage. You can also use the JavaScript library directly in browser environments with appropriate bundling.

Where can I find the source code for the Swarm CID Converter?

The source code is maintained in the agazso/swarm-cid-converter repository on GitHub. While the ethersphere/awesome-swarm repository lists and describes the tool in its README.md file, the actual implementation resides in the separate converter repository.

Is the conversion between Swarm hashes and CIDs lossless?

Yes. The conversion is lossless and bidirectional. The tool extracts the underlying SHA-256 digest from Swarm hashes and repackages it as a CID v1 using the ethash multicodec. Because no data is discarded during this transformation, you can convert a Swarm hash to a CID and back to the original Swarm URL without data loss.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}