Package Exports

filecoin-pin
filecoin-pin/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (filecoin-pin) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Filecoin Pin

An IPFS Pinning Service API implementation that pins to Filecoin's PDP service, providing ongoing proof of possession of your pinned content using Filecoin's proving system.

Overview

Filecoin Pin is a TypeScript daemon that implements the IPFS Pinning Service API to enable users to pin IPFS content to Filecoin using familiar IPFS tooling like Kubo's ipfs pin remote commands.

How It Works

Serve Pin Service: The daemon runs an HTTP server that implements the IPFS Pinning Service API
Receive Pin Requests: When you run ipfs pin remote add, Kubo sends a pin request to the service
Fetch Blocks from IPFS: The service connects to the IPFS network and fetches blocks for the requested CID (usually from the requesting node itself)
Store in CAR: As blocks arrive, they're written directly to a CAR (Content Addressable aRchive) file on disk
Upload to PDP Provider: Once all blocks are collected, the CAR file is uploaded to a Proof of Data Possession (PDP) service provider
Commit to Filecoin: The PDP provider commits the data to the Filecoin blockchain
Start Proving: The storage provider begins generating ongoing proofs that they still possess your data

This bridges the gap between IPFS's content-addressed storage and Filecoin's incentivized persistence layer, giving you the best of both worlds - easy pinning with long-term storage guarantees.

⚠️ Alpha Software: This is currently alpha software, only deploying on Filecoin's Calibration Test network with storage providers participating in network testing, not dedicating long-term persistence.

You need a Filecoin calibration network wallet funded with USDFC. See the USDFC documentation which has a "Testnet Resources" section for getting USDFC on calibnet.

Quick Start

Prerequisites

Node.js 24+ and npm

Installation

git clone https://github.com/FilOzone/filecoin-pin
cd filecoin-pin
npm install

Development

# Start development server with hot reload
npm run dev

# Build the project
npm run build

# Run tests
npm test

# Lint code
npm run lint
npm run lint:fix

Configuration

Configuration is managed through environment variables. The service uses platform-specific default directories for data storage following OS conventions.

Environment Variables

# REQUIRED - Without this, the service will not start
export PRIVATE_KEY="your-filecoin-private-key"      # Ethereum private key (must be funded with USDFC on calibration network)

# Optional configuration with defaults
export PORT=3456                                    # API server port (default: 3456)
export HOST="localhost"                             # API server host (default: localhost)
export RPC_URL="https://api.calibration.node.glif.io/rpc/v1"  # Filecoin RPC endpoint
export DATABASE_PATH="./pins.db"                    # SQLite database location (default: see below)
export CAR_STORAGE_PATH="./cars"                    # Temporary CAR file directory (default: see below)
export LOG_LEVEL="info"                             # Log level (default: info)

Default Data Directories

When DATABASE_PATH and CAR_STORAGE_PATH are not specified, the service uses platform-specific defaults:

Linux: ~/.local/share/filecoin-pin/ (follows XDG Base Directory spec)
macOS: ~/Library/Application Support/filecoin-pin/
Windows: %APPDATA%/filecoin-pin/
Other: ~/.filecoin-pin/

Running the Daemon

⚠️ PRIVATE_KEY is required - The service will not start without it.

# Start the daemon
PRIVATE_KEY=0x... npm start

# Or with custom configuration
PRIVATE_KEY=0x... PORT=8080 RPC_URL=wss://... npm start

CLI Usage

# Show help
npx filecoin-pin help

# Show version
npx filecoin-pin version

# Start server
npx filecoin-pin daemon

Using with IPFS/Kubo

Once the daemon is running, configure it as a remote pinning service in Kubo:

# Add the pinning service (replace <bearer-token> with any non-empty string for now)
ipfs pin remote service add filecoin-pin http://localhost:3456 <bearer-token>

# Pin content to Filecoin
ipfs pin remote add --service=filecoin-pin QmYourContentCID

# List remote pins
ipfs pin remote ls --service=filecoin-pin

# Check pin status
ipfs pin remote ls --service=filecoin-pin --status=pinning,queued,pinned

Development Scripts

npm run build - Compile TypeScript to JavaScript
npm run dev - Start development server with hot reload
npm start - Run compiled output
npm test - Run linting, type checking, unit tests, and integration tests
npm run test:unit - Run unit tests only
npm run test:integration - Run integration tests only
npm run test:watch - Run tests in watch mode
npm run lint - Check code style with ts-standard
npm run lint:fix - Auto-fix code style issues
npm run typecheck - Type check without emitting files

License

Dual-licensed under MIT + Apache 2.0

filecoin-pin