# 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 Client RPC.

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.

    enum class PrintOrVisualise {
        Print,
        Visualise
    }

    fun main(args: Array<String>) {
        if (args.size < 2) {
            throw IllegalArgumentException("Usage: <binary> <node address> [Print|Visualise]")
        }
        val nodeAddress = HostAndPort.fromString(args[0])
        val printOrVisualise = PrintOrVisualise.valueOf(args[1])
        val certificatesPath = Paths.get("build/trader-demo/buyer/certificates")

Now we can connect to the node itself:

        val client = CordaRPCClient(nodeAddress, certificatesPath)
        client.start()
        val proxy = client.proxy()

`proxy` now exposes the full RPC interface of the node:

        /**
         * Returns a pair of currently in-progress state machine infos and an observable of future state machine adds/removes.
         */
        @RPCReturnsObservables
        fun stateMachinesAndUpdates(): Pair<List<StateMachineInfo>, Observable<StateMachineUpdate>>

        /**
         * Returns a pair of head states in the vault and an observable of future updates to the vault.
         */
        @RPCReturnsObservables
        fun vaultAndUpdates(): Pair<List<StateAndRef<ContractState>>, Observable<Vault.Update>>

        /**
         * Returns a pair of all recorded transactions and an observable of future recorded ones.
         */
        @RPCReturnsObservables
        fun verifiedTransactions(): Pair<List<SignedTransaction>, Observable<SignedTransaction>>

        /**
         * Returns a snapshot list of existing state machine id - recorded transaction hash mappings, and a stream of future
         * such mappings as well.
         */
        @RPCReturnsObservables
        fun stateMachineRecordedTransactionMapping(): Pair<List<StateMachineTransactionMapping>, Observable<StateMachineTransactionMapping>>

        /**
         * Executes the given command, possibly triggering cash creation etc.
         * TODO: The signature of this is weird because it's the remains of an old service call, we should have a call for each command instead.
         */
        fun executeCommand(command: ClientToServiceCommand): TransactionBuildResult

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.

        val (transactions: List<SignedTransaction>, futureTransactions: Observable<SignedTransaction>) = proxy.verifiedTransactions()

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.

        when (printOrVisualise) {
            PrintOrVisualise.Print -> {
                futureTransactions.startWith(transactions).subscribe { transaction ->
                    println("NODE ${transaction.id}")
                    transaction.tx.inputs.forEach { input ->
                        println("EDGE ${input.txhash} ${transaction.id}")
                    }
                }
                CompletableFuture<Unit>().get() // block indefinitely
            }

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

            PrintOrVisualise.Visualise -> {
                val graph = SingleGraph("transactions")
                transactions.forEach { transaction ->
                    graph.addNode<Node>("${transaction.id}")
                }
                transactions.forEach { transaction ->
                    transaction.tx.inputs.forEach { ref ->
                        graph.addEdge<Edge>("$ref", "${ref.txhash}", "${transaction.id}")
                    }
                }
                futureTransactions.subscribe { transaction ->
                    graph.addNode<Node>("${transaction.id}")
                    transaction.tx.inputs.forEach { ref ->
                        graph.addEdge<Edge>("${ref}", "${ref.txhash}", "${transaction.id}")
                    }
                }
                graph.display()
            }
        }
    }

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.