Skip to content

Architecture

Aviv Eyal edited this page Jun 5, 2018 · 16 revisions

Node Software Architecture

This document provides a high-level overview of the various OS APIs, components and protocols.

Spacemesh Node

The go-spacemesh software is packaged as a cross-platform cli executable for linux, os X and Windows. The following diagram outlines the node's main components. The software package is using the host OS TCP/IP services for networking, host CPU for computation and host OS mounted storage for local storage.

Node Configuration

Users configure a node behavior on startup by using CLI argument and flags, by setting values in the node's default config file or by specifying a path to a custom config file.

Node Clients

Users interact with a running node instance, and receive information about the node runtime status, using a local HTML5 app running in a web browser or in the Spacemesh UI desktop App. The HTML5 app provides a basic Spacemesh wallet and node status dashboard. Alternatively they may start another node instance in REPL mode that is attached to another running node instance. Clients may run on another computer by remotely connecting to a node via its grpc or http-json servers.

Node CLI

The node cli supports an optional custom runtime configuration via flags, params. On first run, the user will be guided through the steps of creating a new node via an interactive CLI wizard.

gRPC Server

An http2/gRPC end-point implementing the Spacemesh API. The API is used by the local HTML5 app and can be used by other types of local front-ends to interact with a running node.

http-json Server

An http-json end-point implementing the Spacemesh API. Allows clients that can access http-json web services to interact with a running node instance.

The Spacemesh API

OS Services are provided the endpoint servers (http-json, gRPC, CLI) via one well-defined api. The API is implemented in an integration / business logic layer that uses the various OS services to implement API functionality.

Wallet App

The wallet app allows users to create and to manage standard BIP32/BIP39 HD wallets and to execute coin transfer and smart contract transactions. The app is using the grpc or the http/json server to communicate with a node instance.

Dashboard App

The dashboard app displays node runtime information and allows the user to provide supported runtime configurations that do not require restarting a node and initiate a node restart.

Cloud API Gateway

The gateway provides OS service to remote clients using the http-json API. A cloud gateway provides an Internet facing API to the Spacemesh platform. Using a deployed gateway, remote clients can read the computer state and submit signed transactions to the network.

OS Services

The OS Services implement the OS API using the various OS components. It is an integration layer where functionality is implemented using internal components and APIs.

OS components

Used by the OS Services. Each component provides a well-defined set of OS capabilities.

State Channels Protocol

This component implement payment channel protocols to provide a scalable off-chain payment transaction support. This includes storage and monitoring of channels state and incentives and slashing conditions to secure the channel from malicious behavior, capabilities to set up a payment channel between any two accounts and to settle channels back to the canonical accounts on-chain state.

Smart Contracts VM

This components provide the smart contracts execution environment. It is responsible for executing smart contracts and update computer state. It is used by the blockchain protocol to apply smart contract method calls included in user submitted transactions.

Ledger Protocol

This component is responsible to determine the canonical computer state based on blocks in the blockmesh provided by the Spacemesh Protocol. The computer state includes accounts balances, transaction receipts and smart contracts state. The protocol ensures to remove conflicting transactions from blocks submitted by validators to the blockmesh. It updates the state by using the Smart Contracts VM to execute smart contracts state changing methods.

Blocks Producer

This component is responsible for collecting user transactions broadcasted to the network into blocks and submitting the blocks to the network according to the consensus protocol. e.g. when the validator is eligible to submit blocks to a blockmesh epoch (measured as a mesh layers range).

Proof of Space Time Component

This component is responsible for POST (proof of space time) related operation. It handles the POST setup phase and is responsible to generate response to verifiers challenges to prove the node POST commitment. It uses a POET (proof of elapsed time) service to create self-contained POST proofs. Poet services are conceptually similar to Ethereal light client services - they are decentralized, anyone can run them and clients can validate the date they provide.

Spacemesh Protocol

The Spacemesh protocol is responsible for constructing and updating the blockmash with validator submitted blocks. It runs the fast Hare and the slow Tortoise protocols on the blockmesh.

p2p Protocols

The p2p protocols used by the various OS components to communicate with other nodes on the network. The strongly typed app-specific protocols utilize the core p2p and Gossip protocols and are responsible for implementing protocol-specific logic. For clarifications on how this design works please look at the Ping protocol in the repo. The protocols support fire-and-forget pattern as well as the async request-response pattern. The OS supports routing of p2p messages to the applicable protocol for handling new incoming requests and incoming responses for locally issued requests.

Core p2p, DHT, Gossip

The core low-level p2p functionality include a baseline protocol for a secure, authenticated and compact messaging between any two nodes and for gossip-style broadcasting of p2p messages to the network. This include a handshake protocol which is used to establish such virtual p2p session between any 2 nodes. app-specific p2p messages are sent on the network using these sessions. The core is using tcp/ip connections between nodes but is robust enough to re-create connections on-demand in case of network errors. Nodes discovery and virtual p2p swarm are implemented using a DHT component. Broadcasting a message to the whole network is implemented using a Gossip-like protocol. Messages designated to a specific node may be broadcasted to the whole network or messages without a specific target node may also be broadcasted to the network. These type of messages are used by the various higher-level p2p protocols.

Host OS TCP/IP

The host OS provides standard TCP/IP services to the OS core p2p components.

Getting Started

Dev Guides

Product Specs

Clone this wiki locally