Before following this tutorial, make sure you've installed
- Docker (https://www.docker.com/)
- Metamask (https://metamask.io)
You will need a private-public key pair to register your service in SNET. Generate them in Metamask before you start this tutorial.
Run this tutorial from a bash terminal.
We'll use C++ gRPC, for more details see https://grpc.io/docs/
In this tutorial we'll create a C++ service and publish it in SingularityNET.
Setup and run a docker container. We'll install C++ gRPC stuff in a container because of this warning from the authors:
"WARNING: After installing with make install there is no easy way to uninstall,
which can cause issues if you later want to remove the grpc and/or protobuf
installation or upgrade to a newer version."
In this tutorial we'll develop our service inside the docker container.
Setup a ubuntu:18.04 docker container using provided Dockerfile.
$ docker build --build-arg language=cpp -t snet_cpp_service https://github.com/singnet/wiki.git#master:/tutorials/Docker
$ docker run -p 7000:7000 -ti snet_cpp_service bash
From this point we follow the tutorial in the Docker container's prompt.
# cd wiki/tutorials/howToWriteCPPService
Create the skeleton structure for your service's project
# ./create_project.sh PROJECT_NAME ORGANIZATION_NAME SERVICE_NAME SERVICE_PORT
PROJECT_NAME is a short tag for your project. It will be used to name
project's directory and as a namespace tag in the .proto file.
ORGANIZATION_NAME is the name of an organization that you are a member or owner.
SERVICE_NAME is the name of your service.
SERVICE_PORT is the port number (in localhost) the service will listen to.
create_project.sh will create a directory named PROJECT_NAME with a basic
empty implementation of the service.
In this tutorial we'll implement a service with two methods:
- int div(int a, int b)
- string check(int a)
So we'll use this command line to create project's skeleton
# ./create_project.sh tutorial snet math-operations 7070
# cd tutorial
Now we'll customize the skeleton code to actually implement our basic service.
We need to edit src/service_spec/tutorial.proto and define
- the data structures used to carry input and output of the methods, and
- the RPC API of the service.
Take a look at https://developers.google.com/protocol-buffers/docs/overview to
understand everything you can do in the .proto file.
In this tutorial our src/service_spec/tutorial.proto will be like this:
syntax = "proto3";
package tutorial;
message IntPair {
int32 a = 1;
int32 b = 2;
}
message SingleInt {
int32 v = 1;
}
message SingleString {
string s = 1;
}
service ServiceDefinition {
rpc div(IntPair) returns (SingleInt) {}
rpc check(SingleInt) returns (SingleString) {}
}Each message statement define a data structure used either as input or output
in the API. The service statement defines the RPC API itself.
In order to actually implement our API we need to edit src/server.cc.
Look for PROTO_TYPES and replace the using statements to reflect our data
types defined in step 3.
using tutorial::ServiceDefinition;
using tutorial::IntPair;
using tutorial::SingleInt;
using tutorial::SingleString;Now look for SERVICE_API and replace doSomething() by our actual API methods:
Status div(ServerContext* context, const IntPair* input, SingleInt* output) override {
output->set_v(input->a() / input->b());
return Status::OK;
}
Status check(ServerContext* context, const SingleInt* input, SingleString* output) override {
if (input->v() != 0) {
output->set_s("OK");
} else {
output->set_s("NOK");
}
return Status::OK;
}Now we'll write a client to test our server locally (without using the
blockchain). Edit src/client.cc.
Look for PROTO_TYPES and replace the using statements to reflect our data
types defined in Step 3.
using tutorial::ServiceDefinition;
using tutorial::IntPair;
using tutorial::SingleInt;
using tutorial::SingleString;Now look for TEST_CODE and replace doSomething() implementation by our
testing code:
void doSomething(int argc, char** argv) {
int n1 = atoi(argv[1]);
int n2 = atoi(argv[2]);
ClientContext context1;
SingleInt divisor;
SingleString checkDivisor;
divisor.set_v(n2);
Status status1 = stub_->check(&context1, divisor, &checkDivisor);
if (! status1.ok()) {
std::cout << "doSomething rpc failed." << std::endl;
return;
}
if (checkDivisor.s() != "OK") {
std::cout << "Check failed." << std::endl;
return;
}
ClientContext context2;
IntPair input;
SingleInt result;
input.set_a(n1);
input.set_b(n2);
Status status2 = stub_->div(&context2, input, &result);
if (status2.ok()) {
std::cout << result.v() << std::endl;
} else {
std::cout << "doSomething rpc failed." << std::endl;
}
}To build the service:
# ./build.sh
At this point you should have server and client in bin/
To test our server locally (without using the blockchain)
# ./bin/server &
# ./bin/client 12 4
You should have something like the following output:
root@1eee79873d63:~/install/tutorial# ./bin/server &
[1] 4217
root@1eee79873d63:~/install/tutorial# Server listening on 0.0.0.0:7070
./bin/client 12 4
3
At this point you have successfully built a gRPC C++ service. The executables
in bin/ can be used from anywhere inside the container (they don't need
anything from the installation directory) or outside the container if you have
C++ gRPC libraries installed.
The next steps in this tutorial will publish the service in SingularityNET.
Now you must follow the howToPublishService tutorial to publish this service or use our script (next step).
You'll also need a SNET CLI identity (check step 3 from howToPublishService).
First, make sure you killed the server process started in Step 7.
Then publish and start your service:
# ./publishAndStartService.sh PAYMENT_ADDRESS
Replace PAYMENT_ADDRESS by your public key (wallet).
Example:
# ./publishAndStartService.sh 0xA6E06cF37110930D2906e6Ae70bA6224eDED917B
This will start the SNET Daemon and your service. If everything goes well you will
see the blockchain transaction logs and then the following messages
(respectively from: your service and SNET Daemon):
[blockchain log]
Server listening on 0.0.0.0:7070
[daemon initial log]
INFO[0002] Blockchain is enabled: instantiate payment validation interceptor
INFO[0002] PaymentChannelStorageClient="&{ConnectionTimeout:5s RequestTimeout:3s Endpoints:[http://127.0.0.1:2379]}"
INFO[0002] Default payment handler registered defaultPaymentType=escrow
DEBU[0002] starting daemon
You can double check if it has been properly published using
# snet organization list-services snet
Optionally you can un-publish the service
# snet service delete snet math-operations
Actually, since this is just a tutorial, you are expected to un-publish your service as soon as you finish the tests.
Other snet commands and options (as well as their documentation) can be found
here.
You can test your service making requests in command line:
The testServiceRequest.sh script is set to use channel id 0, if your
SNET CLI identity already had opened previous channels, you'll have to
set channel id manually at.
# ./testServiceRequest.sh 12 4
[blockchain log]
response:
v: 3
That's it. Remember to delete your service as explained in Step 9.
# snet service delete snet math-operations