@hfunlabs/hypurr-connect 0.1.0

package/README.md

@@ -0,0 +1,363 @@
+# @hfunlabs/hypurr-connect
+
+React authentication and wallet connectivity library for the [Hyperliquid](https://hyperliquid.xyz) decentralized exchange via the [Hypurr](https://hypurr.fun) gRPC backend. Provides two authentication paths — **Telegram OAuth** and **EOA wallet** (MetaMask / browser wallet) — with a unified `ExchangeClient` API for placing orders, managing positions, and executing any L1 action.
+
+## Features
+
+- **Dual auth flows** — Telegram OAuth (server-side signing) and EOA wallet (client-side agent key signing)
+- **Unified exchange client** — Same `ExchangeClient` interface regardless of auth method
+- **gRPC transport** — Custom transport that routes exchange actions through the Hypurr backend for Telegram users
+- **Agent key management** — Automatic generation, on-chain approval, and localStorage persistence of agent keys for EOA wallets
+- **Session persistence** — Auth state survives page reloads via localStorage
+- **Responsive login modal** — Centered modal on desktop, bottom drawer on mobile with framer-motion animations
+- **USDC balance tracking** — Built-in clearinghouse balance fetching with manual refresh
+
+## Installation
+
+```bash
+pnpm add @hfunlabs/hypurr-connect
+```
+
+### Peer Dependencies
+
+Install the required peer dependencies:
+
+```bash
+pnpm add @hfunlabs/hyperliquid @protobuf-ts/grpcweb-transport @protobuf-ts/runtime-rpc framer-motion react
+```
+
+| Peer Dependency                  | Version             |
+| -------------------------------- | ------------------- |
+| `@hfunlabs/hyperliquid`          | `0.30.2-hfunlabs.2` |
+| `@protobuf-ts/grpcweb-transport` | `>=2.0.0`           |
+| `@protobuf-ts/runtime-rpc`       | `>=2.0.0`           |
+| `framer-motion`                  | `>=10.0.0`          |
+| `react`                          | `>=18.0.0`          |
+
+## Quick Start
+
+### 1. Wrap your app with the provider
+
+```tsx
+import { HypurrConnectProvider } from "@hfunlabs/hypurr-connect";
+
+const config = {
+  isTestnet: false,
+  telegram: {
+    botUsername: "YourBot",
+    botId: "123456789",
+  },
+};
+
+function App() {
+  return (
+    <HypurrConnectProvider config={config}>
+      <YourApp />
+    </HypurrConnectProvider>
+  );
+}
+```
+
+### 2. Use the hook anywhere in your app
+
+```tsx
+import { useHypurrConnect } from "@hfunlabs/hypurr-connect";
+
+function TradingPanel() {
+  const { user, isLoggedIn, exchange, usdcBalance, openLoginModal, logout } =
+    useHypurrConnect();
+
+  if (!isLoggedIn) {
+    return <button onClick={openLoginModal}>Connect</button>;
+  }
+
+  return (
+    <div>
+      <p>Welcome, {user.displayName}</p>
+      <p>Balance: {usdcBalance} USDC</p>
+      <button onClick={logout}>Disconnect</button>
+    </div>
+  );
+}
+```
+
+### 3. Add the login modal
+
+```tsx
+import { LoginModal, useHypurrConnect } from "@hfunlabs/hypurr-connect";
+
+function AppShell() {
+  const { loginModalOpen, closeLoginModal } = useHypurrConnect();
+
+  return (
+    <>
+      {loginModalOpen && (
+        <LoginModal
+          onConnectWallet={() => {
+            // Open your wagmi/RainbowKit wallet modal here
+          }}
+        />
+      )}
+      <MainContent />
+    </>
+  );
+}
+```
+
+## Configuration
+
+### `HypurrConnectConfig`
+
+```typescript
+interface HypurrConnectConfig {
+  grpcTimeout?: number; // Request timeout in ms (default: 15000)
+  isTestnet?: boolean; // Use testnet endpoints (default: false)
+  telegram?: {
+    botUsername: string; // Telegram bot username for the login widget
+    botId: string; // Telegram bot ID for the OAuth URL
+  };
+}
+```
+
+The `telegram` block is only required if you want to support Telegram login.
+
+### Dependencies
+
+This package depends on [`hypurr-grpc`](https://gitlab.com/hypurr/hypurr-grpc) (public GitLab repo) for generated protobuf service clients. It is installed directly from Git — no registry auth is needed.
+
+## Authentication Flows
+
+### Telegram Login
+
+1. User clicks "Telegram" in the `LoginModal`
+2. A popup opens to `oauth.telegram.org` with the configured bot
+3. User authorizes; Telegram posts auth data back via `postMessage`
+4. The provider calls the Hypurr gRPC backend (`telegramUser`) to fetch the user's wallet address and ID
+5. An `ExchangeClient` is created with `GrpcExchangeTransport` — all exchange actions are signed **server-side** by the Hypurr backend
+6. Session is persisted in localStorage (`hypurr-connect-tg-user`)
+
+### EOA Wallet Login
+
+1. User clicks "Wallet" in the `LoginModal`; the `onConnectWallet` callback fires
+2. Your app connects the wallet (e.g., via wagmi) and calls `loginEoa(address)`
+3. The user must approve an agent key before trading:
+   - Call `approveAgent(signTypedDataAsync)` with the wallet's signing function
+   - A random agent key pair is generated locally
+   - The wallet signs an EIP-712 `ApproveAgent` message
+   - The approval is submitted to Hyperliquid
+   - The agent key is persisted in localStorage (`hypurr-connect-agent:{address}`)
+4. An `ExchangeClient` is created with `HttpTransport` + `PrivateKeySigner` — all exchange actions are signed **client-side** with the agent key
+
+### Using the Exchange Client
+
+Once authenticated (and agent approved for EOA), the `exchange` object from `useHypurrConnect()` is a fully functional `ExchangeClient` from `@hfunlabs/hyperliquid`. Use it for any L1 action:
+
+```tsx
+const { exchange, agentReady } = useHypurrConnect();
+
+// Place an order (works identically for Telegram and EOA users)
+if (exchange) {
+  const result = await exchange.placeOrder({
+    asset: 0,
+    isBuy: true,
+    limitPx: "50000",
+    sz: "0.001",
+    orderType: { limit: { tif: "Gtc" } },
+  });
+}
+```
+
+## API Reference
+
+### Components
+
+#### `HypurrConnectProvider`
+
+```tsx
+<HypurrConnectProvider config={HypurrConnectConfig}>
+  {children}
+</HypurrConnectProvider>
+```
+
+Context provider that manages all auth state, gRPC clients, exchange clients, and balance tracking. Must wrap any component that uses `useHypurrConnect`.
+
+#### `LoginModal`
+
+```tsx
+<LoginModal
+  onConnectWallet={() => void}
+  walletIcon?: ReactNode       // Custom icon for the wallet button (defaults to MetaMask icon)
+/>
+```
+
+Animated modal with Telegram and Wallet login buttons. Renders as a centered modal on desktop (>=640px) and a bottom drawer on mobile. Uses the `closeLoginModal` function from context to dismiss.
+
+### Hook
+
+#### `useHypurrConnect(): HypurrConnectState`
+
+Returns the full auth and exchange state. Throws if used outside `HypurrConnectProvider`.
+
+### `HypurrConnectState`
+
+| Property             | Type                                                     | Description                                    |
+| -------------------- | -------------------------------------------------------- | ---------------------------------------------- |
+| `user`               | `HypurrUser \| null`                                     | Current authenticated user                     |
+| `isLoggedIn`         | `boolean`                                                | Whether a user is authenticated                |
+| `isLoading`          | `boolean`                                                | Whether auth is in progress                    |
+| `error`              | `string \| null`                                         | Last auth error message                        |
+| `authMethod`         | `AuthMethod`                                             | `"telegram"`, `"eoa"`, or `null`               |
+| `exchange`           | `ExchangeClient \| null`                                 | Hyperliquid exchange client for L1 actions     |
+| `usdcBalance`        | `string \| null`                                         | User's USDC balance from the clearinghouse     |
+| `usdcBalanceLoading` | `boolean`                                                | Whether balance is being fetched               |
+| `refreshBalance`     | `() => void`                                             | Manually re-fetch USDC balance                 |
+| `loginModalOpen`     | `boolean`                                                | Whether the login modal is visible             |
+| `openLoginModal`     | `() => void`                                             | Show the login modal                           |
+| `closeLoginModal`    | `() => void`                                             | Hide the login modal                           |
+| `loginTelegram`      | `(data: TelegramLoginData) => void`                      | Authenticate with Telegram OAuth data          |
+| `loginEoa`           | `(address: \`0x\${string}\`) => void`                    | Authenticate with an EOA wallet address        |
+| `logout`             | `() => void`                                             | Clear all auth state and localStorage          |
+| `agent`              | `StoredAgent \| null`                                    | Current agent key (EOA flow only)              |
+| `agentReady`         | `boolean`                                                | Whether the agent key is approved and ready    |
+| `approveAgent`       | `(signTypedDataAsync: SignTypedDataFn) => Promise<void>` | Generate and approve a new agent key           |
+| `clearAgent`         | `() => void`                                             | Remove the agent key from state and storage    |
+| `botId`              | `string`                                                 | Telegram bot ID from config                    |
+| `authDataMap`        | `Record<string, string>`                                 | Raw Telegram auth data as key-value pairs      |
+| `telegramClient`     | `TelegramClient`                                         | Low-level gRPC client for the Telegram service |
+| `staticClient`       | `StaticClient`                                           | Low-level gRPC client for the Static service   |
+
+### Types
+
+#### `HypurrUser`
+
+```typescript
+interface HypurrUser {
+  address: string; // Ethereum address
+  walletId: number; // Hypurr wallet ID
+  displayName: string; // "@username", first_name, or truncated address
+  photoUrl?: string; // Telegram profile photo URL
+  authMethod: AuthMethod; // "telegram" | "eoa"
+  telegramId?: string; // Telegram user ID (string)
+}
+```
+
+#### `AuthMethod`
+
+```typescript
+type AuthMethod = "telegram" | "eoa" | null;
+```
+
+#### `TelegramLoginData`
+
+```typescript
+interface TelegramLoginData {
+  id: number;
+  first_name: string;
+  last_name?: string;
+  username?: string;
+  photo_url?: string;
+  auth_date: number;
+  hash: string;
+}
+```
+
+#### `StoredAgent`
+
+```typescript
+interface StoredAgent {
+  privateKey: `0x${string}`;
+  address: `0x${string}`;
+  approvedAt: number; // Timestamp when approved on-chain
+}
+```
+
+#### `SignTypedDataFn`
+
+```typescript
+type SignTypedDataFn = (params: {
+  domain: Record<string, unknown>;
+  types: Record<string, { name: string; type: string }[]>;
+  primaryType: string;
+  message: Record<string, unknown>;
+}) => Promise<`0x${string}`>;
+```
+
+### Classes
+
+#### `GrpcExchangeTransport`
+
+Custom `IRequestTransport` implementation that routes exchange actions through the Hypurr gRPC backend (used by Telegram auth).
+
+```typescript
+class GrpcExchangeTransport implements IRequestTransport {
+  isTestnet: boolean;
+  constructor(config: GrpcExchangeTransportConfig);
+  request<T>(
+    endpoint: "info" | "exchange" | "explorer",
+    payload: unknown,
+    signal?: AbortSignal,
+  ): Promise<T>;
+}
+```
+
+- **`exchange` endpoint** — Serializes the action to bytes and calls `telegramClient.hyperliquidCoreAction()` via gRPC. The Hypurr backend validates the auth data and signs the action server-side.
+- **`info` / `explorer` endpoints** — Proxied directly to the Hyperliquid HTTP API.
+
+```typescript
+interface GrpcExchangeTransportConfig {
+  isTestnet?: boolean;
+  telegramClient: TelegramClient;
+  authDataMap: Record<string, string>;
+  walletId: number;
+}
+```
+
+### Factory Functions
+
+#### `createTelegramClient(config: HypurrConnectConfig): TelegramClient`
+
+Creates a gRPC-Web client for the Telegram service.
+
+#### `createStaticClient(config: HypurrConnectConfig): StaticClient`
+
+Creates a gRPC-Web client for the Static service.
+
+Both use `GrpcWebFetchTransport` with the configured `baseUrl`, `timeout`, and `origin` metadata.
+
+## localStorage Keys
+
+| Key                              | Content                                                        |
+| -------------------------------- | -------------------------------------------------------------- |
+| `hypurr-connect-tg-user`         | Serialized `TelegramLoginData` (persists Telegram session)     |
+| `hypurr-connect-agent:{address}` | Serialized `StoredAgent` (persists EOA agent keys per address) |
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                  HypurrConnectProvider                   │
+│                                                         │
+│  ┌───────────────┐          ┌────────────────────────┐  │
+│  │ Telegram Auth │──gRPC──▶ │  GrpcExchangeTransport │  │
+│  │  (server-     │          │  ┌──────────────────┐   │  │
+│  │   signed)     │          │  │ telegramClient    │   │  │
+│  └───────────────┘          │  │ .hyperliquidCore  │   │  │
+│                              │  │  Action()         │   │  │
+│  ┌───────────────┐          │  └──────────────────┘   │  │
+│  │   EOA Auth    │──HTTP──▶ │  HttpTransport          │  │
+│  │  (agent key   │          │  + PrivateKeySigner     │  │
+│  │   signed)     │          └────────────────────────┘  │
+│  └───────────────┘                    │                  │
+│                                       ▼                  │
+│                              ┌──────────────┐           │
+│                              │ExchangeClient│           │
+│                              └──────────────┘           │
+│                                       │                  │
+│                                       ▼                  │
+│                              Hyperliquid L1              │
+└─────────────────────────────────────────────────────────┘
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,113 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { ExchangeClient, IRequestTransport } from '@hfunlabs/hyperliquid';
+import { StaticClient } from 'hypurr-grpc/ts/hypurr/static/static_service.client';
+import { TelegramClient } from 'hypurr-grpc/ts/hypurr/telegram/telegram_service.client';
+
+interface HypurrConnectConfig {
+    grpcTimeout?: number;
+    isTestnet?: boolean;
+    telegram?: {
+        botUsername: string;
+        botId: string;
+    };
+}
+interface TelegramLoginData {
+    id: number;
+    first_name: string;
+    last_name?: string;
+    username?: string;
+    photo_url?: string;
+    auth_date: number;
+    hash: string;
+}
+type AuthMethod = "telegram" | "eoa" | null;
+interface HypurrUser {
+    address: string;
+    walletId: number;
+    displayName: string;
+    photoUrl?: string;
+    authMethod: AuthMethod;
+    telegramId?: string;
+}
+interface StoredAgent {
+    privateKey: `0x${string}`;
+    address: `0x${string}`;
+    approvedAt: number;
+}
+type SignTypedDataFn = (params: {
+    domain: Record<string, unknown>;
+    types: Record<string, {
+        name: string;
+        type: string;
+    }[]>;
+    primaryType: string;
+    message: Record<string, unknown>;
+}) => Promise<`0x${string}`>;
+interface HypurrConnectState {
+    user: HypurrUser | null;
+    isLoggedIn: boolean;
+    isLoading: boolean;
+    error: string | null;
+    authMethod: AuthMethod;
+    exchange: ExchangeClient<any> | null;
+    usdcBalance: string | null;
+    usdcBalanceLoading: boolean;
+    refreshBalance: () => void;
+    loginModalOpen: boolean;
+    openLoginModal: () => void;
+    closeLoginModal: () => void;
+    loginTelegram: (data: TelegramLoginData) => void;
+    loginEoa: (address: `0x${string}`) => void;
+    logout: () => void;
+    agent: StoredAgent | null;
+    agentReady: boolean;
+    approveAgent: (signTypedDataAsync: SignTypedDataFn) => Promise<void>;
+    clearAgent: () => void;
+    botId: string;
+    authDataMap: Record<string, string>;
+    telegramClient: TelegramClient;
+    staticClient: StaticClient;
+}
+
+declare function useHypurrConnect(): HypurrConnectState;
+declare function HypurrConnectProvider({ config, children, }: {
+    config: HypurrConnectConfig;
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+
+interface LoginModalProps {
+    onConnectWallet: () => void;
+    walletIcon?: ReactNode;
+}
+declare function LoginModal({ onConnectWallet, walletIcon }: LoginModalProps): react_jsx_runtime.JSX.Element;
+
+interface GrpcExchangeTransportConfig {
+    isTestnet?: boolean;
+    telegramClient: TelegramClient;
+    authDataMap: Record<string, string>;
+    walletId: number;
+}
+/**
+ * Routes exchange requests through the Hypurr gRPC backend (HyperliquidCoreAction)
+ * for server-side signing. The backend handles signature generation.
+ *
+ * The SDK-generated nonce is forwarded; the action payload is JSON-encoded as bytes.
+ * Info/explorer requests are proxied directly to the Hyperliquid HTTP API.
+ */
+declare class GrpcExchangeTransport implements IRequestTransport {
+    isTestnet: boolean;
+    private telegramClient;
+    private authDataMap;
+    private walletId;
+    private infoUrl;
+    constructor(config: GrpcExchangeTransportConfig);
+    request<T>(endpoint: "info" | "exchange" | "explorer", payload: unknown, signal?: AbortSignal): Promise<T>;
+    private exchangeViaGrpc;
+    private directRequest;
+}
+
+declare function createTelegramClient(config: HypurrConnectConfig): TelegramClient;
+declare function createStaticClient(config: HypurrConnectConfig): StaticClient;
+
+export { type AuthMethod, GrpcExchangeTransport, type GrpcExchangeTransportConfig, type HypurrConnectConfig, HypurrConnectProvider, type HypurrConnectState, type HypurrUser, LoginModal, type LoginModalProps, type SignTypedDataFn, type StoredAgent, type TelegramLoginData, createStaticClient, createTelegramClient, useHypurrConnect };