lndart.cln_grpc

🎯 Dart GRPC client for core lightning 🎯

Project Homepage

Table of Content

• Introduction
• How to Use
• How Contribute
• License

Introduction

A dart library which facilitates dart GRPC client for core lightning

Why cln_grpc?

cln_grpc library is a GRPC wrapper with a generic interface which facilitates easy interaction with core lightning for dart and flutter. It can be used to direclty access core lightning node and to perform some operations on it such as calling rpc method supported by the GRPC interface.

How to Use

How to connect to core lightning using cln_grpc

To connect to a grpc server we need port of server, host and server credentials

Here in this library the only required parameter is path to certificates for authentification, and also provides some optional parameters such as

• host("localhost" by default): Where the server is running, this need to match what is declared inside the tls certificate
• port(8001 by default): where the grpc server is running, specified as grpc-port in the core lightning option
• authority("localhost" by default)
• channelcredentials: Options controlling TLS security settings on a ClientChannel.

To initiate the client and make a connection with the server we declare client like this:

var client = GRPCClient(rootPath: "<path_to_certificates>");

How to call a method:

There are several ways to call a method

1. call getinfo with a parse function

  var response = await client.getinfo(onDecode: (Map<String, dynamc> json) => json);
  print('Response from server\n$response');

2. generic call <T, R> with a parse function

Here we need to serialize the request method in order to encode it from json to map

class ListTransactionProxy extends Serializable {
  ListtransactionsRequest proxy;

  ListTransactionProxy(this.proxy);

  factory ListTransactionProxy.build() =>
      ListTransactionProxy(ListtransactionsRequest());

  @override
  Map<String, dynamic> toJSON() => proxy.toProto3Json() as Map<String, dynamic>;

  @override
  T as<T>() => proxy as T;
}

after serializing the request we call the generic "call" method and provide some requires parameters as below

  var transactionList =
      await client.call<ListTransactionProxy, ListtransactionsResponse>(
          method: "listtransactions", params: ListTransactionProxy.build());
  print("Transactions of node");
  print(transactionList.transactions);

3. Direct acces to stub incase a method is not found implemented(skip the library architecture)

  var forwardsList=await client.stub.listForwards(ListforwardsRequest());
  print("forwards of node");
  print(forwardsList.forwards);

Close client connection:

Shutting down the grpc client connection is really easy calling the close method like this:

  client.close();

How Contribute

Build system

You can use the make file to make sure that your code can pass the sanity code check of the CI:

The make file contains the following target:

• make: formatting, analyze and compile the code;
• make fmt: formatting and analyze the code;
• make check: run the unit test (if any)

Read out Hacking guide to find and learn on how we manage the change request (Pull request) workflow.

Generation Code

In order to update the code client from the new proto file generated by core lightning, we need to copy the new file in the proton we need to generate some dart files from the protos, and use the following commands to update the dart code:

Requirements:

• Upgrade protobuf version equal or above release 3.15.
• Add protoc-gen-dart in your path.
• Or else use this command protoc --dart_out=grpc:./lib/src/ --plugin=protoc-gen-dart=$HOME/.pub-cache/bin/protoc-gen-dart ./protos/primitives.proto ./protos/node.proto with plugin flag to generate the .pb.dart files.

Here are the steps to generate .pb.dart files:

• Be on the root of the project.
• Run this command make gen to generate the .pb.dart files for both /primitives.proto and /node.proto.
• Rename ./lib/src/protos to ./lib/src/generated.

License

Copyright 2022 Vincenzo Palazzo <vincenzopalazzodev@gmail.com>. All rights reserved.

Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:

    * Redistributions of source code must retain the above copyright
      notice, this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above
      copyright notice, this list of conditions and the following
      disclaimer in the documentation and/or other materials provided
      with the distribution.
    * Neither the name of Google Inc. nor the names of its
      contributors may be used to endorse or promote products derived
      from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.