You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
rpc NewValidationEndpoint (NewValidationRequest) returns (NewValidationResponse) {}; // New RPC method
19
19
}
20
20
21
21
message NewValidationRequest {
22
-
string data = 1;
22
+
string data = 1;
23
23
}
24
24
25
25
message NewValidationResponse {
26
-
bool success = 1;
27
-
string message = 2;
26
+
bool success = 1;
27
+
string message = 2;
28
28
}
29
29
```
30
30
31
-
You can also define a completely new service and corresponding messages in a new `.proto` file, such as `services/newservice/newservice_api.proto`.
31
+
**Note:** All service names in Teranode use the `API` suffix (e.g., `SubtreeValidationAPI`, `ValidatorAPI`, `BlockchainAPI`).
32
+
33
+
You can also define a completely new service and corresponding messages in a new `.proto` file, such as `services/newservice/newservice_api/newservice_api.proto`.
32
34
33
35
#### Step 2: Update the `Makefile`
34
36
@@ -37,9 +39,9 @@ Once your new or modified `.proto` file is ready, you need to update the `Makefi
37
39
To add a new service or dependency, follow these steps:
38
40
39
41
1.**Locate the `Makefile`** in the project root.
40
-
2.**Add a new `protoc` command** for your new `.proto` file under the `gen`section.
42
+
2.**Add a new `protoc` command** for your new `.proto` file under the `gen`target.
41
43
42
-
For example, if you created a new `newservice_api.proto` file in the `services/newservice/` directory, add a new `protoc` command like this:
44
+
For example, if you created a new `newservice_api.proto` file in the `services/newservice/newservice_api/` directory, add a new `protoc` command like this:
**Note:** The directory structure follows the pattern `services/<service_name>/<service_name>_api/<service_name>_api.proto`.
57
+
54
58
This ensures that the new `.proto` file is processed and generates the corresponding Go code (both the message definitions and the gRPC stubs).
55
59
56
60
#### Step 3: Regenerate the Protobuf Files
@@ -69,51 +73,151 @@ This will generate the necessary Go files for all services, including the newly
69
73
70
74
Once the Go files have been generated, you can verify that the new service or endpoint is available by checking the generated `.pb.go` and `_grpc.pb.go` files. For instance, after adding a new method, you should see:
71
75
72
-
- The new RPC method in the `SubtreeValidationServiceServer` interface in the `_grpc.pb.go` file.
76
+
- The new RPC method in the `SubtreeValidationAPIServer` interface in the `_grpc.pb.go` file.
73
77
- The new request and response message types in the `.pb.go` file.
74
78
75
-
Here’s what you might expect in `subtreevalidation_api_grpc.pb.go`:
79
+
Here's what you might expect in `subtreevalidation_api_grpc.pb.go`:
76
80
77
81
```go
78
-
//SubtreeValidationServiceServer is the server API for SubtreeValidationService.
NewValidationEndpoint(context.Context, *NewValidationRequest) (*NewValidationResponse, error) // New RPC method
82
86
}
83
87
```
84
88
85
-
#### Example: Adding a New Protobuf Dependency
89
+
#### Example: Creating a Complete New Service
86
90
87
-
Let’s say you want to add a new`.proto` file that defines a shared data model used across several services. This file could be called `common.proto` and might look like this:
91
+
When creating a new service from scratch, your`.proto` file should include all required elements. Here's a complete example for `services/newservice/newservice_api/newservice_api.proto`:
88
92
89
93
```proto
90
94
syntax = "proto3";
91
95
92
-
package common;
96
+
option go_package = "./;newservice_api";
97
+
98
+
package newservice_api;
99
+
100
+
import "google/protobuf/timestamp.proto";
101
+
102
+
// NewServiceAPI provides methods for the new service functionality
// EmptyMessage represents an empty message structure used for health check requests
112
+
message EmptyMessage {}
113
+
114
+
// HealthResponse encapsulates the service health status information
115
+
message HealthResponse {
116
+
bool ok = 1;
117
+
string details = 2;
118
+
google.protobuf.Timestamp timestamp = 3;
119
+
}
93
120
94
-
message CommonMessage {
95
-
string id = 1;
96
-
string content = 2;
121
+
// ProcessDataRequest defines the input for data processing
122
+
message ProcessDataRequest {
123
+
string data = 1;
124
+
}
125
+
126
+
// ProcessDataResponse contains the processing result
127
+
message ProcessDataResponse {
128
+
bool success = 1;
129
+
string result = 2;
97
130
}
98
131
```
99
132
100
-
To add this new `common.proto` file to your project and make it available to other services, follow these steps:
133
+
**Key elements to include:**
101
134
102
-
1.**Add the `common.proto` file** to the `model` or `shared` directory (or another appropriate location).
103
-
2.**Update the `Makefile`** by adding a `protoc` command to generate the Go files for `common.proto`.
135
+
-`syntax = "proto3";` - Specifies the protobuf version
136
+
-`option go_package = "./;newservice_api";` - Required for Go code generation
137
+
-`package newservice_api;` - Package name matching the directory structure
138
+
- Import statements for dependencies (e.g., `google/protobuf/timestamp.proto`)
139
+
- Service definition with `API` suffix
140
+
- Common patterns like `HealthGRPC` endpoint (present in all services)
141
+
- Comprehensive comments for all messages and RPC methods
104
142
105
-
For example:
106
-
```makefile
107
-
protoc \
108
-
--proto_path=. \
109
-
--go_out=. \
110
-
--go_opt=paths=source_relative \
111
-
model/common.proto
143
+
#### Example: Using Shared Protobuf Models
144
+
145
+
Teranode already provides shared data models in `model/model.proto` that can be used across services. To use these in your new service:
146
+
147
+
1.**Import the model** in your service's `.proto` file:
148
+
149
+
```proto
150
+
import "model/model.proto";
151
+
```
152
+
153
+
2.**Reference the model types** in your messages:
154
+
155
+
```proto
156
+
message MyServiceRequest {
157
+
model.MiningCandidate candidate = 1;
158
+
string additional_data = 2;
159
+
}
160
+
```
161
+
162
+
If you need to add new shared models, update `model/model.proto` directly. The Makefile already includes this file in the `gen` target, so running `make gen` will regenerate the code.
163
+
164
+
**Existing shared proto files:**
165
+
166
+
-`model/model.proto` - Core data models (MiningCandidate, BlockInfo, etc.)
167
+
-`errors/error.proto` - Error handling structures
168
+
-`stores/utxo/status.proto` - UTXO status definitions
169
+
170
+
#### Step 5: Implement the Service Interface
171
+
172
+
After generating the protobuf files, you need to implement the service interface in your Go code. Create an implementation file (e.g., `services/newservice/service.go`):
0 commit comments