Developing Decentralized Applications (dApps) with the Fair Data Protocol (FDP) on Swarm

The awesome-swarm repository indexes a complete ecosystem of tools—including FairOS-DFS, Mantaray-js, and the Bee client—that enables developers to build FDP-compliant dApps where users maintain sovereign control over their personal data on Swarm's decentralized storage network.

The ethersphere/awesome-swarm repository serves as the definitive, curated directory for open-source projects that comprise the Swarm stack. This comprehensive list helps developers quickly assemble the precise libraries and frameworks needed for developing decentralized applications (dApps) with the Fair Data Protocol (FDP) on Swarm, combining Ethereum’s incentivized peer-to-peer storage with interoperable data structures that prioritize personal data ownership.

FDP Architecture and the Swarm Stack

The README.md in the awesome-swarm repository organizes the ecosystem into architectural layers that map directly to FDP development workflows. Understanding these layers is essential for assembling a complete dApp stack.

Core Architectural Layers

• Network / Node: The Bee client provides the foundational HTTP API for storage and retrieval on Swarm. This is the base layer that all FDP implementations rely upon.
• Client Libraries: Bee-JS wraps the Bee API in TypeScript/JavaScript, simplifying node interaction from application code.
• Data Model (Manifests): Mantaray-js handles Swarm manifests—the mutable, versioned data structures that serve as the building blocks for FDP-Files and FDP-Folders.
• FDP Integration: FairOS-DFS implements the Fair Data Protocol specification, adding personal data ownership, access control, and provenance on top of Swarm manifests.
• Tooling & UX: Swarm-CLI and Bee Dashboard provide command-line and graphical interfaces for node management and data inspection.
• Deployment & CI/CD: FDP-play orchestrates local Bee clusters with Docker for testing FDP workflows.

Key FDP Data Concepts

When building with FDP, you work with specific abstractions defined in the Fair Data Protocol:

• FDP-Files / FDP-Folders: Represented as Swarm manifests that store metadata—including owner identity, access policies, and encryption keys—alongside the underlying chunk data.
• Decentralized Identity (DID): FDP integrates with DID methods to bind data ownership to verifiable identifiers, resolvable via Swarm hash links.
• Access-Control Lists (ACL): Implemented as encrypted manifest entries; decryption keys determine read/write permissions.
• Versioning & Mutability: Swarm’s pinning mechanism combined with Mantaray’s mutable pointer system enables FDP objects to evolve while preserving immutable historical snapshots.

Setting Up an FDP Development Environment

Local development requires a Bee node configured for FDP compatibility. The ecosystem provides specific tooling to automate this setup.

Launching a Local FDP-Compatible Cluster

The fdp-play repository (listed under Community / Ecosystem in README.md) provides Docker orchestration for a complete FDP environment:

git clone https://github.com/fairDataSociety/fdp-play.git
cd fdp-play
docker compose up -d

This launches a Bee node preconfigured to work with FairOS-DFS, enabling immediate FDP development without connecting to mainnet.

Building dApps with FairOS-DFS

FairOS-DFS is the primary distributed file system implementation of FDP on Swarm. The JavaScript SDK abstracts manifest handling, encryption, and ACL logic defined by the protocol.

Installing the FDP SDK

Add the Fairdrive SDK to your project to interact with FDP structures:

npm install @fairdatasociety/fairdrive-sdk

Creating FDP Folders and Uploading Files

The SDK provides the Fairdrive class to manage FDP-Folders (mutable manifests) and file operations. Below is a complete workflow for creating a folder and uploading data:

import { Fairdrive } from '@fairdatasociety/fairdrive-sdk'

async function uploadDemo() {
  // Connect to the local Bee node (default address)
  const fd = new Fairdrive({ apiUrl: 'http://localhost:1633' })

  // Create a new FDP folder (mutable manifest)
  const folder = await fd.createFolder('my-data')

  // Upload a JSON document inside the folder
  const data = { greeting: 'Hello, Swarm + FDP!' }
  await fd.uploadFile(
    data,
    `my-data/hello.json`,
    { folderId: folder.id }
  )

  console.log('File uploaded, manifest CID:', folder.manifestCid)
}
uploadDemo()

The createFolder method initializes a Mantaray manifest structure that FDP recognizes as a folder, while uploadFile handles chunking, encryption, and manifest updates.

Implementing Mutability and Versioning

FDP objects support updates through mutable pointers. To overwrite a file while preserving its history:

await fd.uploadFile(
  { greeting: 'Hello, Swarm + FDP! (updated)' },
  `my-data/hello.json`,
  { folderId: folder.id, update: true }
)

Setting update: true modifies the mutable pointer inside the manifest. The previous version remains accessible via its original CID, enabling versioned data retrieval.

Enforcing Access Control

FDP implements ACL through encrypted manifest entries managed by the SDK. To share a folder with specific permissions:

// Generate a shareable key for another user (read-only)
const share = await fd.shareFolder(folder.id, { read: true, write: false })

// Recipient mounts the folder using the shared secret
await fd.mountSharedFolder(share.secret)

The underlying manifest stores encrypted keys; only holders of the decryption secret can access the data according to the specified ACL.

Retrieving Data via Swarm Gateways

Once uploaded, FDP content is accessible through standard Swarm gateways that resolve manifest CIDs:

# Replace QmXYZ with the actual manifest CID from folder.manifestCid

curl https://gateway.ethswarm.org/bzz:/QmXYZ/hello.json

Gateways resolve the manifest CID to underlying content while respecting FDP conventions for file paths and metadata.

Key Ecosystem Components for FDP Development

The awesome-swarm repository catalogs these essential tools for each development phase:

• Bee: The official Swarm client providing the storage backend (ethersphere/bee).
• Bee-JS: TypeScript library for Bee API interaction (ethersphere/bee-js).
• Mantaray-js: Utilities for creating and manipulating Swarm manifests that underpin FDP data structures (ethersphere/mantaray-js).
• FairOS-DFS: Distributed file system implementing FDP data interoperability and personal data control (fairDataSociety/fairOS-dfs).
• Swarm-CLI: Command-line interface for uploading, downloading, and managing Swarm content (ethersphere/swarm-cli).
• Bee Dashboard: Web UI for visualizing node status and storage metrics (ethersphere/bee-dashboard).
• FDP-play: Docker-based local testing environment for FDP workflows (fairDataSociety/fdp-play).

Summary

• The ethersphere/awesome-swarm repository structures the FDP ecosystem into clear architectural layers—from the Bee network node to high-level FairOS-DFS abstractions.
• FDP-play enables local development by spinning up Dockerized Bee clusters preconfigured for Fair Data Protocol compatibility.
• The Fairdrive SDK exposes methods like createFolder and uploadFile that abstract Mantaray manifest manipulation, encryption, and ACL management.
• FDP implements personal data sovereignty through DID integration, encrypted ACL entries, and mutable manifest pointers that support versioning.
• Production deployment relies on Swarm gateways to resolve FDP manifest CIDs to end-user content.

Frequently Asked Questions

What is the Fair Data Protocol (FDP) on Swarm?

The Fair Data Protocol is a specification for interoperable data structures built on top of Swarm’s decentralized storage. According to the awesome-swarm repository, FDP defines standards for FDP-Files, FDP-Folders, and access control mechanisms that enable users to retain ownership of their personal data while allowing dApps to read and write to these structures in a standardized way.

How does FairOS-DFS implement FDP storage?

FairOS-DFS (Fair Data Society - Decentralized File System) is the reference implementation of FDP listed in the awesome-swarm ecosystem. It creates a file system abstraction on Swarm using Mantaray manifests to represent directories and files, adding layers for encryption, access control, and decentralized identity binding. The JavaScript SDK provides the Fairdrive class that wraps these operations for application developers.

What is the role of Mantaray manifests in FDP dApps?

Mantaray manifests are the low-level data structure that enables FDP’s mutable, versioned storage. As documented in the mantaray-js repository (indexed in awesome-swarm), these manifests create cryptographically signed pointers to content chunks. FDP uses them to build FDP-Folders that can be updated (mutability) while preserving historical versions, and to store encrypted ACL metadata alongside file data.

How do I test FDP dApps locally before mainnet deployment?

Use FDP-play, a Docker-based orchestration tool found in the awesome-swarm list. Running docker compose up -d in the fdp-play repository spins up a complete local environment including a Bee node and FairOS-DFS instance. This allows you to test upload, retrieval, access control, and versioning workflows without spending real tokens or connecting to the public Swarm network.

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