support paying to lightning address

Adds support for WoS' LNURL pay mechanics to support
paying to lightning addresses. I'm intentionally
not supporting traditional bech32-encoded LNURLs, as
they are in the process of deprecation.
See https://github.com/lnurl/luds/blob/luds/17.md and
lnurl/luds#66 (comment)

Closes #1

Author: conduition

examples_test.go

@@ -46,12 +46,41 @@ func ExampleCredentials_OpenWallet() {
 		panic(err)
 	}
 
-	fmt.Println(wallet.LightningAddress())
+	fmt.Println(wallet.LightningAddress().String())
 
 	// output:
 	// [email protected]
 }
 
+func ExampleWallet_PayLightningAddress() {
+	creds := wos.Credentials{
+		APIToken:  "edcc867c-96ff-4b0d-ba68-165c16071de0",
+		APISecret: "91ul0rDKV1gANhQWWyEXhdWaSa6aQwAF",
+	}
+
+	ctx := context.Background()
+	wallet, err := creds.OpenWallet(ctx, nil)
+	if err != nil {
+		panic(err)
+	}
+
+	// [email protected]
+	// API token:  6edf02b8-d4e9-4640-b7e4-90bc97f476ab
+	// API secret: sgN5hn2RibvSba1vv260NvwnwVy0oiuh
+
+	lnAddress, err := wos.ParseLightningAddress("[email protected]")
+	if err != nil {
+		panic(err)
+	}
+
+	payment, err := wallet.PayLightningAddress(ctx, lnAddress, "", 0.00000001)
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Println(payment.Status)
+}
+
 type RemoteSigner struct {
 	URL string
 }

lnaddress.go

@@ -0,0 +1,52 @@
+package wos
+
+import (
+	"errors"
+	"regexp"
+	"strings"
+)
+
+// ErrInvalidLightningAddress is returned when parsing an invalid lightning address.
+var ErrInvalidLightningAddress = errors.New("invalid lightning address")
+
+// This misses some edgecases. Might need to adjust in future.
+// https://stackoverflow.com/a/67686133
+var emailRegex = regexp.MustCompile(`^[a-z0-9._%+\-]+@[a-z0-9.\-]+\.[a-z]{2,4}$`)
+
+// LightningAddress is a `[email protected]` internet identifier which
+// allows senders to request lightning invoices by contacting `domain.tld`,
+// who issues invoices on  behalf of the `user`.
+type LightningAddress struct {
+	Username string
+	Domain   string
+}
+
+// String returns the [email protected] format of the address.
+func (a LightningAddress) String() string {
+	return a.Username + "@" + a.Domain
+}
+
+// LNURL returns the HTTPS URL used for LNURL payRequest, as per LUD-16.
+//
+// https://github.com/lnurl/luds/blob/luds/16.md
+func (a LightningAddress) LNURL() string {
+	return "https://" + a.Domain + "/.well-known/lnurlp/" + a.Username
+}
+
+// ParseLightningAddress parses a [LightningAddress] from a string, returning
+// ErrInvalidLightningAddress if the address is not a valid identifier.
+func ParseLightningAddress(lnAddress string) (LightningAddress, error) {
+	if !emailRegex.MatchString(lnAddress) {
+		return LightningAddress{}, ErrInvalidLightningAddress
+	}
+
+	i := strings.Index(lnAddress, "@")
+	username, domain := lnAddress[:i], lnAddress[i+1:]
+
+	addr := LightningAddress{
+		Username: username,
+		Domain:   domain,
+	}
+
+	return addr, nil
+}

wallet.go

@@ -18,6 +18,10 @@ import (
 // BaseURL is the API URL for the Wallet of Satoshi API.
 const BaseURL = "https://www.livingroomofsatoshi.com"
 
+// ErrOutsideSendableRange is returned when sending to a lightning address, but the amount
+// the caller asks to send is outside the range accepted by the receiver.
+var ErrOutsideSendableRange = errors.New("amount to send to LN address is outside the recipient's accepted range")
+
 type errorResponse struct {
 	Message string
 }
@@ -47,6 +51,14 @@ func checkHTTPResponse(resp *http.Response) error {
 	return err
 }
 
+func fromMillisat(sat uint64) float64 {
+	return float64(sat) / 100_000_000.0 / 1_000.0
+}
+
+func toMillisat(amount float64) uint64 {
+	return uint64(amount * 100_000_000 * 1_000)
+}
+
 // Credentials represents a full set of credentials for a WoS wallet.
 type Credentials struct {
 	// APISecret is a base58 secret needed for write-access to a wallet.
@@ -102,7 +114,7 @@ type Wallet struct {
 	signer           Signer
 	httpClient       *http.Client
 	onChainAddress   string
-	lightningAddress string
+	lightningAddress LightningAddress
 }
 
 // OpenWallet opens an existing wallet using a separate [Reader] and [Signer].
@@ -115,12 +127,17 @@ func OpenWallet(ctx context.Context, reader *Reader, signer Signer) (*Wallet, er
 		return nil, fmt.Errorf("OpenWallet: %w", err)
 	}
 
+	lnAddress, err := ParseLightningAddress(addresses.Lightning)
+	if err != nil {
+		return nil, fmt.Errorf("OpenWallet: %w", err)
+	}
+
 	wallet := &Wallet{
 		reader:           reader,
 		signer:           signer,
 		httpClient:       reader.httpClient,
 		onChainAddress:   addresses.OnChain,
-		lightningAddress: addresses.Lightning,
+		lightningAddress: lnAddress,
 	}
 
 	return wallet, nil
@@ -165,6 +182,11 @@ func CreateWallet(ctx context.Context, httpClient *http.Client) (*Wallet, *Crede
 		return nil, nil, fmt.Errorf("error decoding CreateWallet response: %w", err)
 	}
 
+	lnAddress, err := ParseLightningAddress(respStruct.LightningAddress)
+	if err != nil {
+		return nil, nil, fmt.Errorf("CreateWallet: %w", err)
+	}
+
 	creds := &Credentials{
 		APISecret: respStruct.APISecret,
 		APIToken:  respStruct.APIToken,
@@ -175,14 +197,14 @@ func CreateWallet(ctx context.Context, httpClient *http.Client) (*Wallet, *Crede
 		signer:           creds.SimpleSigner(),
 		httpClient:       httpClient,
 		onChainAddress:   respStruct.OnChainAddress,
-		lightningAddress: respStruct.LightningAddress,
+		lightningAddress: lnAddress,
 	}
 
 	return wallet, creds, nil
 }
 
 // LightningAddress returns the wallet's static Lightning Address.
-func (wallet *Wallet) LightningAddress() string {
+func (wallet *Wallet) LightningAddress() LightningAddress {
 	return wallet.lightningAddress
 }
 
@@ -389,6 +411,64 @@ func (wallet *Wallet) PayInvoice(ctx context.Context, invoice, description strin
 	})
 }
 
+// PayLightningAddress executes a payment of the given BTC amount to a
+// given lightning address. The description is stored in the WoS payment history.
+//
+// Returns ErrOutsideSendableRange if the amount to be sent is outside the receiver's
+// acceptable min/max sendable range.
+//
+// Under the hood, this uses the WoS API to proxy your request to [LightningAddress.Domain],
+// so that the recipient does not see your IP address.
+func (wallet *Wallet) PayLightningAddress(
+	ctx context.Context,
+	lnAddress LightningAddress,
+	description string,
+	amount float64,
+) (*Payment, error) {
+	respData, err := wallet.PostRequest(ctx, "/api/v1/wallet/lnurl", map[string]any{
+		"address": lnAddress.LNURL(),
+	})
+	if err != nil {
+		return nil, fmt.Errorf("PayLightningAddress: %w", err)
+	}
+
+	var lnPayResponseBody struct {
+		Callback    string `json:"callback"`
+		MaxSendable uint64 `json:"maxSendable"`
+		MinSendable uint64 `json:"minSendable"`
+	}
+
+	if err := json.Unmarshal(respData, &lnPayResponseBody); err != nil {
+		return nil, fmt.Errorf("PayLightningAddress: invalid response JSON: %w", err)
+	}
+
+	if maxSendable := fromMillisat(lnPayResponseBody.MaxSendable); amount > maxSendable {
+		return nil, fmt.Errorf(
+			"PayLightningAddress: %w: exceeds maxSendable (%f BTC)",
+			ErrOutsideSendableRange, maxSendable,
+		)
+	} else if minSendable := fromMillisat(lnPayResponseBody.MinSendable); amount < minSendable {
+		return nil, fmt.Errorf(
+			"PayLightningAddress: %w: exceeds minSendable (%f BTC)",
+			ErrOutsideSendableRange, minSendable,
+		)
+	}
+
+	respData, err = wallet.PostRequest(ctx, "/api/v1/wallet/lnPay", map[string]any{
+		"amount":   toMillisat(amount),
+		"callback": lnPayResponseBody.Callback,
+	})
+	if err != nil {
+		return nil, fmt.Errorf("PayLightningAddress: %w", err)
+	}
+
+	var payment Payment
+	if err := json.Unmarshal(respData, &payment); err != nil {
+		return nil, fmt.Errorf("PayLightningAddress: invalid response JSON: %w", err)
+	}
+	return &payment, nil
+}
+
 // PayVariableInvoice executes a payment to a given variable-amount lightning invoice.
 // The description is stored in the WoS payment history.
 //