API v2 specification along with the new requirements

spacemesh/v2/account.proto

@@ -0,0 +1,28 @@
+syntax = "proto3";
+
+package spacemesh.v2;
+
+message Account {
+  oneof versioned {
+    AccountV1 v1 = 1;
+  }
+}
+
+message AccountV1 {
+  string account_id = 1; // account public address
+  AccountState state_current = 2; // current state
+  AccountState state_projected = 3; // projected state (includes pending txs)
+}
+
+message AccountState {
+  uint64 counter = 1; // aka nonce
+  uint64 balance = 2; // known account balance
+}
+
+message AccountRequest {
+  string address = 1;
+};
+
+service AccountService {
+  rpc Get(AccountRequest) returns (Account);
+}

spacemesh/v2/block.proto

@@ -0,0 +1,26 @@
+syntax = "proto3";
+
+import "spacemesh/v2/tx.proto";
+
+package spacemesh.v2;
+
+message Block {
+  oneof versioned {
+    BlockV1 v1 = 1;
+  }
+}
+
+message BlockV1 {
+  bytes id = 1; // block hash
+  repeated Transaction transactions = 2; // block transactions
+  bytes activation_id = 3; // the smesher's activation that this block refers to
+  bytes smesher_id = 4; // the id of the smesher who submitted this block
+}
+
+message BlockRequest {
+  bytes id = 1; // block hash
+}
+
+service BlockService {
+  rpc Get(BlockRequest) returns (Block);
+}

spacemesh/v2/layer.proto

@@ -0,0 +1,35 @@
+syntax = "proto3";
+
+import "spacemesh/v2/block.proto";
+
+package spacemesh.v2;
+
+message Layer {
+  oneof versioned {
+    BlockV1 v1 = 1;
+  }
+}
+
+message LayerV1 {
+  uint32 number = 1; // layer number - not hash - layer content may change
+  enum LayerStatus {
+    LAYER_STATUS_UNSPECIFIED = 0; // not yet approved or confirmed
+    LAYER_STATUS_APPROVED = 1; // approved by hare
+    LAYER_STATUS_CONFIRMED = 2; // confirmed by tortoise
+    LAYER_STATUS_APPLIED = 3; // applied in state
+  }
+  LayerStatus status = 2;
+  bytes hash = 3; // computer layer hash - do we need this?
+  repeated Block blocks = 4; // layer's blocks
+  bytes root_state_hash = 5; // when available - the root state hash of global state in this layer
+}
+
+message LayerRequest {
+  uint32 layer_number = 1;
+  bool include_transactions = 2;
+};
+
+
+service LayerService {
+  rpc Get(LayerRequest) returns (Layer);
+}

spacemesh/v2/network.proto

@@ -0,0 +1,20 @@
+syntax = "proto3";
+
+package spacemesh.v2;
+
+message NetworkInfoRequest {}
+
+message NetworkInfoResponse {
+  uint64 genesis_time = 1; // network genesis time as unix epoch time
+  uint32 epoch_num_layers = 2; // number of layers per epoch
+  uint64 layer_duration = 3; // layer duration, in seconds
+  uint64 max_transactions_per_second = 4;
+  string hrp = 5;
+  uint32 first_genesis = 6;
+  uint32 effective_genesis = 7;
+  uint32 epoch_size = 8;
+}
+
+service NetworkService {
+  rpc Info(NetworkInfoRequest) returns (NetworkInfoResponse);
+}

spacemesh/v2/node.proto

@@ -0,0 +1,18 @@
+syntax = "proto3";
+
+package spacemesh.v2;
+
+message NodeStatusRequest {}
+
+message NodeStatusResponse {
+  uint64 connected_peers = 1; // number of connected neighbors
+  bool   is_synced = 2; // true when meshed is synced
+  uint32 synced_layer = 3; // the last layer node has synced
+  uint32 verified_layer = 4; // the last layer node has verified
+  uint32 head_layer = 5; // head layer is the tip
+  uint32 head_block = 6;
+}
+
+service NodeService {
+  rpc Status(NodeStatusRequest) returns (NodeStatusResponse);
+}

spacemesh/v2/reward.proto

@@ -0,0 +1,32 @@
+syntax = "proto3";
+
+package spacemesh.v2;
+
+message Reward {
+  oneof versioned {
+    RewardV1 v1 = 1;
+  }
+}
+
+message RewardV1 {
+  uint32 layer = 1; // layer award was paid in
+  uint64 total = 2; // total reward paid (sum of tx fee and layer reward)
+  uint64 layer_reward = 3; // tx_fee = total - layer_reward
+  uint32 layer_computed = 4; // layer number of the layer when reward was computed
+  string coinbase = 5; // account awarded this reward
+  bytes smesher = 6;  // id of smesher who earned this reward
+}
+
+message RewardRequest {
+  string coinbase = 1;
+  uint64 offset = 2;
+  uint64 limit = 3;
+}
+
+message RewardList {
+  repeated Reward rewards = 1;
+}
+
+service RewardService {
+  rpc List(RewardRequest) returns (RewardList);
+}

spacemesh/v2/tx.proto

@@ -0,0 +1,114 @@
+syntax = "proto3";
+
+import "google/rpc/status.proto";
+
+package spacemesh.v2;
+
+message Transaction {
+  oneof versioned {
+    TransactionV1 v1 = 1;
+  }
+}
+
+// An immutable Spacemesh transaction.
+// do not include mutable data such as tx state or result.
+message TransactionV1 {
+  bytes id = 1;
+  string principal = 2;
+  string template = 3;
+  uint32 method = 4; // this is actually limited by uint8, but no type for that.
+  Nonce nonce = 5;
+  LayerLimits limits = 6;
+  uint64 max_gas = 7;
+  uint64 gas_price = 8;
+  uint64 max_spend = 9;
+  bytes raw = 10;
+}
+
+message Nonce {
+  uint64 counter = 1;
+  uint32 bitfield = 2; // this is actually limited by uint8, but no type for that.
+}
+
+message LayerLimits {
+  uint32 min = 1;
+  uint32 max = 2;
+}
+
+// TransactionState is the "journey" of a tx from mempool to block inclusion to
+// mesh to STF processing. To know whether or not the tx actually succeeded,
+// and its side effects, check the Receipt in the GlobalStateService.
+message TransactionState {
+  bytes id = 1;
+  enum TransactionState {
+    TRANSACTION_STATE_UNSPECIFIED = 0; // default state
+    TRANSACTION_STATE_REJECTED = 1; // rejected from mempool due to, e.g., invalid syntax
+    TRANSACTION_STATE_INSUFFICIENT_FUNDS = 2; // rejected from mempool by funds check
+    TRANSACTION_STATE_CONFLICTING = 3; // rejected from mempool due to conflicting counter
+    TRANSACTION_STATE_MEMPOOL = 4; // in mempool but not on the mesh yet
+    TRANSACTION_STATE_MESH = 5; // submitted to the mesh
+    TRANSACTION_STATE_PROCESSED = 6; // processed by STF; check Receipt for success or failure
+  }
+  TransactionState state = 2;
+}
+
+message TransactionResult {
+  enum Status {
+    SUCCESS = 0;
+    FAILURE = 1;
+    INVALID = 2;
+  }
+
+  Transaction tx = 1;
+  Status status = 2;
+  string message = 3;
+  uint64 gas_consumed = 4;
+  uint64 fee = 5;
+  bytes block = 6;
+  uint32 layer = 7;
+  repeated string touched_addresses = 8;
+}
+
+message TransactionStreamRequest {
+  uint32 start_layer = 1;
+  uint32 end_layer = 2;
+  bytes id = 3;
+  string address = 4;
+  bool watch = 5;
+}
+
+service TransactionStreamService {
+  rpc Stream(TransactionStreamRequest) returns (stream Transaction);
+}
+
+message TransactionRequest {
+  bytes id = 1;
+  bool include_state = 2;
+  bool include_result = 3;
+}
+
+message TransactionResponse {
+  Transaction tx = 1;
+  TransactionState tx_state = 2;
+  TransactionResult tx_result = 3;
+}
+
+message ParseTransactionRequest {
+  bytes transaction = 1;  // signed binary transaction
+  bool verify = 2;        // if true signature verification will be executed
+}
+
+message SubmitTransactionRequest {
+  bytes  transaction = 1;  // signed binary transaction
+}
+
+message SubmitTransactionResponse {
+  google.rpc.Status status = 1;
+  TransactionState tx_state = 2;
+}
+
+service TransactionService {
+  rpc Get(TransactionRequest) returns (TransactionResponse);
+  rpc ParseTransaction(ParseTransactionRequest) returns (ParseTransactionRequest);
+  rpc SubmitTransaction(SubmitTransactionRequest) returns (SubmitTransactionResponse);
+}