@simplepg/dservice

SimplePage DService

A decentralized backend service for the SimplePage application that provides IPFS storage, blockchain indexing, and REST API endpoints for managing decentralized web pages.

Overview

SimplePage DService is a Node.js service that bridges the gap between the SimplePage smart contract and IPFS storage. It provides:

• IPFS Integration: Upload, retrieve, and manage CAR (Content Addressable aRchive) files
• Blockchain Indexing: Monitor SimplePage contract events and track ENS contenthash updates
• REST API: HTTP endpoints for page operations with automatic Swagger documentation
• List Management: Allow/block list functionality for ENS domains
• Content Finalization: Automatic staging and finalization of page content

Features

🗄️ IPFS Storage

• Upload CAR files with automatic pinning and staging
• Retrieve page content with optimized CAR file generation
• Content finalization based on blockchain events
• Automatic cleanup of old staged content

⛓️ Blockchain Indexing

• Monitor SimplePage contract for new page registrations
• Track ENS contenthash updates for registered domains
• Maintain synchronized state between blockchain and IPFS
• Support for multiple blockchain networks

🌐 REST API

• Upload new pages with domain association
• Retrieve page content by CID
• Automatic OpenAPI/Swagger documentation
• File upload support with multipart/form-data

📋 List Management

• Allow list management for trusted domains
• Block list management for restricted domains
• CLI commands for list operations
• Persistent storage using IPFS pins

Installation

Prerequisites

• Node.js 20+ with ES modules support
• IPFS node (Kubo) running and accessible
• Ethereum RPC endpoint

Install

npm install -g @simplepg/dservice

Usage

Command Line Interface

The DService provides a CLI with various options and subcommands:

# Start the service with default settings
simplepage-dservice

# Start with custom configuration
simplepage-dservice \
  --ipfs-api http://localhost:5001 \
  --api-port 3000 \
  --api-host localhost \
  --rpc https://mainnet.infura.io/v3/YOUR_KEY \
  --start-block 18000000 \
  --chain-id 1

# Manage allow list
simplepage-dservice allow-list show
simplepage-dservice allow-list add example.eth
simplepage-dservice allow-list rm example.eth

# Manage block list
simplepage-dservice block-list show
simplepage-dservice block-list add spam.eth
simplepage-dservice block-list rm spam.eth

Configuration

Environment Variables

Variable	Description	Default
IPFS_API_URL	IPFS API endpoint	http://localhost:5001
API_PORT	HTTP API port	3000
API_HOST	HTTP API host	localhost
RPC_URL	Ethereum RPC URL	http://localhost:8545
START_BLOCK	Starting block for indexing	1
CHAIN_ID	Ethereum chain ID	1

Command Line Options

Option	Short	Description	Default
--ipfs-api	-i	IPFS API URL	http://localhost:5001
--api-port	-p	API port	3000
--api-host	-a	API host	localhost
--rpc	-r	Ethereum RPC URL	http://localhost:8545
--start-block	-b	Starting block number	1
--chain-id	-c	Chain ID	1

API Reference

Base URL

http://localhost:3000

Endpoints

GET /page

Retrieve a page by its CID. Returns a CAR-file containing only index.html and index.md files for each directory contained by the page.

Query Parameters:

• cid (required): Content identifier of the page

Response:

• 200: CAR file containing the page data
• 400: Bad request (missing CID)
• 404: Page not found

Example:

curl "http://localhost:3000/page?cid=bafybeieffej45qo3hqi3eggqoqwgjihscmij42hmhqy3u7se7vzgi7h2zm"

POST /page

Upload a new page.

Query Parameters:

• domain (required): ENS domain for the page

Body:

• file (required): CAR file (application/vnd.ipld.car)

Response:

{
  "cid": "bafybeieffej45qo3hqi3eggqoqwgjihscmij42hmhqy3u7se7vzgi7h2zm"
}

Example:

curl -X POST \
  -F "file=@page.car" \
  "http://localhost:3000/page?domain=example.eth"

GET /info

Get API version information.

Response:

{
  "version": "0.1.0"
}

GET /docs

Interactive API documentation (Swagger UI).

GET /openapi.json

OpenAPI specification in JSON format.

Architecture

Services

IpfsService

Handles all IPFS-related operations:

• CAR file upload and retrieval
• Content pinning and staging
• List management using IPFS pins
• Content finalization

IndexerService

Manages blockchain indexing:

• Monitors SimplePage contract events
• Tracks ENS contenthash updates
• Synchronizes blockchain state with IPFS
• Retrieves page data from other nodes over IPFS
• Handles page finalization triggers

API Service

Provides HTTP endpoints:

• RESTful API for page operations
• Automatic OpenAPI documentation
• File upload handling
• Error handling and validation

Data Flow

• Page Upload: Client uploads CAR file → IPFS storage → Staged pin created
• Blockchain Event: Indexer detects new page registration → Domain added to list
• Contenthash Update: Indexer detects ENS contenthash change → CID tracked
• Finalization: Indexer triggers content finalization → Staged pin → Final pin
• Retrieval: Client requests page → Optimized CAR file generated and served

Development

Running Tests

# Run all tests
npm test

# Run specific test file
npm test -- tests/services/ipfs.test.js

Development Mode

# Start with auto-restart on file changes
npm run dev

Linting

# Run ESLint
npm run lint

Contributing

• Fork the repository
• Create a feature branch
• Make your changes
• Add tests for new functionality
• Ensure all tests pass
• Submit a pull request

License

MIT License - see LICENSE for details.

Support

For questions and support:

• Open an issue on GitHub