corda/docs/source/tutorial-clientrpc-api.rst

Client RPC API

In this tutorial we will build a simple command line utility that connects to a node and dumps the transaction graph to the standard output. We will then put some simple visualisation on top. For an explanation on how the RPC works see clientrpc.

We start off by connecting to the node itself. For the purposes of the tutorial we will run the Trader demo on some local port and connect to the Buyer side. We will pass in the address as a command line argument. To connect to the node we also need to access the certificates of the node, we will access the node's certificates directory directly.

example-code/src/main/kotlin/com/r3corda/docs/ClientRpcTutorial.kt

Now we can connect to the node itself using a valid RPC login. By default the user user1 is available with password test.

example-code/src/main/kotlin/com/r3corda/docs/ClientRpcTutorial.kt

proxy now exposes the full RPC interface of the node:

../../node/src/main/kotlin/com/r3corda/node/services/messaging/CordaRPCOps.kt

The one we need in order to dump the transaction graph is verifiedTransactions. The type signature tells us that the RPC will return a list of transactions and an Observable stream. This is a general pattern, we query some data and the node will return the current snapshot and future updates done to it.

example-code/src/main/kotlin/com/r3corda/docs/ClientRpcTutorial.kt

The graph will be defined by nodes and edges between them. Each node represents a transaction and edges represent output-input relations. For now let's just print NODE <txhash> for the former and EDGE <txhash> <txhash> for the latter.

example-code/src/main/kotlin/com/r3corda/docs/ClientRpcTutorial.kt

Now we can start the trader demo as per described in running-the-demos:

# Build the demo
./gradlew installDist
# Start the buyer
./build/install/r3prototyping/bin/trader-demo --role=BUYER

In another terminal we can connect to it with our client:

# Connect to localhost:31337
./docs/source/example-code/build/install/docs/source/example-code/bin/client-rpc-tutorial localhost:31337 Print

We should see some NODE-s printed. This is because the buyer self-issues some cash for the demo. Unless we ran the seller before we shouldn't see any EDGE-s because the cash hasn't been spent yet.

In another terminal we can now start the seller:

# Start sellers in a loop
for i in {0..9} ; do ./build/install/r3prototyping/bin/trader-demo --role=SELLER ; done

We should start seeing new NODE-s and EDGE-s appearing.

Now let's try to visualise the transaction graph. We will use a graph drawing library called graphstream

example-code/src/main/kotlin/com/r3corda/docs/ClientRpcTutorial.kt

If we run the client with Visualise we should see a simple graph being drawn as new transactions are being created by the seller runs.

That's it! We saw how to connect to the node and stream data from it.