offers: add a SQL-backed store for BOLT 12 offers

docs/release-notes/release-notes-0.22.0.md

@@ -160,6 +160,15 @@
   requests, and invoices, and `ValidateInvoiceForPayment` to bundle the
   payer-side invoice checks into one call.
 
+* [BOLT 12 offer
+  store](https://github.com/lightningnetwork/lnd/pull/11278): add the
+  `offers` package with a SQL-backed store for BOLT 12 offers. The store
+  keeps the encoded offer, a disabled flag and the creation time. It finds
+  an offer by its hash. `CreateOffer` validates the parameters, encodes the
+  offer and stores it. The `offers` table migration is a development
+  migration for now, so a normal build does not change the database
+  schema.
+
 ## Testing
 
 * [BOLT 12 spec test vectors](https://github.com/lightningnetwork/lnd/pull/11001):

offers/create.go

@@ -0,0 +1,179 @@
+package offers
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"github.com/btcsuite/btcd/btcec/v2"
+	"github.com/btcsuite/btcd/chaincfg/v2"
+	"github.com/lightningnetwork/lnd/bolt12"
+	"github.com/lightningnetwork/lnd/clock"
+	"github.com/lightningnetwork/lnd/fn/v2"
+	"github.com/lightningnetwork/lnd/lnwire"
+	"github.com/lightningnetwork/lnd/tlv"
+)
+
+// ErrExpiryNotInFuture is returned when the absolute expiry is not after the
+// creation time, so no payer could use the offer.
+var ErrExpiryNotInFuture = errors.New("absolute expiry is not in the future")
+
+// CreateOfferParams holds the fields of a new offer. Each field maps to a
+// matching offer TLV record.
+type CreateOfferParams struct {
+	// Identity specifies how the offer identifies the receiver. Left holds
+	// the issuer public key (offer_issuer_id), which reveals the node
+	// identity. Right holds blinded message paths (offer_paths), which
+	// preserve privacy.
+	Identity fn.Either[*btcec.PublicKey, []lnwire.BlindedPath]
+
+	// Description is the UTF-8 description of the payment purpose. Required
+	// when Amount is set.
+	Description string
+
+	// AmountMsat is the per-item amount in millisatoshis. Zero means no
+	// fixed amount (the payer must specify invreq_amount).
+	AmountMsat uint64
+
+	// AbsoluteExpiry is seconds since epoch after which the offer expires.
+	// Zero leaves offer_absolute_expiry out, so the offer never expires.
+	AbsoluteExpiry uint64
+
+	// QuantityMax is the maximum items per invoice. None means the offer
+	// does not support quantity selection. Some(0) means unlimited
+	// quantity.
+	QuantityMax fn.Option[uint64]
+
+	// Chains specifies which blockchain networks this offer is valid for.
+	// When empty, the spec defaults to Bitcoin mainnet, so non-mainnet
+	// offers must set this.
+	Chains [][32]byte
+}
+
+// CreateOfferResult reports a created offer. Hash is the lookup key in the
+// offer store.
+type CreateOfferResult struct {
+	// Hash is the SHA256 hash of the TLV-encoded offer.
+	Hash [32]byte
+
+	// Encoded is the bech32-encoded offer string (lno1...).
+	Encoded string
+}
+
+// CreateOffer creates and stores a BOLT 12 offer. It returns the encoded string
+// and the offer hash. It rejects an absolute expiry at or before the time of
+// clk. Any other invalid parameter returns the bolt12 validation error,
+// wrapped. It stores only an offer that the bolt12 reader accepts. The store
+// sets the creation time from its own clock, so clk must be that same clock.
+// Otherwise the expiry check and the stored creation time can disagree.
+func CreateOffer(ctx context.Context, store Store, clk clock.Clock,
+	params CreateOfferParams) (*CreateOfferResult, error) {
+
+	// The codec cannot check the expiry, because it has no clock.
+	if params.AbsoluteExpiry > 0 &&
+		params.AbsoluteExpiry <= uint64(clk.Now().Unix()) {
+
+		return nil, ErrExpiryNotInFuture
+	}
+
+	offer := &bolt12.Offer{}
+
+	params.Identity.WhenLeft(func(key *btcec.PublicKey) {
+		offer.OfferIssuerID = tlv.SomeRecordT(
+			tlv.RecordT[tlv.TlvType22, *btcec.PublicKey]{
+				Val: key,
+			},
+		)
+	})
+	params.Identity.WhenRight(func(paths []lnwire.BlindedPath) {
+		offer.OfferPaths = tlv.SomeRecordT(
+			tlv.RecordT[
+				tlv.TlvType16, lnwire.BlindedPaths,
+			]{
+				Val: lnwire.BlindedPaths{
+					Paths: paths,
+				},
+			},
+		)
+	})
+
+	if len(params.Chains) > 0 {
+		offer.OfferChains = tlv.SomeRecordT(
+			tlv.RecordT[tlv.TlvType2, bolt12.ChainsRecord]{
+				Val: bolt12.ChainsRecord{
+					Chains: params.Chains,
+				},
+			},
+		)
+	}
+
+	if params.Description != "" {
+		offer.OfferDescription = tlv.SomeRecordT(
+			tlv.RecordT[tlv.TlvType10, tlv.Blob]{
+				Val: []byte(params.Description),
+			},
+		)
+	}
+
+	if params.AmountMsat > 0 {
+		amount := bolt12.TUint64(params.AmountMsat)
+		offer.OfferAmount = tlv.SomeRecordT(
+			tlv.RecordT[tlv.TlvType8, bolt12.TUint64]{
+				Val: amount,
+			},
+		)
+	}
+
+	if params.AbsoluteExpiry > 0 {
+		expiry := bolt12.TUint64(params.AbsoluteExpiry)
+		offer.OfferAbsoluteExpiry = tlv.SomeRecordT(
+			tlv.RecordT[tlv.TlvType14, bolt12.TUint64]{
+				Val: expiry,
+			},
+		)
+	}
+
+	params.QuantityMax.WhenSome(func(qty uint64) {
+		offer.OfferQuantityMax = tlv.SomeRecordT(
+			tlv.RecordT[tlv.TlvType20, bolt12.TUint64]{
+				Val: bolt12.TUint64(qty),
+			},
+		)
+	})
+
+	encoded, err := bolt12.EncodeOfferString(offer)
+	if err != nil {
+		return nil, fmt.Errorf("encode offer: %w", err)
+	}
+
+	// The writer accepts some offers that the reader rejects, for example
+	// a record above the P2P size limit. Decode the offer once, so that
+	// the store holds only an offer that a payer and this node can read.
+	readChain := [32]byte(*chaincfg.MainNetParams.GenesisHash)
+	if len(params.Chains) > 0 {
+		readChain = params.Chains[0]
+	}
+	_, err = bolt12.DecodeOfferString(encoded, clk.Now(), readChain)
+	if err != nil {
+		return nil, fmt.Errorf("decode offer: %w", err)
+	}
+
+	offerHash, err := bolt12.OfferHash(offer)
+	if err != nil {
+		return nil, fmt.Errorf("offer hash: %w", err)
+	}
+
+	// The encoded string carries every offer field.
+	_, err = store.InsertOffer(ctx, &Offer{
+		Hash:    offerHash,
+		Encoded: encoded,
+	})
+	if err != nil {
+		return nil, fmt.Errorf("persist offer: %w", err)
+	}
+
+	return &CreateOfferResult{
+		Hash:    offerHash,
+		Encoded: encoded,
+	}, nil
+}