@multiplatform.one/web3 7.32.0 → 7.33.0

package/src/phantom/evm.ts

@@ -0,0 +1,163 @@
+import { numberToHex, type Chain, type EIP1193Provider, type PublicClient } from "viem";
+import { evmClient, type EvmClient } from "../clients/evm";
+import { phantomBrowseUrl } from "./urls";
+
+export type PhantomEthereumProvider = EIP1193Provider & { isPhantom?: boolean };
+
+interface PhantomWindow {
+  phantom?: { ethereum?: PhantomEthereumProvider };
+  ethereum?: PhantomEthereumProvider;
+  location?: { href: string; origin: string; assign(url: string): void };
+  addEventListener?: (type: string, listener: (event: Event) => void) => void;
+  removeEventListener?: (type: string, listener: (event: Event) => void) => void;
+  dispatchEvent?: (event: Event) => boolean;
+}
+
+const phantomRdns = "app.phantom";
+
+/**
+ * Phantom's injected EVM provider: `window.phantom.ethereum`, else a
+ * `window.ethereum` that says it is Phantom. Present in Phantom's desktop
+ * extension and its in-app browser, never in Chrome or Safari on a phone.
+ */
+export function phantomEthereumProvider(
+  win: PhantomWindow = globalThis as PhantomWindow,
+): PhantomEthereumProvider | undefined {
+  const own = win.phantom?.ethereum;
+  if (own?.isPhantom) return own;
+  if (win.ethereum?.isPhantom) return win.ethereum;
+  return undefined;
+}
+
+/**
+ * phantomEthereumProvider, or Phantom's EIP-6963 announcement (rdns
+ * `app.phantom`) when the provider is not on `window` yet. Resolves undefined
+ * after `timeout` ms.
+ */
+export function discoverPhantomEthereumProvider(
+  options: { timeout?: number; window?: PhantomWindow } = {},
+): Promise<PhantomEthereumProvider | undefined> {
+  const win = options.window ?? (globalThis as PhantomWindow);
+  const found = phantomEthereumProvider(win);
+  if (found || !win.addEventListener || !win.dispatchEvent) return Promise.resolve(found);
+  return new Promise((resolve) => {
+    const onAnnounce = (event: Event) => {
+      const detail = (
+        event as CustomEvent<{ info?: { rdns?: string }; provider?: PhantomEthereumProvider }>
+      ).detail;
+      if (detail?.info?.rdns !== phantomRdns || !detail.provider) return;
+      done(detail.provider);
+    };
+    const timer = setTimeout(() => done(phantomEthereumProvider(win)), options.timeout ?? 500);
+    const done = (provider: PhantomEthereumProvider | undefined) => {
+      clearTimeout(timer);
+      win.removeEventListener?.("eip6963:announceProvider", onAnnounce);
+      resolve(provider);
+    };
+    win.addEventListener?.("eip6963:announceProvider", onAnnounce);
+    win.dispatchEvent?.(new Event("eip6963:requestProvider"));
+  });
+}
+
+/**
+ * How this page reaches Phantom's EVM wallet: `injected` when Phantom's
+ * provider is here (extension or Phantom's browser), `browse` when the page
+ * must first reopen inside Phantom with openInPhantom.
+ */
+export function phantomEvmRoute(win: PhantomWindow = globalThis as PhantomWindow) {
+  return phantomEthereumProvider(win) ? ("injected" as const) : ("browse" as const);
+}
+
+export interface OpenInPhantomOptions {
+  /** The page to open in Phantom's browser. Defaults to this page. */
+  url?: string;
+  /** The requesting app. Defaults to this page's origin. */
+  ref?: string;
+  /** Defaults to `location.assign`. */
+  navigate?: (url: string) => void;
+  base?: string;
+  window?: PhantomWindow;
+}
+
+/**
+ * Reopens the page inside Phantom's in-app browser. Call it straight from the
+ * tap handler with nothing awaited first: mobile browsers only follow a link
+ * into another app without a prompt inside the tap's user activation.
+ * Returns the link, for an `<a href>` instead.
+ */
+export function openInPhantom(options: OpenInPhantomOptions = {}): string {
+  const win = options.window ?? (globalThis as PhantomWindow);
+  const url = options.url ?? win.location?.href;
+  const ref = options.ref ?? win.location?.origin ?? url;
+  if (!url || !ref) throw new Error("openInPhantom: no page URL here; pass `url` and `ref`");
+  const link = phantomBrowseUrl(url, ref, { base: options.base });
+  (options.navigate ?? ((target: string) => win.location?.assign(target)))(link);
+  return link;
+}
+
+export interface ConnectPhantomEvmOptions {
+  chain: Chain;
+  /** Defaults to phantomEthereumProvider(). */
+  provider?: PhantomEthereumProvider;
+  publicClient?: PublicClient;
+  rpcUrl?: string;
+}
+
+export class PhantomNotInjectedError extends Error {
+  constructor() {
+    super(
+      "Phantom's EVM provider is not on this page: on a phone, reopen it in Phantom with openInPhantom()",
+    );
+    this.name = "PhantomNotInjectedError";
+  }
+}
+
+const errorCode = (error: unknown) =>
+  (error as { code?: unknown; cause?: { code?: unknown } } | undefined)?.code ??
+  (error as { cause?: { code?: unknown } } | undefined)?.cause?.code;
+
+async function ensureChain(provider: PhantomEthereumProvider, chain: Chain) {
+  const current = await provider.request({ method: "eth_chainId" });
+  if (Number(current) === chain.id) return;
+  const chainId = numberToHex(chain.id);
+  try {
+    await provider.request({ method: "wallet_switchEthereumChain", params: [{ chainId }] });
+  } catch (error) {
+    if (errorCode(error) !== 4902) throw error;
+    await provider.request({
+      method: "wallet_addEthereumChain",
+      params: [
+        {
+          chainId,
+          chainName: chain.name,
+          nativeCurrency: chain.nativeCurrency,
+          rpcUrls: [...chain.rpcUrls.default.http],
+          blockExplorerUrls: chain.blockExplorers ? [chain.blockExplorers.default.url] : undefined,
+        },
+      ],
+    });
+    await provider.request({ method: "wallet_switchEthereumChain", params: [{ chainId }] });
+  }
+}
+
+/**
+ * Connects Phantom's injected EVM wallet, moves it to `chain`, and returns
+ * the mpo EVM client on it, so `erc20.transfer` and `writeContract` go to
+ * Phantom for approval. Testnets such as Base Sepolia need Phantom's Testnet
+ * Mode on.
+ */
+export async function connectPhantomEvm(options: ConnectPhantomEvmOptions): Promise<EvmClient> {
+  const provider = options.provider ?? phantomEthereumProvider();
+  if (!provider) throw new PhantomNotInjectedError();
+  const accounts = await provider.request({ method: "eth_requestAccounts" });
+  const account = accounts[0];
+  if (!account) throw new Error("Phantom returned no EVM account");
+  await ensureChain(provider, options.chain);
+  return evmClient({
+    provider,
+    account,
+    chain: options.chain,
+    publicClient: options.publicClient,
+    rpcUrl: options.rpcUrl,
+  });
+}

package/src/phantom/index.ts

@@ -0,0 +1,16 @@
+// `@multiplatform.one/web3/phantom`: Phantom's EVM wallet from a phone's own
+// browser. Phantom's deeplinks carry no EVM methods, so the page reopens in
+// Phantom's in-app browser (openInPhantom) and connects the provider Phantom
+// injects there (connectPhantomEvm).
+export {
+  connectPhantomEvm,
+  discoverPhantomEthereumProvider,
+  openInPhantom,
+  phantomEthereumProvider,
+  phantomEvmRoute,
+  PhantomNotInjectedError,
+  type ConnectPhantomEvmOptions,
+  type OpenInPhantomOptions,
+  type PhantomEthereumProvider,
+} from "./evm";
+export { phantomBrowseUrl, phantomUniversalLinkBase } from "./urls";

package/src/phantom/urls.spec.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import { phantomBrowseUrl } from "./urls";
+
+describe("phantomBrowseUrl", () => {
+  it("builds the browse link Phantom documents", () => {
+    expect(
+      phantomBrowseUrl(
+        "https://magiceden.io/item-details/8yjN8iRuoiYiKW487cnW9vn6mLBR5E8aCNKsBRmTP9vN",
+        "https://magiceden.io",
+      ),
+    ).toBe(
+      "https://phantom.com/ul/browse/https%3A%2F%2Fmagiceden.io%2Fitem-details%2F8yjN8iRuoiYiKW487cnW9vn6mLBR5E8aCNKsBRmTP9vN?ref=https%3A%2F%2Fmagiceden.io",
+    );
+  });
+
+  it("keeps a page's own query inside the browse link", () => {
+    expect(
+      phantomBrowseUrl(
+        "https://dev.promanager.vip/u/buy?mobile=1&x=a b",
+        "https://dev.promanager.vip",
+        {
+          base: "https://phantom.app/ul/",
+        },
+      ),
+    ).toBe(
+      "https://phantom.app/ul/browse/https%3A%2F%2Fdev.promanager.vip%2Fu%2Fbuy%3Fmobile%3D1%26x%3Da%20b?ref=https%3A%2F%2Fdev.promanager.vip",
+    );
+  });
+});

package/src/phantom/urls.ts

@@ -0,0 +1,16 @@
+/** Phantom's universal-link host. `https://phantom.app/ul` still answers; Phantom asks new code to use this one. */
+export const phantomUniversalLinkBase = "https://phantom.com/ul";
+
+/**
+ * Opens `url` inside Phantom's in-app browser, where Phantom injects
+ * `window.phantom.ethereum`. Phantom's deeplinks carry no EVM methods, so
+ * this is how a phone's browser reaches its EVM wallet.
+ */
+export function phantomBrowseUrl(
+  url: string,
+  ref: string,
+  options: { base?: string } = {},
+): string {
+  const base = (options.base ?? phantomUniversalLinkBase).replace(/\/+$/, "");
+  return `${base}/browse/${encodeURIComponent(url)}?ref=${encodeURIComponent(ref)}`;
+}

package/types/phantom/evm.d.ts

@@ -0,0 +1,76 @@
+import { type Chain, type EIP1193Provider, type PublicClient } from "viem";
+import { type EvmClient } from "../clients/evm";
+export type PhantomEthereumProvider = EIP1193Provider & {
+    isPhantom?: boolean;
+};
+interface PhantomWindow {
+    phantom?: {
+        ethereum?: PhantomEthereumProvider;
+    };
+    ethereum?: PhantomEthereumProvider;
+    location?: {
+        href: string;
+        origin: string;
+        assign(url: string): void;
+    };
+    addEventListener?: (type: string, listener: (event: Event) => void) => void;
+    removeEventListener?: (type: string, listener: (event: Event) => void) => void;
+    dispatchEvent?: (event: Event) => boolean;
+}
+/**
+ * Phantom's injected EVM provider: `window.phantom.ethereum`, else a
+ * `window.ethereum` that says it is Phantom. Present in Phantom's desktop
+ * extension and its in-app browser, never in Chrome or Safari on a phone.
+ */
+export declare function phantomEthereumProvider(win?: PhantomWindow): PhantomEthereumProvider | undefined;
+/**
+ * phantomEthereumProvider, or Phantom's EIP-6963 announcement (rdns
+ * `app.phantom`) when the provider is not on `window` yet. Resolves undefined
+ * after `timeout` ms.
+ */
+export declare function discoverPhantomEthereumProvider(options?: {
+    timeout?: number;
+    window?: PhantomWindow;
+}): Promise<PhantomEthereumProvider | undefined>;
+/**
+ * How this page reaches Phantom's EVM wallet: `injected` when Phantom's
+ * provider is here (extension or Phantom's browser), `browse` when the page
+ * must first reopen inside Phantom with openInPhantom.
+ */
+export declare function phantomEvmRoute(win?: PhantomWindow): "injected" | "browse";
+export interface OpenInPhantomOptions {
+    /** The page to open in Phantom's browser. Defaults to this page. */
+    url?: string;
+    /** The requesting app. Defaults to this page's origin. */
+    ref?: string;
+    /** Defaults to `location.assign`. */
+    navigate?: (url: string) => void;
+    base?: string;
+    window?: PhantomWindow;
+}
+/**
+ * Reopens the page inside Phantom's in-app browser. Call it straight from the
+ * tap handler with nothing awaited first: mobile browsers only follow a link
+ * into another app without a prompt inside the tap's user activation.
+ * Returns the link, for an `<a href>` instead.
+ */
+export declare function openInPhantom(options?: OpenInPhantomOptions): string;
+export interface ConnectPhantomEvmOptions {
+    chain: Chain;
+    /** Defaults to phantomEthereumProvider(). */
+    provider?: PhantomEthereumProvider;
+    publicClient?: PublicClient;
+    rpcUrl?: string;
+}
+export declare class PhantomNotInjectedError extends Error {
+    constructor();
+}
+/**
+ * Connects Phantom's injected EVM wallet, moves it to `chain`, and returns
+ * the mpo EVM client on it, so `erc20.transfer` and `writeContract` go to
+ * Phantom for approval. Testnets such as Base Sepolia need Phantom's Testnet
+ * Mode on.
+ */
+export declare function connectPhantomEvm(options: ConnectPhantomEvmOptions): Promise<EvmClient>;
+export {};
+//# sourceMappingURL=evm.d.ts.map

package/types/phantom/evm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evm.d.ts","sourceRoot":"","sources":["../../src/phantom/evm.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,KAAK,EAAE,KAAK,eAAe,EAAE,KAAK,YAAY,EAAE,MAAM,MAAM,CAAC;AACxF,OAAO,EAAa,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAG3D,MAAM,MAAM,uBAAuB,GAAG,eAAe,GAAG;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAEhF,UAAU,aAAa;IACrB,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,uBAAuB,CAAA;KAAE,CAAC;IACjD,QAAQ,CAAC,EAAE,uBAAuB,CAAC;IACnC,QAAQ,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IACvE,gBAAgB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,KAAK,IAAI,CAAC;IAC5E,mBAAmB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,KAAK,IAAI,CAAC;IAC/E,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC;CAC3C;AAID;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,GAAE,aAA2C,GAC/C,uBAAuB,GAAG,SAAS,CAKrC;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,aAAa,CAAA;CAAO,GACzD,OAAO,CAAC,uBAAuB,GAAG,SAAS,CAAC,CAqB9C;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,GAAE,aAA2C,yBAE/E;AAED,MAAM,WAAW,oBAAoB;IACnC,oEAAoE;IACpE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,MAAM,CAQxE;AAED,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,KAAK,CAAC;IACb,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,uBAAuB,CAAC;IACnC,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,uBAAwB,SAAQ,KAAK;;CAOjD;AA8BD;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,SAAS,CAAC,CAc7F"}

package/types/phantom/index.d.ts

@@ -0,0 +1,3 @@
+export { connectPhantomEvm, discoverPhantomEthereumProvider, openInPhantom, phantomEthereumProvider, phantomEvmRoute, PhantomNotInjectedError, type ConnectPhantomEvmOptions, type OpenInPhantomOptions, type PhantomEthereumProvider, } from "./evm";
+export { phantomBrowseUrl, phantomUniversalLinkBase } from "./urls";
+//# sourceMappingURL=index.d.ts.map

package/types/phantom/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/phantom/index.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,iBAAiB,EACjB,+BAA+B,EAC/B,aAAa,EACb,uBAAuB,EACvB,eAAe,EACf,uBAAuB,EACvB,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,GAC7B,MAAM,OAAO,CAAC;AACf,OAAO,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,QAAQ,CAAC"}

package/types/phantom/urls.d.ts

@@ -0,0 +1,11 @@
+/** Phantom's universal-link host. `https://phantom.app/ul` still answers; Phantom asks new code to use this one. */
+export declare const phantomUniversalLinkBase = "https://phantom.com/ul";
+/**
+ * Opens `url` inside Phantom's in-app browser, where Phantom injects
+ * `window.phantom.ethereum`. Phantom's deeplinks carry no EVM methods, so
+ * this is how a phone's browser reaches its EVM wallet.
+ */
+export declare function phantomBrowseUrl(url: string, ref: string, options?: {
+    base?: string;
+}): string;
+//# sourceMappingURL=urls.d.ts.map

package/types/phantom/urls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"urls.d.ts","sourceRoot":"","sources":["../../src/phantom/urls.ts"],"names":[],"mappings":"AAAA,oHAAoH;AACpH,eAAO,MAAM,wBAAwB,2BAA2B,CAAC;AAEjE;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,OAAO,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GAC9B,MAAM,CAGR"}