Skip to content
Talk with a lightningd/c-lightning with minimal overhead and gjson responses.
Go Makefile
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
cmd
plugin
.gitignore
.gitmodules
LICENSE
README.md
client.go
error.go
helpers.go
keys.go
lightning.go
listener.go
payment.go
porcelain.go

README.md

Useful and fast interface for lightningd. All methods return [gjson.Result](https://godoc.org/github.com/tidwall/gjson#Result), which is a good thing (unless your application relies on a lot of information from many different lightningd responses) and you can learn it in 10 seconds.

Since RPC calls are just relayed and wrapped, you can use lightningd-gjson-rpc to call custom RPC methods if your node has a plugin enabled on it.

godoc.org

This is a simple and resistant client. It is made to survive against faulty lightning node interruptions. It can also talk to spark/sparko HTTP-RPC using the same API, so you can run your app and your node on different machines.

Usage

package main

import (
  "github.com/fiatjaf/lightningd-gjson-rpc"
  "github.com/tidwall/gjson"
)

var ln *lightning.Client

func main () {
    lastinvoiceindex := getFromSomewhereOrStartAtZero()

    ln = &lightning.Client{
        Path:             "/home/whatever/.lightning/lightning-rpc",
        LastInvoiceIndex: lastinvoiceindex, // only needed if you're going to listen for invoices
        PaymentHandler:   handleInvoicePaid, // only needed if you're going to listen for invoices
    }
    ln.ListenForInvoices() // optional

    nodeinfo, err := ln.Call("getinfo")
    if err != nil {
        log.Fatal("getinfo error: " + err.Error())
    }

    log.Print(nodeinfo.Get("alias").String())
}

// this is called with the result of `waitanyinvoice`
func handlePaymentReceived(inv gjson.Result) {
    index := inv.Get("pay_index").Int()
    saveSomewhere(index)

    hash := inv.Get("payment_hash").String()
    log.Print("one of our invoices was paid: " + hash)
}

Passing parameters

There are three modes of passing parameters, you can call either:

// 1. `Call` with a list of parameters, in the order defined by each command;
ln.Call("invoice", 1000000, "my-label", "my description", 3600)

// 2. `Call` with a single `map[string]interface{}` with all parameters properly named; or
ln.Call("invoice", map[string]interface{
    "msatoshi": "1000000,
    "label": "my-label",
    "description": "my description",
    "preimage": "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f"
})

// 3. `CallNamed` with a list of keys and values passed in the proper order.
ln.CallNamed("invoice",
    "msatoshi", "1000000,
    "label", "my-label",
    "description", "my description",
    "preimage", "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f",
    "expiry", 3600,
)

Special methods

Besides providing full access to the c-lightning RPC interface with .Call methods, we also have ListenForInvoices and PayAndWaitUntilResolution for making your life better.

It's good to say also that since we don't have hardcoded methods here you can call custom RPC methods with this library.

Plugins

We have a collection of plugins that expose or use our special methods. Read more about them at cmd/ or download binaries at releases/.

Who's using this?

Besides our own plugins listed in the link above, there's also @lntxbot, the Telegram Lightning wallet; Sparko, our better and cheaper alternative to Spark wallet; Etleneum, the centralized smart contract platform; and Lightning Charger, the lnurl-powered BTC-to-Lightning mobile wallet helper.

You can’t perform that action at this time.