lnchat

package
v0.3.0-alpha Latest Latest
Warning

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

 Go to latest Published: Jun 16, 2022 License: MIT Imports: 29 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrNoRouteFound signifies that no route
	// was found for the provided destination address.
	ErrNoRouteFound = fmt.Errorf("No route found")
	// ErrInvalidAddress signifies that the provided
	// address is invalid.
	ErrInvalidAddress = fmt.Errorf("Invalid address")
	// ErrInsufficientBalance is returned when a payment fails
	// due to insufficient balance.
	ErrInsufficientBalance = fmt.Errorf("Insufficient balance")

	// ErrCancelled is returned when a grpc call returns
	// with code Canceled.
	ErrCancelled = fmt.Errorf("Operation canceled")
	// ErrDeadlineExceeded is returned when a grpc call returns
	// with code DeadlineExceeded.
	ErrDeadlineExceeded = fmt.Errorf("Operation deadline exceeded")

	// ErrUnknown is returned when the error cause cannot be discerned.
	ErrUnknown = fmt.Errorf("Unknown error")
	// ErrInternal is returned when an error was unexpected.
	ErrInternal = fmt.Errorf("Internal error")

	// ErrNetworkUnavailable is returned when a grpc call returns
	// with code Unavailable.
	ErrNetworkUnavailable = fmt.Errorf("Network unavailable")
	// ErrCredentials signifies an error while creating Lightning credentials.
	ErrCredentials = fmt.Errorf("Credential error")
	// ErrPermissionDenied is returned when a grpc call returns
	// with code PermissionDenied.
	ErrPermissionDenied = fmt.Errorf("Permission denied")
)

Functions

func NewCredentials 

func NewCredentials(rpcAddr, tlsPath, macPath string,
	macConstraints MacaroonConstraints) (lnconnect.Credentials, error)

NewCredentials constructs a set of credentials from the address and the TLS and macaroon file paths.

func NewCredentialsFromURL 

func NewCredentialsFromURL(lndConnectURL string,
	macConstraints MacaroonConstraints) (lnconnect.Credentials, error)

NewCredentialsFromURL constructs a set of credentials from an lndconnect URL.

Types

type Amount 

type Amount int64

Amount represents an amount on the Lightning network.

func NewAmount 

func NewAmount(msat int64) Amount

NewAmount creates an amount from a value in millisatoshi.

func (Amount) Msat 

func (a Amount) Msat() int64

Msat returns the amount in millisatoshi.

type BalanceAllocation 

type BalanceAllocation struct {
	// The part of the balance available on the local end (in millisatoshi).
	LocalMsat uint64
	// The part of the balance available on the remote end (in millisatoshi).
	RemoteMsat uint64
}

BalanceAllocation represents the distribution of balance in local and remote endpoints.

type Chain 

type Chain struct {
	// The blockchain of a node.
	Chain string
	// The network a node is operating on.
	Network string
}

Chain represents a blockchain and network of a Lightning node.

type ChannelPoint 

type ChannelPoint struct {
	// The funding transaction ID of the channel opening
	// transaction (hex-encoded and byte-reversed).
	FundingTxid string
	// The output index of the funding transaction.
	OutputIndex uint32
}

ChannelPoint represents a channel, as identified by its funding transaction.

type Error 

type Error struct {
	Err error
	// contains filtered or unexported fields
}

Error represents an error of the lnchat package.

func (Error) Cause 

func (e Error) Cause() error

Cause returns the cause of an Error.

func (Error) Error 

func (e Error) Error() string

func (Error) Unwrap 

func (e Error) Unwrap() error

Unwrap returns the underlying error of an Error.

type HTLCAttempt 

type HTLCAttempt struct {
	// The route of the HTLC.
	Route Route
	// The time the HTLC was sent (in nanoseconds since Unix epoch).
	AttemptTimeNs int64
	// The time the HTLC was resolved (in nanoseconds since Unix epoch).
	ResolveTimeNs int64
	// The status of the HTLC.
	Status lnrpc.HTLCAttempt_HTLCStatus
	// The details of HTLC failure to settle (if any).
	Failure *HTLCFailure
	// The preimage used to settle the HTLC.
	Preimage []byte
}

HTLCAttempt represents an attempt to pay (a portion of) a payment.

type HTLCFailure 

type HTLCFailure struct {
	// The failure code (as defined in BOLT #4, Section "Failure Messages").
	Code lnrpc.Failure_FailureCode
	// The route position of the node that generated the failure.
	// Index 0 represents the sending node.
	NodeIndex uint32
}

HTLCFailure represents a detailed reason for an HTLC failure.

type HopHint 

type HopHint struct {
	// Public key of the node at the channel ingress direction.
	NodeID NodeID
	// The channel id of the channel to be used as hop (short channel id).
	ChanID uint64
	// The base fee of the channel (in millisatoshi).
	FeeBaseMsat uint32
	// The fee rate of the channel (in microsatoshi/sat sent).
	FeeRate uint32
	// The timelock delta of the channel.
	CltvExpiryDelta uint32
}

HopHint contains the necessary information (hop id, fee variables) for a payment to traverse a route leg.

type Invoice 

type Invoice struct {
	// Invoice memo.
	Memo string
	// The preimage hash.
	Hash string
	// The invoice preimage.
	Preimage []byte
	// Encoding of the necessary details for a payment to the invoice.
	PaymentRequest string
	// The value of the invoice.
	Value Amount
	// The amount paid to this invoice, which may differ from its value.
	AmtPaid Amount
	// Creation timestamp (in seconds since Unix epoch).
	CreatedTimeSec int64
	// Settlement timestamp (in seconds since Unix epoch).
	SettleTimeSec int64
	// The invoice expiry (in seconds).
	Expiry int64
	// Delta to use for the timelock of the final hop.
	CltvExpiry uint64
	// Route hints that can be used for payment assistance.
	RouteHints []RouteHint
	// The state of the invoice.
	State InvoiceState
	// The index at which the invoice was added.
	AddIndex uint64
	// The index at which the invoice was settled.
	SettleIndex uint64
	// Indicator of including hints for private channels.
	Private bool
	// The set of HTLCs settling the invoice.
	Htlcs []InvoiceHTLC
}

Invoice reprsents a Lightning invoice.

func (Invoice) GetCustomRecords 

func (inv Invoice) GetCustomRecords() []map[uint64][]byte

GetCustomRecords returns the custom records transferred via the invoice HTLCs.

type InvoiceHTLC 

type InvoiceHTLC struct {
	// The channel id of the channel the HTLC arrived on.
	ChanID uint64
	// The amount paid with this HTLC. May only partially pay an invoice.
	Amount Amount
	// Height at which this HTLC expires.
	ExpiryHeight int32
	// The HTLC state.
	State lnrpc.InvoiceHTLCState
	// The timestamp this HTLC arrived (in seconds since Unix epoch).
	AcceptTimeSec int64
	// The timestamp this HTLC was resolved (in seconds since Unix epoch).
	ResolveTimeSec int64
	// A list of the custom records transported by this HTLC.
	CustomRecords map[uint64][]byte
}

InvoiceHTLC represents an HTLC paying to an invoice.

type InvoiceState 

type InvoiceState int32

InvoiceState represents the state of an invoice. 

const (
	// InvoiceOPEN represents an invoice that has not been paid (yet).
	InvoiceOPEN InvoiceState = iota
	// InvoiceACCEPTED represents an invoice that has been paid but not settled.
	InvoiceACCEPTED
	// InvoiceSETTLED signifies that an invoice has been paid and settled.
	InvoiceSETTLED
	// InvoiceCANCELLED signifies that an invoice has been cancelled.
	InvoiceCANCELLED
)

type InvoiceUpdate 

type InvoiceUpdate struct {
	Inv *Invoice
	Err error
}

InvoiceUpdate represents an invoice update, as returned by SubscribeInvoiceUpdates.

type InvoiceUpdateFilter 

type InvoiceUpdateFilter = func(*Invoice) bool

InvoiceUpdateFilter allows filtering of invoice updates of interest to be returned from InvoiceSubscription

type LightManager 

type LightManager interface {
	GetSelfInfo(ctx context.Context) (SelfInfo, error)
	ListNodes(ctx context.Context) ([]LightningNode, error)
	GetSelfBalance(ctx context.Context) (*SelfBalance, error)

	ConnectNode(ctx context.Context, address string, hostport string) error
	OpenChannel(ctx context.Context, address string,
		private bool, amtMsat, pushAmtMsat uint64,
		minOpenConfirmations int32, txOpts TxFeeOptions) (*ChannelPoint, error)

	VerifySignatureExtractPubkey(ctx context.Context, message, signature []byte) (string, error)
	SignMessage(ctx context.Context, message []byte) ([]byte, error)

	SubscribeInvoiceUpdates(ctx context.Context, startIdx uint64,
		filter InvoiceUpdateFilter) (<-chan InvoiceUpdate, error)
	SubscribePaymentUpdates(ctx context.Context, startIdx uint64,
		filter PaymentUpdateFilter) (<-chan PaymentUpdate, error)
	SendPayment(ctx context.Context, recipient string, amt Amount, payReq string,
		payOpts PaymentOptions, payload map[uint64][]byte,
		filter PaymentUpdateFilter) (<-chan PaymentUpdate, error)

	DecodePayReq(ctx context.Context, payReq string) (*PayReq, error)
	CreateInvoice(ctx context.Context, memo string, amt Amount,
		expiry int64, privateHints bool) (*Invoice, error)
	LookupInvoice(ctx context.Context, payHash string) (*Invoice, error)

	GetRoute(ctx context.Context, recipient string, amt Amount, payReq string,
		payOpts PaymentOptions, payload map[uint64][]byte) (
		route *Route, prob float64, err error)

	Close() error
}

LightManager is the API for the lnchat service.

func New 

func New(creds lnconnect.Credentials, options ...func(LightManager) error) (LightManager, error)

New creates a manager connected to the node daemon with the provided credentials.

type LightningChannel 

type LightningChannel struct {
	// The ID of the Lightning channel.
	ChannelID uint64
	// The Lightning address of the first endpoint (node) of the channel.
	Node1Address string
	// The Lightning address of the second endpoint of the channel.
	Node2Address string
	// Capacity is the channel capacity (in millisatoshi).
	CapacityMsat int64
}

LightningChannel represents a Lightning network channel between two nodes.

type LightningNode 

type LightningNode struct {
	// Alias is the Lightning network alias of the node.
	Alias string
	// Address is the Lightning address of the node.
	Address string
}

LightningNode represents a Lightning network node.

func ResolveAddress 

func ResolveAddress(nodes []LightningNode, address string) []LightningNode

ResolveAddress returns the node with the specified address. If no such node exists on the network view of the underlying lightning node, it returns an empty list.

func ResolveAlias 

func ResolveAlias(nodes []LightningNode, aliasSubstr string) []LightningNode

ResolveAlias returns all nodes whose alias contains the provided substring. It returns a list of nodes, since aliases are not guaranteed to be unique or may not exist at all.

type MacaroonConstraints 

type MacaroonConstraints struct {
	// Timeout restricts the lifetime of
	// the transmitted macaroon (in seconds).
	// A value of 0 (default) does not set a timeout caveat.
	Timeout int64
	// IPLock locks the transmitted macaroon to an IP address.
	// Empty value is ignored.
	IPLock string
}

MacaroonConstraints represents constraints used to derive the macaroon sent for requests.

type NodeID 

type NodeID struct {
	route.Vertex
}

NodeID represents the identifier for a node (a.k.a. its public key).

func NewNodeFromBytes 

func NewNodeFromBytes(b []byte) (NodeID, error)

NewNodeFromBytes creates a NodeID from a pubkey byte slice.

func NewNodeFromString 

func NewNodeFromString(s string) (NodeID, error)

NewNodeFromString creates a NodeID from a pubkey string.

func (NodeID) Bytes 

func (n NodeID) Bytes() []byte

Bytes returns the node identifier as a byte slice.

func (NodeID) String 

func (n NodeID) String() string

String returns the node identifier as a hex-encoded string.

type PayReq 

type PayReq struct {
	// The pubkey of the payee.
	Destination NodeID
	// The payment hash of the invoice.
	Hash string
	// The amount to be paid.
	Amt Amount
	// Creation timestamp (in seconds since Unix epoch).
	CreatedTimeSec int64
	// Expiry offset since creation time (in seconds).
	Expiry int64
	// Delta to use for the timelock of the final hop.
	CltvExpiry uint64
	// Route hints that can be used for payment.
	RouteHints []RouteHint
}

PayReq represents a request for payment on the Lightning network.

type Payment 

type Payment struct {
	// The payment hash of the payment.
	Hash string
	// The preimage of the payment hash.
	Preimage string
	// The payment value.
	Value Amount
	// The timestamp of payment creation (in nanoseconds since Unix epoch).
	CreationTimeNs int64
	// The payment request the payment fulfils. May be empty.
	PaymentRequest string
	// The status of the payment.
	Status PaymentStatus
	// The payment index of the payment.
	PaymentIndex uint64
	// The HTLC attempts made to settle the payment.
	Htlcs []HTLCAttempt
}

Payment represents a Lightning payment.

func (*Payment) GetCustomRecords 

func (p *Payment) GetCustomRecords() []map[uint64][]byte

GetCustomRecords retrieves the custom records contained in the successful payment HTLCs.

func (*Payment) GetDestination 

func (p *Payment) GetDestination() (NodeID, error)

type PaymentOptions 

type PaymentOptions struct {
	// FeeLimitMsat is the maximum amount of fees (in millisatoshi)
	// the sender is willing to give in order to send a message.
	FeeLimitMsat int64
	// FinalCltvDelta is the difference in blocks from the current height
	// that should be used for the timelock of the final hop.
	FinalCltvDelta int32
	// TimeoutSecs is the upper limit (in seconds) afforded for
	// attempting to send a message.
	TimeoutSecs int32
}

PaymentOptions contains the payment details for sending a message.

type PaymentStatus 

type PaymentStatus int32

PaymentStatus represents the status of a payment. 

const (
	// PaymentUNKNOWN denotes the status of a payment as unknown.
	PaymentUNKNOWN PaymentStatus = iota
	// PaymentINFLIGHT signifies that a payment has not been resolved yet.
	PaymentINFLIGHT
	// PaymentSUCCEEDED signifies the success of a payment
	PaymentSUCCEEDED
	// PaymentFAILED signifies the failure of a payment.
	PaymentFAILED
)

type PaymentUpdate 

type PaymentUpdate struct {
	Payment *Payment
	Err     error
}

PaymentUpdate represents a payment update, as returned by SendPayment

type PaymentUpdateFilter 

type PaymentUpdateFilter = func(*Payment) bool

PaymentUpdateFilter allows filtering of payment updates of interest to be returned from SendPayment.

type PreImage 

type PreImage = lntypes.Preimage

PreImage is the type of a payment preimage.

type PreImageHash 

type PreImageHash = lntypes.Hash

PreImageHash is the preimage hash of a payment.

type Route 

type Route struct {
	// The cumulative (final) time lock across the entire route.
	TimeLock uint32
	// The amount sent via this route, disregarding the fees.
	Amt Amount
	// The fees of this route.
	Fees Amount
	// The list of hops of the route.
	Hops []RouteHop
}

Route represents a route (a list of hops) on the Lightning network through which a payment is (partially) fulfilled.

type RouteHint 

type RouteHint struct {
	// A list of hop hints that define the route hint.
	HopHints []HopHint
}

RouteHint is a hint that can assist a payment in reaching a destination node.

type RouteHop 

type RouteHop struct {
	// The (unique) ID of the channel used for the hop.
	ChannelID uint64
	// The pubkey of the hop egress (may be empty).
	NodeID NodeID
	// The amount to be forwarded to the next hop.
	AmtToForward Amount
	// The fees awarded to the egress node to forward the HTLC to the next hop.
	Fees Amount
	// HTLC expiry.
	Expiry uint32
	// TODO: We probably need MPPRecord and AMPRecord as well.
	// The custom records for the hop.
	CustomRecords map[uint64][]byte
}

RouteHop represents a hop of a route.

type SelfBalance 

type SelfBalance struct {
	// The confirmed balance of the node's wallet (in satoshi).
	WalletConfirmedBalanceSat int64
	// The unconfirmed balance of the node's wallet (in satoshi).
	WalletUnconfirmedBalanceSat int64

	// The balance available across all open channels.
	ChannelBalance BalanceAllocation
	// The balance in pending open channels.
	PendingOpenBalance BalanceAllocation
	// The unsettled balance across all open channels.
	UnsettledBalance BalanceAllocation
}

SelfBalance contains information about the underlying Lightning node balance.

type SelfInfo 

type SelfInfo struct {
	// Node holds the general node information.
	Node LightningNode
	// Chains are the chains of the current node.
	Chains []Chain
}

SelfInfo contains information about the underlying Lightning node.

type TxFeeOptions 

type TxFeeOptions struct {
	// A manual fee rate of sats per virtual byte of the funding transaction.
	SatPerVByte uint64
	// A number of blocks from the current that the transaction
	// should confirm by, which is used for fee estimation.
	TargetConfBlock uint32
}

TxFeeOptions represents ways to control the fee of on-chain transactions.

Source Files

View all Source files

Directories

Path Synopsis

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.