@hfunlabs/hypurr-connect 0.1.2 → 0.1.4

package/src/HypurrConnectProvider.tsx

@@ -3,8 +3,7 @@ import {
   HttpTransport,
   type IRequestTransport,
 } from "@hfunlabs/hyperliquid";
-import { approveAgent as sdkApproveAgent } from "@hfunlabs/hyperliquid/api/exchange";
-import { PrivateKeySigner } from "@hfunlabs/hyperliquid/signing";
+import { PrivateKeySigner, signUserSignedAction } from "@hfunlabs/hyperliquid/signing";
 import type { TelegramUserResponse } from "hypurr-grpc/ts/hypurr/telegram/telegram_service";
 import type {
   TelegramUser as HypurrTelegramUser,
@@ -35,6 +34,7 @@ import { createStaticClient, createTelegramClient } from "./grpc";
 import { GrpcExchangeTransport } from "./GrpcExchangeTransport";
 import type {
   AuthMethod,
+  EoaSigner,
   HypurrConnectConfig,
   HypurrConnectState,
   HypurrUser,
@@ -46,6 +46,8 @@ import type {
 /** @internal context value — extends the public type with fields used only by library internals */
 interface InternalConnectState extends HypurrConnectState {
   loginTelegram: (data: TelegramLoginData) => void;
+  botUsername: string;
+  useWidget: boolean;
 }
 
 const TELEGRAM_STORAGE_KEY = "hypurr-connect-tg-user";
@@ -125,9 +127,19 @@ export function HypurrConnectProvider({
     (async () => {
       try {
         const authData = toAuthDataMap(tgLoginData);
-        const { response } = await tgClient.telegramUser({ authData });
+        const [{ response: userResp }, { response: walletsResp }] =
+          await Promise.all([
+            tgClient.telegramUser({ authData }),
+            tgClient.telegramUserWallets({ authData }),
+          ]);
         if (cancelled) return;
-        setTgUser((response as TelegramUserResponse).user ?? null);
+        const user = (userResp as TelegramUserResponse).user ?? null;
+        if (user) {
+          // TelegramUser.wallets lacks twap/scale sessions; replace with
+          // the full wallets from TelegramUserWallets which populates them.
+          user.wallets = walletsResp.wallets;
+        }
+        setTgUser(user);
       } catch (err) {
         if (cancelled) return;
         console.error("[HypurrConnect] gRPC TelegramUser failed:", err);
@@ -147,6 +159,7 @@ export function HypurrConnectProvider({
   const [agent, setAgent] = useState<StoredAgent | null>(null);
   const [eoaLoading, setEoaLoading] = useState(false);
   const [eoaError, setEoaError] = useState<string | null>(null);
+  const eoaSignerRef = useRef<EoaSigner | null>(null);
 
   // ── Derived auth ─────────────────────────────────────────────
   const authMethod: AuthMethod = tgLoginData
@@ -223,7 +236,12 @@ export function HypurrConnectProvider({
 
   // ── Exchange client ──────────────────────────────────────────
   // Telegram: GrpcExchangeTransport → HyperliquidCoreAction (server signs)
-  // EOA: HttpTransport + agent wallet (SDK signs locally)
+  // EOA: dual wallet — agent key for L1 actions, master signer for user-signed
+  //   actions (transfers, withdrawals, etc.). The dual wallet inspects the
+  //   EIP-712 domain name to decide which key signs each request.
+  //   When a signer is available but no agent exists yet, the dual wallet
+  //   auto-provisions an agent on the first L1 action (triggers one extra
+  //   wallet popup for the approveAgent user-signed action).
 
   const onDeadAgentRef = useRef<((address: `0x${string}`) => void) | null>(
     null,
@@ -234,6 +252,20 @@ export function HypurrConnectProvider({
     setEoaError("Agent expired or was deregistered. Please reconnect.");
   };
 
+  // Mutable slot for the agent signer — the dual wallet reads this so it can
+  // pick up a newly provisioned agent without waiting for a React re-render.
+  const agentSignerRef = useRef<PrivateKeySigner | null>(
+    agent ? new PrivateKeySigner(agent.privateKey) : null,
+  );
+  useEffect(() => {
+    agentSignerRef.current = agent
+      ? new PrivateKeySigner(agent.privateKey)
+      : null;
+  }, [agent]);
+
+  // Lock to prevent concurrent auto-provisioning attempts
+  const provisioningRef = useRef<Promise<PrivateKeySigner> | null>(null);
+
   const agentReady =
     authMethod === "telegram" || (authMethod === "eoa" && !!agent);
 
@@ -254,14 +286,16 @@ export function HypurrConnectProvider({
     }
 
     if (authMethod === "eoa" && eoaAddress) {
-      if (!agent) {
+      const hasSigner = !!eoaSignerRef.current;
+
+      if (!agent && !hasSigner) {
         const noAgentTransport: IRequestTransport = {
           isTestnet: config.isTestnet ?? false,
           request(): Promise<never> {
             throw new Error(
-              "[HypurrConnect] No agent key approved. " +
-                "Call approveAgent(signTypedDataAsync) before using the exchange client. " +
-                "This is required for EOA wallets to sign transactions on Hyperliquid.",
+              "[HypurrConnect] No agent key approved and no wallet signer available. " +
+                "Either call approveAgent(signTypedDataAsync) or pass a signer to " +
+                "connectEoa(address, { signTypedData, chainId }).",
             );
           },
         };
@@ -272,9 +306,8 @@ export function HypurrConnectProvider({
         });
       }
 
-      const inner = new HttpTransport({
-        isTestnet: config.isTestnet ?? false,
-      });
+      const isTestnet = config.isTestnet ?? false;
+      const inner = new HttpTransport({ isTestnet });
       const deadAgentAddr = eoaAddress;
       const guardedTransport: IRequestTransport = {
         isTestnet: inner.isTestnet,
@@ -293,10 +326,160 @@ export function HypurrConnectProvider({
           }
         },
       };
-      const wallet = new PrivateKeySigner(agent.privateKey);
+
+      const signerRef = eoaSignerRef;
+      const agentRef = agentSignerRef;
+      const provRef = provisioningRef;
+      const ownerAddress = eoaAddress;
+
+      /**
+       * Auto-provision an agent key when one doesn't exist yet.
+       *
+       * Bypasses the SDK's `executeUserSignedAction` (and its per-address
+       * semaphore) to avoid deadlocking when called from inside
+       * `dualWallet.signTypedData`, which is already inside the SDK's
+       * `executeL1Action` lock for the same address.
+       */
+      const ensureAgent = async (): Promise<PrivateKeySigner> => {
+        const existing = agentRef.current;
+        if (existing) return existing;
+
+        if (provRef.current) return provRef.current;
+
+        const signer = signerRef.current;
+        if (!signer) {
+          throw new Error(
+            "[HypurrConnect] No wallet signer available to auto-provision agent. " +
+              "Pass a signer to connectEoa(address, { signTypedData, chainId }).",
+          );
+        }
+
+        provRef.current = (async () => {
+          try {
+            const { privateKey, address: agentAddress } =
+              await generateAgentKey();
+
+            const chainIdHex = `0x${signer.chainId.toString(16)}` as `0x${string}`;
+            const nonce = Date.now();
+            const action = {
+              type: "approveAgent" as const,
+              signatureChainId: chainIdHex,
+              hyperliquidChain: (isTestnet ? "Testnet" : "Mainnet") as
+                | "Testnet"
+                | "Mainnet",
+              agentAddress: agentAddress.toLowerCase() as `0x${string}`,
+              agentName: AGENT_NAME,
+              nonce,
+            };
+
+            const approveAgentTypes = {
+              "HyperliquidTransaction:ApproveAgent": [
+                { name: "hyperliquidChain", type: "string" },
+                { name: "agentAddress", type: "address" },
+                { name: "agentName", type: "string" },
+                { name: "nonce", type: "uint64" },
+              ],
+            };
+
+            const wallet = {
+              // eslint-disable-next-line @typescript-eslint/no-explicit-any
+              signTypedData(params: any) {
+                return signer.signTypedData(params);
+              },
+              getAddresses: async () => [ownerAddress] as `0x${string}`[],
+              getChainId: async () => signer.chainId,
+            };
+
+            const signature = await signUserSignedAction({
+              wallet,
+              action,
+              types: approveAgentTypes,
+            });
+
+            const apiUrl = isTestnet
+              ? "https://api.hyperliquid-testnet.xyz/exchange"
+              : "https://api.hyperliquid.xyz/exchange";
+
+            const res = await fetch(apiUrl, {
+              method: "POST",
+              headers: { "Content-Type": "application/json" },
+              body: JSON.stringify({ action, signature, nonce }),
+            });
+
+            const body = await res.json();
+            if (body?.status === "err") {
+              throw new Error(
+                `approveAgent API error: ${body.response ?? JSON.stringify(body)}`,
+              );
+            }
+
+            const remote = await fetchActiveAgent(ownerAddress, isTestnet);
+            const validUntil =
+              remote?.validUntil ?? Date.now() + 7 * 24 * 60 * 60 * 1000;
+
+            const stored: StoredAgent = {
+              privateKey,
+              address: agentAddress,
+              approvedAt: Date.now(),
+              validUntil,
+            };
+            saveAgent(ownerAddress, stored);
+
+            const newSigner = new PrivateKeySigner(privateKey);
+            agentRef.current = newSigner;
+            setAgent(stored);
+
+            return newSigner;
+          } finally {
+            provRef.current = null;
+          }
+        })();
+
+        return provRef.current;
+      };
+
+      // Dual wallet: routes signing based on the EIP-712 domain.
+      // "Exchange" domain → L1 action → agent key signs (auto-provisions if needed).
+      // "HyperliquidSignTransaction" domain → user-signed → master wallet (popup).
+      const dualWallet = {
+        address: ownerAddress,
+        async signTypedData(params: {
+          domain: {
+            name?: string;
+            version?: string;
+            chainId?: number;
+            verifyingContract?: `0x${string}`;
+            salt?: `0x${string}`;
+          };
+          types: Record<string, { name: string; type: string }[]>;
+          primaryType: string;
+          message: Record<string, unknown>;
+        }): Promise<`0x${string}`> {
+          if (params.domain.name === "HyperliquidSignTransaction") {
+            const signer = signerRef.current;
+            if (!signer) {
+              throw new Error(
+                "[HypurrConnect] No wallet signer available for user-signed actions. " +
+                  "Pass a signer to connectEoa(address, { signTypedData, chainId }).",
+              );
+            }
+            return signer.signTypedData(
+              params as Parameters<typeof signer.signTypedData>[0],
+            );
+          }
+
+          const agentSigner = await ensureAgent();
+          return agentSigner.signTypedData(params);
+        },
+      };
+
       return new ExchangeClient({
         transport: guardedTransport,
-        wallet,
+        wallet: dualWallet,
+        signatureChainId: () => {
+          const id = signerRef.current?.chainId ?? 42161;
+          return `0x${id.toString(16)}` as `0x${string}`;
+        },
       });
     }
 
@@ -415,22 +598,26 @@ export function HypurrConnectProvider({
     setEoaError(null);
   }, []);
 
-  const connectEoa = useCallback((address: `0x${string}`) => {
-    setEoaAddress(address);
-    setTgLoginData(null);
-    setTgUser(null);
-    setTgError(null);
-    setEoaError(null);
-    localStorage.removeItem(TELEGRAM_STORAGE_KEY);
+  const connectEoa = useCallback(
+    (address: `0x${string}`, signer?: EoaSigner) => {
+      eoaSignerRef.current = signer ?? null;
+      setEoaAddress(address);
+      setTgLoginData(null);
+      setTgUser(null);
+      setTgError(null);
+      setEoaError(null);
+      localStorage.removeItem(TELEGRAM_STORAGE_KEY);
 
-    const existing = loadAgent(address);
-    if (existing && existing.validUntil > Date.now()) {
-      setAgent(existing);
-    } else {
-      if (existing) clearStoredAgent(address);
-      setAgent(null);
-    }
-  }, []);
+      const existing = loadAgent(address);
+      if (existing && existing.validUntil > Date.now()) {
+        setAgent(existing);
+      } else {
+        if (existing) clearStoredAgent(address);
+        setAgent(null);
+      }
+    },
+    [],
+  );
 
   const approveAgentFn = useCallback(
     async (signTypedDataAsync: SignTypedDataFn, chainId: number) => {
@@ -440,6 +627,8 @@ export function HypurrConnectProvider({
         );
       }
 
+      eoaSignerRef.current = { signTypedData: signTypedDataAsync, chainId };
+
       setEoaLoading(true);
       setEoaError(null);
       try {
@@ -457,20 +646,59 @@ export function HypurrConnectProvider({
         const { privateKey, address: agentAddress } = await generateAgentKey();
         const isTestnet = config.isTestnet ?? false;
 
+        const chainIdHex = `0x${chainId.toString(16)}` as `0x${string}`;
+        const nonce = Date.now();
+        const action = {
+          type: "approveAgent" as const,
+          signatureChainId: chainIdHex,
+          hyperliquidChain: (isTestnet ? "Testnet" : "Mainnet") as
+            | "Testnet"
+            | "Mainnet",
+          agentAddress: agentAddress.toLowerCase() as `0x${string}`,
+          agentName: AGENT_NAME,
+          nonce,
+        };
+
+        const approveAgentTypes = {
+          "HyperliquidTransaction:ApproveAgent": [
+            { name: "hyperliquidChain", type: "string" },
+            { name: "agentAddress", type: "address" },
+            { name: "agentName", type: "string" },
+            { name: "nonce", type: "uint64" },
+          ],
+        };
+
         const wallet = {
-          signTypedData: signTypedDataAsync,
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          signTypedData(params: any) {
+            return signTypedDataAsync(params);
+          },
           getAddresses: async () => [eoaAddress] as `0x${string}`[],
           getChainId: async () => chainId,
         };
-        const transport = new HttpTransport({ isTestnet });
 
-        await sdkApproveAgent(
-          { transport, wallet },
-          {
-            agentAddress: agentAddress.toLowerCase() as `0x${string}`,
-            agentName: AGENT_NAME,
-          },
-        );
+        const signature = await signUserSignedAction({
+          wallet,
+          action,
+          types: approveAgentTypes,
+        });
+
+        const apiUrl = isTestnet
+          ? "https://api.hyperliquid-testnet.xyz/exchange"
+          : "https://api.hyperliquid.xyz/exchange";
+
+        const res = await fetch(apiUrl, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ action, signature, nonce }),
+        });
+
+        const body = await res.json();
+        if (body?.status === "err") {
+          throw new Error(
+            `approveAgent API error: ${body.response ?? JSON.stringify(body)}`,
+          );
+        }
 
         const remote = await fetchActiveAgent(eoaAddress, isTestnet);
         const validUntil =
@@ -502,6 +730,7 @@ export function HypurrConnectProvider({
     setEoaAddress(null);
     setAgent(null);
     setEoaError(null);
+    eoaSignerRef.current = null;
     localStorage.removeItem(TELEGRAM_STORAGE_KEY);
   }, []);
 
@@ -543,6 +772,8 @@ export function HypurrConnectProvider({
       clearAgent: handleClearAgent,
 
       botId: config.telegram?.botId ?? "",
+      botUsername: config.telegram?.botUsername ?? "",
+      useWidget: config.telegram?.useWidget ?? false,
 
       authDataMap,
       telegramClient: tgClient,
@@ -578,6 +809,8 @@ export function HypurrConnectProvider({
       agentReady,
       handleClearAgent,
       config.telegram?.botId,
+      config.telegram?.botUsername,
+      config.telegram?.useWidget,
       authDataMap,
       tgClient,
       staticClient,

package/src/LoginModal.tsx

@@ -14,6 +14,7 @@ import {
 import { useHypurrConnectInternal } from "./HypurrConnectProvider";
 import { MetaMaskColorIcon } from "./icons/MetaMaskColorIcon";
 import { TelegramColorIcon } from "./icons/TelegramColorIcon";
+import { TelegramLoginWidget } from "./TelegramLoginWidget";
 import type { TelegramLoginData } from "./types";
 
 export interface LoginModalProps {
@@ -130,8 +131,14 @@ function HoverButton({
 }
 
 export function LoginModal({ onConnectWallet, walletIcon }: LoginModalProps) {
-  const { loginTelegram, loginModalOpen, closeLoginModal, botId } =
-    useHypurrConnectInternal();
+  const {
+    loginTelegram,
+    loginModalOpen,
+    closeLoginModal,
+    botId,
+    botUsername,
+    useWidget,
+  } = useHypurrConnectInternal();
 
   const handleTelegramAuth = useCallback(
     (user: TelegramLoginData) => {
@@ -195,10 +202,17 @@ export function LoginModal({ onConnectWallet, walletIcon }: LoginModalProps) {
           overflow: "hidden",
         }}
       >
-        <HoverButton onClick={openTelegramOAuth}>
-          <TelegramColorIcon style={iconSize} />
-          Telegram
-        </HoverButton>
+        {useWidget && botUsername ? (
+          <TelegramLoginWidget
+            botUsername={botUsername}
+            onAuth={handleTelegramAuth}
+          />
+        ) : (
+          <HoverButton onClick={openTelegramOAuth}>
+            <TelegramColorIcon style={iconSize} />
+            Telegram
+          </HoverButton>
+        )}
       </div>
 
       <div style={dividerStyle} />

package/src/TelegramLoginWidget.tsx

@@ -0,0 +1,62 @@
+import { useEffect, useRef } from "react";
+import type { TelegramLoginData } from "./types";
+
+const WIDGET_SCRIPT_URL = "https://telegram.org/js/telegram-widget.js?22";
+const CALLBACK_NAME = "__hypurrConnectTelegramAuth";
+
+export interface TelegramLoginWidgetProps {
+  botUsername: string;
+  onAuth: (data: TelegramLoginData) => void;
+  buttonSize?: "large" | "medium" | "small";
+  cornerRadius?: number;
+  showUserPhoto?: boolean;
+  requestAccess?: boolean;
+}
+
+export function TelegramLoginWidget({
+  botUsername,
+  onAuth,
+  buttonSize = "large",
+  cornerRadius,
+  showUserPhoto = true,
+  requestAccess = true,
+}: TelegramLoginWidgetProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const onAuthRef = useRef(onAuth);
+  onAuthRef.current = onAuth;
+
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+
+    (window as unknown as Record<string, unknown>)[CALLBACK_NAME] = (
+      user: TelegramLoginData,
+    ) => {
+      onAuthRef.current(user);
+    };
+
+    const script = document.createElement("script");
+    script.src = WIDGET_SCRIPT_URL;
+    script.async = true;
+    script.setAttribute("data-telegram-login", botUsername);
+    script.setAttribute("data-size", buttonSize);
+    script.setAttribute("data-onauth", `${CALLBACK_NAME}(user)`);
+    script.setAttribute("data-userpic", String(showUserPhoto));
+    if (requestAccess) {
+      script.setAttribute("data-request-access", "write");
+    }
+    if (cornerRadius !== undefined) {
+      script.setAttribute("data-radius", String(cornerRadius));
+    }
+
+    container.innerHTML = "";
+    container.appendChild(script);
+
+    return () => {
+      container.innerHTML = "";
+      delete (window as unknown as Record<string, unknown>)[CALLBACK_NAME];
+    };
+  }, [botUsername, buttonSize, cornerRadius, showUserPhoto, requestAccess]);
+
+  return <div ref={containerRef} />;
+}

package/src/index.ts

@@ -4,11 +4,15 @@ export {
 } from "./HypurrConnectProvider";
 export { LoginModal } from "./LoginModal";
 export type { LoginModalProps } from "./LoginModal";
+export { TelegramLoginWidget } from "./TelegramLoginWidget";
+export type { TelegramLoginWidgetProps } from "./TelegramLoginWidget";
 export { GrpcExchangeTransport } from "./GrpcExchangeTransport";
 export type { GrpcExchangeTransportConfig } from "./GrpcExchangeTransport";
 export { createTelegramClient, createStaticClient } from "./grpc";
+export { createEoaSigner } from "./types";
 export type {
   AuthMethod,
+  EoaSigner,
   HypurrConnectConfig,
   HypurrConnectState,
   HypurrUser,
@@ -20,3 +24,7 @@ export type {
 // Re-export wallet types from hypurr-grpc so consumers don't need the dependency
 export type { HyperliquidWallet } from "hypurr-grpc/ts/hypurr/wallet";
 export type { TelegramChatWalletPack } from "hypurr-grpc/ts/hypurr/user";
+export type {
+  HyperliquidWalletScaleSession,
+  HyperliquidWalletTwapSession,
+} from "hypurr-grpc/ts/hypurr/tools";

package/src/types.ts

@@ -1,17 +1,18 @@
 import type { ExchangeClient } from "@hfunlabs/hyperliquid";
 import type { StaticClient } from "hypurr-grpc/ts/hypurr/static/static_service.client";
 import type { TelegramClient } from "hypurr-grpc/ts/hypurr/telegram/telegram_service.client";
-import type { HyperliquidWallet } from "hypurr-grpc/ts/hypurr/wallet";
 import type { TelegramChatWalletPack } from "hypurr-grpc/ts/hypurr/user";
+import type { HyperliquidWallet } from "hypurr-grpc/ts/hypurr/wallet";
 
 // ─── Config ──────────────────────────────────────────────────────
 
 export interface HypurrConnectConfig {
   grpcTimeout?: number;
   isTestnet?: boolean;
-  telegram?: {
+  telegram: {
     botUsername: string;
-    botId: string;
+    botId?: string;
+    useWidget: boolean;
   };
 }
 
@@ -59,6 +60,51 @@ export type SignTypedDataFn = (params: {
   message: Record<string, unknown>;
 }) => Promise<`0x${string}`>;
 
+/** Wallet signer provided at EOA connect time for user-signed actions. */
+export interface EoaSigner {
+  signTypedData: SignTypedDataFn;
+  chainId: number;
+}
+
+/**
+ * Create an {@link EoaSigner} from any EIP-712 signing function.
+ *
+ * Accepts either a direct function or a `{ current }` ref object so the
+ * signer always calls through to the latest function (avoids stale closures
+ * with React hooks like wagmi's `useSignTypedData`).
+ *
+ * @example wagmi v2 — ref pattern (recommended)
+ * ```ts
+ * const { signTypedDataAsync } = useSignTypedData();
+ * const chainId = useChainId();
+ * const signerRef = useRef(signTypedDataAsync);
+ * signerRef.current = signTypedDataAsync; // stays fresh every render
+ *
+ * // call once — the ref keeps it up to date
+ * connectEoa(address, createEoaSigner(signerRef, chainId));
+ * ```
+ *
+ * @example direct function (e.g. from viem WalletClient)
+ * ```ts
+ * connectEoa(address, createEoaSigner(client.signTypedData, chainId));
+ * ```
+ */
+export function createEoaSigner(
+  signTypedDataAsync:
+    | ((args: Record<string, unknown>) => Promise<`0x${string}`>)
+    | { current: (args: Record<string, unknown>) => Promise<`0x${string}`> },
+  chainId: number,
+): EoaSigner {
+  const resolve =
+    typeof signTypedDataAsync === "function"
+      ? signTypedDataAsync
+      : (args: Record<string, unknown>) => signTypedDataAsync.current(args);
+  return {
+    signTypedData: (params) => resolve(params),
+    chainId,
+  };
+}
+
 // ─── Context state ───────────────────────────────────────────────
 
 export interface HypurrConnectState {
@@ -69,9 +115,10 @@ export interface HypurrConnectState {
   error: string | null;
   authMethod: AuthMethod;
 
-  // SDK ExchangeClient — works for all L1 actions
+  // SDK ExchangeClient — handles both L1 (agent-signed) and user-signed actions.
   // Telegram: backed by GrpcExchangeTransport (HyperliquidCoreAction)
-  // EOA: backed by HttpTransport + agent wallet
+  // EOA: uses a dual wallet — agent key for L1 actions, master wallet for
+  //   user-signed actions (transfers, withdrawals, etc.) when a signer is provided.
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   exchange: ExchangeClient<any> | null;
 
@@ -109,7 +156,7 @@ export interface HypurrConnectState {
   closeLoginModal: () => void;
 
   // Auth actions
-  connectEoa: (address: `0x${string}`) => void;
+  connectEoa: (address: `0x${string}`, signer?: EoaSigner) => void;
   approveAgent: (
     signTypedDataAsync: SignTypedDataFn,
     chainId: number,