feat: wallet improvements

doc/ndk_flutter/qr-scanner.md

@@ -6,36 +6,145 @@ order: 90
 
 # QR scanner
 
-Some `ndk_flutter` widgets can read a value from a QR code. For example, the wallet widgets
-let the user scan an NWC connection URI (`nostr+walletconnect://...`) instead of typing it.
+The add-wallet flow accepts NWC connection URIs, Lightning and BIP353 addresses, BOLT12
+offers, BIP321 URIs, and HTTPS Cashu mint URLs from one QR scanner.
 
 `ndk_flutter` does **not** bundle a camera/scanner dependency. Instead you provide your own
 scanner, so you stay in control of the camera plugin, runtime permissions, and the UI. When you
-don't provide one, the scan button is hidden and users can still paste a value manually.
+don't provide one, users can still paste a value manually. The shared wallet-input screen is
+the sole add-wallet entry point; the previous intermediate Add Wallet screen no longer exists.
+Your scanner remains responsible for camera-permission rationale and denial handling.
 
 ## Provide a scanner
 
-A scanner is a callback that opens your scanning UI and returns the scanned string, or `null`
-if the user cancels:
+A scanner is a callback that opens your scanning UI and returns a scanned value, a launched
+wallet connection, or `null` if the user cancels:
 
 ```dart
-typedef NwcUriScanner = Future<String?> Function(BuildContext context);
+typedef WalletInputScanner = Future<WalletInputScanResult?> Function(
+  BuildContext context,
+  WalletInputScannerConfiguration configuration,
+);
 ```
 
 Pass it to the widget (or dialog) that needs it. For wallets, that's `NWallets`:
 
 :::code source="../../packages/sample-app/lib/wallets.dart" language="dart" range="72-76" title="wire a scanner into NWallets" :::
 
-The same `nwcUriScanner:` parameter is accepted by the standalone add-wallet dialogs:
+Pass the scanner to the unified dialog directly when you do not use `NWallets`:
 
 ```dart
-showAddNwcWalletDialog(context, ndkFlutter, nwcUriScanner: scanNwcUri);
-showNwcConnectionOptionsDialog(context, ndkFlutter, nwcUriScanner: scanNwcUri);
+showAddWalletTypeDialog(
+  context,
+  ndkFlutter,
+  walletInputScanner: scanWalletInput,
+);
 ```
 
-The widgets validate the scanned value (e.g. that an NWC URI starts with
-`nostr+walletconnect://`) and show an error for anything else, so your callback only needs to
-return the raw scanned string.
+Show `configuration.supportedInputDescription` in the scanner so users know which QR codes
+work. Render `configuration.connectionOptions` beside camera and paste controls to expose the
+standard installed-wallet chooser, Alby Go, custom providers, and web-wallet integrations
+directly from the scanner. Listen to `configuration.connectionState` while an external flow is
+active. Keep the scanner open through `awaitingReturn`, `connecting`, and `failed`; use
+`retryPendingConnection` and `cancelPendingConnection` for retry and back actions. Return
+`WalletInputScanResult.connectionStarted()` after the state reaches `connected`.
+
+The widget classifies and validates scanned values. Return scanned values as
+`WalletInputScanResult.value(rawText)`. For pasted or
+typed values, pass `manuallyEntered: true` so confirmation allows editing.
+Legacy `nwcUriScanner` and `bolt12InputScanner` callbacks remain available on their
+type-specific dialogs.
+
+## Wallet-assisted NWC connections
+
+On Android and iOS, the unified flow includes the standard NWC wallet chooser and Alby Go.
+Add installed or web wallet integrations with `nwcConnectionOptions`:
+
+Alby Go uses the branded `nostr+walletauth+alby://` NWC-08 flow. If direct app launch
+fails because Alby Go is not installed, the same authorization request is shown as a QR
+code. Web and desktop platforms show this QR directly for scanning with Alby Go on a phone.
+The client keeps its generated secret locally, verifies any returned `state` tag,
+discovers the wallet-service public key from its kind `13194` info event, and honors any
+wallet-service `relay` tag.
+
+Wallet-auth requests include `state`. For compatibility with deployed Alby implementations,
+responses and info events may omit it; a present but mismatched state is always rejected.
+Separate-phone QR requests omit `return_to` because no same-device callback is possible.
+
+Coinos uses its fixed service public key and `wss://relay.coinos.io`. Because its info event
+is not addressed to the generated client key, the client subscribes to info events from that
+fixed service key and keeps validating later events until the approved connection works.
+No manual confirmation is required.
+
+```dart
+NWallets(
+  ndkFlutter: ndkFlutter,
+  walletInputScanner: scanWalletInput,
+  nwcConnectionOptions: [
+    NwcConnectionOption(
+      label: 'My web wallet',
+      subtitle: 'Approve the connection in your browser',
+      connect: (context, ndkFlutter, coordinator) {
+        const callback = 'myapp://nwc';
+        return coordinator.connectWithUri(
+          context,
+          launchUri: Uri.parse(
+            'https://wallet.example/connect?callback=myapp%3A%2F%2Fnwc',
+          ),
+          callback: callback,
+          walletName: 'My web wallet',
+        );
+      },
+    ),
+  ],
+)
+```
+
+Client-key web wallets can receive configurable app metadata and a freshly generated public
+key. Default Alby Cloud, Alby Go, and Coinos connections keep a live discovery dialog open
+until a usable info event arrives or the user cancels:
+
+```dart
+NwcConnectionOption(
+  id: 'coinos',
+  label: 'Coinos',
+  connect: (context, ndkFlutter, coordinator) {
+    return coordinator.connectWebWalletAuth(
+      context,
+      authorizationEndpoint: Uri.parse('https://coinos.io/apps/new'),
+      appName: 'My app',
+      discoveryRelay: 'wss://relay.coinos.io',
+      callback: 'myapp://nwc',
+      walletName: 'Coinos',
+      walletServicePubkey:
+          'ba80990666ef0b6f4ba5059347beb13242921e54669e680064ca755256a1e3a6',
+      allowUntaggedInfoEvent: true,
+    );
+  },
+)
+```
+
+Call `NWalletsState.resumePendingWalletAuth()` from mobile resumed lifecycle callbacks.
+Legacy providers without client-tagged discovery events are revalidated every five
+seconds while their connection screen remains open.
+
+Use NWC-07 callback flow to launch `nostrnwc://connect`. Android resolves it using
+normal system intent handling, including user defaults and multiple compatible apps:
+
+```dart
+return coordinator.connectInstalledWallet(
+  context,
+  config: const AlbyGoConnectConfig(
+    appName: 'My app',
+    appIconUrl: 'https://example.com/icon.png',
+    callback: 'myapp://nwc',
+  ),
+);
+```
+
+Forward callback URLs to `NWalletsState.onProtocolUrlReceived`. Wallet-auth callback results
+return `relay_url` and `wallet_pubkey`; when `state` is present, it must match. Legacy providers
+may return a `nostr+walletconnect://` value in a callback query parameter.
 
 ## Example: scanning with mobile_scanner
 
@@ -49,8 +158,7 @@ flutter pub add mobile_scanner
 
 The callback just opens a dialog that wraps the camera view and pops the first decoded value:
 
-:::code source="../../packages/sample-app/lib/nwc_qr_scanner.dart" language="dart" range="8-13" title="scanNwcUri callback" :::
+:::code source="../../packages/sample-app/lib/nwc_qr_scanner.dart" language="dart" range="7-12" title="scanWalletInput callback" :::
 
-The full dialog lives in
-[`packages/sample-app/lib/nwc_qr_scanner.dart`](https://github.com/relaystr/ndk/blob/master/packages/sample-app/lib/nwc_qr_scanner.dart).
-It adds a camera preview, a paste fallback, error handling, and a desktop/web-safe layout.
+`packages/sample-app/lib/nwc_qr_scanner.dart` only adapts the host camera implementation.
+Wallet choices, paste/manual input, errors, and layout live in `ndk_flutter`.

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,47 @@
 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',
+      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

@@ -20,6 +20,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,12 @@ 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}');