@effectstream/wallets 0.100.17 → 0.100.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effectstream/wallets",
-  "version": "0.100.17",
+  "version": "0.100.19",
   "license": "MIT",
   "homepage": "https://effectstream.github.io/docs/",
   "repository": {
@@ -11,12 +11,58 @@
   "bugs": {
     "url": "https://github.com/effectstream/effectstream/issues"
   },
-  "exports": "./src/mod.ts",
+  "exports": {
+    ".": "./src/mod.ts",
+    "./evm-viem": "./src/evm/viem.ts",
+    "./cardano-local": "./src/cardano/local.ts",
+    "./midnight-local": "./src/midnight/local.ts"
+  },
+  "peerDependencies": {
+    "@effectstream/midnight-contracts": "0.100.19",
+    "@lucid-evolution/lucid": "^0.4.29",
+    "@lucid-evolution/provider": "^0.1.90",
+    "@lucid-evolution/utils": "^0.1.66",
+    "@midnight-ntwrk/ledger-v8": "^8.0.3",
+    "@midnight-ntwrk/wallet-sdk-hd": "^3.0.1",
+    "@midnight-ntwrk/wallet-sdk-unshielded-wallet": "^2.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@effectstream/midnight-contracts": {
+      "optional": true
+    },
+    "@lucid-evolution/lucid": {
+      "optional": true
+    },
+    "@lucid-evolution/provider": {
+      "optional": true
+    },
+    "@lucid-evolution/utils": {
+      "optional": true
+    },
+    "@midnight-ntwrk/ledger-v8": {
+      "optional": true
+    },
+    "@midnight-ntwrk/wallet-sdk-hd": {
+      "optional": true
+    },
+    "@midnight-ntwrk/wallet-sdk-unshielded-wallet": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@effectstream/midnight-contracts": "0.100.19",
+    "@lucid-evolution/lucid": "^0.4.30",
+    "@lucid-evolution/provider": "^0.1.91",
+    "@lucid-evolution/utils": "^0.1.66",
+    "@midnight-ntwrk/ledger-v8": "8.0.3",
+    "@midnight-ntwrk/wallet-sdk-hd": "3.0.1",
+    "@midnight-ntwrk/wallet-sdk-unshielded-wallet": "2.1.0"
+  },
   "dependencies": {
-    "@effectstream/concise": "0.100.17",
-    "@effectstream/crypto": "0.100.17",
-    "@effectstream/event-client": "0.100.17",
-    "@effectstream/utils": "0.100.17",
+    "@effectstream/concise": "0.100.19",
+    "@effectstream/crypto": "0.100.19",
+    "@effectstream/event-client": "0.100.19",
+    "@effectstream/utils": "0.100.19",
     "@aurowallet/mina-provider": "^1.0.12",
     "@metamask/providers": "^22.1.0",
     "@midnight-ntwrk/dapp-connector-api": "4.0.1",

package/src/avail/wrapper.ts

@@ -3,6 +3,7 @@ import type { IProvider } from "../IProvider.ts";
 import type { WalletMode, ApiForMode } from "../utils.ts";
 import type { LoginInfoMap } from "../wallet-modes.ts";
 import { type AvailJsApi, AvailConnector } from "./avail.ts";
+import { formatError } from "../helpers/format-error.ts";
 
 // Problematic dependency for deno-fresh
 import { Keyring } from "avail-js-sdk";
@@ -31,7 +32,7 @@ async function connectWallet(
     console.log(`availJsLoginWrapper: Error while logging into wallet name}`);
     return {
       success: false,
-      errorMessage: err.message ?? String(err),
+      errorMessage: formatError(err),
     }
   }
 }

package/src/cardano/local.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, test } from "bun:test";
+import { CryptoManager } from "@effectstream/crypto";
+import { AddressType } from "@effectstream/utils";
+import { CardanoLocalConnector } from "./local.ts";
+
+describe("CardanoLocalProvider", () => {
+  test("connect from seed produces a bech32 address", async () => {
+    const provider = await CardanoLocalConnector.instance().connectFromSeed({
+      network: "Preview",
+    });
+    const { type, address } = provider.getAddress();
+    expect(type).toBe(AddressType.CARDANO);
+    expect(address.startsWith("addr_test1")).toBe(true);
+  });
+
+  test("signMessage produces a signature that @effectstream/crypto verifies", async () => {
+    const provider = await CardanoLocalConnector.instance().connectFromSeed({
+      network: "Preview",
+    });
+    const message = "hello effectstream";
+    const signature = await provider.signMessage(message);
+
+    const cardanoCrypto = CryptoManager.getCryptoManager(AddressType.CARDANO);
+    const ok = await cardanoCrypto.verifySignature(
+      provider.getAddress().address,
+      message,
+      signature,
+    );
+    expect(ok).toBe(true);
+  });
+});

package/src/cardano/local.ts

@@ -0,0 +1,159 @@
+import { AddressType } from "@effectstream/utils";
+import { utf8ToHex } from "web3-utils";
+import type {
+  ActiveConnection,
+  AddressAndType,
+  IProvider,
+  UserSignature,
+} from "../IProvider.ts";
+import type { CardanoApi, CardanoAddress } from "./cardano.ts";
+
+export type CardanoLocalNetwork = "Mainnet" | "Preprod" | "Preview" | "Custom";
+
+export type CardanoLocalConnectArgs = {
+  /** BIP-39 mnemonic. Generated via `@lucid-evolution/utils#generateSeedPhrase` when omitted. */
+  seedPhrase?: string;
+  /** Cardano network — must match the chain address the signature is verified against. */
+  network: CardanoLocalNetwork;
+  /**
+   * Optional Lucid `Provider`. Pass when the caller wants Lucid to fetch UTxOs
+   * or submit transactions through this wallet. Pure signing does not require it.
+   */
+  provider?: unknown;
+};
+
+/**
+ * `getConnection().api` shape. Mirrors the CIP-30 subset that the rest of
+ * Effectstream's Cardano code consumes from a real injected wallet (signData,
+ * getUsedAddresses) so existing consumers work unchanged.
+ */
+export type CardanoLocalApi = {
+  /** CIP-30 signData. Returns COSE_Sign1 (signature) + COSE_Key (key) as hex. */
+  signData: (
+    address: string,
+    payloadHex: string,
+  ) => Promise<{ signature: string; key: string }>;
+  /** Hex-encoded address list, matching CIP-30 `getUsedAddresses`. */
+  getUsedAddresses: () => Promise<string[]>;
+  /** Underlying Lucid handle for callers that need tx-building. */
+  lucid: unknown;
+  /** Generated/passed seed phrase. Exposed so tests can persist/reuse the wallet. */
+  seedPhrase: string;
+};
+
+export class CardanoLocalConnector {
+  private provider: CardanoLocalProvider | undefined;
+  private static INSTANCE: undefined | CardanoLocalConnector = undefined;
+
+  static instance(): CardanoLocalConnector {
+    if (CardanoLocalConnector.INSTANCE == null) {
+      CardanoLocalConnector.INSTANCE = new CardanoLocalConnector();
+    }
+    return CardanoLocalConnector.INSTANCE;
+  }
+
+  connectFromSeed = async (
+    args: CardanoLocalConnectArgs,
+  ): Promise<CardanoLocalProvider> => {
+    const lucidMod = await import("@lucid-evolution/lucid").catch(() => {
+      throw new Error(
+        "@lucid-evolution/lucid is required for WalletMode.CardanoLocal. Install it as a peer dependency.",
+      );
+    });
+    const utilsMod = await import("@lucid-evolution/utils").catch(() => {
+      throw new Error(
+        "@lucid-evolution/utils is required for WalletMode.CardanoLocal. Install it as a peer dependency.",
+      );
+    });
+
+    const seedPhrase = args.seedPhrase ?? utilsMod.generateSeedPhrase();
+    // Lucid's wallet().address() requires a Provider to be set even for pure
+    // signing. When the caller doesn't supply one, fall back to an in-memory
+    // Emulator so signing-only flows (e2e tests, wallet-connect dry runs) work
+    // without standing up Blockfrost / YACI.
+    let provider = args.provider;
+    if (provider == null) {
+      const providerMod = await import("@lucid-evolution/provider").catch(() => {
+        throw new Error(
+          "@lucid-evolution/provider is required when no provider is supplied to CardanoLocal.",
+        );
+      });
+      provider = new providerMod.Emulator([]);
+    }
+    const lucid = await lucidMod.Lucid(provider as never, args.network);
+    lucid.selectWallet.fromSeed(seedPhrase);
+
+    const bech32Address = await lucid.wallet().address();
+    const hexAddress = await addressToHex(lucid, bech32Address);
+
+    const api: CardanoLocalApi = {
+      signData: async (address, payloadHex) => {
+        return await lucid.wallet().signMessage(address, payloadHex);
+      },
+      getUsedAddresses: async () => [hexAddress],
+      lucid,
+      seedPhrase,
+    };
+
+    const conn: ActiveConnection<CardanoApi> = {
+      api,
+      metadata: {
+        name: "cardano-local",
+        displayName: "Cardano (local seed)",
+      },
+    };
+
+    this.provider = new CardanoLocalProvider(conn, {
+      bech32: bech32Address,
+      hex: hexAddress,
+    });
+    return this.provider;
+  };
+
+  getProvider = (): undefined | CardanoLocalProvider => {
+    return this.provider;
+  };
+
+  getOrThrowProvider = (): CardanoLocalProvider => {
+    if (this.provider == null) {
+      throw new Error("CardanoLocalConnector not initialized yet");
+    }
+    return this.provider;
+  };
+
+  isConnected = (): boolean => {
+    return this.provider != null;
+  };
+}
+
+export class CardanoLocalProvider implements IProvider<CardanoApi> {
+  constructor(
+    private readonly conn: ActiveConnection<CardanoApi>,
+    readonly address: CardanoAddress,
+  ) {}
+
+  getConnection = (): ActiveConnection<CardanoApi> => {
+    return this.conn;
+  };
+
+  getAddress = (): AddressAndType => {
+    return {
+      type: AddressType.CARDANO,
+      address: this.address.bech32,
+    };
+  };
+
+  signMessage = async (message: string): Promise<UserSignature> => {
+    const hexMessage = utf8ToHex(message).slice(2);
+    const { signature, key } = await (
+      this.conn.api as CardanoLocalApi
+    ).signData(this.address.bech32, hexMessage);
+    return `${signature}+${key}`;
+  };
+}
+
+async function addressToHex(lucid: any, bech32Address: string): Promise<string> {
+  const utilsMod = await import("@lucid-evolution/utils");
+  const details = utilsMod.getAddressDetails(bech32Address);
+  return details.address.hex;
+}

package/src/cardano/wrapper-local.ts

@@ -0,0 +1,31 @@
+import type { Result } from "@effectstream/utils";
+import type { IProvider } from "../IProvider.ts";
+import type { WalletMode, ApiForMode } from "../utils.ts";
+import type { LoginInfoMap } from "../wallet-modes.ts";
+import { CardanoLocalConnector } from "./local.ts";
+import { formatError } from "../helpers/format-error.ts";
+
+export async function cardanoLocalLoginWrapper(
+  loginInfo: LoginInfoMap[WalletMode.CardanoLocal],
+): Promise<Result<IProvider<ApiForMode<WalletMode.CardanoLocal>>>> {
+  try {
+    console.log("cardanoLocalLoginWrapper: building Lucid wallet from seed");
+    const provider = await CardanoLocalConnector.instance().connectFromSeed({
+      seedPhrase: loginInfo.seedPhrase,
+      network: loginInfo.network,
+      provider: loginInfo.provider,
+    });
+    return {
+      success: true,
+      result: provider as unknown as IProvider<
+        ApiForMode<WalletMode.CardanoLocal>
+      >,
+    };
+  } catch (err) {
+    console.log("cardanoLocalLoginWrapper: error while building local Cardano wallet");
+    return {
+      success: false,
+      errorMessage: formatError(err),
+    };
+  }
+}

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.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from "bun:test";
+import { CryptoManager } from "@effectstream/crypto";
+import { AddressType } from "@effectstream/utils";
+import { ViemConnector } from "./viem.ts";
+
+const TEST_KEY =
+  "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80" as const;
+const EXPECTED_ADDR = "0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266";
+
+describe("ViemEvmProvider", () => {
+  test("derives the hardhat default address from its private key", async () => {
+    const provider = await ViemConnector.instance().connectFromPrivateKey({
+      privateKey: TEST_KEY,
+      rpcUrl: "http://localhost:8545",
+    });
+    const { type, address } = provider.getAddress();
+    expect(type).toBe(AddressType.EVM);
+    expect(address).toBe(EXPECTED_ADDR);
+  });
+
+  test("signMessage produces a signature that @effectstream/crypto verifies", async () => {
+    const provider = await ViemConnector.instance().connectFromPrivateKey({
+      privateKey: TEST_KEY,
+      rpcUrl: "http://localhost:8545",
+    });
+    const message = "hello effectstream";
+    const signature = await provider.signMessage(message);
+
+    const evmCrypto = CryptoManager.getCryptoManager(AddressType.EVM);
+    const ok = await evmCrypto.verifySignature(
+      provider.getAddress().address,
+      message,
+      signature,
+    );
+    expect(ok).toBe(true);
+  });
+});

package/src/evm/viem.ts

@@ -0,0 +1,195 @@
+import {
+  createPublicClient,
+  createWalletClient,
+  http,
+  type Chain,
+  type Hex,
+  type PrivateKeyAccount,
+  type WalletClient,
+} from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { AddressType } from "@effectstream/utils";
+import type {
+  ActiveConnection,
+  AddressAndType,
+  IProvider,
+  UserSignature,
+} from "../IProvider.ts";
+import type { EvmAddress } from "./types.ts";
+
+export type ViemApi = WalletClient;
+
+export type ViemConnectArgs = {
+  privateKey: Hex;
+  rpcUrl: string;
+  chain?: Chain;
+};
+
+export class ViemConnector {
+  private provider: ViemEvmProvider | undefined;
+  private static INSTANCE: undefined | ViemConnector = undefined;
+
+  static instance(): ViemConnector {
+    if (ViemConnector.INSTANCE == null) {
+      ViemConnector.INSTANCE = new ViemConnector();
+    }
+    return ViemConnector.INSTANCE;
+  }
+
+  connectFromPrivateKey = async (
+    args: ViemConnectArgs,
+  ): Promise<ViemEvmProvider> => {
+    const account = privateKeyToAccount(args.privateKey);
+    const client = createWalletClient({
+      account,
+      chain: args.chain,
+      transport: http(args.rpcUrl),
+    });
+    this.provider = await ViemEvmProvider.init(client, account);
+    return this.provider;
+  };
+
+  connectExternal = async (
+    conn: ActiveConnection<ViemApi>,
+  ): Promise<ViemEvmProvider> => {
+    const account = conn.api.account;
+    if (account == null) {
+      throw new Error(
+        "ViemConnector.connectExternal: WalletClient.account is null. Build the client with createWalletClient({ account, ... }).",
+      );
+    }
+    this.provider = await ViemEvmProvider.init(conn.api, account, conn.metadata);
+    return this.provider;
+  };
+
+  getProvider = (): undefined | ViemEvmProvider => {
+    return this.provider;
+  };
+
+  getOrThrowProvider = (): ViemEvmProvider => {
+    if (this.provider == null) {
+      throw new Error("ViemConnector not initialized yet");
+    }
+    return this.provider;
+  };
+
+  isConnected = (): boolean => {
+    return this.provider != null;
+  };
+}
+
+export class ViemEvmProvider implements IProvider<ViemApi> {
+  constructor(
+    private readonly conn: ActiveConnection<ViemApi>,
+    private readonly account: PrivateKeyAccount | WalletClient["account"],
+    readonly address: EvmAddress,
+  ) {}
+
+  static init = async (
+    client: ViemApi,
+    account: NonNullable<WalletClient["account"]>,
+    metadata?: { name: string; displayName: string },
+  ): Promise<ViemEvmProvider> => {
+    const conn: ActiveConnection<ViemApi> = {
+      api: client,
+      metadata: metadata ?? {
+        name: "viem-local",
+        displayName: "Viem (local)",
+      },
+    };
+    return new ViemEvmProvider(conn, account, account.address as EvmAddress);
+  };
+
+  getConnection = (): ActiveConnection<ViemApi> => {
+    return this.conn;
+  };
+
+  getAddress = (): AddressAndType => {
+    return {
+      type: AddressType.EVM,
+      address: this.address.toLowerCase(),
+    };
+  };
+
+  signMessage = async (message: string): Promise<UserSignature> => {
+    if (this.account == null) {
+      throw new Error("ViemEvmProvider.signMessage: account is missing");
+    }
+    return await this.conn.api.signMessage({
+      account: this.account,
+      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/evm/wrapper-ethers.ts

@@ -3,6 +3,7 @@ import type { IProvider } from "../IProvider.ts";
 import type { WalletMode, ApiForMode } from "../utils.ts";
 import type { LoginInfoMap } from "../wallet-modes.ts";
 import { type EthersApi, EthersConnector } from "./ethers.ts";
+import { formatError } from "../helpers/format-error.ts";
 
 async function connectWallet(
   loginInfo: LoginInfoMap[WalletMode.EvmEthers]
@@ -22,7 +23,7 @@ async function connectWallet(
 
     return {
       success: false,
-      errorMessage: err instanceof Error ? err.message : String(err),
+      errorMessage: formatError(err),
     };
   }
 }

package/src/evm/wrapper-viem.ts

@@ -0,0 +1,31 @@
+import type { Result } from "@effectstream/utils";
+import type { IProvider } from "../IProvider.ts";
+import type { WalletMode, ApiForMode } from "../utils.ts";
+import type { LoginInfoMap } from "../wallet-modes.ts";
+import { type ViemApi, ViemConnector } from "./viem.ts";
+import { formatError } from "../helpers/format-error.ts";
+
+export async function viemLoginWrapper(
+  loginInfo: LoginInfoMap[WalletMode.EvmViem],
+): Promise<Result<IProvider<ApiForMode<WalletMode.EvmViem>>>> {
+  try {
+    console.log("viemLoginWrapper: building viem WalletClient from private key");
+    const provider = await ViemConnector.instance().connectFromPrivateKey({
+      privateKey: loginInfo.privateKey,
+      rpcUrl: loginInfo.rpcUrl,
+      chain: loginInfo.chain,
+    });
+    return {
+      success: true,
+      result: provider as unknown as IProvider<ApiForMode<WalletMode.EvmViem>>,
+    };
+  } catch (err) {
+    console.log("viemLoginWrapper: error while building local viem wallet");
+    return {
+      success: false,
+      errorMessage: formatError(err),
+    };
+  }
+}
+
+export type { ViemApi };

package/src/helpers/format-error.ts

@@ -0,0 +1,31 @@
+/**
+ * Coerce anything a wallet/SDK can throw or reject with into a readable
+ * string.
+ *
+ * Wallet bridges return errors in three common shapes:
+ *   1. `Error` instances (most JS SDKs)
+ *   2. CIP-30-style `{ code: number, info: string }` (Midnight Lace, some
+ *      Cardano wallets, Mina/Auro)
+ *   3. Plain strings or numbers
+ *
+ * `String(obj)` on shape #2 yields the useless `"[object Object]"`, which
+ * leaks into UIs as "Error: [object Object]". This helper unpacks all three.
+ */
+export function formatError(err: unknown): string {
+  if (err == null) return "";
+  if (err instanceof Error) return err.message;
+  if (typeof err === "string") return err;
+  if (typeof err === "object") {
+    const o = err as { info?: string; message?: string; code?: number };
+    if (typeof o.info === "string") {
+      return o.code != null ? `${o.info} (code ${o.code})` : o.info;
+    }
+    if (typeof o.message === "string") return o.message;
+    try {
+      return JSON.stringify(err);
+    } catch {
+      // Cyclic objects land here.
+    }
+  }
+  return String(err);
+}

package/src/helpers/local-icons.ts

@@ -0,0 +1,35 @@
+/**
+ * Inline SVG icons for the three local-JS wallet modes.
+ *
+ * Each is a 32x32 circle filled with the chain's brand colour and the letters
+ * "JS" centered in white, so the wallets-ui (and templates) can distinguish
+ * the seed-driven local wallets from injected browser-extension wallets at a
+ * glance.
+ *
+ * Returned as `data:image/svg+xml` data URIs so they slot directly into
+ * `WalletOption.icon`, which the UI renders inside `<img>` tags.
+ */
+
+function encodeSvg(svg: string): string {
+  return `data:image/svg+xml;utf8,${encodeURIComponent(svg)}`;
+}
+
+function jsCircle(fill: string, textFill = "#ffffff"): string {
+  return (
+    `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">` +
+    `<circle cx="16" cy="16" r="16" fill="${fill}"/>` +
+    `<text x="16" y="21" text-anchor="middle" ` +
+    `font-family="Inter,-apple-system,BlinkMacSystemFont,Segoe UI,sans-serif" ` +
+    `font-weight="700" font-size="13" fill="${textFill}">JS</text>` +
+    `</svg>`
+  );
+}
+
+/** Orange circle — EVM Viem local wallet. */
+export const evmViemIcon = encodeSvg(jsCircle("#F97316"));
+
+/** Cardano brand blue circle — Cardano Lucid local wallet. */
+export const cardanoLocalIcon = encodeSvg(jsCircle("#0033AD"));
+
+/** Near-black circle — Midnight local-seed wallet. */
+export const midnightLocalIcon = encodeSvg(jsCircle("#0A0A0A"));