EarthFast Litepaper

By: EarthFast Team

Introduction

Many decentralized projects still rely on a centralized frontend. From a project’s perspective, the entity that controls what bytes get served is more important than who serves the bytes for the frontend. Existing solutions require the project team to take some action when updating their frontend software, whether that’s deploying to their own servers or deploying to a hosting provider.

We introduce a system that shifts the responsibility for updating the frontend from the project team to a group of community voters. Once configured, decisions regarding what content gets served are completely removed from the project team.

In other words, this mechanism offers a way for teams to fully and securely decentralize frontend management and hosting.

How it Works

Anyone can register a new project on-chain to be hosted by node operators in the Earthfast network ecosystem, and define a public key or smart contract (the project controller) capable of controlling the details around this registration. The controller would likely be an on-chain governance structure native to the project, to achieve the goal stated above.

The project controller defines 1) how many nodes should host the project, as a function of desired decentralization and capacity, and 2) what data bundle should be served to fulfill requests made against the project construct. It is also capable of updating these parameters as and when it chooses.

The on-chain project construct must maintain a balance of funds, used to purchase the desired node capacity. Funds can be deposited on behalf of a project by anyone without permission.

Independent of the project construct, one or more domains can be paired with the project by 1) pointing their nameservers with a traditional domain registrar to a domain node in the EarthFast network. This bridges traditional DNS-registered names into the EarthFast network, allowing end users to access a project from a normal web browser without the need for a browser extension or other workaround.

Request Serving Flow

The diagram below shows the high level architecture of the system from the perspective of an end user that’s loading a website hosted by the EarthFast network. A short summary of each component is provided thereafter, with full details in later sections.

Nameserver

A project’s domain name must resolve to EarthFast network domain nodes via traditional DNS, but the network is not prescriptive about the nameserver used. It could, for example, just be the nameserver that’s provided by the domain registrar.

Domain Node

A server that is responsible for hosting a project’s domain via SSL, but hosting none of its website content. It handles HTTPS on the project’s domain, returning the EarthFast network Secure Enclave (which contains an embedded list of content nodes).

Secure Enclave

A web browser service worker that handles all requests for loading a project’s website from the project’s set of content nodes. The Secure Enclave integrity checks all of the data retrieved from content nodes, ensuring the veracity of the site being served to the end user.

Content Node

A server that is responsible for delivering static website resources of the projects hosted by the EarthFast network. It handles HTTPS on its operator-provided domain name.

Request Sequence Diagram

End user requests are serviced as shown in the diagram below. As indicated, there can be considered “trusted” and “trustless” sections of the flow, where trust is bestowed from the perspective of the project. From the perspective of the end user, the entire network can and should be considered as trustworthy as any other traditional static website hosting system.

The “trusted” section, which includes the DNS nameserver and the domain node, contains the infrastructure components that have the right and ability to act as the project domain. Critically, they are able to provision SSL certificates for the domain, and therefore must be trusted to act in the best interest of the project at all times. This trusted section of the request flow can be considered a bootstrapping phase, as it only executes the first time an end user visits the project domain (and occasionally thereafter for software upgrades).

Once the trusted section has successfully bootstrapped and installed the Secure Enclave the first time a user visits a site, the remainder (and bulk) of the request flow needs no implicit or explicit trust for subsequent site visits.

Project Costs

A project is responsible for purchasing resources from the network on an ongoing basis. This is accomplished by leasing content nodes from operators in the EarthFast network, thereby reserving all of a given node’s compute resources for the duration of a single billing epoch. This model should be familiar to infrastructure operators because it’s analogous to how they currently manage a fleet (e.g. “We'll run 8 VMs to safely handle our traffic this month, which will cost $X per instance/month”).

Payments are distributed automatically to content nodes at the end of each billing epoch based on their performance (more on this later). The payment comes from an on-chain escrow that each project is required to maintain. The escrow is managed by the protocol, which enforces that the pool contains sufficient funds to satisfy a given project’s total lease cost for the upcoming billing epoch. Projects can fund this escrow to service the project for months or years.

Content node software includes DDoS prevention tools. Between these guardrails and the way project costs are calculated, projects are not at risk of unbounded bandwidth costs even when subjected to high traffic attacks.

Content Node Marketplace

Content nodes are responsible for servicing the vast majority of the network’s requests. As such, projects must decide how many content nodes they want/need to serve their users. This decision will be based on compute/bandwidth requirements, the project’s desire for serving redundancy, and the project’s desire for decentralization. Each content node will be required to meet a minimum technical specification (e.g. cpu, memory, i/o), so determining an appropriately sized footprint will be straightforward.

Once a project has decided how many content nodes they want, they must reserve them via a two-sided market where they are the buyer and content node operators are the sellers. Operators can list their content nodes as available for lease, setting their own instance price. Projects can choose to reserve nodes based on cost, historic performance, geographic placement, node operator identity, or any combination of these properties.

Importantly, content nodes are single-tenant, so once they’ve been leased for a project they are no longer available to any other project for the duration of the lease.

Automated Matching

While some projects will choose to retain tight control over which content nodes they lease on an ongoing basis, many will prefer an approach that can be automated and need only be supervised from time to time. The EarthFast network plans to provide automated matching software that can be configured and used for this purpose.

Projects will be able to choose from a variety of matching strategies to be run before the start of a new epoch, allowing them to tailor their infrastructure based on their needs. Inputs such as lease cost, past performance, verified operator status, geolocation, and more will be fed into the algorithm and used to select how many and which specific content nodes to lease.

Billing Reconciliation

At the end of each epoch, the total cost for each project gets calculated and the funds distributed to the operators as follows:

$Cost_{Project} = \sum_{Content Nodes}Cost_{Instance}$

$Cost_{Instance}=NodePrice * UptimeRatio$

Estimated Data Transferred

Content nodes are expected to service the bandwidth needs of their leasing projects, which will vary from project to project and epoch to epoch. However, given the nature of the sites likely to be served by the network (i.e. small, static), and the heavy caching that’s built into the secure enclave, bandwidth costs should be a very small fraction of the expense of running a node. Content node operators should set their lease price to account for this “all-in” pricing model.

To assist content node operators in setting their pricing, as well as to identify problematic/abusive projects, the network will track bandwidth usage on a per-project basis and make this information available in the marketplace. This is accomplished by polling all of the content nodes at the end of each epoch. Due to the fact that end users will be fetching website resources from random content nodes, it’s expected that each content node would serve roughly the same amount of data as all of its peers in the same geographic region. The total estimated data transferred per content node will be determined as follows:

Ask each content node how many GB of outbound data it transferred.
Discard outlier values.
Calculate the mean of the remaining values.

Note: content node operators that regularly report bandwidth usage that’s considered an outlier may be penalized via slashing (more on this later).

Domain Nodes

The final type of node is the domain node, which is responsible for serving a project’s root domain.

It must:

Have (or be able to provision) SSL certificates for the project domain.
Read the current set of a project’s leased content nodes from the blockchain.
Serve an HTML landing page with the Secure Enclave.

It may:

Resolve DNS for the project domain.
Serve dynamic content to robots (e.g. Open Graph).

In this first version of the protocol, projects themselves (or their communities) are expected to operate domain nodes. This is largely due to the sensitivity around requirement #1 - tight control over who has access to an SSL certificate for the project domain should be retained.

This presents a potential opportunity for someone in the EarthFast network community to become a domain-node-operator-for-hire, where it would be up to them and a project to work out an appropriate incentive/disincentive structure that meets their needs.

In future protocol versions, it might be possible for content nodes to optionally serve as managed domain nodes, if opted-into by the project.

Secure Enclave

In order to provide a trustworthy experience for end users while delegating the serving infrastructure to a decentralized network of node operators, the EarthFast network includes client-side software that validates the bytes received from content nodes to ensure they weren’t tampered with. This client-side software is dubbed the Secure Enclave and is implemented as a service worker that runs in the web browser.

The Secure Enclave gets installed the first time an end user loads a project website; it is served by a domain node in the trustful section of the flow and contains an initial set of content nodes to use for bootstrapping. Once installed, it handles every outbound network request for the website, returning only verified content to the browser’s rendering/interpretation engines.

Domain nodes are queried by the Secure Enclave to determine/validate the set of content nodes that are active for the current project. Once this list is available, a project-generated manifest containing site resource checksums is fetched from multiple content nodes – they must all match. Thereafter, every request for an individual resource (HTML, CSS, Javascript, etc.) is fetched from a single content node and checked against the known-good checksum from the manifest. Any mismatches or missing checksums are immediately rejected and discarded.

A high-level overview of the flow is shown in the following diagram:

On-Chain Layer

The entire data model for the EarthFast network is stored on the blockchain, and it includes all of the information necessary to serve projects on their associated domains. Importantly, ownership of the current website content for a project is delegated to a single address, such that only that address is capable of modifying the site. The delegated address may be any governance structure that’s appropriate for the project and its community.

Below is a summary of the EarthFast network’s smart contracts data that’s kept on chain. Note that the actual data layout and smart contract structure may be different in production.

EarthFastRegistry

Entry point for EarthFast contracts and keeps track of projects, nodes, operators and reservations
Manages billing epoch and stores values for epoch start, end, duration and function to advance to the next epoch

string private _version;          // Interpreted by the node software, used for automatic upgrading of the nodes
uint256 private _nonce;           // Auto-incremented value used for generating unique ids
uint256 private _lastEpochStart;  // Timestamp of the last epoch start in seconds since 1/1/1970 midnight UTC
uint256 private _lastEpochLength; // Duration of the last epoch in seconds
uint256 private _nextEpochLength; // Duration of the next epoch in seconds
uint256 private _cuedEpochLength; // Pending change of the epoch duration, becomes effective after the next epoch
uint256 private _gracePeriod;     // Period in seconds at the end of the epoch when node prices can't change
ERC20Permit private _usdc;
EarthFastToken private _token;
EarthFastBilling private _billing;
EarthFastNodes private _nodes;
EarthFastOperators private _operators;
EarthFastProjects private _projects;
EarthFastReservations private _reservations;

EarthFastProjects

Entry point to manage Projects on the EarthFast Network
Allows projects to be created, modified and deleted

EarthFastProject {
	bytes32 id;       // Hash of nonce
	address owner;    // Who can change project settings
	string name;      // A human-friendly name for the project
	string email;     // Used for administrative notifications
	uint256 escrow;   // USDC amount deposited by the project
	uint256 reserve;  // Part of escrow that is locked to pay for the last and next epoch
	string content;   // What to serve by content nodes
	bytes32 checksum; // Checksum of the content field
	string metadata;  // Serialized JSON metadata string for future additions or annotations
}
mapping(bytes32 => EarthFastProject) private _projects;

EarthFastNodes

Entry point to manage instances of content nodes on the EarthFast Network
Allows nodes to be created, modified, enabled, disabled and deleted

struct EarthFastNode {
	bytes32 id;         // Hash of nonce
	bytes32 operatorId; // Who can change node settings, pricing, disable or delete this node
	string host;        // Interpreted by the node software
	string region;      // Interpreted by the node software
	bool topology;      // Whether this is a topology or content node
	bool disabled;      // Disabled node won't take new reservations, and won't renew when current epoch ends
	// Content nodes only. Slots that hold corresponding values for the last and the next epoch.
	uint256[2] prices;     // Full-epoch price in USDC if node is not reserved, or prorated price if node is reserved
	bytes32[2] projectIds; // Project that reserved this node for the respective epoch, or zero if not reserved
}
mapping(bytes32 => EarthFastNode) private _nodes;

EarthFastReservations

Entry point to manage Reservations by projects for a set of content nodes
Allows reservations for a set of content nodes to be created, modified and deleted and listed
Does not store any internal state, modifies the projectIds property of the respective EarthFastNodes

EarthFastBilling

Works in concert with EarthFastRegistry (which manages the epoch) to manage billing and renewals within an epoch
Contains function to pay out tokens from project escrow to node operators and renew reservations for nodes into next epoch

uint256 private _billingNodeIndex; // Ensures consistency during incremental reconciliation
uint256 private _renewalNodeIndex; // Ensures consistency during incremental reconciliation

Tokenomics Framework

The EarthFast token sits at the center of the network, aligning the incentives of the principal stakeholders (project teams and node operators of the three respective node types). Through this structure, network-wide infrastructure and continuous improvement of the network can coexist with the marketplace dynamic between content nodes and projects.

Projects

Projects registered on-chain must maintain a minimum balance (escrow) of the USDC token with their registration that is proportional to the number of content nodes they lease. This allows for spikes in usage to be absorbed and a grace period for projects to top-up the balance necessary to get back into a healthy state afterwards without interruption of service.

Node Staking

Content nodes must maintain a minimum stake of EarthFast tokens at all times. The first version of the protocol does not have Domain Nodes staking requirements. The role of the minimum stake is to ensure serving accurate content by the nodes. This stake is subject to slashing if the network requirements are violated by the node.

Content Nodes

The primary compensation for content nodes is the direct fee paid to them for hosting by the project they pair with. Content nodes may also be additionally incentivised through the new issuance of the token, as directed by vote of the token holders. The number of content nodes on the network is expected to expand/contract in direct relation to demand from projects.

Domain Nodes

In this first version of the protocol, domain nodes don’t have staking requirements, and don’t need to be compensated because projects themselves (or their communities) are expected to operate them, as described earlier in this document.

Resource Fees

EarthFast network resources include individual node instances (including in a specific geographic region), and in the future may include compute and other work.

EarthFast node operators set the price for their node instances in the USDC token. Each project deposits tokens into an escrow to reserve and pay for these resources.

Last updated 7 months ago