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

$3

- 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

$3

- 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

$3

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

$3

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

Installation

$3

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

$3

``bash
npm install -g @simplepg/dservice
`

Usage

$3

The DService provides a CLI with various options and subcommands:

`bash


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

$3

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

$3

| 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

$3


`
http://localhost:3000
`

$3

#### 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:
`bash
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:
`json
{
"cid": "bafybeieffej45qo3hqi3eggqoqwgjihscmij42hmhqy3u7se7vzgi7h2zm"
}
`

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

#### GET /info
Get API version information.

Response:
`json
{
"version": "0.1.0"
}
`

#### GET /docs
Interactive API documentation (Swagger UI).

#### GET /openapi.json
OpenAPI specification in JSON format.

Architecture

$3

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

$3

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

Development

$3

`bash


Run all tests

npm test

Run specific test file

npm test -- tests/services/ipfs.test.js
`

$3

`bash


Start with auto-restart on file changes


npm run dev
`

$3

`bash


Run ESLint


npm run lint
``

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

License

MIT License - see LICENSE for details.

Support

For questions and support:
- Open an issue on GitHub