IPFS Routes (Storage)

The IPFS Routes are part of the unified backend service (apps/ai/routes/ipfs). This module provides decentralized storage capabilities through a local Helia IPFS node, integrated within the consolidated backend architecture.

Core Technologies

The service is built using:

• Helia: A modern, lightweight implementation of IPFS for JavaScript.
• @helia/unixfs & @helia/json: Plugins for handling standard file systems and JSON data on IPFS.
• Express: The web server framework exposing the IPFS functionality as a RESTful API.
• Multer: A middleware for handling multipart/form-data, used for file uploads.

Functionality

This service provides a bridge for your application to interact with IPFS without needing a full IPFS node running in the browser or the native mobile app.

Key Capabilities

1. Data Upload: Endpoints to accept files or JSON data, add them to the IPFS network via the running Helia node, and return the immutable Content Identifier (CID).
2. Data Retrieval: Functionality to fetch data from the network using its CID.
3. Pinning (Optional): Depending on configuration, it can handle pinning to ensure data persistence.

API Usage & Security

As part of the unified backend, IPFS routes are protected by multiple security layers:

Authentication & API Keys

• Privy Authentication: All IPFS operations require valid Privy access tokens
• API Key Protection: Upload operations additionally require x-api-key header to prevent abuse
• Unified Security: Benefits from the shared authentication middleware of the consolidated backend

Example Interaction

To upload a file, the client sends a POST request with Privy auth and API key headers:

POST /api/ipfs/upload-image
Authorization: Bearer <privy-token>
x-api-key: <api-key>
Content-Type: multipart/form-data

# File data...

Response:

{
  "success": true,
  "imageCID": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "imageURL": "https://your-backend.fly.dev/api/ipfs/image/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
}

The client can then store CIDs on-chain using the Move routes (/api/move) or reference them in the database.

Running Locally

The IPFS routes are part of the unified backend. To start the backend locally:

# From project root - starts all services including IPFS routes
pnpm dev

# Or start the unified backend specifically
pnpm start:ai

The unified backend runs on port 3005 by default, with IPFS routes accessible at /api/ipfs/*. The Helia IPFS node initializes automatically during server startup, which may take a few seconds for the first request.