From 188e4d4bec76e8c2fec3d5c755db650cc694694a Mon Sep 17 00:00:00 2001
From: Tim Akinbo <takinbo@gmail.com>
Date: Wed, 1 Mar 2017 00:49:10 +0100
Subject: [PATCH] docs/grpc: added instructions for writing gRPC clients in
 Python

This commit adds a basic set of instructions for installing the necessary
gRPC dependencies to be able to drive `lnd` using Python. In the future,
this section will be expanded with additional example
scripts/applications.
---
 docs/grpc/python.md | 50 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)
 create mode 100644 docs/grpc/python.md

diff --git a/docs/grpc/python.md b/docs/grpc/python.md
new file mode 100644
index 00000000..a3faaa91
--- /dev/null
+++ b/docs/grpc/python.md
@@ -0,0 +1,50 @@
+# How to write a Python gRPC client for the Lightning Network Daemon #
+
+This section enumerates what you need to do to write a client that communicates with lnd in Python.
+
+Lnd uses the gRPC protocol for communication with clients like lncli. gRPC is based on protocol buffers
+and as such, you will need to compile the lnd proto file in Python before you can use it to communicate with
+lnd. The following are the steps to take.
+
+* Create a virtual environment for your project
+```
+$ virtualenv lnd
+```
+* Activate the virtual environment
+```
+$ source lnd/bin/activate
+```
+* Install dependencies (googleapis-common-protos is required due to the use of google/api/annotations.proto)
+```
+(lnd)$ pip install grpcio grpcio-tools googleapis-common-protos
+```
+* Clone the google api's repository (required due to the use of google/api/annotations.proto)
+```
+(lnd)$ git clone https://github.com/googleapis/googleapis.git
+```
+* Copy the lnd rpc.proto file (you'll find this in lnrpc/rpc.proto) or just download it
+```
+(lnd)$ curl -o rpc.proto -s https://raw.githubusercontent.com/lightningnetwork/lnd/master/lnrpc/rpc.proto
+```
+* Compile the proto file
+```
+(lnd)$ python -m grpc_tools.protoc --proto_path=googleapis:. --python_out=. --grpc_python_out=. rpc.proto
+```
+
+After following these steps, two files `rpc_pb2.py` and `rpc_pb2_grpc.py` will be generated. These files will be
+imported in your project while writing your clients. Here's an example of a simple client that was built using these.
+
+```
+# python-based lnd client to retrieve and display wallet balance
+
+import grpc
+
+import rpc_pb2 as ln
+import rpc_pb2_grpc as lnrpc
+
+channel = grpc.insecure_channel('localhost:10009')
+stub = lnrpc.LightningStub(channel)
+
+response = stub.WalletBalance(ln.WalletBalanceRequest(witness_only=True))
+print(response.balance)
+```