@lightninglabs/wavelength-react-native 0.1.0

package/src/client.test.ts

@@ -0,0 +1,307 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import {
+  NativeWavelengthClient,
+  type NativeActivityEvent,
+  type WavelengthNativeModule,
+} from './client.ts';
+import type { WavelengthEvent } from '@lightninglabs/wavelength-core';
+
+// A scriptable fake of the native module: records calls, replays canned JSON,
+// and hands the test the event listener so it can inject activity events.
+function makeFake() {
+  const calls: Array<{ method: string; paramsJson: string }> = [];
+  const responses = new Map<string, string>();
+  const startActivityRequests: string[] = [];
+  let startActivityCount = 0;
+  let stopActivityCount = 0;
+  let stopActivityRejects = false;
+  let deferredStop: { promise: Promise<void>; resolve: () => void } | null = null;
+  let listener: ((event: NativeActivityEvent) => void) | null = null;
+  let unsubscribed = 0;
+
+  const native: WavelengthNativeModule = {
+    call(method, paramsJson) {
+      calls.push({ method, paramsJson });
+      const canned = responses.get(method);
+      if (canned === 'REJECT') {
+        return Promise.reject(new Error('boom'));
+      }
+      return Promise.resolve(canned ?? '');
+    },
+    startActivity(reqJson) {
+      startActivityCount += 1;
+      startActivityRequests.push(reqJson);
+      return Promise.resolve();
+    },
+    stopActivity() {
+      stopActivityCount += 1;
+      if (deferredStop) {
+        return deferredStop.promise;
+      }
+      return stopActivityRejects
+        ? Promise.reject(new Error('close failed'))
+        : Promise.resolve();
+    },
+    getDefaultDataDir() {
+      return Promise.resolve('/data/wavelength');
+    },
+  };
+
+  const subscribe = (l: (event: NativeActivityEvent) => void) => {
+    listener = l;
+    return () => {
+      unsubscribed += 1;
+      listener = null;
+    };
+  };
+
+  return {
+    native,
+    subscribe,
+    calls,
+    responses,
+    startActivityRequests,
+    failStopActivity: () => {
+      stopActivityRejects = true;
+    },
+    deferStopActivity: () => {
+      let resolve!: () => void;
+      const promise = new Promise<void>((r) => {
+        resolve = r;
+      });
+      deferredStop = { promise, resolve };
+      return () => deferredStop!.resolve();
+    },
+    emit: (e: NativeActivityEvent) => listener?.(e),
+    counts: () => ({ startActivityCount, stopActivityCount, unsubscribed }),
+  };
+}
+
+describe('NativeWavelengthClient', () => {
+  it('callFacade parses a native scalar JSON response', async () => {
+    const fake = makeFake();
+    const client = new NativeWavelengthClient(fake.native, fake.subscribe);
+    fake.responses.set('isRunning', 'true');
+
+    assert.equal(await client.callFacade('isRunning'), true);
+    assert.equal(fake.calls[0].method, 'isRunning');
+  });
+
+  it('normalizes a native JSON facade response in core', async () => {
+    const fake = makeFake();
+    const client = new NativeWavelengthClient(fake.native, fake.subscribe);
+    fake.responses.set('list', JSON.stringify({
+      View: 'activity',
+      Activity: { Entries: null },
+      VTXOs: null,
+      Onchain: null,
+    }));
+
+    assert.deepEqual(await client.callFacade('list'), {
+      view: 'activity',
+      activity: { entries: [] },
+      vtxos: undefined,
+      onchain: undefined,
+    });
+  });
+
+  it('start injects the platform data dir and dials grpc', async () => {
+    const fake = makeFake();
+    const client = new NativeWavelengthClient(fake.native, fake.subscribe);
+    fake.responses.set('getInfo', '{"WalletState":0}');
+
+    await client.start({ network: 'regtest', arkServerAddress: 'h:7070' });
+
+    const cfg = JSON.parse(fake.calls[0].paramsJson) as Record<string, unknown>;
+    assert.equal(cfg.data_dir, '/data/wavelength');
+    assert.equal(cfg.server_transport, 'grpc');
+    assert.equal(cfg.server_address, 'h:7070');
+    assert.equal(fake.calls[1].method, 'getInfo');
+  });
+
+  it('start keeps an explicit dataDir', async () => {
+    const fake = makeFake();
+    const client = new NativeWavelengthClient(fake.native, fake.subscribe);
+    fake.responses.set('getInfo', '{}');
+
+    await client.start({ network: 'regtest', dataDir: '/custom' });
+
+    const cfg = JSON.parse(fake.calls[0].paramsJson) as Record<string, unknown>;
+    assert.equal(cfg.data_dir, '/custom');
+  });
+
+  it('wraps native rejections in WavelengthError', async () => {
+    const fake = makeFake();
+    const client = new NativeWavelengthClient(fake.native, fake.subscribe);
+    fake.responses.set('getInfo', 'REJECT');
+
+    await assert.rejects(client.getInfo(), (err: Error) => {
+      assert.equal(err.name, 'WavelengthError');
+      assert.equal(err.message, 'boom');
+      return true;
+    });
+  });
+
+  it('startActivity opens once and re-emits entries camelized', async () => {
+    const fake = makeFake();
+    const client = new NativeWavelengthClient(fake.native, fake.subscribe);
+    const events: WavelengthEvent[] = [];
+    client.subscribe((e) => events.push(e));
+
+    await client.startActivity({
+      includeExisting: true,
+      kinds: ['send', 'exit'],
+      cursor: 99,
+    });
+    await client.startActivity();
+    assert.equal(fake.counts().startActivityCount, 1);
+    assert.deepEqual(JSON.parse(fake.startActivityRequests[0]), {
+      includeExisting: true,
+      kinds: ['send', 'exit'],
+      cursor: 99,
+    });
+
+    fake.emit({
+      kind: 'entry',
+      payload: '{"Kind":"send","Progress":null,"Request":null}',
+    });
+    assert.deepEqual(events, [
+      {
+        type: 'activity',
+        payload: { kind: 'send', progress: undefined, request: undefined },
+      },
+    ]);
+  });
+
+  it('emits activityStream failed on a native error and allows reopening', async () => {
+    const fake = makeFake();
+    const client = new NativeWavelengthClient(fake.native, fake.subscribe);
+    const events: WavelengthEvent[] = [];
+    client.subscribe((e) => events.push(e));
+
+    await client.startActivity();
+    fake.emit({ kind: 'error', payload: 'stream broke' });
+
+    assert.deepEqual(events, [
+      {
+        type: 'activityStream',
+        payload: { state: 'failed', message: 'stream broke' },
+      },
+    ]);
+
+    await client.startActivity();
+    assert.equal(fake.counts().startActivityCount, 2);
+  });
+
+  it('emits activityStream ended on an unexpected native end and allows reopening', async () => {
+    const fake = makeFake();
+    const client = new NativeWavelengthClient(fake.native, fake.subscribe);
+    const events: WavelengthEvent[] = [];
+    client.subscribe((e) => events.push(e));
+
+    await client.startActivity();
+    fake.emit({ kind: 'end', payload: '' });
+
+    assert.deepEqual(events, [
+      { type: 'activityStream', payload: { state: 'ended' } },
+    ]);
+
+    await client.startActivity();
+    assert.equal(fake.counts().startActivityCount, 2);
+  });
+
+  it('serializes a stop-then-start so the subscribe waits for the close', async () => {
+    const fake = makeFake();
+    const client = new NativeWavelengthClient(fake.native, fake.subscribe);
+
+    await client.startActivity();
+    assert.equal(fake.counts().startActivityCount, 1);
+
+    const resolveStop = fake.deferStopActivity();
+    client.stopActivity();
+    const secondStart = client.startActivity();
+    // Let the chain advance as far as it can while the stop is still pending.
+    await Promise.resolve();
+    await Promise.resolve();
+    // The second subscribe must not have fired while the close is in flight.
+    assert.equal(fake.counts().startActivityCount, 1);
+
+    resolveStop();
+    await secondStart;
+    // Once the close resolved, the serialized start subscribed.
+    assert.equal(fake.counts().startActivityCount, 2);
+  });
+
+  it('drops an unparseable activity entry with a contextual log', async () => {
+    const fake = makeFake();
+    const client = new NativeWavelengthClient(fake.native, fake.subscribe);
+    const events: WavelengthEvent[] = [];
+    client.subscribe((e) => events.push(e));
+
+    await client.startActivity();
+    fake.emit({ kind: 'entry', payload: '{not json' });
+
+    assert.equal(events.length, 1);
+    assert.equal(events[0].type, 'log');
+    const payload = events[0].payload as { level: string; message: string };
+    assert.equal(payload.level, 'error');
+    assert.match(payload.message, /dropped an unparseable activity entry/);
+  });
+
+  it('logs a warning when the native close fails', async () => {
+    const fake = makeFake();
+    const client = new NativeWavelengthClient(fake.native, fake.subscribe);
+    const events: WavelengthEvent[] = [];
+    client.subscribe((e) => events.push(e));
+
+    await client.startActivity();
+    fake.failStopActivity();
+    client.stopActivity();
+    // The rejection is handled asynchronously; let the microtask run.
+    await Promise.resolve();
+    await Promise.resolve();
+
+    assert.equal(events.length, 1);
+    const payload = events[0].payload as { level: string; message: string };
+    assert.equal(payload.level, 'warn');
+    assert.match(payload.message, /failed to close the activity stream/);
+  });
+
+  it('stopActivity and dispose release native resources', async () => {
+    const fake = makeFake();
+    const client = new NativeWavelengthClient(fake.native, fake.subscribe);
+    await client.startActivity();
+
+    client.stopActivity();
+    // The stop runs on the serialized op chain; let it settle before asserting.
+    await Promise.resolve();
+    await Promise.resolve();
+    assert.equal(fake.counts().stopActivityCount, 1);
+
+    client.dispose();
+    assert.equal(fake.counts().unsubscribed, 1);
+  });
+
+  it('closes the native stream when disposed with an open subscription', async () => {
+    const fake = makeFake();
+    const client = new NativeWavelengthClient(fake.native, fake.subscribe);
+    const events: WavelengthEvent[] = [];
+    client.subscribe((e) => events.push(e));
+
+    await client.startActivity();
+    client.dispose();
+    // dispose enqueues the native close on the op chain; let it settle.
+    await Promise.resolve();
+    await Promise.resolve();
+
+    // The subscription must actually be closed, not leaked.
+    assert.equal(fake.counts().stopActivityCount, 1);
+    // A terminal end after a client-initiated dispose stays silent.
+    fake.emit({ kind: 'end', payload: '' });
+    assert.deepEqual(
+      events.filter((e) => e.type === 'activityStream'),
+      [],
+    );
+  });
+});

package/src/client.ts

@@ -0,0 +1,222 @@
+import {
+  BaseWavelengthClient,
+  WavelengthError,
+  errorMessage,
+} from '@lightninglabs/wavelength-core';
+import type {
+  ActivityStreamOptions,
+  Entry,
+  FacadeMethod,
+  RuntimeConfig,
+  WalletInfo,
+} from '@lightninglabs/wavelength-core';
+
+/**
+ * The subset of the native Turbo Module the client depends on. Narrowed to an
+ * interface (rather than the generated Spec) so unit tests can inject a fake
+ * without loading react-native.
+ */
+export type WavelengthNativeModule = {
+  /** Invokes a facade verb by name with a JSON payload, returning JSON. */
+  call(method: string, paramsJson: string): Promise<string>;
+  /** Opens the native activity subscription. */
+  startActivity(reqJson: string): Promise<void>;
+  /** Closes the native activity subscription. */
+  stopActivity(): Promise<void>;
+  /** Resolves the platform default wallet data directory. */
+  getDefaultDataDir(): Promise<string>;
+};
+
+/**
+ * One 'wavelengthActivity' device event from the native side: an activity
+ * entry, a clean end of stream, or a stream error.
+ */
+export type NativeActivityEvent = {
+  /** The native pump's event kind. */
+  kind: 'entry' | 'end' | 'error';
+  /** The entry JSON for 'entry', the error message for 'error', else ''. */
+  payload: string;
+};
+
+/**
+ * Subscribes a listener to the native 'wavelengthActivity' events and
+ * returns an unsubscribe function. The factory wires this to
+ * NativeEventEmitter; unit tests supply their own.
+ */
+export type SubscribeToNativeEvents = (
+  listener: (event: NativeActivityEvent) => void,
+) => () => void;
+
+  /**
+ * The React Native transport: implements {@link BaseWavelengthClient}'s pipe
+ * over the gomobile Turbo Module. JSON strings cross the RN bridge, then the
+ * shared base client normalizes responses and streamed entries in TS.
+  */
+export class NativeWavelengthClient extends BaseWavelengthClient {
+  // The embedded daemon runs natively, so it dials the servers over gRPC.
+  protected readonly serverTransport = 'grpc' as const;
+
+  private removeNativeListener: (() => void) | null = null;
+  // Serializes start/stop native ops so a start always waits for a pending
+  // stop's native close to finish before it subscribes.
+  private opChain: Promise<void> = Promise.resolve();
+  // Whether a native subscription is currently open. Only read and written
+  // inside serialized ops, so it never races.
+  private streamOpen = false;
+  private native: WavelengthNativeModule;
+  private subscribeToNativeEvents: SubscribeToNativeEvents;
+
+  constructor(
+    native: WavelengthNativeModule,
+    subscribeToNativeEvents: SubscribeToNativeEvents,
+  ) {
+    super();
+    this.native = native;
+    this.subscribeToNativeEvents = subscribeToNativeEvents;
+  }
+
+  // enqueue runs op after the previous op settles, whether it fulfilled or
+  // rejected, so a rejected native call cannot stall the chain.
+  private enqueue(op: () => Promise<void>): Promise<void> {
+    const next = this.opChain.then(op, op);
+    this.opChain = next;
+
+    return next;
+  }
+
+  // The runtime is compiled into the app binary, so there is nothing to load.
+  ready(): Promise<void> {
+    return Promise.resolve();
+  }
+
+  // start fills in the platform default data directory when the caller did
+  // not choose one; only the native side knows the app's sandbox paths.
+  override async start(config: RuntimeConfig): Promise<WalletInfo> {
+    return super.start({
+      ...config,
+      dataDir: config.dataDir ?? (await this.native.getDefaultDataDir()),
+    });
+  }
+
+  protected async invokeFacade<T = unknown>(
+    method: FacadeMethod,
+    params: unknown = {},
+  ): Promise<T> {
+    try {
+      const resultJson = await this.native.call(
+        method,
+        JSON.stringify(params ?? {}),
+      );
+
+      return (resultJson ? JSON.parse(resultJson) : null) as T;
+    } catch (err) {
+      throw new WavelengthError(errorMessage(err), 'wavelength_error', {
+        cause: err,
+      });
+    }
+  }
+
+  // startActivity opens the native pull subscription; the native side pumps
+  // entries to 'wavelengthActivity' device events, which are re-emitted here
+  // as typed 'activity' events. Idempotent while a stream is open.
+  protected async openActivityStream(
+    opts: ActivityStreamOptions,
+  ): Promise<void> {
+    return this.enqueue(async () => {
+      if (this.streamOpen) {
+        return;
+      }
+      this.removeNativeListener ??= this.subscribeToNativeEvents((event) =>
+        this.onNativeEvent(event),
+      );
+      await this.native.startActivity(
+        JSON.stringify({
+          includeExisting: opts.includeExisting ?? false,
+          kinds: opts.kinds ?? [],
+          cursor: opts.cursor ?? 0,
+        }),
+      );
+      this.streamOpen = true;
+    });
+  }
+
+  stopActivity(): void {
+    void this.enqueue(async () => {
+      if (!this.streamOpen) {
+        return;
+      }
+      // Native stop detaches the old subscription before close and emits no
+      // terminal event for it, so a queued start can safely open a new pump.
+      this.streamOpen = false;
+      try {
+        await this.native.stopActivity();
+      } catch (err) {
+        // A failed native close means the pump may still be running; surface
+        // it instead of swallowing so a zombie stream is at least diagnosable.
+        this.emit({
+          type: 'log',
+          payload: {
+            level: 'warn',
+            message: `failed to close the activity stream: ${errorMessage(err)}`,
+          },
+        });
+      }
+    });
+  }
+
+  private onNativeEvent(event: NativeActivityEvent): void {
+    switch (event.kind) {
+    case 'entry': {
+      let entry: Entry;
+      try {
+        entry = this.normalizeActivityEntry(JSON.parse(event.payload));
+      } catch (err) {
+        this.emit({
+          type: 'log',
+          payload: {
+            level: 'error',
+            message: `dropped an unparseable activity entry: ${errorMessage(err)}`,
+          },
+        });
+
+        return;
+      }
+      this.emit({ type: 'activity', payload: entry });
+
+      return;
+    }
+
+    case 'end':
+      this.streamOpen = false;
+      this.emit({ type: 'activityStream', payload: { state: 'ended' } });
+
+      return;
+
+    case 'error':
+      this.streamOpen = false;
+      this.emit({
+        type: 'activityStream',
+        payload: { state: 'failed', message: event.payload },
+      });
+
+      return;
+
+    default:
+      this.emit({
+        type: 'log',
+        payload: {
+          level: 'warn',
+          message: `unknown wavelength native event: ${event.kind}`,
+        },
+      });
+    }
+  }
+
+  dispose(): void {
+    // super.dispose() calls stopActivity(). Keep streamOpen intact until that
+    // queued stop reads it, or disposal would leak the native pump.
+    super.dispose();
+    this.removeNativeListener?.();
+    this.removeNativeListener = null;
+  }
+}

package/src/config.test.ts

@@ -0,0 +1,28 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { defaultConfig } from './config.ts';
+
+describe('defaultConfig (react-native)', () => {
+  it('returns the gRPC host:port preset for a hosted network', () => {
+    assert.deepEqual(defaultConfig('signet'), {
+      network: 'signet',
+      arkServerAddress: 'signet.wavelength.lightning.finance:443',
+      walletEsploraUrl: 'https://mempool-signet.testnet.lightningcluster.com/api',
+      swapServerAddress: 'swap.signet.wavelength.lightning.finance:443',
+    });
+  });
+
+  it('merges overrides over the preset', () => {
+    const config = defaultConfig('testnet4', { dataDir: '/wallet' });
+    assert.equal(config.network, 'testnet4');
+    assert.equal(config.dataDir, '/wallet');
+    assert.equal(
+      config.arkServerAddress,
+      'lumosd-testnet4.testnet.lightningcluster.com:443',
+    );
+    assert.equal(
+      config.swapServerAddress,
+      'swapd-testnet4.testnet.lightningcluster.com:443',
+    );
+  });
+});

package/src/config.ts

@@ -0,0 +1,28 @@
+import {
+  networkDefaults,
+  type PresetNetwork,
+  type RuntimeConfig,
+} from '@lightninglabs/wavelength-core';
+
+/**
+ * Returns a ready-to-use {@link RuntimeConfig} for a network on the React
+ * Native transport, preloaded with the canonical public gRPC host:port
+ * addresses and merged with any overrides. Pass overrides to set dataDir or
+ * point at your own infrastructure, e.g.
+ * `defaultConfig('signet', { dataDir: '/wallet' })`.
+ *
+ * Only the preset networks are accepted (see {@link PresetNetwork}). mainnet
+ * and regtest have no preset: build their config by hand, mainnet with your
+ * own gRPC addresses and allowMainnet, regtest with local addresses and the
+ * insecure-transport flags.
+ *
+ * @param network - The Bitcoin network to build a config for.
+ * @param overrides - Fields that override the network preset's defaults.
+ * @returns The merged runtime configuration.
+ */
+export function defaultConfig(
+  network: PresetNetwork,
+  overrides: Partial<RuntimeConfig> = {},
+): RuntimeConfig {
+  return { network, ...networkDefaults(network, 'grpc'), ...overrides };
+}

package/src/index.ts

@@ -0,0 +1,102 @@
+import { NativeEventEmitter, NativeModules } from 'react-native';
+import {
+  createWalletEngine,
+  type WavelengthClient,
+  type PasskeyCeremony,
+  type DistributiveOmit,
+  type WalletEngine,
+  type WalletEngineOptions,
+} from '@lightninglabs/wavelength-core';
+import NativeWavelength from './NativeWavelength.ts';
+import { NativeWavelengthClient } from './client.ts';
+import {
+  nativePasskeyCeremony,
+  type NativePasskeyCeremonyOptions,
+} from './passkey.ts';
+
+/**
+ * Creates a {@link WavelengthClient} backed by the React Native transport: the
+ * daemon compiled into the app via the gomobile bindings. Takes no options
+ * today; an options parameter can be added later without a breaking change.
+ */
+export function createNativeClient(): WavelengthClient {
+  // NativeModules.Wavelength is the interop view of the Turbo Module; the
+  // emitter needs it (or any module carrying addListener/removeListeners) to
+  // route 'wavelengthActivity' device events on both platforms.
+  const emitter = new NativeEventEmitter(NativeModules.Wavelength);
+
+  return new NativeWavelengthClient(NativeWavelength, (listener) => {
+    const subscription = emitter.addListener('wavelengthActivity', listener);
+
+    return () => subscription.remove();
+  });
+}
+
+/**
+ * Options for {@link createNativeWalletEngine}. See {@link WalletEngineOptions}
+ * for the config/autoStart field docs; the type requires config when
+ * autoStart is true.
+ */
+export type NativeWalletEngineOptions = DistributiveOmit<
+  WalletEngineOptions,
+  'client'
+>;
+
+/**
+ * Creates a {@link WalletEngine} over the React Native transport: the
+ * one-call setup for an RN app. Pass the engine to WavelengthProvider from
+ * \@lightninglabs/wavelength-react.
+ */
+export function createNativeWalletEngine(
+  options: NativeWalletEngineOptions = {},
+): WalletEngine {
+  return createWalletEngine({
+    client: createNativeClient(),
+    ...options,
+  });
+}
+
+/**
+ * Creates the native (Android Credential Manager / iOS AuthenticationServices)
+ * implementation of the {@link PasskeyCeremony} contract; pass it to
+ * useWalletPasskey, or drive it directly. Requires the relying-party domain
+ * to be associated with your app (assetlinks.json on Android, an Associated
+ * Domains entitlement plus apple-app-site-association on iOS). iOS support is
+ * experimental and needs iOS 18 or newer at runtime.
+ */
+export function createNativePasskeyCeremony(
+  options: NativePasskeyCeremonyOptions,
+): PasskeyCeremony {
+  return nativePasskeyCeremony(NativeWavelength, options);
+}
+
+/**
+ * Resolves the platform default wallet data directory (the same directory
+ * {@link createNativeClient}'s client uses when RuntimeConfig.dataDir is not
+ * set). Exposed for app-level data management: showing the storage location,
+ * backing it up, or deleting it to wipe the wallet.
+ *
+ * Returns a plain absolute filesystem path with no URI scheme; a consumer that
+ * needs a `file://` URL (for example to delete the directory) must add it. The
+ * directory is not guaranteed to exist until the runtime has started.
+ */
+export function getDefaultDataDir(): Promise<string> {
+  return NativeWavelength.getDefaultDataDir();
+}
+
+export type {
+  NativePasskeyCeremonyOptions,
+  WavelengthPasskeyNativeModule,
+} from './passkey.ts';
+
+export { defaultConfig } from './config.ts';
+export { NativeWavelengthClient } from './client.ts';
+export type {
+  NativeActivityEvent,
+  SubscribeToNativeEvents,
+  WavelengthNativeModule,
+} from './client.ts';
+
+// Re-export the core contract so an RN consumer can import the client and
+// every type/enum from this one package, the way wavelength-web already does.
+export * from '@lightninglabs/wavelength-core';