New Smesher API

proto/spacemesh/v1/api_config.yaml

@@ -76,13 +76,17 @@ http:
       body: "*"
 
     # SmesherService
-    - selector: spacemesh.v1.SmesherService.IsSmeshing
-      post: "/v1/smesher/issmeshing"
+    - selector: spacemesh.v1.SmesherService.SmeshingStatus
+      post: "/v1/smesher/smeshingstatus"
     - selector: spacemesh.v1.SmesherService.StartSmeshing
       post: "/v1/smesher/startsmeshing"
+      body: "*"
     - selector: spacemesh.v1.SmesherService.StopSmeshing
       post: "/v1/smesher/stopsmeshing"
       body: "*"
+    - selector: spacemesh.v1.SmesherService.PostComputeProviders
+      post: "/v1/smesher/postcomputeproviders"
+      body: "*"
     - selector: spacemesh.v1.SmesherService.SmesherID
       post: "/v1/smesher/smesherid"
     - selector: spacemesh.v1.SmesherService.Coinbase
@@ -95,15 +99,11 @@ http:
     - selector: spacemesh.v1.SmesherService.SetMinGas
       post: "/v1/smesher/setmingas"
       body: "*"
-    - selector: spacemesh.v1.SmesherService.PostStatus
-      post: "/v1/smesher/poststatus"
-    - selector: spacemesh.v1.SmesherService.PostComputeProviders
-      post: "/v1/smesher/postcomputeproviders"
-    - selector: spacemesh.v1.SmesherService.CreatePostData
-      post: "/v1/smesher/createpostdata"
+    - selector: spacemesh.v1.SmesherService.EstimatedRewards
+      post: "/v1/smesher/estimatedrewards"
       body: "*"
-    - selector: spacemesh.v1.SmesherService.StopPostDataCreationSession
-      post: "/v1/smesher/stoppostdatacreationsession"
+    - selector: spacemesh.v1.SmesherService.Config
+      post: "/v1/smesher/config"
       body: "*"
 
     # TransactionService

proto/spacemesh/v1/smesher.proto

@@ -6,60 +6,47 @@ import "spacemesh/v1/smesher_types.proto";
 
 // Readonly basic node data
 service SmesherService {
-    /////// Smeshing (mining) management
+    // Returns the node's current smeshing status
+    rpc SmeshingStatus (google.protobuf.Empty) returns (SmeshingStatusResponse);
 
-    // Returns true iff node is currently smeshing
-    rpc IsSmeshing(google.protobuf.Empty) returns (IsSmeshingResponse);
+    // Start smeshing. If the post data is incomplete or missing, data creation
+    // session will be preceded. Changing of the post potions (e.g., number of labels),
+    // after initial setup, is supported.
+    // Returns success if request is accepted by node , failure if it fails
+    rpc StartSmeshing (StartSmeshingRequest) returns (StartSmeshingResponse);
 
-    // Start smeshing
-    // Returns error if post data is incomplete or missing
-    rpc StartSmeshing(StartSmeshingRequest) returns (StartSmeshingResponse);
+    // Stop smeshing or the preceding post data session, and optionally attempt to
+    // delete the post data files(s).
+    // Returns success if request is accepted by node, failure if it fails
+    rpc StopSmeshing (StopSmeshingRequest) returns (StopSmeshingResponse);
+
+    // Returns a list of available post compute providers for creating post data
+    rpc PostComputeProviders (PostComputeProvidersRequest) returns (PostComputeProvidersResponse);
 
-    // Stop smeshing and optionally attempt to delete post init file(s)
-    // Returns success if request is accepted by node, error if it fails
-    rpc StopSmeshing(StopSmeshingRequest) returns (StopSmeshingResponse);
+    // Returns a stream of updates regarding the current or the upcoming post data creation session
+    rpc PostDataCreationProgressStream (google.protobuf.Empty) returns (stream PostDataCreationProgressStreamResponse);
 
     // Get the current smesher id generated by the node
-    rpc SmesherID(google.protobuf.Empty) returns (SmesherIDResponse);
+    rpc SmesherID (google.protobuf.Empty) returns (SmesherIDResponse);
 
     // Get the current coinbase
-    rpc Coinbase(google.protobuf.Empty) returns (CoinbaseResponse);
+    rpc Coinbase (google.protobuf.Empty) returns (CoinbaseResponse);
 
     // Set the coinbase
     // Returns success if request succeeds, failure if it fails
-    rpc SetCoinbase(SetCoinbaseRequest) returns (SetCoinbaseResponse);
+    rpc SetCoinbase (SetCoinbaseRequest) returns (SetCoinbaseResponse);
 
     // Get the current min gas for including txs in blocks by this smesher
-    rpc MinGas(google.protobuf.Empty) returns (MinGasResponse);
+    rpc MinGas (google.protobuf.Empty) returns (MinGasResponse);
 
     // Set a min gas units for including txs in blocks by this smesher
     // Returns success if request succeeds, failure if it fails
-    rpc SetMinGas(SetMinGasRequest) returns (SetMinGasResponse);
-    
+    rpc SetMinGas (SetMinGasRequest) returns (SetMinGasResponse);
+
     // Estimate smeshing rewards over the next upcoming epoch
     rpc EstimatedRewards(EstimatedRewardsRequest) returns (EstimatedRewardsResponse);
 
-    /////// Proofs of space data files management
-
-    // Returns post data status from the node
-    rpc PostStatus(google.protobuf.Empty) returns (PostStatusResponse);
-
-    // Returns a list of available post compute providers for creating post data
-    rpc PostComputeProviders(google.protobuf.Empty) returns (PostComputeProvidersResponse);
-
-    // Starts (or continues) a post init phase. Supports resuming a previously
-    // started init session, as well as changing post params (e.g., post data size)
-    // after initial setup.
-    // Returns success if request is accepted by node, failure if it fails
-    rpc CreatePostData(CreatePostDataRequest) returns (CreatePostDataResponse);
-
-    // Stop an ongoing post data init phase and optionally attempt to delete
-    // the post data file(s)
-    // Returns success if request is accepted by node, failure if it fails
-    rpc StopPostDataCreationSession(StopPostDataCreationSessionRequest) returns (StopPostDataCreationSessionResponse);
-
-    // STREAMS
-
-    // Returns a stream of updates to post data file(s) during the init phase
-    rpc PostDataCreationProgressStream(google.protobuf.Empty) returns (stream PostDataCreationProgressStreamResponse);
+    // TODO: document
+    rpc Config(google.protobuf.Empty) returns (ConfigResponse);
 }
+

proto/spacemesh/v1/smesher_types.proto

@@ -4,14 +4,19 @@ option go_package = "github.com/spacemeshos/api/release/go/spacemesh/v1";
 import "spacemesh/v1/types.proto";
 import "google/rpc/status.proto";
 
-message IsSmeshingResponse {
-    bool is_smeshing = 1;
+message SmeshingStatusResponse {
+    enum SmeshingStatus {
+        SMESHING_STATUS_UNSPECIFIED = 0; // Lane's favorite impossible value
+        SMESHING_STATUS_IDLE = 1;
+        SMESHING_STATUS_CREATING_POST_DATA = 2;
+        SMESHING_STATUS_ACTIVE = 3;
+    }
+    SmeshingStatus status = 1;
 }
 
 message StartSmeshingRequest {
     AccountId coinbase = 1;
-    string data_dir = 2;
-    SimpleInt commitment_size = 3;
+    PostInitOpts opts = 2;
 }
 
 message StartSmeshingResponse {
@@ -42,13 +47,6 @@ message SetMinGasResponse {
     google.rpc.Status status = 1;
 }
 
-message CreatePostDataResponse {
-    google.rpc.Status status = 1;
-}
-
-message StopPostDataCreationSessionResponse {
-    google.rpc.Status status = 1;
-}
 
 message SmesherIDResponse {
     AccountId account_id = 1;
@@ -77,57 +75,37 @@ enum ComputeApiClass {
     COMPUTE_API_CLASS_VULKAN = 3;
 }
 
-// Basic post data. Used for users to provide requested post data and by
-// other messages which contain post data.
-message PostData {
-    string path = 1; // User provided path to create the post data files at
-    uint64 data_size = 2; // Requested post data size
-    bool   append = 3; // Append to existing files if they exist. Otherwise overwrite.
-    bool   throttle = 4; // Throttle down setup phase computations while user is interactive on system
-    uint32 provider_id = 5; // A PostProvider id
+// Post init options. Used to define the requested options and by
+// other messages which contain the options.
+message PostInitOpts {
+    string data_dir = 1; // User provided path to create the post data files at
+    uint32 num_units = 2; // Number of PoST data commitment units to generate
+    uint32 num_files = 3; // Number of files to equally distribute the labels among
+    uint32 compute_provider_id = 4; // A PostProvider id
+    bool throttle = 5; // Throttle down setup phase computations while user is interactive on system
 }
 
 message CreatePostDataRequest {
-    PostData data = 1;
+    PostInitOpts opts = 1;
 }
 
 // Param passed to methods to indicate a request to delete data files
 message StopSmeshingRequest {
     bool delete_files = 1;
 }
 
-message StopPostDataCreationSessionRequest {
-    bool delete_files = 1;
+message PostComputeProvidersRequest {
+    bool benchmark = 1;
 }
 
-// Proof of space data status
-message PostStatus {
-    PostData post_data = 1; // basic post data (set previously by the user)
-    enum FilesStatus {
-        FILES_STATUS_UNSPECIFIED = 0; // Lane's favorite impossible value
-        FILES_STATUS_NOT_FOUND = 1; // Expected data files do not exist
-        FILES_STATUS_PARTIAL = 2; // Some files exist and init can be continued (and may be in progress)
-        FILES_STATUS_COMPLETE = 3; // Expected data files are available and verified
-    }
-    FilesStatus files_status = 2;
-    bool init_in_progress = 3; // True if init process is currently in progress
-    uint64 bytes_written = 4; // Bytes written to the data files (actual total files sizes)
-    string error_message = 5; // Last init process error message
-    enum ErrorType {
-        ERROR_TYPE_UNSPECIFIED = 0; // Lane's favorite imposible value
-        ERROR_TYPE_FILE_NOT_FOUND = 1; // All expected post data files not found in expected path
-        ERROR_TYPE_READ_ERROR = 2; // Failure to read from a data file
-        ERROR_TYPE_WRITE_ERROR = 3; // Failure to write to a data file
-    }
-    ErrorType error_type = 6;
-}
-
-message PostStatusResponse {
-    PostStatus status = 1;
+// Proof of space data creation session status
+message SessionStatus {
+    PostInitOpts session_opts = 1; // The current session init options
+    uint64 num_labels_written = 2; // Number of labels written to the data files
 }
 
 message PostDataCreationProgressStreamResponse {
-    PostStatus status = 1;
+    SessionStatus status = 1;
 }
 
 message EstimatedRewardsRequest {}
@@ -138,6 +116,13 @@ message EstimatedRewardsRequest {}
 message EstimatedRewardsResponse {
     // The amount of the total estimated reward in the next upcoming epoch
     Amount amount = 1;
-    // The commitment size that this estimated reward corresponds to (part of global config)
-    uint64 data_size = 2;
+    // The number of PoST data commitment units that this estimated reward corresponds to (part of global config)
+    uint32 num_units = 2;
+}
+
+message ConfigResponse {
+    uint32 bits_per_label = 1;
+    uint64 labels_per_unit = 2;
+    uint32 min_num_units = 3;
+    uint32 max_num_units = 4;
 }

proto/spacemesh/v1/types.proto

@@ -73,7 +73,7 @@ message Activation {
     SmesherId smesher_id = 3; // id of smesher who created the ATX
     AccountId coinbase = 4; // coinbase account id
     ActivationId prev_atx = 5; // previous ATX pointed to
-    uint64 commitment_size = 6; // commitment size in bytes
+    uint32 num_units = 6; // number of PoST data commitment units
 }
 
 // An immutable Spacemesh transaction.