Module: Lightning

Defined in:
lib/lightning/node.rb,
lib/lightning/stub.rb,
lib/lightning/config.rb,
lib/lightning/version.rb,
lib/lightning/channels.rb,
lib/lightning/invoices.rb

Overview

Namespace for classes and modules that handle communication with your LND node

Defined Under Namespace

Classes: Configuration

Constant Summary collapse

VERSION =

Current SDK version number.

'0.1.1'.freeze

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.configuration ⇒ Object

Returns the value of attribute configuration



4
5
6
 
# File 'lib/lightning/config.rb', line 4

def configuration
  @configuration
end

Class Method Details

.addinvoice(**args) ⇒ Lnrpc::AddInvoiceResponse

Add a new invoice, expressing intent for a future payment. Invoices without an amount can be created by not supplying any parameters or providing an amount of 0. These invoices allow the payee to specify the amount of satoshis they wish to send.

Examples:

Create a new invoice

Lightning.addinvoice(value: 500, memo: '1x Cappuccino')

Parameters:

  • args (Hash) —

    a customizable set of options

Options Hash (**args):

  • :value (Integer) — default: 0 —

    Amount in satoshis

  • :expiry (Integer) — default: 3600 —

    Payment request expiry time in seconds.

  • :memo (String) — default: '' —

    An optional memo to attach along with the invoice. Used for record keeping purposes for the invoices creator, and will also be set in the description field of the encoded payment request if the description_hash field is not being used.

Returns:

  • (Lnrpc::AddInvoiceResponse)

Since:

  • 0.1.0



26
27
28
29
30
31
32
33
 
# File 'lib/lightning/invoices.rb', line 26

def addinvoice(**args)
  stub.add_invoice(
    Lnrpc::Invoice.new(
      value: args[:value], expiry: args[:expiry],
      memo: args[:memo]
    )
  )
end

.closedchannels(**args) ⇒ Lnrpc::ClosedChannelsResponse

Closedchannels returns a description of all the closed channels that this node was a participant in.

Examples:

Receive a list of closed channels

Lightning.closedchannels

Receive a list of closed channels

Lightning.closedchannels

Parameters:

  • args (Hash) —

    a customizable set of options

Options Hash (**args):

  • :cooperative (Boolean) — default: false
  • :local_force (Boolean) — default: false
  • :remote_force (Boolean) — default: false
  • :breach (Boolean) — default: false
  • :funding_canceled (Boolean) — default: false
  • :abandoned (Boolean) — default: false

Returns:

  • (Lnrpc::ClosedChannelsResponse)

Since:

  • 0.1.1



22
23
24
25
26
27
28
29
30
 
# File 'lib/lightning/channels.rb', line 22

def closedchannels(**args)
  stub.closed_channels(
    Lnrpc::ClosedChannelsRequest.new(
      cooperative: args[:cooperative], local_force: args[:local_force],
      remote_force: args[:remote_force], breach: args[:breach],
      funding_canceled: args[:funding_canceled], abandoned: args[:abandoned]
    )
  )
end

.configure {|configuration| ... } ⇒ Object

The configure class method stores a Configuration object inside the Lightning module. Anything set from the configure block is an attr_accessor on the Configuration class.

Examples:

Configure your application

Lightning.configure do |config|
  config.grcp_host = '127.0.0.1'
  config.grcp_port = '10009'
  config.macaroon_path = '~/.lnd/data/chain/bitcoin/mainnet/admin.macaroon'
  config.certificate_path = '~/.lnd/tls.cert'
end

Yields:

Since:

  • 0.1.1



20
21
22
23
 
# File 'lib/lightning/config.rb', line 20

def self.configure
  self.configuration ||= Configuration.new
  yield(configuration)
end

.decodepayreq(pay_req) ⇒ Lnrpc::PayReq

Decodepayreq takes an encoded payment request string and attempts to decode it, returning a full description of the conditions encoded within the payment request.

Examples:

Decode a payment request

Lightning.decodepayreq("lnbc5u1pwt0...qxht38d")

Parameters:

  • pay_req (String) —

    The payment request string to be decoded

Returns:

  • (Lnrpc::PayReq)

Since:

  • 0.1.0



46
47
48
49
 
# File 'lib/lightning/invoices.rb', line 46

def decodepayreq(pay_req)
  opts = { pay_req: pay_req }
  stub.decode_pay_req(Lnrpc::PayReqString.new(opts))
end

.getinfo ⇒ Lnrpc::GetInfoResponse

Returns general information concerning the lightning node including it's identity pubkey, alias, the chains it is connected to, and information concerning the number of open+pending channels.

Examples:

Receive node info

Lightning.getinfo

Returns:

  • (Lnrpc::GetInfoResponse)

Since:

  • 0.1.0



13
14
15
 
# File 'lib/lightning/node.rb', line 13

def getinfo
  stub.get_info(Lnrpc::GetInfoRequest.new)
end

.getnetworkinfo ⇒ Lnrpc::NetworkInfo

Getnetworkinfo returns some basic stats about the known channel graph from the point of view of the node.

Examples:

Get network info

Lightning.getnetworkinfo

Returns:

  • (Lnrpc::NetworkInfo)

Since:

  • 0.1.1



25
26
27
28
29
 
# File 'lib/lightning/node.rb', line 25

def getnetworkinfo
  stub.get_network_info(
    Lnrpc::NetworkInfoRequest.new
  )
end

.getnodeinfo(pubkey) ⇒ Lnrpc::NodeInfo

Getnodeinfo returns the latest advertised, aggregated, and authenticated channel information for the specified node identified by its public key.

Examples:

Get node information from a pubkey

Lightning.getnodeinfo("030c3...c14f")

Parameters:

  • The (String) —

    public key of the node you want get info from

Returns:

  • (Lnrpc::NodeInfo)

Since:

  • 0.1.1



40
41
42
43
44
 
# File 'lib/lightning/node.rb', line 40

def getnodeinfo(pubkey)
  stub.get_node_info(
    Lnrpc::NodeInfoRequest.new(pub_key: pubkey)
  )
end

.listchannels(**args) ⇒ Lnrpc::ListChannelsResponse

Listchannels returns a description of all the open channels that this node is a participant in.

Examples:

Receive a list of open channels

Lightning.listchannels

Parameters:

  • args (Hash) —

    a customizable set of options

Options Hash (**args):

  • :active_only (Boolean) — default: false
  • :inactive_only (Boolean) — default: false
  • :public_only (Boolean) — default: false
  • :private_only (Boolean) — default: false

Returns:

  • (Lnrpc::ListChannelsResponse)

Since:

  • 0.1.1



45
46
47
48
49
50
51
52
 
# File 'lib/lightning/channels.rb', line 45

def listchannels(**args)
  stub.list_channels(
    Lnrpc::ListChannelsRequest.new(
      active_only: args[:active_only], inactive_only: args[:inactive_only],
      public_only: args[:public_only], private_only: args[:private_only]
    )
  )
end

.listinvoices(**args) ⇒ Lnrpc::ListInvoiceResponse

Listinvoices the retrieval of all invoices currently stored within the database. It has full support for paginationed responses, allowing users to query for specific invoices through their add_index. This can be done by using either the first_index_offset or last_index_offset fields included in the response as the index_offset of the next request. The reversed flag is set by default in order to paginate backwards. If you wish to paginate forwards, you must explicitly set the flag to false. If none of the parameters are specified, then the last 100 invoices will be returned. For example: if you have 200 invoices, “listinvoices” will return the last 100 created. If you wish to retrieve the previous 100, the first_offset_index of the response can be used as the index_offset of the next listinvoices request.

Examples:

List all invoices

Lightning.listinvoices

Parameters:

  • args (Hash) —

    a customizable set of options

Options Hash (**args):

  • :num_max_invoices (Integer) — default: 100 —

    The max number of invoices to return in the response to this query.

  • :index_offset (Integer) — default: 0 —

    The index of an invoice that will be used as either the start or end of a query to determine which invoices should be returned in the response.

  • :pending_only (Boolean) — default: false —

    If set, only unsettled invoices will be returned in the response.

  • :reversed (Boolean) — default: false —

    If set, the invoices returned will result from seeking backwards from the specified index offset. This can be used to paginate backwards.

Returns:

  • (Lnrpc::ListInvoiceResponse)

Since:

  • 0.1.0



84
85
86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/lightning/invoices.rb', line 84

def listinvoices(**args)
  num_max_invoices = args[:num_max_invoices]
  index_offset = args[:index_offset]
  pending_only = args[:pending_only]
  reversed = args[:reversed]

  stub.list_invoices(
    Lnrpc::ListInvoiceRequest.new(
      num_max_invoices: num_max_invoices, index_offset: index_offset,
      pending_only: pending_only, reversed: reversed
    )
  )
end

.pendingchannels ⇒ Lnrpc::PendingChannelsResponse

Pendingchannels returns a list of all the channels that are currently considered “pending”. A channel is pending if it has finished the funding workflow and is waiting for confirmations for the funding txn, or is in the process of closure, either initiated cooperatively or non- cooperatively.

Examples:

Receive a list of pending channels

Lightning.pendingchannels

Returns:

  • (Lnrpc::PendingChannelsResponse)

Since:

  • 0.1.1



65
66
67
68
69
 
# File 'lib/lightning/channels.rb', line 65

def pendingchannels
  stub.pending_channels(
    Lnrpc::PendingChannelsRequest.new
  )
end

.subscribeinvoices(**args) ⇒ Array<Lnrpc::Invoice>

Subscribeinvoices returns a uni-directional stream (server -> client) for notifying the client of newly added/settled invoices. The caller can optionally specify the add_index and/or the settle_index. If the add_index is specified, then we'll first start by sending add invoice events for all invoices with an add_index greater than the specified value. If the settle_index is specified, the next, we'll send out all settle events for invoices with a settle_index greater than the specified value. One or both of these fields can be set. If no fields are set, then we'll only send out the latest add/settle events.

Parameters:

  • args (Hash) —

    a customizable set of options

Options Hash (**args):

  • :add_index (Integer) — default: 0 —

    If specified (non-zero), then we'll first start by sending out notifications for all added indexes with an add_index greater than this value. This allows callers to catch up on any events they missed while they weren't connected to the streaming RPC.

  • :settle_index (Integer) — default: 0 —

    If specified (non-zero), then we'll first start by sending out notifications for all settled indexes with an settle_index greater than this value. This allows callers to catch up on any events they missed while they weren't connected to the streaming RPC.

Returns:

  • (Array<Lnrpc::Invoice>) —

    • stream

Since:

  • 0.1.1



122
123
124
125
126
127
128
129
130
131
 
# File 'lib/lightning/invoices.rb', line 122

def subscribeinvoices(**args)
  stub.subscribe_invoices(
    Lnrpc::InvoiceSubscription.new(
      add_index: args[:add_index],
      settle_index: args[:settle_index]
    )
  ) do |invoice|
    yield(invoice)
  end
end