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 and layers. The software package is using the host OS TCP/IP services for networking, host CPU for computation and host OS mounted storage for accessing local storage.
Users configure the node's 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. The node has a default config file with default values. These values may be overridden by CLI flags or by a custom config file.
Users interact with a running node instance, and receive information about the node runtime status by using a local HTML5 app. The app can run in a web browser or in the Spacemesh UI desktop App. The HTML5 app provides a basic Spacemesh wallet and node status dashboard. Alternatively, users may start another node instance in REPL mode that is attached to a locally running node instance. Clients running on another computer by remotely connecting to a node via its grpc or http-json servers.
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.
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.
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.
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.
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.
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.
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.
- Users need to provide to the node the public account id for validation award (coinbase). This can be done by using the config file or via command line arguments.
- Nodes should be Internet routable over their advertised main TCP/IP address.
- Node grpc server and http-json server should not be Internet routable.
- Node grpc and http-json server do not provide a method to perform transactions that do not include the initiator signature. It is the responsibility of wallet apps to sign transactions on behalf of users and use the node servers to submit transactions to the platform. This design ensures that even if the node's grpc and/or http-json are Internet accessible, then an attacker will not be able to execute transactions on behalf of the user.
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.