invoices

package
v0.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 22, 2024 License: MIT Imports: 17 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// DefaultHtlcHoldDuration defines the default for how long mpp htlcs
	// are held while waiting for the other set members to arrive.
	DefaultHtlcHoldDuration = 120 * time.Second
)

Variables

View Source 
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")

	// ErrShuttingDown is returned when an operation failed because the
	// invoice registry is shutting down.
	ErrShuttingDown = errors.New("invoice registry shutting down")
)

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 slog.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 slog.

Types

type FailResolutionResult added in v0.3.0 

type FailResolutionResult uint8

FailResolutionResult provides metadata about a htlc that was failed by the registry. It can be used to take custom actions on resolution of the htlc. 

const (

	// ResultReplayToCanceled is returned when we replay a canceled invoice.
	ResultReplayToCanceled FailResolutionResult

	// ResultInvoiceAlreadyCanceled is returned when trying to pay an
	// invoice that is already canceled.
	ResultInvoiceAlreadyCanceled

	// ResultInvoiceAlreadySettled is returned when trying to pay an invoice
	// that is already settled.
	ResultInvoiceAlreadySettled

	// ResultAmountTooLow is returned when an invoice is underpaid.
	ResultAmountTooLow

	// ResultExpiryTooSoon is returned when we do not accept an invoice
	// payment because it expires too soon.
	ResultExpiryTooSoon

	// ResultCanceled is returned when we cancel an invoice and its
	// associated htlcs.
	ResultCanceled

	// ResultInvoiceNotOpen is returned when a mpp invoice is not open.
	ResultInvoiceNotOpen

	// ResultMppTimeout is returned when an invoice paid with multiple
	// partial payments times out before it is fully paid.
	ResultMppTimeout

	// ResultAddressMismatch is returned when the payment address for a mpp
	// invoice does not match.
	ResultAddressMismatch

	// ResultHtlcSetTotalMismatch is returned when the amount paid by a
	// htlc does not match its set total.
	ResultHtlcSetTotalMismatch

	// ResultHtlcSetTotalTooLow is returned when a mpp set total is too low
	// for an invoice.
	ResultHtlcSetTotalTooLow

	// ResultHtlcSetOverpayment is returned when a mpp set is overpaid.
	ResultHtlcSetOverpayment

	// ResultInvoiceNotFound is returned when an attempt is made to pay an
	// invoice that is unknown to us.
	ResultInvoiceNotFound

	// ResultKeySendError is returned when we receive invalid keysend
	// parameters.
	ResultKeySendError

	// ResultMppInProgress is returned when we are busy receiving a mpp
	// payment.
	ResultMppInProgress

	// ResultHtlcInvoiceTypeMismatch is returned when an AMP HTLC targets a
	// non-AMP invoice and vice versa.
	ResultHtlcInvoiceTypeMismatch

	// ResultAmpError is returned when we receive invalid AMP parameters.
	ResultAmpError

	// ResultAmpReconstruction is returned when the derived child
	// hash/preimage pairs were invalid for at least one HTLC in the set.
	ResultAmpReconstruction
)

func (FailResolutionResult) FailureString added in v0.3.0 

func (f FailResolutionResult) FailureString() string

FailureString returns a string representation of the result.

Note: it is part of the FailureDetail interface.

func (FailResolutionResult) IsSetFailure added in v0.5.0 

func (f FailResolutionResult) IsSetFailure() bool

IsSetFailure returns true if this failure should result in the entire HTLC set being failed with the same result.

func (FailResolutionResult) String added in v0.3.0 

func (f FailResolutionResult) String() string

String returns a string representation of the result.

type HTLCPreimages added in v0.5.0 

type HTLCPreimages = map[channeldb.CircuitKey]lntypes.Preimage

HTLCPreimages is a map of CircuitKey to preimage.

type HTLCSet added in v0.5.0 

type HTLCSet = map[channeldb.CircuitKey]*channeldb.InvoiceHTLC

HTLCSet is a map of CircuitKey to InvoiceHTLC.

type HtlcFailResolution added in v0.3.0 

type HtlcFailResolution struct {

	// AcceptHeight is the original height at which the htlc was accepted.
	AcceptHeight int32

	// Outcome indicates the outcome of the invoice registry update.
	Outcome FailResolutionResult
	// contains filtered or unexported fields
}

HtlcFailResolution is an implementation of the HtlcResolution interface which is returned when a htlc is failed.

func NewFailResolution added in v0.3.0 

func NewFailResolution(key channeldb.CircuitKey,
	acceptHeight int32, outcome FailResolutionResult) *HtlcFailResolution

NewFailResolution returns a htlc failure resolution.

func (*HtlcFailResolution) CircuitKey added in v0.3.0 

func (f *HtlcFailResolution) CircuitKey() channeldb.CircuitKey

CircuitKey returns the circuit key for the htlc that we have a resolution for.

Note: it is part of the HtlcResolution interface.

type HtlcResolution added in v0.3.0 

type HtlcResolution interface {
	// CircuitKey returns the circuit key for the htlc that we have a
	// resolution for.
	CircuitKey() channeldb.CircuitKey
}

HtlcResolution describes how an htlc should be resolved.

type HtlcSettleResolution added in v0.3.0 

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

	// acceptHeight is the original height at which the htlc was accepted.
	AcceptHeight int32

	// Outcome indicates the outcome of the invoice registry update.
	Outcome SettleResolutionResult
	// contains filtered or unexported fields
}

HtlcSettleResolution is an implementation of the HtlcResolution interface which is returned when a htlc is settled.

func NewSettleResolution added in v0.3.0 

func NewSettleResolution(preimage lntypes.Preimage,
	key channeldb.CircuitKey, acceptHeight int32,
	outcome SettleResolutionResult) *HtlcSettleResolution

NewSettleResolution returns a htlc resolution which is associated with a settle.

func (*HtlcSettleResolution) CircuitKey added in v0.3.0 

func (s *HtlcSettleResolution) CircuitKey() channeldb.CircuitKey

CircuitKey returns the circuit key for the htlc that we have a resolution for.

Note: it is part of the HtlcResolution interface.

type InvoiceExpiryWatcher added in v0.3.0 

type InvoiceExpiryWatcher struct {
	sync.Mutex
	// contains filtered or unexported fields
}

InvoiceExpiryWatcher handles automatic invoice cancellation of expried invoices. Upon start InvoiceExpiryWatcher will retrieve all pending (not yet settled or canceled) invoices invoices to its watcing queue. When a new invoice is added to the InvoiceRegistry, it'll be forarded to the InvoiceExpiryWatcher and will end up in the watching queue as well. If any of the watched invoices expire, they'll be removed from the watching queue and will be cancelled through InvoiceRegistry.CancelInvoice().

func NewInvoiceExpiryWatcher added in v0.3.0 

func NewInvoiceExpiryWatcher(clock clock.Clock,
	expiryDelta, startHeight uint32, startHash *chainhash.Hash,
	notifier chainntnfs.ChainNotifier) *InvoiceExpiryWatcher

NewInvoiceExpiryWatcher creates a new InvoiceExpiryWatcher instance.

func (*InvoiceExpiryWatcher) AddInvoices added in v0.3.0 

func (ew *InvoiceExpiryWatcher) AddInvoices(invoices ...invoiceExpiry)

AddInvoices adds invoices to the InvoiceExpiryWatcher.

func (*InvoiceExpiryWatcher) Start added in v0.3.0 

func (ew *InvoiceExpiryWatcher) Start(
	cancelInvoice func(lntypes.Hash, bool) error) error

Start starts the the subscription handler and the main loop. Start() will return with error if InvoiceExpiryWatcher is already started. Start() expects a cancellation function passed that will be use to cancel expired invoices by their payment hash.

func (*InvoiceExpiryWatcher) Stop added in v0.3.0 

func (ew *InvoiceExpiryWatcher) Stop()

Stop quits the expiry handler loop and waits for InvoiceExpiryWatcher to fully stop.

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, expiryWatcher *InvoiceExpiryWatcher,
	cfg *RegistryConfig) *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) 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 added in v0.2.0 

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

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

func (*InvoiceRegistry) HodlUnsubscribeAll added in v0.2.0 

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

HodlUnsubscribeAll cancels the subscription.

func (*InvoiceRegistry) LookupInvoice 

func (i *InvoiceRegistry) LookupInvoice(rHash lntypes.Hash) (channeldb.Invoice,
	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.

TODO(roasbeef): ignore if settled?

func (*InvoiceRegistry) LookupInvoiceByRef added in v0.6.0 

func (i *InvoiceRegistry) LookupInvoiceByRef(
	ref channeldb.InvoiceRef) (channeldb.Invoice, error)

LookupInvoiceByRef looks up an invoice by the given reference, if found then we're able to pull the funds pending within an HTLC.

func (*InvoiceRegistry) NotifyExitHopHtlc added in v0.2.0 

func (i *InvoiceRegistry) NotifyExitHopHtlc(rHash lntypes.Hash,
	amtPaid lnwire.MilliAtom, expiry uint32, currentHeight int32,
	circuitKey channeldb.CircuitKey, hodlChan chan<- interface{},
	payload Payload) (HtlcResolution, error)

NotifyExitHopHtlc attempts to mark an invoice as 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.

In the case that the htlc is part of a larger set of htlcs that pay to the same invoice (multi-path payment), the htlc is held until the set is complete. If the set doesn't fully arrive in time, a timer will cancel the held htlc.

func (*InvoiceRegistry) SettleHodlInvoice added in v0.2.0 

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() error

Stop signals the registry for a graceful shutdown.

func (*InvoiceRegistry) SubscribeNotifications 

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

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 added in v0.2.0 

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

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 Payload added in v0.3.0 

type Payload interface {
	// MultiPath returns the record corresponding the option_mpp parsed from
	// the onion payload.
	MultiPath() *record.MPP

	// AMPRecord returns the record corresponding to the option_amp record
	// parsed from the onion payload.
	AMPRecord() *record.AMP

	// CustomRecords returns the custom tlv type records that were parsed
	// from the payload.
	CustomRecords() record.CustomSet
}

Payload abstracts access to any additional fields provided in the final hop's TLV onion payload.

type RegistryConfig added in v0.3.0 

type RegistryConfig struct {
	// FinalCltvRejectDelta defines the number of blocks before the expiry
	// of the htlc where we no longer settle it as an exit hop and instead
	// cancel it back. Normally this value should be lower than the cltv
	// expiry of any invoice we create and the code effectuating this should
	// not be hit.
	FinalCltvRejectDelta int32

	// HtlcHoldDuration defines for how long mpp htlcs are held while
	// waiting for the other set members to arrive.
	HtlcHoldDuration time.Duration

	// Clock holds the clock implementation that is used to provide
	// Now() and TickAfter() and is useful to stub out the clock functions
	// during testing.
	Clock clock.Clock

	// AcceptKeySend indicates whether we want to accept spontaneous key
	// send payments.
	AcceptKeySend bool

	// AcceptAMP indicates whether we want to accept spontaneous AMP
	// payments.
	AcceptAMP bool

	// GcCanceledInvoicesOnStartup if set, we'll attempt to garbage collect
	// all canceled invoices upon start.
	GcCanceledInvoicesOnStartup bool

	// GcCanceledInvoicesOnTheFly if set, we'll garbage collect all newly
	// canceled invoices on the fly.
	GcCanceledInvoicesOnTheFly bool

	// KeysendHoldTime indicates for how long we want to accept and hold
	// spontaneous keysend payments.
	KeysendHoldTime time.Duration
}

RegistryConfig contains the configuration parameters for invoice registry.

type SettleResolutionResult added in v0.3.0 

type SettleResolutionResult uint8

SettleResolutionResult provides metadata which about a htlc that was failed by the registry. It can be used to take custom actions on resolution of the htlc. 

const (

	// ResultSettled is returned when we settle an invoice.
	ResultSettled SettleResolutionResult

	// ResultReplayToSettled is returned when we replay a settled invoice.
	ResultReplayToSettled

	// ResultDuplicateToSettled is returned when we settle an invoice which
	// has already been settled at least once.
	ResultDuplicateToSettled
)

func (SettleResolutionResult) String added in v0.3.0 

func (s SettleResolutionResult) String() string

String returns a string representation of the result.

type SingleInvoiceSubscription added in v0.2.0 

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 added in v0.2.0 

func (i *SingleInvoiceSubscription) Cancel()

Cancel unregisters the InvoiceSubscription, freeing any previously allocated resources.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.