# Create invoices from the command line using Python and Polar ###### tags: `workshops_mln` This is a workshop to create a lightning app to create bolt11 invoices from the console using an LND node **Table of Contents** [TOC] ## Author Twitter for corrections, comments or suggestions: [@bitao36](https://twitter.com/bitao36) This tutorial was prepared for the [Mastering Lightning Socratic Seminar](https://libreriadesatoshi.com/) through [@libreriadesatoshi](https://twitter.com/libdesatoshi). ## Requirements :information_source: :::info Have Linux installed Have Polar installed Having created a network in Polar with two nodes, one of them LND Have Python 3.10 installed ::: ## Lightning Polar Lightning Polar (hereinafter Polar) is an application that allows you to quickly create a local network of lightning nodes. [Polar Workshop](/cutFDwM_TNaz-4GcDBXHCA) ## Connection to the LND node As seen in previous classes, connections can be made to an LND node using REST, however in this case we will do it using gRPC, which is the most used way. ### What is gGRPC gRPC (gRPC Remote Procedure Call) is an open source framework developed by Google to facilitate remote communication between distributed services. It uses HTTP/2 for transport, Protocol Buffers (protobufs) for message serialization and can operate in many programming languages. Here I explain how the connection works on the client side and the server side: #### Stubs and Skeletons Client Stub: On the client side, gRPC generates stubs from the service definitions in the .proto file. Stubs allow the client to call server methods as if they were local methods. Server Skeleton: On the server side, gRPC generates skeletons that deserialize incoming requests, call the corresponding methods on the server, and serialize the responses back to the client. ### gRPC access to LND node gRPC Stub Generation Use the grpc_tools.protoc file to generate stubs in your preferred programming language. The LND proto files can be found in the official LND repository on GitHub. In the repository that you will use later, the necessary files to generate invoices are already generated, however here are the commands to generate them. With the following commands we will generate the necessary files for the gRPC client in Python that will help us generate bolt11 invoices. ``` $sudo apt-get install python3-dev $python3 -m venv lndproto $source lndproto/bin/activate $pip3 install grpcio grpcio-tools googleapis-common-protos mypy-protobuf $git clone https://github.com/googleapis/googleapis.git $curl -o lightning.proto -s https://raw.githubusercontent.com/lightningnetwork/lnd/master/lnrpc/lightning.proto python -m grpc_tools.protoc --proto_path=googleapis:. --mypy_out=. --python_out=. --grpc_python_out=. lightning.proto ``` After following these steps these three files are generated: ```lightning_pb2.py, lightning_pb2_grpc.py and lightning_pb2.pyi ``` If other LND subsystems are required, such as router or invoice status, similar commands are used, changing the name of the .proto files. For the router subsystem: ``` curl -o router.proto -s https://raw.githubusercontent.com/lightningnetwork/lnd/master/lnrpc/routerrpc/router.proto python3 -m grpc_tools.protoc --proto_path=googleapis:. --mypy_out=. --python_out=. --grpc_python_out=. router.proto ``` After following these steps these three files are generated: router_pb2.py, router_pb2_grpc.py and router_pb2.pyi For the invoices subsystem: ``` curl -o invoices.proto -s https://raw.githubusercontent.com/lightningnetwork/lnd/master/lnrpc/invoicesrpc/invoices.proto python3 -m grpc_tools.protoc --proto_path=googleapis:. --mypy_out=. --python_out=. --grpc_python_out=. invoices.proto ``` After following these steps these three files are generated: ``` invoices_pb2_grpc.py, invoices_pb2.py, invoices_pb2.pyi ``` ### TLS Authentication and Macaroons LND uses TLS certificates and macaroons for authentication. You will need to upload the TLS certificate and the appropriate macaroon to make authenticated calls. ### But what is a macaroon? Macaroons are portable tokens that can be used to control access to protected resources. They differ from other authentication tokens in that they can be restricted with additional conditions called caveats. These restrictions allow fine granularity in authorization, without the need to modify the server. #### Creation of the Macaroon: When an LND node starts up, it generates several predefined macaroons for different purposes (admin.macaroon, invoice.macaroon, readonly.macaroon). These macaroons contain a series of identifiers and an HMAC (Hash-based Message Authentication Code) signature that guarantees their integrity. #### Restrictions or Caveats: Macaroons can be restricted with additional conditions, known as caveats. For example, a macaroon can be limited to only be valid for a certain time, or to only allow access to certain API methods. Caveats can be of two types: * First-party caveats: Restrict the macaroon so that the same server that created the macaroon can verify it. * Third-party caveats: Require an external authority for verification. #### Macaroon Verification: When a client sends a macaroon with a request to the LND API, the server verifies the signature of the macaroon and any caveats present. If the signature is valid and all caveats are met, the server allows access to the requested resources. ## Run project in Python We will use a project that already has a base component configured to create the connection to an LND node using gRPC. When executing the project, the amount of satoshis with which you want to create the invoice is requested with an optional description. If the amount is an integer greater than zero, the bolt11 invoice is created, otherwise you are asked to enter the amount of satoshis again. 1. Clone github project: ``` git clone https://github.com/bitao36/pylapp.git ``` 1. Create virtual environment: ```$ python3 -m venv venv ``` 1. Activate virtual environment: ```$ source venv/bin/activate ``` 1. Install dependencies: ```$ pip3 install -r requirements.txt``` 1. Run Polar 1. Create a network with at least two nodes, one of them LND 1. Get cert file and macaroons from LND node and copy them to credentials folder of cloned project 1. Run project ```$ python3 app.py``` ## Test project Enter the amount in sats and an optional description. If everything went well, an invoice bolt11 is printed in the console. You can decode it to verify the information with the following program to decode invoices https://lndecode.com/ Now you can go to Polar and pay in invoice with a node other than the one that generated the invoice.