Protocol

The Simple Page protocol combines immutable IPFS roots with mutable ENS names. Content changes are prepared off-chain, but publication is finalized by an on-chain ENS contenthash update.

Node Architecture

Each Simple Page Node runs independently with:

  • An IPFS/Kubo node for blocks, pins, MFS state, and peer discovery.
  • A Simple Page API for page, file, history, ref, and capability endpoints.
  • A blockchain indexer for SimplePage contract events and ENS resolver/contenthash changes.
  • Local allow/block list policy.

Nodes are discovered through the dservice text record on new.simplepage.eth.

Content Lifecycle

The content lifecycle: subscription, staging, publishing, finalization, retrieval, and history.

1. Subscription

A user subscribes through SimplePageManager.subscribe(domain, duration). The manager charges the USD-priced ETH fee, refunds excess ETH, and mints or updates the SimplePage NFT for the ENS domain.

Nodes index the SimplePage contract and learn which domains have active subscriptions.

2. Staging

The browser or CLI builds a CAR and uploads it to a Simple Page Node.

For normal browser publishing:

POST /page?domain=example.eth

For draft publishing:

POST /refs/example.eth

The node validates the active subscription, imports the CAR into IPFS, and stores temporary staged data. The default staged lifetime is one hour.

3. Publication

Publication means setting the ENS contenthash to the new IPFS CID.

The browser publish page, history restore page, and drafts review page all prepare an ENS resolver setContenthash transaction. The owner or manager wallet signs that transaction.

4. Finalization

Nodes watch ENS resolver and ContenthashChanged events. When a tracked domain points to a staged CID, nodes finalize the content by pinning it and updating their internal indexes.

If a node did not receive the original upload, it can retrieve blocks from IPFS or other nodes when finalizing.

5. Retrieval

Visitors usually read content through ENS HTTP gateways such as eth.link. Simple Page clients and tooling can also fetch lightweight CARs directly from a Node with:

GET /page?cid=<cid>

Raw blocks can be fetched with:

GET /file?cid=<cid>

The /file endpoint serves local block data and is not intended to be a general-purpose public IPFS gateway.

6. History

Every Simple Page publish stores the previous root under _prev/0/. Nodes also index publish history and expose it through:

GET /history?domain=example.eth

The frontend uses this to show a visual timeline and to restore a previous CID by publishing it again as the ENS contenthash.

Off-Chain Drafts And Agents

Drafts allow a CLI or external system to prepare content without controlling the ENS owner key.

The flow is:

  1. The CLI generates an Ed25519 key and did:key identity.
  2. simplepage auth <domain> prints an Agents page URL.
  3. The ENS owner signs a SIWE capability for that agent key.
  4. The CLI signs refs that point to content CIDs.
  5. Nodes verify the ref signature and SIWE capability before storing the draft.
  6. The ENS owner reviews and publishes a draft in /spg-drafts.

Capabilities expire. Ref names are scoped to each ENS domain and advance by sequence number.

Network Properties

Independent Nodes

Each Node maintains its own IPFS storage, indexer state, allow/block list, and API configuration. A Node can choose which domains to index and which content to retain.

Multiple Endpoints

The dservice text record can list multiple endpoints. Clients randomize endpoint order and try available nodes.

Censorship Resistance

ENS, Ethereum, and IPFS are separate layers. If one gateway or node is blocked, users can use another gateway, another RPC endpoint, another Simple Page Node, or their own infrastructure.

Integrity

All content is addressed by CID. Any content change produces a different root. Publication is verifiable because the active CID is set by an ENS transaction.

Pin And State Data

Nodes store operational data in IPFS/MFS under a chain-specific namespace. This includes staged content, finalized content, subscription status, history indexes, refs, capabilities, and list state.

Important concepts:

  • Staged content is temporary until an ENS event finalizes it.
  • Finalized content is pinned by the node.
  • History entries link domains, CIDs, parents, transactions, and block data.
  • Refs and capabilities sync across peers when peer discovery is enabled.