@effectstream/wallets 0.100.17 → 0.100.19

package/src/helpers/pick-mode.ts

@@ -0,0 +1,89 @@
+import { WalletMode } from "../utils.ts";
+import type { LoginInfo, LoginInfoMap } from "../wallet-modes.ts";
+
+export type ChainKey = "evm" | "cardano" | "midnight";
+
+type StripMode<T> = T extends { mode: WalletMode } ? Omit<T, "mode"> : T;
+
+type LocalModeForChain<C extends ChainKey> = C extends "evm"
+  ? WalletMode.EvmViem
+  : C extends "cardano"
+  ? WalletMode.CardanoLocal
+  : C extends "midnight"
+  ? WalletMode.MidnightLocal
+  : never;
+
+type InjectedModeForChain<C extends ChainKey> = C extends "evm"
+  ? WalletMode.EvmInjected
+  : C extends "cardano"
+  ? WalletMode.Cardano
+  : C extends "midnight"
+  ? WalletMode.Midnight
+  : never;
+
+export type LocalOptionsForChain<C extends ChainKey> = StripMode<
+  LoginInfoMap[LocalModeForChain<C>]
+>;
+
+export type InjectedOptionsForChain<C extends ChainKey> = StripMode<
+  LoginInfoMap[InjectedModeForChain<C>]
+>;
+
+export type PickWalletModeArgs<C extends ChainKey> = {
+  chain: C;
+  /** True → return a local-wallet LoginInfo; false → injected. */
+  preferLocal: boolean;
+  /** Options for the local-wallet branch. Required because callers can't no-op a local wallet (it needs a seed/key). */
+  localOptions: LocalOptionsForChain<C>;
+  /** Options for the injected branch. Required so users always see the same wallet picker UX. */
+  injectedOptions: InjectedOptionsForChain<C>;
+};
+
+/**
+ * Pick between an injected (browser-extension) and a local (seed/key) wallet
+ * based on `preferLocal`, and return a ready-to-pass `LoginInfo` for
+ * `walletLogin()`. Both branches return the same `Wallet` shape from
+ * `walletLogin`, so the rest of the app does not need to branch on mode.
+ *
+ * Typical use (Vite frontend, headless test, etc.):
+ * ```ts
+ * const wallet = await walletLogin(pickWalletMode({
+ *   chain: "midnight",
+ *   preferLocal: import.meta.env.VITE_WALLET_MODE === "local",
+ *   localOptions: { seed, networkId },
+ *   injectedOptions: { preference: { name: "lace" }, networkId },
+ * }));
+ * ```
+ */
+export function pickWalletMode<C extends ChainKey>(
+  args: PickWalletModeArgs<C>,
+): LoginInfo {
+  if (args.preferLocal) {
+    const mode = localModeFor(args.chain);
+    return { mode, ...(args.localOptions as object) } as LoginInfo;
+  }
+  const mode = injectedModeFor(args.chain);
+  return { mode, ...(args.injectedOptions as object) } as LoginInfo;
+}
+
+function localModeFor(chain: ChainKey): WalletMode {
+  switch (chain) {
+    case "evm":
+      return WalletMode.EvmViem;
+    case "cardano":
+      return WalletMode.CardanoLocal;
+    case "midnight":
+      return WalletMode.MidnightLocal;
+  }
+}
+
+function injectedModeFor(chain: ChainKey): WalletMode {
+  switch (chain) {
+    case "evm":
+      return WalletMode.EvmInjected;
+    case "cardano":
+      return WalletMode.Cardano;
+    case "midnight":
+      return WalletMode.Midnight;
+  }
+}

package/src/midnight/local.test.ts

@@ -0,0 +1,157 @@
+import { describe, expect, mock, test } from "bun:test";
+import { Buffer } from "node:buffer";
+import { AddressType } from "@effectstream/utils";
+import { verifySignature } from "@midnight-ntwrk/ledger-v8";
+import { CryptoManager } from "@effectstream/crypto";
+import { MidnightLocalConnector, type MidnightLocalApi } from "./local.ts";
+
+const DETERMINISTIC_SEED =
+  "0000000000000000000000000000000000000000000000000000000000000001";
+
+describe("MidnightLocalProvider", () => {
+  test("derives an unshielded bech32 address from a deterministic seed", async () => {
+    const provider = await MidnightLocalConnector.instance().connectFromSeed({
+      seed: DETERMINISTIC_SEED,
+      networkId: "undeployed",
+    });
+    const { type, address } = provider.getAddress();
+    expect(type).toBe(AddressType.MIDNIGHT);
+    expect(typeof address).toBe("string");
+    expect(address.length).toBeGreaterThan(0);
+  });
+
+  test("signMessage produces a signature that verifies via ledger-v8", async () => {
+    const provider = await MidnightLocalConnector.instance().connectFromSeed({
+      seed: DETERMINISTIC_SEED,
+      networkId: "undeployed",
+    });
+    const api = provider.getConnection().api as unknown as MidnightLocalApi;
+    const message = "hello effectstream";
+    const signed = await api.signData(message, {
+      encoding: "text",
+      keyType: "unshielded",
+    });
+
+    const messageBytes = Buffer.from(message, "utf-8");
+    const ok = verifySignature(
+      signed.verifyingKey as never,
+      messageBytes,
+      signed.signature as never,
+    );
+    expect(ok).toBe(true);
+
+    // signMessage on the IProvider surface returns "signature|verifyingKey"
+    // (Midnight signing is non-deterministic, so the inner signature differs
+    // each call). The combined form is what CryptoManager.Midnight() consumes.
+    const sig = await provider.signMessage(message);
+    const [innerSig, innerVk, ...rest] = sig.split("|");
+    expect(rest).toEqual([]);
+    expect(innerVk).toBe(signed.verifyingKey);
+    const okAgain = verifySignature(
+      innerVk as never,
+      messageBytes,
+      innerSig as never,
+    );
+    expect(okAgain).toBe(true);
+  });
+
+  test("facade mode: networkUrls triggers buildWalletFacade and exposes the full WalletFacade on the api", async () => {
+    // Sentinel objects so we can assert the facade-path code actually wired
+    // through whatever buildWalletFacade returned.
+    const fakeFacade = { __kind: "WalletFacade", shielded: {}, dust: {}, unshielded: {} };
+    const fakeShielded = {
+      address: {
+        coinPublicKeyString: () => "deadbeef-coin-pub-key",
+        encryptionPublicKeyString: () => "deadbeef-enc-pub-key",
+      },
+      balances: {},
+    };
+    const buildSpy = mock(async (
+      networkUrls: unknown,
+      seed: string,
+      _networkId: unknown,
+      _syncMode: unknown,
+    ) => ({
+      wallet: fakeFacade,
+      zswapSecretKeys: {} as never,
+      walletZswapSecretKeys: {} as never,
+      dustSecretKey: {} as never,
+      walletDustSecretKey: {} as never,
+      dustAddress: `dust-for-${seed.slice(0, 8)}`,
+      unshieldedAddress: `unshielded-for-${seed.slice(0, 8)}`,
+      unshieldedKeystore: {} as never,
+      __echoedNetworkUrls: networkUrls,
+    }));
+    const getInitialSpy = mock(async (_shielded: unknown) => fakeShielded);
+
+    mock.module("@effectstream/midnight-contracts/wallet-info", () => ({
+      buildWalletFacade: buildSpy,
+      getInitialShieldedState: getInitialSpy,
+    }));
+
+    const provider = await MidnightLocalConnector.instance().connectFromSeed({
+      seed: DETERMINISTIC_SEED,
+      networkId: "undeployed",
+      networkUrls: {
+        indexer: "http://127.0.0.1:8088/api/v3/graphql",
+        indexerWS: "ws://127.0.0.1:8088/api/v3/graphql/ws",
+        node: "http://127.0.0.1:9944",
+        proofServer: "http://127.0.0.1:6300",
+      },
+    });
+
+    expect(buildSpy).toHaveBeenCalledTimes(1);
+    const [networkUrlsArg, seedArg, networkIdArg, syncModeArg] = buildSpy.mock.calls[0]!;
+    expect(seedArg).toBe(DETERMINISTIC_SEED);
+    expect(networkIdArg).toBe("undeployed");
+    expect(syncModeArg).toBe("all");
+    expect(networkUrlsArg).toMatchObject({
+      indexer: "http://127.0.0.1:8088/api/v3/graphql",
+      indexerWS: "ws://127.0.0.1:8088/api/v3/graphql/ws",
+      node: "http://127.0.0.1:9944",
+      proofServer: "http://127.0.0.1:6300",
+      id: "undeployed",
+    });
+
+    const api = provider.getConnection().api as unknown as MidnightLocalApi;
+    expect(api.walletFacade).toBe(fakeFacade);
+    expect(api.dustAddress).toBe(`dust-for-${DETERMINISTIC_SEED.slice(0, 8)}`);
+    expect(api.shieldedAddress).toBe("deadbeef-coin-pub-key");
+
+    // getShieldedAddresses no longer throws in facade mode.
+    await expect(api.getShieldedAddresses()).resolves.toEqual({
+      shieldedAddress: "deadbeef-coin-pub-key",
+    });
+
+    expect(provider.getConnection().metadata.displayName).toBe(
+      "Midnight (local seed, facade)",
+    );
+
+    mock.restore();
+  });
+
+  test("signMessage round-trips through CryptoManager.Midnight().verifySignature", async () => {
+    const provider = await MidnightLocalConnector.instance().connectFromSeed({
+      seed: DETERMINISTIC_SEED,
+      networkId: "undeployed",
+    });
+    const message = "hello effectstream from @effectstream/crypto";
+    const sig = await provider.signMessage(message);
+
+    const midnightCrypto = CryptoManager.getCryptoManager(AddressType.MIDNIGHT);
+    const ok = await midnightCrypto.verifySignature(
+      provider.getAddress().address,
+      message,
+      sig,
+    );
+    expect(ok).toBe(true);
+
+    // Tampering with the message must fail verification.
+    const tampered = await midnightCrypto.verifySignature(
+      provider.getAddress().address,
+      `${message} tampered`,
+      sig,
+    );
+    expect(tampered).toBe(false);
+  });
+});

package/src/midnight/local.ts

@@ -0,0 +1,375 @@
+import { Buffer } from "node:buffer";
+import { AddressType, type MidnightAddress } from "@effectstream/utils";
+import type {
+  ActiveConnection,
+  AddressAndType,
+  IProvider,
+  UserSignature,
+} from "../IProvider.ts";
+import type { MidnightApi } from "./midnight.ts";
+
+/**
+ * Network endpoints required to bring up the full WalletFacade. Mirrors
+ * `NetworkUrls` from `@effectstream/midnight-contracts` but with every field
+ * required (so consumers can't accidentally leave one unset).
+ */
+export type MidnightLocalNetworkUrls = {
+  /** GraphQL indexer HTTP endpoint. */
+  indexer: string;
+  /** GraphQL indexer WebSocket endpoint. */
+  indexerWS: string;
+  /** Midnight node RPC endpoint (used as the wallet relay; http→ws is rewritten internally). */
+  node: string;
+  /** Proof-server HTTP endpoint. */
+  proofServer: string;
+  /** Optional network id override; defaults to `connectFromSeed`'s `networkId` arg. */
+  id?: string;
+};
+
+export type MidnightLocalSyncMode = "all" | "dust-only";
+
+export type MidnightLocalConnectArgs = {
+  /** 64-character hex seed. Generated when omitted. */
+  seed?: string;
+  /** Midnight network id — sets the bech32 prefix on the unshielded address. */
+  networkId: string;
+  /**
+   * Network URLs for the full WalletFacade. When supplied, the connector builds
+   * a complete wallet (shielded + dust + unshielded) via
+   * `@effectstream/midnight-contracts.buildWalletFacade` and exposes it on
+   * `getConnection().api.walletFacade`. Required for shielded tx submission,
+   * `balanceAndProveTransaction`, dust fee payment, etc.
+   *
+   * When omitted, the connector returns the signing-only path (unshielded
+   * keystore `signData`) — useful for offline signature flows or signature
+   * verification dry runs that don't need to stand up indexer + proof-server.
+   */
+  networkUrls?: MidnightLocalNetworkUrls;
+  /** Defaults to "all" when `networkUrls` is supplied. Ignored otherwise. */
+  syncMode?: MidnightLocalSyncMode;
+};
+
+/**
+ * Shape exposed on `getConnection().api`. Mirrors a subset of `ConnectedAPI`
+ * that the rest of Effectstream's Midnight code consumes:
+ *   - `signData` mirrors the dapp-connector-api shape (works in both modes).
+ *   - `getShieldedAddresses` returns the real shielded coin public key when
+ *     the full facade is built; throws in signing-only mode.
+ *   - `walletFacade` / `dustAddress` / `shieldedAddress` are populated only
+ *     when `networkUrls` was supplied at connect time.
+ */
+export type MidnightLocalApi = {
+  signData: (
+    data: string,
+    options: { encoding: "text" | "hex"; keyType: "unshielded" },
+  ) => Promise<{ data: string; signature: string; verifyingKey: string }>;
+  getShieldedAddresses: () => Promise<{ shieldedAddress: string }>;
+  /** The derived seed, exposed so tests can persist/reuse the wallet. */
+  seed: string;
+  /** Public verifying key for the unshielded signing role (hex). */
+  verifyingKey: string;
+  /** Bech32-encoded unshielded address. */
+  unshieldedAddress: string;
+  /**
+   * Full Midnight `WalletFacade`. Populated only when `networkUrls` was passed
+   * to `connectFromSeed`. Cast to
+   * `import("@midnight-ntwrk/wallet-sdk-facade").WalletFacade` for typed
+   * access. Carries `submitTransaction`, `balanceFinalizedTransaction`,
+   * `balanceUnboundTransaction`, `balanceUnprovenTransaction`, `signRecipe`,
+   * `signUnprovenTransaction`, `state()`, `waitForSyncedState()`, etc.
+   */
+  walletFacade?: unknown;
+  /** Bech32-encoded dust address. Populated only in facade mode. */
+  dustAddress?: string;
+  /** Hex-encoded shielded coin public key. Populated only in facade mode. */
+  shieldedAddress?: string;
+  /**
+   * Escape hatch: the entire `WalletResult` returned by
+   * `@effectstream/midnight-contracts.buildWalletFacade`. Exposes the raw
+   * secret keys (`zswapSecretKeys`, `dustSecretKey`, `unshieldedKeystore`) that
+   * advanced flows (manual tx balancing, custom dust handling) need. Cast to
+   * `import("@effectstream/midnight-contracts").WalletResult`.
+   * Populated only in facade mode.
+   */
+  walletResult?: unknown;
+};
+
+export class MidnightLocalConnector {
+  private provider: MidnightLocalProvider | undefined;
+  private static INSTANCE: undefined | MidnightLocalConnector = undefined;
+
+  static instance(): MidnightLocalConnector {
+    if (MidnightLocalConnector.INSTANCE == null) {
+      MidnightLocalConnector.INSTANCE = new MidnightLocalConnector();
+    }
+    return MidnightLocalConnector.INSTANCE;
+  }
+
+  /**
+   * Build a Midnight wallet identity from a hex seed.
+   *
+   * Two modes, picked by whether `args.networkUrls` is supplied:
+   *
+   *  - **Facade mode** (`networkUrls` set): builds the full Midnight wallet via
+   *    `@effectstream/midnight-contracts.buildWalletFacade` — shielded + dust +
+   *    unshielded sub-wallets, connected to a live indexer + node + proof
+   *    server. The complete `WalletFacade` is exposed on
+   *    `getConnection().api.walletFacade`, enabling `submitTransaction`,
+   *    `balanceAndProveTransaction`, dust fee payment, etc. Requires
+   *    `@effectstream/midnight-contracts` to be installed (optional peer dep).
+   *
+   *  - **Signing-only mode** (`networkUrls` omitted): derives the unshielded
+   *    keystore from the seed and exposes a CIP-30-shaped `signData` backed by
+   *    `unshieldedKeystore.signData(...)`. No network IO. Suitable for offline
+   *    signature flows and signature-verification dry runs.
+   */
+  connectFromSeed = async (
+    args: MidnightLocalConnectArgs,
+  ): Promise<MidnightLocalProvider> => {
+    if (args.networkUrls != null) {
+      return await this.connectWithFacade(args, args.networkUrls);
+    }
+    return await this.connectSigningOnly(args);
+  };
+
+  private connectSigningOnly = async (
+    args: MidnightLocalConnectArgs,
+  ): Promise<MidnightLocalProvider> => {
+    const { hdMod, keystoreMod } = await loadKeystoreDeps();
+
+    const seed = args.seed ?? generateRandomHexSeed(32);
+    const unshieldedSeed = deriveUnshieldedSeed(
+      hdMod,
+      seed,
+      hdMod.Roles.NightExternal,
+    );
+    const unshieldedKeystore = keystoreMod.createKeystore(
+      unshieldedSeed,
+      args.networkId as never,
+    );
+
+    const unshieldedAddress = unshieldedKeystore.getBech32Address().asString();
+    const verifyingKey = String(unshieldedKeystore.getPublicKey());
+
+    const api: MidnightLocalApi = {
+      signData: async (data, options) => {
+        const bytes =
+          options.encoding === "hex"
+            ? Buffer.from(data, "hex")
+            : Buffer.from(data, "utf-8");
+        const signature = unshieldedKeystore.signData(bytes);
+        return {
+          data,
+          signature: String(signature),
+          verifyingKey,
+        };
+      },
+      getShieldedAddresses: async () => {
+        throw new Error(
+          "MidnightLocal signing-only mode does not expose a shielded address. Pass `networkUrls` to connectFromSeed to build the full WalletFacade.",
+        );
+      },
+      seed,
+      verifyingKey,
+      unshieldedAddress,
+    };
+
+    const conn: ActiveConnection<MidnightApi> = {
+      api: api as unknown as MidnightApi,
+      metadata: {
+        name: "midnight-local",
+        displayName: "Midnight (local seed)",
+      },
+    };
+
+    this.provider = new MidnightLocalProvider(
+      conn,
+      unshieldedAddress as MidnightAddress,
+      unshieldedKeystore,
+    );
+    return this.provider;
+  };
+
+  private connectWithFacade = async (
+    args: MidnightLocalConnectArgs,
+    networkUrls: MidnightLocalNetworkUrls,
+  ): Promise<MidnightLocalProvider> => {
+    // Use the `/wallet-info` subpath, not the package barrel: the barrel
+    // re-exports `deploy.ts` (`node:fs/promises`), which breaks browser bundles
+    // of `@effectstream/wallets`.
+    const contractsMod = await import(
+      "@effectstream/midnight-contracts/wallet-info"
+    ).catch(() => {
+      throw new Error(
+        "@effectstream/midnight-contracts is required when `networkUrls` is passed to MidnightLocal.connectFromSeed. Install it as a peer dependency.",
+      );
+    });
+    const { hdMod, keystoreMod } = await loadKeystoreDeps();
+
+    const seed = args.seed ?? generateRandomHexSeed(32);
+    const unshieldedSeed = deriveUnshieldedSeed(
+      hdMod,
+      seed,
+      hdMod.Roles.NightExternal,
+    );
+    const unshieldedKeystore = keystoreMod.createKeystore(
+      unshieldedSeed,
+      args.networkId as never,
+    );
+    const verifyingKey = String(unshieldedKeystore.getPublicKey());
+
+    const fullNetworkUrls = {
+      indexer: networkUrls.indexer,
+      indexerWS: networkUrls.indexerWS,
+      node: networkUrls.node,
+      proofServer: networkUrls.proofServer,
+      id: networkUrls.id ?? args.networkId,
+    };
+
+    const walletResult = await contractsMod.buildWalletFacade(
+      fullNetworkUrls,
+      seed,
+      args.networkId as never,
+      args.syncMode ?? "all",
+    );
+
+    const initialShielded = await contractsMod.getInitialShieldedState(
+      walletResult.wallet.shielded,
+    );
+    const shieldedAddress = initialShielded.address.coinPublicKeyString();
+
+    const api: MidnightLocalApi = {
+      signData: async (data, options) => {
+        const bytes =
+          options.encoding === "hex"
+            ? Buffer.from(data, "hex")
+            : Buffer.from(data, "utf-8");
+        const signature = unshieldedKeystore.signData(bytes);
+        return {
+          data,
+          signature: String(signature),
+          verifyingKey,
+        };
+      },
+      getShieldedAddresses: async () => ({ shieldedAddress }),
+      seed,
+      verifyingKey,
+      unshieldedAddress: walletResult.unshieldedAddress,
+      walletFacade: walletResult.wallet,
+      dustAddress: walletResult.dustAddress,
+      shieldedAddress,
+      walletResult,
+    };
+
+    const conn: ActiveConnection<MidnightApi> = {
+      api: api as unknown as MidnightApi,
+      metadata: {
+        name: "midnight-local",
+        displayName: "Midnight (local seed, facade)",
+      },
+    };
+
+    this.provider = new MidnightLocalProvider(
+      conn,
+      walletResult.unshieldedAddress as MidnightAddress,
+      unshieldedKeystore,
+    );
+    return this.provider;
+  };
+
+  getProvider = (): undefined | MidnightLocalProvider => {
+    return this.provider;
+  };
+
+  getOrThrowProvider = (): MidnightLocalProvider => {
+    if (this.provider == null) {
+      throw new Error("MidnightLocalConnector not initialized yet");
+    }
+    return this.provider;
+  };
+
+  isConnected = (): boolean => {
+    return this.provider != null;
+  };
+}
+
+export class MidnightLocalProvider implements IProvider<MidnightApi> {
+  constructor(
+    private readonly conn: ActiveConnection<MidnightApi>,
+    readonly address: MidnightAddress,
+    private readonly unshieldedKeystore: unknown,
+  ) {}
+
+  getConnection = (): ActiveConnection<MidnightApi> => {
+    return this.conn;
+  };
+
+  getAddress = (): AddressAndType => {
+    return {
+      type: AddressType.MIDNIGHT,
+      address: this.address,
+    };
+  };
+
+  signMessage = async (message: string): Promise<UserSignature> => {
+    const signed = await (this.conn.api as unknown as MidnightLocalApi).signData(
+      message,
+      { encoding: "text", keyType: "unshielded" },
+    );
+    // Format: "signature|verifyingKey". Midnight signatures are not
+    // self-recovering (unlike EVM ECDSA), so the verifier needs the public
+    // key to call ledger-v8.verifySignature. Mirrors Cardano's "sig+key"
+    // convention, just with `|` as the separator to keep the formats distinct.
+    return `${signed.signature}|${signed.verifyingKey}`;
+  };
+
+  /** Expose the keystore for callers that need the raw signing primitive. */
+  getUnshieldedKeystore = (): unknown => this.unshieldedKeystore;
+}
+
+async function loadKeystoreDeps(): Promise<{
+  hdMod: typeof import("@midnight-ntwrk/wallet-sdk-hd");
+  keystoreMod: typeof import("@midnight-ntwrk/wallet-sdk-unshielded-wallet");
+}> {
+  const hdMod = await import("@midnight-ntwrk/wallet-sdk-hd").catch(() => {
+    throw new Error(
+      "@midnight-ntwrk/wallet-sdk-hd is required for WalletMode.MidnightLocal.",
+    );
+  });
+  const keystoreMod = await import(
+    "@midnight-ntwrk/wallet-sdk-unshielded-wallet"
+  ).catch(() => {
+    throw new Error(
+      "@midnight-ntwrk/wallet-sdk-unshielded-wallet is required for WalletMode.MidnightLocal.",
+    );
+  });
+  return { hdMod, keystoreMod };
+}
+
+function deriveUnshieldedSeed(
+  hdMod: typeof import("@midnight-ntwrk/wallet-sdk-hd"),
+  seedHex: string,
+  role: import("@midnight-ntwrk/wallet-sdk-hd").Role,
+): Uint8Array {
+  const seedBuffer = Buffer.from(seedHex, "hex");
+  const hdResult = hdMod.HDWallet.fromSeed(seedBuffer);
+  if (hdResult.type !== "seedOk") {
+    throw new Error(`HDWallet.fromSeed failed: ${hdResult.type}`);
+  }
+  const derivation = hdResult.hdWallet
+    .selectAccount(0)
+    .selectRole(role)
+    .deriveKeyAt(0);
+  if (derivation.type !== "keyDerived") {
+    throw new Error(`HDWallet.deriveKeyAt failed: ${derivation.type}`);
+  }
+  return Buffer.from(derivation.key);
+}
+
+function generateRandomHexSeed(byteLength: number): string {
+  const bytes = new Uint8Array(byteLength);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}