feat: bip321 & bolt12 support for NWC & wallets

doc/library-development/publish.md

@@ -8,6 +8,10 @@ order: 100
 
 ## publish to github
 
+make sure ndk version.dart is up to date with version from pubspec.yaml, if not run:
+
+`dart run build_runner build --delete-conflicting-outputs`
+
 Create a tag
 `git tag -a v1.2.3 -m "Release v1.2.3"`
 

packages/drift/lib/src/drift_cache_manager.dart

@@ -10,12 +10,7 @@ import 'package:ndk/domain_layer/entities/nip_65.dart';
 import 'package:ndk/domain_layer/entities/pubkey_mapping.dart';
 import 'package:ndk/domain_layer/entities/read_write_marker.dart';
 import 'package:ndk/domain_layer/entities/user_relay_list.dart';
-import 'package:ndk/domain_layer/entities/wallet/providers/cashu/cashu_wallet.dart';
-import 'package:ndk/domain_layer/entities/wallet/providers/nwc/nwc_wallet.dart';
-import 'package:ndk/domain_layer/entities/wallet/providers/lnurl/lnurl_wallet.dart';
-import 'package:ndk/domain_layer/entities/wallet/wallet.dart';
-import 'package:ndk/domain_layer/entities/wallet/wallet_transaction.dart';
-import 'package:ndk/domain_layer/entities/wallet/wallet_type.dart';
+import 'package:ndk/domain_layer/entities/wallet/wallet_factory.dart';
 import 'package:ndk/domain_layer/repositories/wallets_repo.dart';
 import 'package:ndk/ndk.dart';
 import 'package:ndk/shared/nips/nip01/event_kind_classification.dart';
@@ -1968,37 +1963,13 @@ class DriftCacheManager extends WalletsRepo implements CacheManager {
         .map((e) => e.toString())
         .toSet();
 
-    switch (type) {
-      case WalletType.CASHU:
-        return CashuWallet(
-          id: row.id,
-          name: row.name,
-          supportedUnits: supportedUnits,
-          mintUrl: metadata['mintUrl'] as String,
-          mintInfo: CashuMintInfo.fromJson(
-            metadata['mintInfo'] as Map<String, dynamic>,
-            mintUrl: metadata['mintUrl'] as String,
-          ),
-        );
-      case WalletType.NWC:
-        return NwcWallet(
-          id: row.id,
-          name: row.name,
-          supportedUnits: supportedUnits,
-          nwcUrl: metadata['nwcUrl'] as String,
-        );
-      case WalletType.LNURL:
-        return LnurlWallet(
-          id: row.id,
-          name: row.name,
-          supportedUnits: supportedUnits,
-          identifier: metadata['identifier'] as String,
-          lnurlPayUrl: metadata['lnurlPayUrl'] as String,
-          minSendable: metadata['minSendable'] as int?,
-          maxSendable: metadata['maxSendable'] as int?,
-          metadataFetchedAt: metadata['metadataFetchedAt'] as int?,
-        );
-    }
+    return WalletFactory.fromStorage(
+      id: row.id,
+      name: row.name,
+      type: type,
+      supportedUnits: supportedUnits,
+      metadata: metadata,
+    );
   }
 
   @override

packages/drift/test/drift_cache_manager_test.dart

@@ -1,10 +1,48 @@
 import 'package:drift/native.dart';
 import 'package:flutter_test/flutter_test.dart';
-import 'package:ndk/domain_layer/entities/event_cache_records.dart';
+import 'package:ndk/entities.dart';
 import 'package:ndk_drift/ndk_drift.dart';
 import 'package:ndk_cache_manager_test_suite/ndk_cache_manager_test_suite.dart';
 
 void main() {
+  test('persists and restores a BOLT12 wallet', () async {
+    final db = NdkCacheDatabase.forTesting(NativeDatabase.memory());
+    final cacheManager = DriftCacheManager(db);
+    const offer =
+        'lno1pqqq5xj5wajkcan9gdshx6pq23jhxarfdenjqstyv3ex2umnzcss80xkrjkyrjk43u5dgu8f6a450fg2cnjtg7lhg76c3gtk5gdhshns';
+    final wallet = Bolt12Wallet(
+      id: 'bolt12-test',
+      name: 'BOLT12 test wallet',
+      supportedUnits: const {'sat'},
+      offer: offer,
+      source: 'alice@example.com',
+      bip353Address: 'alice@example.com',
+      description: 'Test offer',
+      offerId: 'offer-id',
+      issuer: 'Test issuer',
+      currency: 'USD',
+      expiresAt: 2000000000,
+      quantityMax: 10,
+      hasBlindedPaths: true,
+      metadata: const {'cardColor': 123},
+    );
+
+    await cacheManager.storeWallet(wallet);
+    final restored = await cacheManager.getWallet(wallet.id) as Bolt12Wallet;
+
+    expect(restored.offer, offer);
+    expect(restored.bip353Address, wallet.bip353Address);
+    expect(restored.description, wallet.description);
+    expect(restored.issuer, wallet.issuer);
+    expect(restored.currency, wallet.currency);
+    expect(restored.expiresAt, wallet.expiresAt);
+    expect(restored.quantityMax, wallet.quantityMax);
+    expect(restored.hasBlindedPaths, isTrue);
+    expect(restored.metadata['cardColor'], 123);
+
+    await cacheManager.close();
+  });
+
   test('persists full event delivery record state', () async {
     final db = NdkCacheDatabase.forTesting(NativeDatabase.memory());
     final cacheManager = DriftCacheManager(db);

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

@@ -17,6 +17,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/example/wallets/send.dart

@@ -7,7 +7,8 @@ import 'package:ndk/domain_layer/entities/cashu/cashu_user_seedphrase.dart';
 import 'package:ndk/ndk.dart';
 
 Future<void> main() async {
-  final invoice = Platform.environment['INVOICE']!;
+  final payment = Platform.environment['PAYMENT']!;
+  final amountSats = int.parse(Platform.environment['AMOUNT'] ?? '1000');
 
   final ndk = Ndk(
     NdkConfig(
@@ -29,10 +30,11 @@ Future<void> main() async {
 
     final walletId = Platform.environment['WALLET_ID'] ?? wallets.first.id;
 
-    final result = await ndk.wallets.send(walletId: walletId, invoice: invoice);
+    final result = await ndk.wallets.payBip321(walletId: walletId, payment: payment, amountMsat: amountSats * 1000);
 
     print('Payment result:');
     print('- preimage: ${result.preimage}');
+    print('- payerProof: ${result.payerProof}');
     print('- fees paid: ${result.feesPaid / 1000} sats');
     if (result.errorCode != null || result.errorMessage != null) {
       print('- error code: ${result.errorCode}');

packages/ndk/lib/data_layer/models/wallet_transaction_model.dart

@@ -19,6 +19,7 @@ class WalletTransactionModel {
       case WalletType.NWC:
         return NwcWalletTransactionModel.fromJson(json);
       case WalletType.LNURL:
+      case WalletType.BOLT12:
         return LnurlWalletTransactionModel.fromJson(json);
     }
   }

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'),
+    };
+  }
+}