Lightning APIs for Grails V 0.5.2-Beta, 2019-02-07

Introduction

Grails 3.3.x Plugin to integrate LightningJ into a Grails application.

For more information on LightningJ project see https://www.lightningj.org

More information and source code can be found on the Github site. There it is possible to report issues and contribute code.

If you want updates on this project, follow https://twitter.com/LightningJ_org on twitter.

Important: This API is still in beta and API methods might change before real production release.
All use of this library is on your own risk.

License

This library is Open Source and released under the LGPL v3 License. A link to the license agreement can be found here.

Whats New

  • 0.5.2-Beta : Updated with 0.5.2-Beta version of LightningJ

  • 0.5.0-Beta : Updated with 0.5.0-Beta version of LightningJ

  • 0.5.0-Beta-rc2 : Updated with 0.5.0-Beta-rc2 version of LightningJ

  • 0.5.0-Beta-rc1 : Updated with 0.5.0-Beta-rc1 version of LightningJ

  • 0.4.2-Beta-2 : Updated with 0.4.2-Beta-2 version of LightningJ

  • 0.4.2-Beta : Updated with 0.4.2 version of LightningJ

  • 0.4.1-Beta : Updated with 0.4.1 version of LightningJ

  • 0.3-Beta : This is the initial release with LndService and Controller enhancements.

Roadmap

  • Create example application showing how to integrate lightning calls inside your web application.

  • Support asynchronous feedback to browser.

Using LightningJ-Grails Library

Step 1 Add Plugin to build.gradle

In the dependencies section add:

    compile "org.lightningj:lightningj-grails:0.5.2-Beta"

All tags and releases is signed with bintrays internal GPG keys due to lack of support of SmartCard Signing in the grails plugin publishing process.

Step 2 Add LND Configuration

In application.yml add configuration to initialize the LND Service APIs

# LightingJ Grails configuration
lightningj:
    lnd:
        host: localhost
        port: 20001
        trustedcert: "~/Library/Application Support/Lnd/tls.cert"
        macaroon: "~/Library/Application Support/Lnd/admin.macaroon"

The host, port and trustedcert settings are mandatory and macaroon might be omitted if LND is run in --nomacaroons mode.

If more advanced configuration is needed it is possible to initialize LND APIs using a custom GRPC ManagedChannel, but this have to be done before any LND API calls. For instance in BootStrap.groovy. To manually initialize the APIs call the lndService.init(..) method and in that case is no settings in application.yml required.

Step 3 Inject the LND Service

In your artifacts (controller, services, etc) will LndService be injected automatically. See example below on how to access the different APIs.

    class InvoiceController {

        LndService lndService

        def index() {
           // To make a synchronous call use lndService.sync.<method>
           lndService.sync.walletBalance()

           // To make a asynchronous call use lndService.async.<method>
           lndService.async.walletBalance(new StreamObserver<WalletBalanceResponse>() {
                       @Override
                       void onNext(WalletBalanceResponse value) {
                       }

                       @Override
                       void onError(Throwable t) {
                       }

                       @Override
                       void onCompleted() {
                       }
            })

            // To access the wallet APIs use lndService.wallet.sync.<method> and lndService.wallet.async.<method>

        }

Important remember to add some form of authorization mechanism since the code above will make calls to LND anonymous.

For more details on how to use the APIs see https://www.lightningj.org and the library’s JavaDoc

Controller Enhancements

The plugin enhances all controllers with two help methods to simplify the conversion between JSON and or XML and wrapped LND GRPC Messages.

The first method are 'asMessage(Class messageType)' that automatically parses request data into LND message depending on the content negotiation done by the client, i.e the contentType sent in the request.

The second method is a render(Message message) method that renders the wrapped LND message into content negotiated format (XML or JSON). Either by the client specifying the content type in the 'Accept' header or by ending the controller url with '.json' or '.xml'.

Supported contentTypes in request and responses are 'application/json', 'text/json', 'application/xml' and 'text/xml'.

Here is an example of a controller using the extra methods:

    class InvoiceController {

        LndService lndService

        def index() {
           // asMessage converts from XML or JSON to wrapped LND Message
           Invoice invoice = asMessage Invoice
           // Call LND using the sync API
           AddInvoiceResponse response = lndService.sync.addInvoice(invoice)
           // Render the response back to JSON or XML
           render response
        }

    }

Building the Plugin

To build from source clone the repository and use gradlew to build.

git clone https://github.com/lightningj-org/lightningj-grails.git
cd lightningj-grails
./gradlew install

The generated plugin can now be used in your project by using mavenLocal.