JavaScript implementation of the SimplePage backend service
npm install @simplepg/dserviceA decentralized backend service for the SimplePage application that provides IPFS storage, blockchain indexing, and REST API endpoints for managing decentralized web pages.
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
- Node.js 20+ with ES modules support
- IPFS node (Kubo) running and accessible
- Ethereum RPC endpoint
``bash`
npm install -g @simplepg/dservice
The DService provides a CLI with various options and subcommands:
`bashStart the service with default settings
simplepage-dservice
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 pageResponse:
-
200: CAR file containing the page data
- 400: Bad request (missing CID)
- 404: Page not foundExample:
`bash
curl "http://localhost:3000/page?cid=bafybeieffej45qo3hqi3eggqoqwgjihscmij42hmhqy3u7se7vzgi7h2zm"
`#### POST /page
Upload a new page.
Query Parameters:
-
domain (required): ENS domain for the pageBody:
-
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 testRun 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
``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
MIT License - see LICENSE for details.
For questions and support:
- Open an issue on GitHub