use stateless invoices

README.md

@@ -15,7 +15,7 @@ For the setup, it is assumed that there are multiple LND nodes running with conn
   there are momentary disconnects. Not running with this option can lead to
   HTLCs failing after the invoice that they pay to has been marked as settled. 
 
-* Create a postgres database
+* Create a postgres database. Note that `lnmux` uses stateless invoices. This means that the database only contains settled invoices.
 
 * Create a config file for `lnmuxd` named `lnmux.yml`. An [example](lnmux.yml.example) can be found in this repository. The config file contains the following elements:
   * LND nodes configuration: TLS certificate, macaroon, address and pubkey. Pubkey is configured as a protection against unintentionally connecting to the wrong node.
@@ -26,14 +26,16 @@ For the setup, it is assumed that there are multiple LND nodes running with conn
 
 * Migrate the database to the latest version: `go run ./cmd/lnmuxd -c lnmux.yml migrate up`
 
-* Run `lnmuxd`: `go run ./cmd/lnmuxd -c lnmux.yml run`. This opens connections to all LND nodes via the HTLC interceptor API. When HTLCs come in, they are matched against the invoice database. If there is a match, the invoice is marked as settled and a settle action is returned to the LND instance holding the HTLC. For multi-part payments, `lnmuxd` holds matching HTLCs until the full invoice amount is in.
+* Run `lnmuxd`: `go run ./cmd/lnmuxd -c lnmux.yml run`. This opens connections to all LND nodes via the HTLC interceptor API. Incoming htlcs are collected and assembled into sets. When a set is complete, an external application connected to `lnmux` decides whether to settle the invoice. If the application sends a settle request, the invoice is marked as settled in the `lnmux` database and a settle action is returned to the LND instance(s) holding the HTLC(s).
 
 * Invoice generation is taken over by `lnmuxd`. It is no longer a responsibility of the LND nodes. To generate an invoice, run:
 
   `grpcurl -plaintext -v -d '{"amt_msat":20000, "expiry_secs":600}' localhost:19090 lnmux.Service.AddInvoice`. 
 
    If you decode the invoice, you'll find route hints from each node in the cluster to the `lnmuxd` public key. `lnmuxd` acts as a virtual node without real channels.
 
+   The invoice is not stored in the `lnmux` database and does not take up any disk space. This makes `lnmux` particularly suitable for scenarios where large numbers of invoices are generated.
+
   Below is an example invoice generated by `lnmuxd`.
 ```
 {
@@ -110,13 +112,16 @@ If you've set up `lnmuxd` correctly, output similar to what is shown below is ex
 
 ![](invoice_lifecycle.png)
 
-Notice that the transition from `settle requested` to `settled` is marked as `[future]`. The transition is happening already, but not backed by an actual final settle event from lnd. See https://github.com/lightningnetwork/lnd/issues/6208.
+Note that only the states `accepted`, `settle requested` and `settled` are published to callers of the `SubscribeSingleInvoice` rpc.
+
+The transition from `settle requested` to `settled` is marked as `[future]`. This transition is happening already, but not backed by an actual final settle event from lnd. See https://github.com/lightningnetwork/lnd/issues/6208.
 
 ## Regtest testing
 
 The minimal setup to test on regtest is to create three LND nodes A, B and C. Create channels between B and A and between B and C. Connect `lnmuxd` to the nodes A and C. Pay invoices from node B, while experimenting with online status and liquidity of A and C.
 
 ## Experimental
 
-This software is in an experimental state. Use at your own risk.
+This software is in an experimental state. At this stage, breaking changes can happen and may not always include a database migration. Use at your own risk.
+
 

cmd/lnmuxd/lnmux_proto/lnmux.proto

@@ -33,23 +33,12 @@ message SubscribeSingleInvoiceRequest {
 
 message SubscribeSingleInvoiceResponse {
     enum InvoiceState {
-      STATE_OPEN = 0;
-      STATE_ACCEPTED = 1;
-      STATE_SETTLE_REQUESTED = 2;
-      STATE_SETTLED = 3;
-      STATE_CANCELLED = 4;
-    }
-
-    enum CancelledReason {
-      REASON_NONE = 0;
-      REASON_EXPIRED = 1;
-      REASON_ACCEPT_TIMEOUT = 2;
-      REASON_EXTERNAL = 3;
+      STATE_ACCEPTED = 0;
+      STATE_SETTLE_REQUESTED = 1;
+      STATE_SETTLED = 2;
     }
 
     InvoiceState state = 1;
-
-    CancelledReason cancelled_reason = 2;
 }
 
 message SettleInvoiceRequest {

cmd/lnmuxd/run.go

@@ -81,6 +81,7 @@ func runAction(c *cli.Context) error {
 			HtlcHoldDuration:     30 * time.Second,
 			AcceptTimeout:        60 * time.Second,
 			Logger:               log,
+			PrivKey:              identityKey,
 			AutoSettle:           cfg.AutoSettle,
 		},
 	)

cmd/lnmuxd/server.go

@@ -4,7 +4,6 @@ import (
 	"context"
 	"errors"
 	"fmt"
-	"math/rand"
 	"time"
 
 	"github.com/bottlepay/lnmux"
@@ -39,8 +38,6 @@ func newServer(creator *lnmux.InvoiceCreator, registry *lnmux.InvoiceRegistry) (
 
 func marshallInvoiceState(state persistence.InvoiceState) lnmux_proto.SubscribeSingleInvoiceResponse_InvoiceState {
 	switch state {
-	case persistence.InvoiceStateOpen:
-		return lnmux_proto.SubscribeSingleInvoiceResponse_STATE_OPEN
 
 	case persistence.InvoiceStateAccepted:
 		return lnmux_proto.SubscribeSingleInvoiceResponse_STATE_ACCEPTED
@@ -51,33 +48,11 @@ func marshallInvoiceState(state persistence.InvoiceState) lnmux_proto.SubscribeS
 	case persistence.InvoiceStateSettled:
 		return lnmux_proto.SubscribeSingleInvoiceResponse_STATE_SETTLED
 
-	case persistence.InvoiceStateCancelled:
-		return lnmux_proto.SubscribeSingleInvoiceResponse_STATE_CANCELLED
-
 	default:
 		panic("unknown invoice state")
 	}
 }
 
-func marshallCancelledReason(reason persistence.CancelledReason) lnmux_proto.SubscribeSingleInvoiceResponse_CancelledReason {
-	switch reason {
-	case persistence.CancelledReasonNone:
-		return lnmux_proto.SubscribeSingleInvoiceResponse_REASON_NONE
-
-	case persistence.CancelledReasonExpired:
-		return lnmux_proto.SubscribeSingleInvoiceResponse_REASON_EXPIRED
-
-	case persistence.CancelledReasonAcceptTimeout:
-		return lnmux_proto.SubscribeSingleInvoiceResponse_REASON_ACCEPT_TIMEOUT
-
-	case persistence.CancelledReasonExternal:
-		return lnmux_proto.SubscribeSingleInvoiceResponse_REASON_EXTERNAL
-
-	default:
-		panic("unknown cancelled reason")
-	}
-}
-
 func (s *server) SubscribeSingleInvoice(req *lnmux_proto.SubscribeSingleInvoiceRequest,
 	subscription lnmux_proto.Service_SubscribeSingleInvoiceServer) error {
 
@@ -136,8 +111,7 @@ func (s *server) SubscribeSingleInvoice(req *lnmux_proto.SubscribeSingleInvoiceR
 			}
 
 			err := subscription.Send(&lnmux_proto.SubscribeSingleInvoiceResponse{
-				State:           marshallInvoiceState(update.State),
-				CancelledReason: marshallCancelledReason(update.CancelledReason),
+				State: marshallInvoiceState(update.State),
 			})
 			if err != nil {
 				return err
@@ -170,7 +144,6 @@ func (s *server) AddInvoice(ctx context.Context,
 
 	// Create the invoice.
 	expiry := time.Duration(req.ExpirySecs) * time.Second
-	expiryTime := time.Now().Add(expiry)
 	invoice, preimage, err := s.creator.Create(
 		req.AmtMsat, expiry, req.Description, descHash, finalCltvExpiry,
 	)
@@ -180,20 +153,6 @@ func (s *server) AddInvoice(ctx context.Context,
 
 	hash := preimage.Hash()
 
-	// Store invoice.
-	creationData := &persistence.InvoiceCreationData{
-		InvoiceCreationData: invoice.InvoiceCreationData,
-		CreatedAt:           invoice.CreationDate,
-		ID:                  int64(rand.Int31()),
-		PaymentRequest:      invoice.PaymentRequest,
-		ExpiresAt:           expiryTime,
-	}
-
-	err = s.registry.NewInvoice(creationData)
-	if err != nil {
-		return nil, err
-	}
-
 	return &lnmux_proto.AddInvoiceResponse{
 		PaymentRequest: invoice.PaymentRequest,
 		Hash:           hash[:],

invoice_creator.go

@@ -1,7 +1,7 @@
 package lnmux
 
 import (
-	"crypto/rand"
+	"encoding/binary"
 	"time"
 
 	"github.com/btcsuite/btcd/btcec/v2"
@@ -17,6 +17,8 @@ import (
 	"github.com/bottlepay/lnmux/types"
 )
 
+var byteOrder = binary.BigEndian
+
 const virtualChannel = 12345
 
 type InvoiceCreatorConfig struct {
@@ -65,6 +67,8 @@ func (c *InvoiceCreator) Create(amtMSat int64, expiry time.Duration,
 	memo string, descHash *lntypes.Hash, cltvDelta uint64) (
 	*Invoice, lntypes.Preimage, error) {
 
+	creationDate := time.Now()
+
 	// Get features.
 	featureMgr, err := feature.NewManager(feature.Config{})
 	if err != nil {
@@ -77,11 +81,27 @@ func (c *InvoiceCreator) Create(amtMSat int64, expiry time.Duration,
 
 	nodeSigner := netann.NewNodeSigner(nodeKeySigner)
 
-	paymentPreimage := &lntypes.Preimage{}
-	if _, err := rand.Read(paymentPreimage[:]); err != nil {
+	privKey, err := c.keyRing.DerivePrivKey(c.idKeyDesc)
+	if err != nil {
 		return nil, lntypes.Preimage{}, err
 	}
-	paymentHash := paymentPreimage.Hash()
+
+	expiryTime := creationDate.Add(expiry)
+	statelessData, err := encodeStatelessData(
+		privKey.Serialize(), amtMSat, expiryTime,
+	)
+	if err != nil {
+		return nil, lntypes.Preimage{}, err
+	}
+
+	paymentHash := statelessData.preimage.Hash()
+
+	// TODO: Optionally we could encrypt the payment metadata here, just like
+	// rust-lightning does:
+	// https://github.com/lightningdevkit/rust-lightning/blob/a600eee87c96ee8865402e86bb1865011bf2d2de/lightning/src/ln/inbound_payment.rs#L166
+	//
+	// Background:
+	// https://github.com/lightningdevkit/rust-lightning/issues/1171#issuecomment-1162817360
 
 	// We also create an encoded payment request which allows the
 	// caller to compactly send the invoice to the payer. We'll create a
@@ -128,17 +148,11 @@ func (c *InvoiceCreator) Create(amtMSat int64, expiry time.Duration,
 	invoiceFeatures := featureMgr.Get(feature.SetInvoice)
 	options = append(options, zpay32.Features(invoiceFeatures))
 
-	// Generate and set a random payment address for this invoice. If the
-	// sender understands payment addresses, this can be used to avoid
-	// intermediaries probing the receiver.
-	var paymentAddr [32]byte
-	if _, err := rand.Read(paymentAddr[:]); err != nil {
-		return nil, lntypes.Preimage{}, err
-	}
-	options = append(options, zpay32.PaymentAddr(paymentAddr))
+	// Set the payment address.
+	options = append(options, zpay32.PaymentAddr(statelessData.paymentAddr))
 
 	// Create and encode the payment request as a bech32 (zpay32) string.
-	creationDate := time.Now()
+
 	payReq, err := zpay32.NewInvoice(
 		c.activeNetParams, paymentHash, creationDate, options...,
 	)
@@ -159,12 +173,11 @@ func (c *InvoiceCreator) Create(amtMSat int64, expiry time.Duration,
 		CreationDate:   creationDate,
 		PaymentRequest: payReqString,
 		InvoiceCreationData: types.InvoiceCreationData{
-			FinalCltvDelta:  int32(payReq.MinFinalCLTVExpiry()),
 			Value:           lnwire.MilliSatoshi(amtMSat),
-			PaymentPreimage: *paymentPreimage,
-			PaymentAddr:     paymentAddr,
+			PaymentPreimage: statelessData.preimage,
+			PaymentAddr:     statelessData.paymentAddr,
 		},
 	}
 
-	return newInvoice, *paymentPreimage, nil
+	return newInvoice, statelessData.preimage, nil
 }