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

> Build FDP compliant dApps on Swarm. Leverage FairOS DFS Mantarayjs and Bee client for sovereign data control on decentralized storage. Explore awesome-swarm.

- Repository: [Ethersphere/awesome-swarm](https://github.com/ethersphere/awesome-swarm)
- Tags: tutorial
- Published: 2026-03-01

---

**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`](https://github.com/ethersphere/awesome-swarm/blob/main/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`](https://github.com/ethersphere/awesome-swarm/blob/main/README.md)) provides Docker orchestration for a complete FDP environment:

```bash
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:

```bash
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:

```javascript
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:

```javascript
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:

```javascript
// 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:

```bash

# 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.