Skip to main content
Version: 0.1.0

Spacemesh Protocol Documentation

Introduction#

This document and the documents it links to collectively present an overview of the Spacemesh protocol in its entirety, and its constituent components.

See What is Spacemesh?, below, for more information on the project.

See Learn More, below, for links to many other resources on Spacemesh, both technical and non-technical.

Intended audience#

These documents are intended for a developer audience, with an eye towards making the protocol and client architecture accessible to those who wish to read, use, and contribute to the development of the Spacemesh protocol via its various client implementations. Where necessary, technical details of the protocol have been simplified or omitted entirely in favor of readability and legibility to a developer audience (where this has happened, there is typically a note with a link for further reading).

Those looking for a more formal, research-oriented presentation of the Spacemesh protocol, including formal security proofs, should refer to the Protocol whitepaper.

Repository Contents#

The remainder of this document contains a high-level overview of the Spacemesh protocol, and how all of the pieces fit together. You may also wish to dive deeper into the various components of the protocol:

Hare Protocol#

What is Spacemesh?#

Spacemesh is a fair, race-free, permissionless blockchain protocol currently implemented in the open source go-spacemesh codebase. The protocol implements a decentralized ledger (a DAG structure, known as the mesh) with a native cryptocurrency (Smesh, also known as SMH) that anyone is free to mine and transact. What’s more, the protocol is designed in such a way that anyone with free hard drive space and a stable Internet connection can mine from home (by running the Spacemesh App) and earn guaranteed rewards in the form of SMH coin, a process known as Smeshing in Spacemesh terminology.

Spacemesh research and development is led by a team of full-time contributors employed by the Spacemesh development company. However, Spacemesh is also an active open source project and a community of dedicated researchers, developers, and other contributors around the world. Learn more about the Spacemesh protocol at the project homepage, and about the project and its goals in the manifesto.

Spacemesh basics#

In Spacemesh, we divide time into fixed-length units we call layers, which are further grouped together into longer intervals called epochs. Layers are similar to Bitcoin's average ten minute block time, with a couple of important differences. For one thing, unlike in Proof of Work-based blockchains like Bitcoin and Ethereum where block time is the product of a Poisson process and thus random, layers in Spacemesh occur at precisely fixed intervals of time. This is due to the deterministic nature of the Spacemesh protocol. For another thing, in Spacemesh, many blocks are produced in each layer rather than only a single block. (Formally, a layer in Spacemesh is defined as a set of blocks produced during a fixed time interval, i.e., the layer is the blocks, not the time interval.)

Read on to learn more about the details of the Spacemesh protocol. You may also find this high-level protocol overview helpful.

Why race-free?#

The Spacemesh protocol guarantees that each Smesher that follows the rules of the protocol is eligible to produce multiple blocks during each epoch. Note also that Smeshing is entirely permissionless: in other words, anyone who runs the Spacemesh software and follows the rules of the protocol is guaranteed to be rewarded with Smesh coins at each epoch. This is in contrast to both Proof of Work-based protocols, such as Bitcoin, where rewards are probabilistic and only professional miners and mining pools stand a realistic chance of earning them; as well as to Proof of Stake-based protocols, where one must hold a substantial amount of the token before they are eligible to participate and earn rewards.

Spacemesh is able to achieve this nice property due to certain unique characteristics of its consensus mechanism (see also Consensus): in particular, the fact that it’s race-free, i.e., it does not require Smeshers to compete to produce blocks in a given layer, but rather allows many blocks to be produced at each layer. This results in a DAG data structure rather than a chain. See The race to race-free (or why we chose mesh over chain) for more information on this design choice.

Core Infrastructure#

Spacemesh infrastructure consists of several distinct core components. These components are built and maintained separately, but work in concert to enable the broader Spacemesh network and ecosystem.

Go-spacemesh#

The largest and most complex component of the network infrastructure is the go-spacemesh full node implementation. This codebase implements the bulk of the Spacemesh core protocol and can be used to run a protocol-compatible full node on a variety of different systems and architectures, including a trustless full node that independently verifies each transaction, and a mining (Smeshing, in Spacemesh terminology) node that additionally participates in consensus, produces blocks and collects rewards.

As the name implies, go-spacemesh is written in the Go programming language, and consists of a number of different modules that implement core components of the protocol such as mining, consensus, networking, P2P sync, and state. See go-spacemesh for more, in particular Go-spacemesh Architecture.

Note that, unlike full node implementations for certain other blockchain protocols, go-spacemesh does not include wallet functionality.

PoET server#

PoET stands for “Proof of Elapsed Time.” It’s a core part of the Spacemesh consensus protocol, where it’s used to prove that a miner has allocated a chunk of hard drive space to the protocol for some period of time. PoST, described below, is used to prove that space has been allocated; PoET is responsible for the time component of space-time.

PoET is implemented as a web service, separate from go-spacemesh, that anyone can run and offer as a service to Smeshers. Many Smeshers can share a single PoET server, and one Smesher may opt to utilize multiple PoET servers for redundancy. Go-spacemesh includes code to communicate with a PoET server.

For more information see PoET and the PoET codebase.

Spacemesh App#

The Spacemesh App is a GUI-based desktop application built for Windows, Mac, and Linux that has two main functions: it acts as a wallet, allowing a user to hold and transact Smesh coin, and it allows a user to mine (known as Smeshing) by allocating a certain amount of hard drive space, constructing and submitting eligibility proofs, producing blocks, and collecting rewards.

The App runs an instance of the go-spacemesh full node under the hood. For more information see the Spacemesh App codebase.

Testing#

Testing is a critical part of the software development workflow across all of the independent components of the Spacemesh network. There is no single, universal test suite; rather, each component implements its own unit and integration tests. For instance, you can find the go-spacemesh tests inside the tests/ folder of the repository.

DevOps#

The only piece of infrastructure that’s strictly required to join the Spacemesh network is a copy of the go-spacemesh client (along with the Spacemesh App if Smeshing). However, running multiple clients (such as setting up a local network, or a dev testnet), and/or ensuring redundancy among these nodes, requires additional tooling. There is tooling to run a local testnet, to operate multiple nodes, and to collect events and store them in a database.

SVM#

SVM is the Spacemesh Virtual Machine, a WebAssembly-compatible smart contract engine. This project is experimental and aims to add smart contract functionality to a future protocol release. Note that, since it is not part of the testnet, SVM is not covered further in the rest of these documents at present. See the repository and this blog post for more information about SVM.

Mining#

### Proof of Space-time

In Spacemesh, a miner establishes eligibility to produce blocks and participate in consensus by publishing an Activation Transaction (ATX), which contains (among other things) a Proof of Space-time.

These proofs have two phases. In the initial phase, known as the initialization phase, a miner allocates a chunk of hard drive space to the protocol, and commits to the contents of that space. The space is filled with cryptographic junk such that for the duration that this space is committed to Spacemesh it cannot be used for any other purpose. This hard drive space is the space component of the space-time resource that underlies a Proof of Space-time.

In the ongoing phase, known as the execution phase, the miner must submit a new ATX containing a proof of ongoing eligibility each epoch.

See Mining for more information on how these proofs are generated and utilized.

Producing blocks#

Once a miner has successfully generated and submitted an eligibility proof, the process of actually producing blocks is relatively straightforward. The miner can calculate which layers in a given epoch they are eligible to produce blocks. (The number of layers during which they are eligible, and thus, the number of blocks they produce in each epoch, will vary depending upon the total number of miners, but the epoch size is set sufficiently large that, unless the number of miners becomes enormous, each miner will be eligible to produce multiple blocks per epoch.)

Miners collect transactions into a local transaction pool, and once per eligible layer they assemble them into blocks and broadcast those blocks to the network. See Mining for more information on this process.

Consensus#

Consensus in the Spacemesh protocol consists of several independent components that work together to allow each network node to independently arrive at the same canonical view of blocks and transactions in a Byzantine Fault Tolerant-fashion, i.e., even if those nodes haven't seen precisely the same information at precisely the same time. What follows is a very brief overview; see Consensus for more information.

Tortoise and Hare#

Once many miners have produced candidate blocks for a given layer, how does the network achieve consensus on the canonical set of blocks and transactions that form the layer? In other words, how does a transaction become finalized?

Spacemesh employs a two-step process to achieve finality. The first step is the Hare protocol, which each node runs at the end of every layer. It’s a Byzantine agreement protocol that allows the network to quickly achieve consensus on a canonical set of blocks. The output of the Hare allows bootstrapping of the consensus of the Tortoise, which is a slower, vote-based protocol that methodically counts the votes for and against each block, leading to eventual, final consistency. Each node uses the output of the Hare protocol to decide which previous blocks its newly-produced blocks should vote for. See Consensus for more information on these protocols.

Networking#

The Spacemesh network consists of a peer-to-peer network of independent nodes, each running go-spacemesh (or another Spacemesh protocol client). Messages, which may consist of new transactions, old or new blocks, votes on consensus, etc., transit the network in one of only two fashions: a message may be transmitted from one node directly to a recipient node (e.g., in response to a request for a particular piece of data, such as a block), or a message may be gossiped across the entire network (e.g., a new transaction or block).

For more information, see P2P Networking.

Data Structures#

The basic building blocks of the Spacemesh protocol, and the overall, canonical mesh data structure, are transactions and blocks. Transactions are account-based, and contain a sender, a recipient, an amount, a signature, and a few other pieces of data. Blocks collate zero or more transactions into a discrete set, and contain a block height (layer number), a signature of the miner, a proof of eligibility, and a few other pieces of data. See Mining for more information.

Other relevant data structures include the various types of proof produced and submitted by miners and other services (PoET, ATX), and vote messages exchanged as part of the Hare protocol.

Learn More#

The documents contained in this repository are intended to provide a high-level, developer-centric overview of the Spacemesh protocol and the various infrastructure that implements the protocol. For additional resources, see the following:

Contribute#

All of the core components of the Spacemesh network and protocol, including everything described above, is open source and permissively-licensed, and we welcome contributions from all community members. We have a set of open bounties, and we are in the process of launching a grants program where you can apply for funding to work on a project of your choice that you feel will add value to the Spacemesh network and ecosystem. Watch the Spacemesh homepage for an announcement.

In addition to reading these docs, familiarizing yourself with the code, and running your own node, the best way to get started is to work on a good-first-issue in a codebase such as go-spacemesh. You can chat with other Spacemesh core developers and app developers on Gitter, or join a regular core devs call (participation information will be shared soon).

Edit this page
Last updated on by Aviv Eyal