Architecture
This document provides a high-level overview of the various OS APIs, components and protocols.
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. The main way to configure a node is using CLI params and flags or by modifying values in the node's config file. The node provides runtime APIs that allow interacting with the node while it is running using a local HTML5 browser app or via a cloud-facing API gateway.
The cli supports custom OS runtime configuration via flags, params and a config file. These allow modifying the default node runtime configuration. On first run, starting up the node cli app will guide the user through the steps for creating a new validator account and for starting the POST setup phase.
The OS is providing its services to clients via a 2 main apis - gRPC and http-json. These APIs are designed to execute commands, transactions, read accounts data and coin balances and read smart contracts state.
An http2/gRPC end-point implementing the OS 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.
An http-json end-point implementing the OS API. Allows clients that can access http-json web services to interact with a running node.
The OS is designed to be used by various local clients - clients running on the same host OS. OS APIs are not exposed to remote network connections.
The html5 app is designed to provide a browser-based interface to the OS. It uses the http-json API endpoint to communicate with the OS. It is designed as a front-end only component.
The gateway provides OS service to remote clients using the http-json API spec. A cloud gateway provides an Internet facing API to the platform. Using a deployed gateway, remote clients can read the computer state and submit signed transactions to the network.
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.
Used by the OS Services. Each component provides a well-defined set of OS capabilities.
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.
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.
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.
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).
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.
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.
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.
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.
The host OS provides standard TCP/IP services to the OS core p2p components.