@effectstream/wallets 0.100.18 → 0.100.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effectstream/wallets",
-  "version": "0.100.18",
+  "version": "0.100.20",
   "license": "MIT",
   "homepage": "https://effectstream.github.io/docs/",
   "repository": {
@@ -18,6 +18,7 @@
     "./midnight-local": "./src/midnight/local.ts"
   },
   "peerDependencies": {
+    "@effectstream/midnight-contracts": "0.100.20",
     "@lucid-evolution/lucid": "^0.4.29",
     "@lucid-evolution/provider": "^0.1.90",
     "@lucid-evolution/utils": "^0.1.66",
@@ -26,6 +27,9 @@
     "@midnight-ntwrk/wallet-sdk-unshielded-wallet": "^2.1.0"
   },
   "peerDependenciesMeta": {
+    "@effectstream/midnight-contracts": {
+      "optional": true
+    },
     "@lucid-evolution/lucid": {
       "optional": true
     },
@@ -46,6 +50,7 @@
     }
   },
   "devDependencies": {
+    "@effectstream/midnight-contracts": "0.100.20",
     "@lucid-evolution/lucid": "^0.4.30",
     "@lucid-evolution/provider": "^0.1.91",
     "@lucid-evolution/utils": "^0.1.66",
@@ -54,10 +59,10 @@
     "@midnight-ntwrk/wallet-sdk-unshielded-wallet": "2.1.0"
   },
   "dependencies": {
-    "@effectstream/concise": "0.100.18",
-    "@effectstream/crypto": "0.100.18",
-    "@effectstream/event-client": "0.100.18",
-    "@effectstream/utils": "0.100.18",
+    "@effectstream/concise": "0.100.20",
+    "@effectstream/crypto": "0.100.20",
+    "@effectstream/event-client": "0.100.20",
+    "@effectstream/utils": "0.100.20",
     "@aurowallet/mina-provider": "^1.0.12",
     "@metamask/providers": "^22.1.0",
     "@midnight-ntwrk/dapp-connector-api": "4.0.1",

package/src/effectstream.ts

@@ -5,6 +5,7 @@ import { type Chain, numberToHex } from "viem";
 import { utf8ToHex } from "web3-utils";
 import type { EthersEvmProvider } from "./evm/ethers.ts";
 import type { EvmInjectedProvider } from "./evm/injected.ts";
+import type { ViemEvmProvider } from "./evm/viem.ts";
 import type { AbiItem } from "web3-utils";
 import { type TransactionReceipt, Web3 } from "web3";
 import { createMessageForBatcher } from "@effectstream/concise";
@@ -189,7 +190,8 @@ export async function sendSelfSequencedTransaction(
 
   const evmProvider = wallet.provider as
     | EthersEvmProvider
-    | EvmInjectedProvider;
+    | EvmInjectedProvider
+    | ViemEvmProvider;
 
   const hexData = utf8ToHex(JSON.stringify(conciseData));
   const effectstreamL2Contract = await effectstreamConfig.getEffectstreamL2Contract();

package/src/evm/viem.ts

@@ -1,4 +1,5 @@
 import {
+  createPublicClient,
   createWalletClient,
   http,
   type Chain,
@@ -119,4 +120,76 @@ export class ViemEvmProvider implements IProvider<ViemApi> {
       message,
     });
   };
+
+  /**
+   * Submit an EIP-1193-shaped transaction request (matching the
+   * `EvmInjectedProvider.sendTransaction` shape — all numeric fields are
+   * hex strings) by delegating to viem's hoisted `walletClient.sendTransaction`.
+   *
+   * `account` + `chain` are hoisted on the underlying `WalletClient` at
+   * connect time (see `ViemConnector.connectFromPrivateKey`), so we only
+   * need to convert the hex-string numeric fields to bigints that viem
+   * expects, and pass through `to` / `data` as 0x-strings.
+   *
+   * Without this method, the high-level `sendTransaction(wallet, …)` helper
+   * in `effectstream.ts` rejects with `evmProvider.sendTransaction is not a
+   * function` when invoked against a `WalletMode.EvmViem` wallet — blocking
+   * any frontend that wants to drive the engine's tx flow via the local-JS
+   * wallet (e.g. headless Playwright e2e tests).
+   */
+  sendTransaction = async (tx: {
+    to?: string;
+    from: string;
+    gas?: string;
+    gasPrice?: string;
+    data: string;
+    value?: string;
+    maxPriorityFeePerGas?: string;
+    maxFeePerGas?: string;
+  }): Promise<{ txHash: string }> => {
+    if (this.account == null) {
+      throw new Error("ViemEvmProvider.sendTransaction: account is missing");
+    }
+    const toBigInt = (h?: string): bigint | undefined =>
+      h == null ? undefined : BigInt(h);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const hash = await (this.conn.api as any).sendTransaction({
+      account: this.account,
+      to: tx.to as `0x${string}` | undefined,
+      data: tx.data as `0x${string}`,
+      value: toBigInt(tx.value),
+      gas: toBigInt(tx.gas),
+      gasPrice: toBigInt(tx.gasPrice),
+      maxFeePerGas: toBigInt(tx.maxFeePerGas),
+      maxPriorityFeePerGas: toBigInt(tx.maxPriorityFeePerGas),
+    });
+    if (typeof hash !== "string") {
+      throw new Error(
+        `[ViemEvmProvider.sendTransaction] expected string tx hash, got ${typeof hash}`,
+      );
+    }
+
+    // Wait for the receipt + verify status. viem's sendTransaction returns
+    // the hash as soon as the tx is broadcast, NOT once it has mined. If we
+    // returned the hash without checking the receipt, a reverted tx would
+    // look "successful" to the engine's `wait-receipt` confirmation path,
+    // and the indexer would never see a matching event because the contract
+    // call reverted on chain. Match the EvmInjected / EthersEvmProvider
+    // contract: only return when the tx is mined AND its status is 0x1.
+    const chain = (this.conn.api as WalletClient).chain;
+    const transport = (this.conn.api as WalletClient).transport;
+    const publicClient = createPublicClient({
+      chain: chain ?? undefined,
+      transport: http((transport as { url?: string })?.url),
+    });
+    const receipt = await publicClient.waitForTransactionReceipt({
+      hash: hash as `0x${string}`,
+    });
+    if (receipt.status !== "success") {
+      throw new Error(
+        `[ViemEvmProvider.sendTransaction] tx ${hash} reverted on chain (status=${receipt.status})`,
+      );
+    }
+    return { txHash: hash };
+  };
 }

package/src/midnight/local.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test } from "bun:test";
+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";
@@ -55,6 +55,81 @@ describe("MidnightLocalProvider", () => {
     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,

package/src/midnight/local.ts

@@ -8,20 +8,55 @@ import type {
 } 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`. A minimal subset of `ConnectedAPI`
+ * 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.
- *   - `getShieldedAddresses` is stubbed (shielded sync is out of scope for the
- *     lite/seed-only path — callers that need shielded/dust addresses should
- *     build the full WalletFacade via `@effectstream/midnight-contracts`).
+ *   - `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: (
@@ -35,6 +70,28 @@ export type MidnightLocalApi = {
   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 {
@@ -51,27 +108,34 @@ export class MidnightLocalConnector {
   /**
    * Build a Midnight wallet identity from a hex seed.
    *
-   * This is the "lite" / signing-only path: it derives the unshielded
-   * keystore from the seed and exposes a CIP-30-shaped `signData` backed by
-   * `unshieldedKeystore.signData(...)`. It does NOT bring up the shielded /
-   * dust wallets — that requires a live indexer + proof server and lives in
-   * `@effectstream/midnight-contracts`'s `buildWalletFacade`.
+   * 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> => {
-    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.",
-      );
-    });
+    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(
@@ -102,7 +166,7 @@ export class MidnightLocalConnector {
       },
       getShieldedAddresses: async () => {
         throw new Error(
-          "MidnightLocal lite mode does not expose a shielded address. Build a WalletFacade via @effectstream/midnight-contracts for shielded/dust support.",
+          "MidnightLocal signing-only mode does not expose a shielded address. Pass `networkUrls` to connectFromSeed to build the full WalletFacade.",
         );
       },
       seed,
@@ -126,6 +190,93 @@ export class MidnightLocalConnector {
     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;
   };
@@ -176,6 +327,25 @@ export class MidnightLocalProvider implements IProvider<MidnightApi> {
   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,