Merge pull request #2 from spacemeshos/initial-feedback

Refactoring

README.md

@@ -1,7 +1,28 @@
-# api
+# Spacemesh API
 [Protobuf](https://developers.google.com/protocol-buffers) implementation of the Spacemesh API. This is a work in progress. See the more complete [master API spec](https://docs.google.com/spreadsheets/d/1P89OVWdgJocPy0CGM43Ge7Sx_6dabCBEagaVQfOk9us/edit).
 
-## Building
+## Design
+
+The Spacemesh API consists of several logical services, each of which contains a set of one or more RPC endpoints. The node operator can enable or disable each service independently using the CLI. The current set of services is as follows:
+
+- [NodeService](proto/spacemesh/node.proto) is a readonly interface for reading basic node-related data such as node status, software version and build number, and errors. It also allows a consumer to request that the node start the sync process, thus enabling the stream endpoints.
+- [MeshService](proto/spacemesh/mesh.proto) is a readonly interface that provides access to mesh data such as layer and epoch number, and network ID. It provides streams for watching layers (which contain blocks, transactions, etc.). In the future this service will be expanded to include other mesh-related endpoints.
+- [GlobalStateService](proto/spacemesh/global_state.proto) is a readonly interfact that provides access to data elements that are not explicitly part of the mesh such as accounts, rewards, and transaction state and receipts. In the future this service will be expanded to include additional endpoints for things such as global state hash and events emitted by smart contracts.
+
+In addition to these services, there is also a set of [global types](proto/spacemesh/types.proto) which are shared among all of the services.
+
+## Intended Usage Pattern
+
+### Mesh data processing flow
+1. Client starts a full node with flags set to turn syncing off and to open the GRPC APIs
+1. Client registers on the streaming GRPC api methods that are of interest
+1. Client calls `node.SyncStart()` to request that the node start syncing
+1. Client processes streaming data it receives from the node
+1. Client monitors node using `node.SyncStatusStream()` and `node.ErrorStream()` and handle node critical errors. Return to step 1 as necessary.
+
+## Dev
+
+### Building
 
 Use the [`buf`](https://buf.build/) tool to compile the API to an [image](https://buf.build/docs/inputs). First, [install `buf`](https://buf.build/docs/installation), then run:
 
@@ -15,7 +36,7 @@ to test the build. To output the image in json format, run:
 > buf image build --exclude-source-info -o -#format=json
 ```
 
-## Linting
+### Linting
 
 `buf` runs several [linters](https://buf.build/docs/lint-checkers).
 
@@ -24,3 +45,4 @@ to test the build. To output the image in json format, run:
 ```
 
 This command should have exit code 0 and no output. See the [style guide](https://buf.build/docs/style-guide).
+

proto/spacemesh/global_state.proto

@@ -0,0 +1,26 @@
+syntax = "proto3";
+package spacemesh;
+import "google/protobuf/empty.proto";
+import "spacemesh/types.proto";
+
+// Readonly global state data.
+// Global state data is data which is not explicitly stored in the mesh.
+// Global state is modified only by the state transition function.
+service GlobalStateService {
+    //// Streaming global state data
+
+    // Account changes (e.g., balance and counter/nonce changes).
+    rpc AccountStream(google.protobuf.Empty) returns (stream Account);
+
+    // Rewards are computed by the protocol outside the STF but are a special
+    // case and are passed through the STF since they touch account balances.
+    rpc RewardStream(google.protobuf.Empty) returns (stream Reward);
+
+    // Transaction State - rejected pre-STF, or pending STF, or processed by
+    // STF
+    rpc TransactionStateStream(google.protobuf.Empty) returns (stream TransactionState);
+
+    // Receipts - emitted after tx was processed by STF (or rejected before
+    // STF)
+    rpc TransactionReceiptStream(google.protobuf.Empty) returns (stream TransactionReceipt);
+}

proto/spacemesh/mesh.proto

@@ -0,0 +1,28 @@
+syntax = "proto3";
+package spacemesh;
+import "google/protobuf/empty.proto";
+import "spacemesh/types.proto";
+
+// Readonly API for basic mesh info
+service MeshService {
+    // Network genesis time as unix epoch time
+    rpc GenesisTime(google.protobuf.Empty) returns (SimpleInt);
+
+    // Current layer number
+    rpc CurrentLayer(google.protobuf.Empty) returns (SimpleInt);
+
+    // Current epoch number
+    rpc CurrentEpoch(google.protobuf.Empty) returns (SimpleInt);
+
+    // Network ID
+    rpc NetId(google.protobuf.Empty) returns (SimpleInt);
+
+    // Number of layers per epoch (a network parameter)
+    rpc EpochNumLayers(google.protobuf.Empty) returns (SimpleInt);
+
+    ////////// Streams
+
+    // Layer with blocks and transactions.
+    // Sent each time layer data changes. Designed for heavy-duty clients.
+    rpc LayerStream(google.protobuf.Empty) returns (stream Layer);
+}

proto/spacemesh/node.proto

@@ -0,0 +1,30 @@
+syntax = "proto3";
+package spacemesh;
+import "google/protobuf/empty.proto";
+import "spacemesh/types.proto";
+
+// Readonly basic node data
+service NodeService {
+    // A simple test endpoint
+    rpc Echo(SimpleString) returns (SimpleString);
+
+    // Returns the version of the node software as a semver string
+    rpc Version(google.protobuf.Empty) returns (SimpleString);
+
+    // Returns the github tag or branch used to build the node
+    rpc Build(google.protobuf.Empty) returns (SimpleString);
+
+    //  Current node status
+    rpc Status(google.protobuf.Empty) returns (NodeStatus);
+
+    // Request that the node start syncing the mesh
+    rpc SyncStart(google.protobuf.Empty) returns (google.protobuf.Empty);
+
+    ////////// Node streaming data
+
+    // Sync status events
+    rpc SyncStatusStream(google.protobuf.Empty) returns (stream NodeSyncStatus);
+
+    // Node error events
+    rpc ErrorStream(google.protobuf.Empty) returns (stream NodeError);
+}