What are macaroon files in LND

In this post we will review what are the macaroon files used in the implementation of Lightning Network LND and what is its operation. We will implement the use of a remote invoice.macaroon file that will allow us to perform certain operations on the invoices by creating and paying an invoice of 1 satoshi.

What are the macaroon files?

The macaroon files are a kind of cookie used by the lncli client and the lnd server to verify that you have the right to carry out certain operations on a Lightning Network node. When the files are generated, the service searches for the macaroon ID and verifies that the file was initially signed with the root code of the service. One of the special features of the macaroon files is that you can generate files with limited capabilities on the node such as generate invoices and share it with someone else.

By default when the lnd service is started, 3 macaroon files are created, which are the admin.macaroon, the readonly.macaroon and the invoice.macaroon. As its name implies, the readonly allows only execute read-only commands, the invoice only commands related to the invoices and the admin allows the complete management of the node.

What are these files for?

Lnd allows to execute default RPC methods by exposing a REST service and uses the macaroon for validation and authentication. It must be taken into account that if lnd is executed with the -no-macaroons option, the server will not take into account any validation call. To check its operation we must use a GRPC client that access the rest of the LND service through https. Since the macaroon files are encoded as a hexadecimal string, it must be sent in said format to achieve the connection. For this case we have collaborated with @jochemin owner of https://bitcoineando.es/ to access your node remotely using the invoice.macaroon file that he has shared with us. Then we have obtained the hexa string of the file using the xxd command referred to in the documentation of the following repository.

In order to implement the use of this functionality we have cloned the repository located at https://github.com/robclark56/lightningtip-PHP modifying the connection string to access its node.

To verify that we have correctly encoded the hexadecimal string of the invoice file of the remote node, we must execute from the console a call to the server using CURL. Executing this command allows us to access the API and call the getinfo method.

As the file invoke macaroon does not give us permission to execute the getinfo command we get this output:

However when calling the invoices method it lists all the invoices: (we have hidden some strings and the public IP address).

Later we have modified the file lightningTip.php to change the visualization like this:

Now we are ready to create a invoice in jochemin’s node and pay it in this link

It is appreciated that we have created an invoice with description «prueba» and we have paid for it. Consulting the invoice after this we see that it has been created and paid correctly in the remote node.

With these steps we can use one of the functionalities of the macaroon files to create and pay invoices of any LND Node that has shared its file with us.