Protocol

The SimplePage protocol is a decentralized system that enables the creation, distribution, and retrieval of web pages across a network of IPFS nodes. Each participant runs both an IPFS node and a SimplePage node, creating a resilient, distributed web hosting infrastructure.

Architecture Overview

The SimplePage protocol consists of multiple independent nodes, each running:

IPFS Node: Handles content storage, retrieval, and peer-to-peer networking
SimplePage Node (DService): Provides blockchain indexing, content management, and REST API

Key Components

Blockchain Integration: Monitors SimplePage smart contracts and ENS contenthash updates
IPFS Storage: Manages CAR (Content Addressed Archive) files for page content
Content Finalization: Automatic staging and finalization based on blockchain events
List Management: Allow/block list functionality for domain filtering
REST API: HTTP endpoints for page operations

Protocol Flow

1. Page Registration

When a user registers a new SimplePage:

Smart Contract Interaction: User interacts with SimplePage contract, registering their ENS domain
Blockchain Event: Contract emits a Transfer event (minting to non-zero address)
Node Detection: All DService nodes detect the event through their indexer services
Domain Tracking: Nodes add the domain to their internal tracking lists
Resolver Monitoring: Nodes begin monitoring the ENS resolver for contenthash updates

2. Content Upload and Staging

When content is uploaded to any DService node:

CAR File Upload: User uploads a CAR file containing their page content
Domain Validation: Node checks if the domain has an active subscription
IPFS Import: Content is imported into the local IPFS node
Staged Pinning: Content is pinned with a temporary label (spg_staged_{domain}_{timestamp})
Response: Node returns the root CID to the user

3. Content Finalization

The finalization process ensures content becomes permanently available:

Contenthash Update: User updates their ENS domain's contenthash to point to the page CID
Event Detection: DService nodes detect the ContenthashChanged event
Finalization Trigger: Node checks if the content is already finalized
Content Retrieval: If content isn't staged locally (not uploaded via CAR-file to this node), node retrieves it from the IPFS network
Final Pin Creation: Content is moved from staged to final pin status
Content Provision: All CIDs in the page are provided to the IPFS DHT
Cleanup: Old staged pins are removed

4. Content Retrieval

When users request page content:

CID Resolution: User provides a CID for the page they want to retrieve
IPFS Lookup: Node queries IPFS network for the content
CAR Generation: Node creates an optimized CAR file containing only necessary blocks
Content Delivery: CAR file is served to the user

Multi-Node Network

Node Independence

Each DService node operates independently:

Autonomous Indexing: Each node maintains its own blockchain indexer
Independent Storage: Each node manages its own IPFS storage
Local Lists: Each node maintains its own allow/block lists
Custom Configuration: Each node can have different filtering policies

Content Distribution

The protocol leverages IPFS's peer-to-peer nature:

Automatic Discovery: IPFS nodes automatically discover content across the network
Selective Indexing: Nodes can use block-lists to exclude domains they don't want to index
Restrictive Filtering: Nodes can use allow-lists to tightly restrict indexing to specific domains
Resilient Retrieval: If one node goes offline, content remains available from others
Bandwidth Optimization: Nodes only store content they've explicitly pinned

Synchronization Mechanisms

Nodes stay synchronized through:

Blockchain Consensus: All nodes read from the same blockchain state
IPFS DHT: Content availability is announced through IPFS's distributed hash table
Event Processing: Each node processes the same blockchain events independently
List Management: Nodes can share allow/block lists through IPFS pins

Node Discovery

The SimplePage network provides resilience through endpoint discovery:

ENS Text Record: The new.simplepage.eth ENS domain maintains a dservice text record containing a list of SimplePage node endpoints
Client Resilience: Applications (like the SimplePage frontend) can query this record to discover available API endpoints
Automatic Failover: Clients can automatically switch between available nodes if one becomes unavailable

Content Lifecycle

Staging Phase

Temporary Storage: Content is pinned with temporary labels
Time-Limited: Staged content expires after configurable time (default: 1 hour)
Automatic Cleanup: Old staged pins are automatically pruned
Domain Association: Staged content is associated with specific domains

Finalization Phase

Permanent Storage: Content moves to permanent pin status
Blockchain Verification: Finalization requires corresponding blockchain event
DHT Provision: Content is announced to IPFS network
Cleanup: Old staged versions are removed

Blocking and Removal

Block List: Domains can be added to block lists
Automatic Nuking: Blocked domains have their content automatically removed
CID Cleanup: All associated IPFS blocks are removed
Finalization Removal: Domain is removed from finalization tracking

Data Structures

IPFS Pins

The protocol uses IPFS pins for data management:

spg_staged_{domain}_{timestamp}: Temporary staged content
spg_list_{name}: Various tracking lists (domains, resolvers, etc.)
spg_finalizations: DAG containing finalization state
spg_latest_block_number: Current blockchain sync position

Finalization Map

A DAG-CBOR structure tracking finalized content:

{
  "example.eth": [
    { "blockNumber": 12345, "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi" },
    { "blockNumber": 12350, "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi" }
  ]
}

List Management

Various lists are maintained as IPFS pins:

domains: All registered SimplePage domains
resolvers: ENS resolver addresses being monitored
contenthash_{domain}: Contenthash update history per domain
allow: Domains allowed for synchronization
block: Domains blocked from synchronization

Network Resilience

Fault Tolerance

The protocol provides resilience through:

No Single Point of Failure: Multiple independent nodes
Content Replication: IPFS automatically replicates popular content
Event Replay: Nodes can catch up from any blockchain position
Graceful Degradation: Individual node failures don't affect the network

Content Availability

Content remains available because:

IPFS DHT: Content location is distributed across the network
Multiple Providers: Content is cached by multiple nodes that have indexed it
Automatic Discovery: IPFS nodes automatically find content providers
Persistent Pinning: Finalized content is permanently pinned
Network Retrieval: Nodes can retrieve content from the IPFS network even if not locally staged

Security Considerations

Access Control

Domain Validation: Only subscribed domains can upload content
List Filtering: Nodes can implement allow/block lists
Content Verification: Blockchain events provide cryptographic verification
IPFS Security: Leverages IPFS's built-in content addressing

Content Integrity

Cryptographic Hashes: All content is identified by cryptographic CIDs
Blockchain Verification: Content finalization requires blockchain proof
Immutable Storage: IPFS provides immutable content storage
Tamper Detection: Any modification changes the content's CID

Performance Optimizations

CAR File Optimization

Selective Inclusion: Only necessary blocks are included in CAR files
Directory Filtering: _files directories are excluded from lightweight CARs
Block Deduplication: IPFS automatically deduplicates identical blocks
Compression: CAR files use efficient binary encoding

Caching Strategies

LRU Caching: Frequently accessed lists are cached in memory
Block Caching: IPFS nodes cache frequently accessed blocks
DHT Caching: Content location information is cached
Staged Content: Temporary content is cached for quick access

< Prev (Components)・ Next (API) >