Skip to main content

RPC

Oasis Node exposes an RPC interface to enable external applications to query current consensus and runtime states, submit transactions, etc.

The RPC interface is ONLY exposed via an AF_LOCAL socket called internal.sock located in the node's data directory. This interface should NEVER be directly exposed over the network as it has no authentication and allows full control, including shutdown, of a node.

In order to support remote clients and different protocols (e.g. REST), a gateway that handles things like authentication and rate limiting should be used.

info

An example of such a gateway is the Oasis Core Rosetta Gateway which exposes a subset of the consensus layer via the Rosetta API.

Protocol​

Like other parts of Oasis Core, the RPC interface exposed by Oasis Node uses the gRPC protocol with the CBOR codec (instead of Protocol Buffers). If your application is written in Go, you can use the convenience gRPC wrappers provided by Oasis Core to create clients. Check the Oasis SDK for more information.

For example to create a gRPC client connected to the Oasis Node endpoint exposed by your local node at /path/to/datadir/internal.sock you can do:

import (
    // ...
    oasisGrpc "github.com/oasisprotocol/oasis-core/go/common/grpc"
)

// ...

conn, err := oasisGrpc.Dial("unix:/path/to/datadir/internal.sock")

This will automatically handle setting up the required gRPC dial options for setting up the CBOR codec and error mapping interceptors. For more detail about the gRPC helpers see the API documentation.

Errors​

We use a specific convention to provide more information about the exact error that occurred when processing a gRPC request. See the gRPC specifics section for details.

Services​

We use the same service method namespacing convention as gRPC over Protocol Buffers. All Oasis Core services have unique identifiers starting with oasis-core. followed by the service identifier. A single slash (/) is used as the separator in method names, e.g., /oasis-core.NodeControl/IsSynced.

The following gRPC services are exposed (with links to API documentation):

For more details about what the exposed services do see the respective documentation sections. The Go API also provides gRPC client implementations for all of the services which can be used after establishing a gRPC connection via the internal socket (multiple clients can share the same gRPC connection). For example in case of the consensus service using the connection we established in the previous example:

import (
    // ...
    consensus "github.com/oasisprotocol/oasis-core/go/consensus/api"
)

// ...

cc := consensus.NewConsensusClient(conn)
err := cc.SubmitTx(ctx, &tx)