invoices

Documentation

Index

• Variables
• func DisableLog()
• func UseLogger(logger btclog.Logger)
• type HodlEvent
• type HtlcCancelReason
  • func (r HtlcCancelReason) String() string
• type InvoiceRegistry
  • func NewRegistry(cdb *channeldb.DB, decodeFinalCltvExpiry func(invoice string) (uint32, error), ...) *InvoiceRegistry
  • func (i *InvoiceRegistry) AddDebugInvoice(amt btcutil.Amount, preimage lntypes.Preimage)
  • func (i *InvoiceRegistry) AddInvoice(invoice *channeldb.Invoice, paymentHash lntypes.Hash) (uint64, error)
  • func (i *InvoiceRegistry) CancelInvoice(payHash lntypes.Hash) error
  • func (i *InvoiceRegistry) HodlUnsubscribeAll(subscriber chan<- interface{})
  • func (i *InvoiceRegistry) LookupInvoice(rHash lntypes.Hash) (channeldb.Invoice, uint32, error)
  • func (i *InvoiceRegistry) NotifyExitHopHtlc(rHash lntypes.Hash, amtPaid lnwire.MilliSatoshi, expiry uint32, ...) (*HodlEvent, error)
  • func (i *InvoiceRegistry) SettleHodlInvoice(preimage lntypes.Preimage) error
  • func (i *InvoiceRegistry) Start() error
  • func (i *InvoiceRegistry) Stop()
  • func (i *InvoiceRegistry) SubscribeNotifications(addIndex, settleIndex uint64) *InvoiceSubscription
  • func (i *InvoiceRegistry) SubscribeSingleInvoice(hash lntypes.Hash) *SingleInvoiceSubscription
• type InvoiceSubscription
  • func (i *InvoiceSubscription) Cancel()
• type SingleInvoiceSubscription
  • func (i *SingleInvoiceSubscription) Cancel()

Variables

var (
	// DebugPre is the default debug preimage which is inserted into the
	// invoice registry if the --debughtlc flag is activated on start up.
	// All nodes initialized with the flag active will immediately settle
	// any incoming HTLC whose rHash corresponds with the debug
	// preimage.
	DebugPre, _ = lntypes.MakePreimage(bytes.Repeat([]byte{1}, 32))

	// DebugHash is the hash of the default preimage.
	DebugHash = DebugPre.Hash()
)

var (
	// ErrInvoiceExpiryTooSoon is returned when an invoice is attempted to be
	// accepted or settled with not enough blocks remaining.
	ErrInvoiceExpiryTooSoon = errors.New("invoice expiry too soon")

	// ErrInvoiceAmountTooLow is returned  when an invoice is attempted to be
	// accepted or settled with an amount that is too low.
	ErrInvoiceAmountTooLow = errors.New("paid amount less than invoice amount")
)

Functions

func DisableLog

func DisableLog()

DisableLog disables all library log output. Logging output is disabled by default until UseLogger is called.

func UseLogger

func UseLogger(logger btclog.Logger)

UseLogger uses a specified Logger to output package logging info. This should be used in preference to SetLogWriter if the caller is also using btclog.

Types

type HodlEvent

type HodlEvent struct {
	// Preimage is the htlc preimage. Its value is nil in case of a cancel.
	Preimage *lntypes.Preimage

	// Hash is the htlc hash.
	Hash lntypes.Hash

	// CancelReason specifies the reason why invoice registry decided to
	// cancel the htlc.
	CancelReason HtlcCancelReason
}

HodlEvent describes how an htlc should be resolved. If HodlEvent.Preimage is set, the event indicates a settle event. If Preimage is nil, it is a cancel event.

type HtlcCancelReason

type HtlcCancelReason uint8

HtlcCancelReason defines reasons for which htlcs can be canceled.

const (
	// CancelInvoiceUnknown is returned if the preimage is unknown.
	CancelInvoiceUnknown HtlcCancelReason = iota

	// CancelExpiryTooSoon is returned when the timelock of the htlc
	// does not satisfy the invoice cltv expiry requirement.
	CancelExpiryTooSoon

	// CancelInvoiceCanceled is returned when the invoice is already
	// canceled and can't be paid to anymore.
	CancelInvoiceCanceled

	// CancelAmountTooLow is returned when the amount paid is too low.
	CancelAmountTooLow
)

func (HtlcCancelReason) String

func (r HtlcCancelReason) String() string

String returns a human readable identifier for the cancel reason.

type InvoiceRegistry

type InvoiceRegistry struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

InvoiceRegistry is a central registry of all the outstanding invoices created by the daemon. The registry is a thin wrapper around a map in order to ensure that all updates/reads are thread safe.

func NewRegistry

func NewRegistry(cdb *channeldb.DB, decodeFinalCltvExpiry func(invoice string) (
	uint32, error), finalCltvRejectDelta int32) *InvoiceRegistry

NewRegistry creates a new invoice registry. The invoice registry wraps the persistent on-disk invoice storage with an additional in-memory layer. The in-memory layer is in place such that debug invoices can be added which are volatile yet available system wide within the daemon.

func (*InvoiceRegistry) AddDebugInvoice

func (i *InvoiceRegistry) AddDebugInvoice(amt btcutil.Amount,
	preimage lntypes.Preimage)

AddDebugInvoice adds a debug invoice for the specified amount, identified by the passed preimage. Once this invoice is added, subsystems within the daemon add/forward HTLCs that are able to obtain the proper preimage required for redemption in the case that we're the final destination.

func (*InvoiceRegistry) AddInvoice

func (i *InvoiceRegistry) AddInvoice(invoice *channeldb.Invoice,
	paymentHash lntypes.Hash) (uint64, error)

AddInvoice adds a regular invoice for the specified amount, identified by the passed preimage. Additionally, any memo or receipt data provided will also be stored on-disk. Once this invoice is added, subsystems within the daemon add/forward HTLCs are able to obtain the proper preimage required for redemption in the case that we're the final destination. We also return the addIndex of the newly created invoice which monotonically increases for each new invoice added. A side effect of this function is that it also sets AddIndex on the invoice argument.

func (*InvoiceRegistry) CancelInvoice

func (i *InvoiceRegistry) CancelInvoice(payHash lntypes.Hash) error

CancelInvoice attempts to cancel the invoice corresponding to the passed payment hash.

func (*InvoiceRegistry) HodlUnsubscribeAll

func (i *InvoiceRegistry) HodlUnsubscribeAll(subscriber chan<- interface{})

HodlUnsubscribeAll cancels the subscription.

func (*InvoiceRegistry) LookupInvoice

func (i *InvoiceRegistry) LookupInvoice(rHash lntypes.Hash) (channeldb.Invoice, uint32, error)

LookupInvoice looks up an invoice by its payment hash (R-Hash), if found then we're able to pull the funds pending within an HTLC. We'll also return what the expected min final CLTV delta is, pre-parsed from the payment request. This may be used by callers to determine if an HTLC is well formed according to the cltv delta.

TODO(roasbeef): ignore if settled?

func (*InvoiceRegistry) NotifyExitHopHtlc

func (i *InvoiceRegistry) NotifyExitHopHtlc(rHash lntypes.Hash,
	amtPaid lnwire.MilliSatoshi, expiry uint32, currentHeight int32,
	hodlChan chan<- interface{}) (*HodlEvent, error)

NotifyExitHopHtlc attempts to mark an invoice as settled. If the invoice is a debug invoice, then this method is a noop as debug invoices are never fully settled. The return value describes how the htlc should be resolved.

When the preimage of the invoice is not yet known (hodl invoice), this function moves the invoice to the accepted state. When SettleHoldInvoice is called later, a resolution message will be send back to the caller via the provided hodlChan. Invoice registry sends on this channel what action needs to be taken on the htlc (settle or cancel). The caller needs to ensure that the channel is either buffered or received on from another goroutine to prevent deadlock.

func (*InvoiceRegistry) SettleHodlInvoice

func (i *InvoiceRegistry) SettleHodlInvoice(preimage lntypes.Preimage) error

SettleHodlInvoice sets the preimage of a hodl invoice.

func (*InvoiceRegistry) Start

func (i *InvoiceRegistry) Start() error

Start starts the registry and all goroutines it needs to carry out its task.

func (*InvoiceRegistry) Stop

func (i *InvoiceRegistry) Stop()

Stop signals the registry for a graceful shutdown.

func (*InvoiceRegistry) SubscribeNotifications

func (i *InvoiceRegistry) SubscribeNotifications(addIndex, settleIndex uint64) *InvoiceSubscription

SubscribeNotifications returns an InvoiceSubscription which allows the caller to receive async notifications when any invoices are settled or added. The invoiceIndex parameter is a streaming "checkpoint". We'll start by first sending out all new events with an invoice index _greater_ than this value. Afterwards, we'll send out real-time notifications.

func (*InvoiceRegistry) SubscribeSingleInvoice

func (i *InvoiceRegistry) SubscribeSingleInvoice(
	hash lntypes.Hash) *SingleInvoiceSubscription

SubscribeSingleInvoice returns an SingleInvoiceSubscription which allows the caller to receive async notifications for a specific invoice.

type InvoiceSubscription

type InvoiceSubscription struct {

	// NewInvoices is a channel that we'll use to send all newly created
	// invoices with an invoice index greater than the specified
	// StartingInvoiceIndex field.
	NewInvoices chan *channeldb.Invoice

	// SettledInvoices is a channel that we'll use to send all setted
	// invoices with an invoices index greater than the specified
	// StartingInvoiceIndex field.
	SettledInvoices chan *channeldb.Invoice
	// contains filtered or unexported fields
}

InvoiceSubscription represents an intent to receive updates for newly added or settled invoices. For each newly added invoice, a copy of the invoice will be sent over the NewInvoices channel. Similarly, for each newly settled invoice, a copy of the invoice will be sent over the SettledInvoices channel.

func (*InvoiceSubscription) Cancel

func (i *InvoiceSubscription) Cancel()

Cancel unregisters the InvoiceSubscription, freeing any previously allocated resources.

type SingleInvoiceSubscription

type SingleInvoiceSubscription struct {

	// Updates is a channel that we'll use to send all invoice events for
	// the invoice that is subscribed to.
	Updates chan *channeldb.Invoice
	// contains filtered or unexported fields
}

SingleInvoiceSubscription represents an intent to receive updates for a specific invoice.

func (*SingleInvoiceSubscription) Cancel

func (i *SingleInvoiceSubscription) Cancel()

Cancel unregisters the InvoiceSubscription, freeing any previously allocated resources.