feat: bip321 & bolt12 support for NWC & wallets

packages/ndk/example/nwc/README.md

@@ -9,3 +9,19 @@ see https://github.com/getAlby/awesome-nwc for more info how to get a wallet sup
 for more logging
 
 `NWC_URI=nostr+walletconnect://.... dart --enable-asserts connect_get_info.dart`
+
+## NWC-321 pay and receive
+
+Pay a BOLT11 invoice through a BIP-321 `lightning` instruction:
+
+`NWC_URI=nostr+walletconnect://.... INVOICE=lnbc... dart pay.dart`
+
+If the invoice has no amount, also provide `AMOUNT_MSAT`:
+
+`NWC_URI=nostr+walletconnect://.... INVOICE=lnbc... AMOUNT_MSAT=21000 dart pay.dart`
+
+Create a fixed-amount BIP-321 URI containing a BOLT11 instruction:
+
+`NWC_URI=nostr+walletconnect://.... AMOUNT_MSAT=21000 DESCRIPTION=hello dart receive.dart`
+
+Omit `AMOUNT_MSAT` to request a variable-amount URI.

packages/ndk/example/nwc/connect_get_info.dart

@@ -16,6 +16,7 @@ void main() async {
 
   if (connection.info != null) {
     print("alias: ${connection.info!.alias}");
+    print("methods: ${connection.info!.methods}");
     if (connection.info!.pubkey != null) {
       print("pubkey: ${connection.info!.pubkey}");
     }

packages/ndk/example/nwc/pay.dart

@@ -0,0 +1,39 @@
+// ignore_for_file: avoid_print
+
+import 'dart:io';
+
+import 'package:ndk/ndk.dart';
+
+void main() async {
+  final ndk = Ndk.emptyBootstrapRelaysConfig();
+
+  // Provide an NWC connection URI and the BOLT11 invoice to pay.
+  final nwcUri = Platform.environment['NWC_URI']!;
+  final invoice = Platform.environment['INVOICE']!;
+  final amountMsat = int.tryParse(
+    Platform.environment['AMOUNT_MSAT'] ?? '',
+  );
+
+  final connection = await ndk.nwc.connect(nwcUri);
+
+  // NWC-321 expects a BIP-321 URI. This example contains only a BOLT11
+  // `lightning` instruction.
+  final payment = Bip321.fromBolt11(invoice);
+
+  final response = await ndk.nwc.pay(
+    connection,
+    payment: payment,
+    // Required only when the BOLT11 invoice has no amount.
+    amountMsat: amountMsat,
+    payerNote: Platform.environment['PAYER_NOTE'],
+  );
+
+  print('transaction id: ${response.transactionId}');
+  print('state: ${response.state}');
+  print('instruction type: ${response.instructionType}');
+  print('amount: ${response.amountMsat} msats');
+  print('fees paid: ${response.feesPaid} msats');
+  print('preimage: ${response.preimage}');
+
+  await ndk.destroy();
+}

packages/ndk/example/nwc/receive.dart

@@ -0,0 +1,29 @@
+// ignore_for_file: avoid_print
+
+import 'dart:io';
+
+import 'package:ndk/ndk.dart';
+
+void main() async {
+  final ndk = Ndk.emptyBootstrapRelaysConfig();
+
+  // Provide an NWC connection URI. Omit AMOUNT_MSAT for a variable amount.
+  final nwcUri = Platform.environment['NWC_URI']!;
+  final amountMsat = int.tryParse(
+    Platform.environment['AMOUNT_MSAT'] ?? '',
+  );
+
+  final connection = await ndk.nwc.connect(nwcUri);
+  final response = await ndk.nwc.receive(
+    connection,
+    amountMsat: amountMsat,
+    description: Platform.environment['DESCRIPTION'],
+  );
+
+  // For now, use a wallet whose `receive` implementation returns a BOLT11
+  // `lightning` instruction in this BIP-321 URI.
+  print('BIP-321 URI: ${response.bip321}');
+  print('transaction id: ${response.transactionId}');
+
+  await ndk.destroy();
+}

packages/ndk/lib/domain_layer/entities/wallet/bip321.dart

@@ -0,0 +1,86 @@
+/// Helpers for BIP-321 URIs containing BOLT11 payment instructions.
+class Bip321 {
+  Bip321._();
+
+  /// Creates a BIP-321 URI containing one BOLT11 `lightning` instruction.
+  static String fromBolt11(String invoice) {
+    if (!invoice.toLowerCase().startsWith('ln')) {
+      throw ArgumentError.value(invoice, 'invoice', 'Must be a BOLT11 invoice');
+    }
+    return Uri(
+      scheme: 'bitcoin',
+      queryParameters: {'lightning': invoice},
+    ).toString();
+  }
+
+  /// Selects the single BOLT11 `lightning` instruction from [payment].
+  static String getBolt11(String payment) {
+    final Uri uri;
+    try {
+      uri = Uri.parse(payment);
+    } on FormatException {
+      throw FormatException('Invalid BIP-321 URI', payment);
+    }
+
+    if (uri.scheme.toLowerCase() != 'bitcoin') {
+      throw FormatException('BIP-321 URI must use the bitcoin scheme', payment);
+    }
+
+    final requiredParameters = uri.queryParametersAll.keys.where(
+      (key) => key.startsWith('req-'),
+    );
+    if (requiredParameters.isNotEmpty) {
+      throw UnsupportedError(
+        'Unsupported required BIP-321 parameter: '
+        '${requiredParameters.first}',
+      );
+    }
+
+    final instructions = uri.queryParametersAll['lightning'];
+    if (instructions == null ||
+        instructions.length != 1 ||
+        instructions.single.isEmpty) {
+      throw const FormatException(
+        'BIP-321 URI must contain one lightning instruction',
+      );
+    }
+
+    final invoice = instructions.single;
+    if (!invoice.toLowerCase().startsWith('ln')) {
+      throw const FormatException('Invalid BOLT11 lightning instruction');
+    }
+    return invoice;
+  }
+
+  /// Returns the BOLT11 amount in millisatoshis, or null when amountless.
+  static int? getBolt11AmountMsat(String invoice) {
+    final separator = invoice.toLowerCase().lastIndexOf('1');
+    if (separator < 0) {
+      throw const FormatException('Invalid BOLT11 invoice');
+    }
+
+    final hrp = invoice.toLowerCase().substring(0, separator);
+    final match = RegExp(
+      r'^ln(?:bcrt|bc|tb|sb)([0-9]*)([munp]?)$',
+    ).firstMatch(hrp);
+    if (match == null) {
+      throw const FormatException('Invalid BOLT11 invoice prefix');
+    }
+
+    final digits = match.group(1)!;
+    if (digits.isEmpty) return null;
+
+    final amount = int.parse(digits);
+    return switch (match.group(2)!) {
+      '' => amount * 100000000000,
+      'm' => amount * 100000000,
+      'u' => amount * 100000,
+      'n' => amount * 100,
+      'p' when amount % 10 == 0 => amount ~/ 10,
+      'p' => throw const FormatException(
+          'BOLT11 pico-bitcoin amount is not a whole millisatoshi',
+        ),
+      _ => throw const FormatException('Invalid BOLT11 amount multiplier'),
+    };
+  }
+}

packages/ndk/lib/domain_layer/entities/wallet/providers/cashu/cashu_wallet_provider.dart

@@ -2,7 +2,10 @@ import 'dart:async';
 
 import '../../../../usecases/cashu/cashu.dart';
 import '../../../../usecases/nwc/responses/pay_invoice_response.dart';
+import '../../../../usecases/nwc/responses/pay_response.dart';
+import '../../../../usecases/nwc/responses/receive_response.dart';
 import '../../../cashu/cashu_mint_info.dart';
+import '../../bip321.dart';
 import '../../wallet.dart';
 import '../../wallet_balance.dart';
 import '../../wallet_provider.dart';
@@ -119,16 +122,39 @@ class CashuWalletProvider implements WalletProvider {
       throw ArgumentError('Expected a CashuWallet');
     }
 
+    final result = await _payBolt11(wallet, invoice, timeout: timeout);
+    return result.legacyResponse;
+  }
+
+  Future<_CashuBolt11Payment> _payBolt11(
+    CashuWallet wallet,
+    String invoice, {
+    int? expectedAmountMsat,
+    Duration? timeout,
+  }) async {
     final draftTransaction = await _cashuUseCase.initiateRedeem(
       mintUrl: wallet.mintUrl,
       request: invoice,
       unit: 'sat',
       method: 'bolt11',
     );
 
-    await for (final transaction in _cashuUseCase.redeem(
+    final amountMsat = draftTransaction.qouteMelt!.amount * 1000;
+    if (expectedAmountMsat != null && amountMsat != expectedAmountMsat) {
+      throw ArgumentError(
+        'BIP-321 amount $expectedAmountMsat msats conflicts with '
+        'the BOLT11 invoice amount $amountMsat msats',
+      );
+    }
+
+    var transactions = _cashuUseCase.redeem(
       draftRedeemTransaction: draftTransaction,
-    )) {
+    );
+    if (timeout != null) {
+      transactions = transactions.timeout(timeout);
+    }
+
+    await for (final transaction in transactions) {
       if (transaction.state == WalletTransactionState.completed) {
         final int feesPaid;
         if (draftTransaction.qouteMelt?.feeReserve != null) {
@@ -137,11 +163,19 @@ class CashuWalletProvider implements WalletProvider {
           feesPaid = 0;
         }
 
-        return PayInvoiceResponse(
+        final legacyResponse = PayInvoiceResponse(
           resultType: 'pay_invoice',
           preimage: null,
           feesPaid: feesPaid,
         );
+        return _CashuBolt11Payment(
+          legacyResponse: legacyResponse,
+          transactionId: draftTransaction.id,
+          amountMsat: amountMsat,
+          createdAt: draftTransaction.initiatedDate ??
+              DateTime.now().millisecondsSinceEpoch ~/ 1000,
+          settledAt: transaction.transactionDate,
+        );
       } else if (transaction.state == WalletTransactionState.failed) {
         throw Exception('Cashu payment failed: ${transaction.completionMsg}');
       }
@@ -195,4 +229,111 @@ class CashuWalletProvider implements WalletProvider {
 
     return invoice;
   }
+
+  @override
+  Future<PayResponse> payBip321(
+    Wallet wallet, {
+    required String payment,
+    int? amountMsat,
+    String? payerNote,
+    Map<String, dynamic>? metadata,
+    Duration? timeout,
+  }) async {
+    if (wallet is! CashuWallet) {
+      throw ArgumentError('Expected a CashuWallet');
+    }
+    if (payerNote?.isNotEmpty == true) {
+      throw UnsupportedError('BOLT11 does not support payer notes');
+    }
+
+    final invoice = Bip321.getBolt11(payment);
+    final invoiceAmountMsat = Bip321.getBolt11AmountMsat(invoice);
+    if (invoiceAmountMsat == null) {
+      throw UnsupportedError(
+        'Cashu does not support paying amountless BOLT11 invoices',
+      );
+    }
+    if (invoiceAmountMsat % 1000 != 0) {
+      throw UnsupportedError(
+        'Cashu only supports whole-satoshi BOLT11 amounts',
+      );
+    }
+    if (amountMsat != null && amountMsat != invoiceAmountMsat) {
+      throw ArgumentError(
+        'BIP-321 amount $amountMsat msats conflicts with '
+        'the BOLT11 invoice amount $invoiceAmountMsat msats',
+      );
+    }
+
+    final result = await _payBolt11(
+      wallet,
+      invoice,
+      expectedAmountMsat: invoiceAmountMsat,
+      timeout: timeout,
+    );
+    return PayResponse(
+      resultType: 'pay',
+      transactionId: result.transactionId,
+      state: 'settled',
+      instructionType: 'bolt11',
+      amountMsat: result.amountMsat,
+      feesPaid: result.legacyResponse.feesPaid,
+      preimage: result.legacyResponse.preimage,
+      createdAt: result.createdAt,
+      settledAt: result.settledAt,
+    );
+  }
+
+  @override
+  Future<ReceiveResponse> receiveBip321(
+    Wallet wallet, {
+    int? amountMsat,
+    String? description,
+    Map<String, dynamic>? metadata,
+    Duration? timeout,
+  }) async {
+    if (amountMsat == null) {
+      throw UnsupportedError(
+        'Cashu does not support variable-amount BOLT11 invoices',
+      );
+    }
+    if (amountMsat <= 0 || amountMsat % 1000 != 0) {
+      throw ArgumentError.value(
+        amountMsat,
+        'amountMsat',
+        'Cashu requires a positive whole-satoshi amount',
+      );
+    }
+    if (description?.isNotEmpty == true) {
+      throw UnsupportedError(
+        'Cashu does not support setting a BOLT11 description',
+      );
+    }
+
+    var invoiceFuture = receive(wallet, amountMsat ~/ 1000);
+    if (timeout != null) {
+      invoiceFuture = invoiceFuture.timeout(timeout);
+    }
+    final invoice = await invoiceFuture;
+    return ReceiveResponse(
+      resultType: 'receive',
+      bip321: Bip321.fromBolt11(invoice),
+    );
+  }
+}
+
+class _CashuBolt11Payment {
+  final PayInvoiceResponse legacyResponse;
+  final String transactionId;
+  final int amountMsat;
+  final int createdAt;
+  final int? settledAt;
+
+  const _CashuBolt11Payment({
+    required this.legacyResponse,
+    required this.transactionId,
+    required this.amountMsat,
+    required this.createdAt,
+    required this.settledAt,
+  });
 }