Skip to content

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/

user password
admin Ng3c35qsRHxyadDk3LM

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.

getBalance

Gets the current balance of an account.

getBlockHeight

Gets the number of blocks in the chain. It can be passed a flag to return the next block index.

getDelegate

Gets the address of the delegate of an account.

getVotingPower

Gets either the actual or the active voting power. - Active voting power includes delegate voting power. - Actual voting power excludes delegate voting power.

[not yet implemented] getAccountBlockCount

Gets the count of all blocks sent by an account.

[not yet implemented] getGlobalBlockCount

Gets the count of all blocks by all accounts.

[not yet implemented] getGlobalTransactionCount

Gets the count of all transactions in the network.

[not yet implemented] getPendingBlocks

Gets all the blocks that are not validated yet.

[not yet implemented] getUnacknowledgedTransactions

Gets transactions without a counterpart receive.

getBlockByID

Gets the block based on its ID.

getBlockByHeight

Gets the block using its index in the chain.

getTransactionByID

Gets a transaction using its ID.

[not yet implemented] getTransactions

Gets all the transactions before a certain transactions with a limit.

[not yet implemented] sendBlock

Sends a block into the network.

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.

[not yet implemented] getWallets

Gets all accounts on a node.

[not yet implemented] getWallet

Gets an account using a address on a node.

[not yet implemented] addWallet

Creates a wallet for a user using a password.

[not yet implemented] removeWallet

Deletes a wallet from the node.

[not yet implemented] signMessage

Signs the message given using the wallets private key stored on the node.

[not yet implemented] signBlock

Signs the block given using the wallets private key stored on the node.

[not yet implemented] verifySignature

Verifies the signature of a message.

[not yet implemented] encryptMessage

Encrypts a message using the recipients public key.

[not yet implemented] decryptMessage

Decrypts a message using the wallets private key stored on the node.

Node Admin Service

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

[not yet implemented] getPeers

Gets a list of all the nodes that this node is directly connected to.

getVersion

Gets the nodes version.

[not yet implemented] upgradeNode

Updates the nodes software.

[not yet implemented] getPendingBlocks

Gets all the blocks that are not validated yet.

getPendingBlockCount

Gets the count of unvalidated blocks.

[not yet implemented] setPendingBlockLimit

Sets a limit to the amount of blocks that are unvalidated.

[not yet implemented] getNodeStatus

Gets the status of the node.

[not yet implemented] getMode

Gets the mode of the node.

[not yet implemented] setMode

Sets the mode of the node.

getNodeName

Gets the name of the node.

setNodeName

Sets the name of the node.

[not yet implemented] getChain

Gets chain name. For example MainNet, testNet etc.

[not yet implemented] getLogs

Gets the node logs.