gRPC API¶

The following document contains general information and caveats about champ's gRPC API.

If you are interested in the specific message types and parameters, check out pog-proto which contains all proto service definitions and prebuilt libraries for rust, typescript and javascript. An auto-generated API documentation is also available (BlockService, NodeAdminService, NodeUserService, NodeWalletManager).

The gRPC API is exposed (by default) on [::1]:50051. For interactions via websites, grpc-web support is available.

In short, the three different services provided are the Block Service, Node Wallet Manager Service and the Node Admin Service.

Canary Build¶

We provide an automated canary build with all the recent features and Henry Gressmann also hosts this build on his home server for testing.

The test-server is available at:

https://pog-metrics.explodingcamera.com and https://pog-grpc.explodingcamera.com

To try out the grpc api, I've set up our preliminary admin panel here:

https://champ-admin-demo.netlify.app/

Admin interface¶

While the admin interface is not yet ready for primetime, the general login/authentication flow is fully implemented. Instructions for running it locally are available here. Once the webinterface reaches a more stable state, it will be automatically bundled with champ for release builds.

Authentication and Authorization¶

Authentication is done with JSON-Web-Tokens. New users can only created through the champ cli using champ user create.

This is the case since all of our authenticated APIs are essentially for intranet type usage and should not be exposed to the public internet. More on that in our securing your champ node section.

After a new account has been created, NodeUser.Login can be called with your username and password to obtain a jwt. From this endpoint you will recieve your token which you can include in the the authorization metadata field to authenticate your request. For endpoints requiring authentication, the node will then validate your token and check if you have the neccecary permisions. Currently, the following permissions are available and can be configured in your champ.toml config file.

"admin.read"         -> Read-access to the NodeAdmin Service
"admin.write"        -> Write-access to the NodeAdmin Service
"wallet.create"      -> Create a wallet on a node
"wallet.{id}.sign"   -> Write.access to a wallet with {id}
"wallet.{id}.manage" -> Edit.access to a wallet with {id}
"wallet.{id}.unlock" -> Write.access to a wallet with {id}
"superadmin"         -> Access to all

Block Service¶

The Block Service acts as the public interface of a node which external applications that, for example, a user's wallet talks to.

Node Wallet Manager Service¶

The Node Wallet Manager Service enables authorized users to interact with wallets stored on a node. This is especially usefull for integrating services like centralized exchanges and online shops.

Node Admin Service¶

The Node Admin Service provides endpoints for managing and administering a node. It is primarily used by the node admin webinterface.