@hfunlabs/hypurr-connect 0.1.0 → 0.1.2

package/README.md

@@ -6,11 +6,11 @@ React authentication and wallet connectivity library for the [Hyperliquid](https
 
 - **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
+- **Multi-wallet management** — Switch between wallets, create/delete wallets, manage wallet packs and labels (Telegram users)
 - **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
+- **Agent key management** — Named agent keys (`"hypurr-connect"`) with on-chain approval, `extraAgents` validation, expiry-aware caching, and automatic dead-agent recovery
 - **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
 
@@ -64,7 +64,7 @@ function App() {
 import { useHypurrConnect } from "@hfunlabs/hypurr-connect";
 
 function TradingPanel() {
-  const { user, isLoggedIn, exchange, usdcBalance, openLoginModal, logout } =
+  const { user, isLoggedIn, exchange, openLoginModal, logout } =
     useHypurrConnect();
 
   if (!isLoggedIn) {
@@ -74,7 +74,6 @@ function TradingPanel() {
   return (
     <div>
       <p>Welcome, {user.displayName}</p>
-      <p>Balance: {usdcBalance} USDC</p>
       <button onClick={logout}>Disconnect</button>
     </div>
   );
@@ -138,22 +137,42 @@ This package depends on [`hypurr-grpc`](https://gitlab.com/hypurr/hypurr-grpc) (
 
 ### EOA Wallet Login
 
+The EOA flow is split into two steps — **connect** and **approve** — so that the synchronous wallet connection never blocks on the signing prompt:
+
 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
+2. Your app connects the wallet (e.g., via wagmi) and calls `connectEoa(address)` — this is **synchronous**, sets the user immediately, and restores a cached agent from localStorage if one is still valid
+3. When you need exchange functionality, call `approveAgent(signTypedDataAsync, chainId)`:
+   - If a valid cached agent exists, it is validated against Hyperliquid's `extraAgents` endpoint and its `validUntil` timestamp — reused only if still active
+   - If no valid agent exists, a fresh key pair is generated and approved on-chain as a **named agent** (`"hypurr-connect"`) via the SDK's `approveAgent`. Named agents are only replaced when another `ApproveAgent` is sent with the same name, so they won't be pruned by unrelated unnamed agent registrations
+   - The agent key and its `validUntil` are persisted in localStorage (`hypurr-connect-agent:{address}`)
+4. Check `agentReady` to know whether the exchange client can sign transactions. If `agentReady` is `false` and you call any method on `exchange`, the SDK throws an explicit error:
+   > `[HypurrConnect] No agent key approved. Call approveAgent(signTypedDataAsync) before using the exchange client.`
+5. Once the agent is approved, the `ExchangeClient` uses `HttpTransport` + `PrivateKeySigner` — all exchange actions are signed **client-side** with the agent key
+6. If an exchange action fails because the agent was pruned or expired, the SDK automatically clears the dead agent and surfaces the error via `error` so the consumer can prompt re-login
+
+```tsx
+// Step 1: Connect wallet (synchronous — safe to call from useEffect)
+const { connectEoa, approveAgent, agentReady, exchange } = useHypurrConnect();
+
+// Call when wallet connects (e.g., wagmi onConnect callback)
+connectEoa(address);
+
+// Step 2: Approve agent (async — triggers wallet signing prompt)
+// Pass the connected wallet's chain ID so the EIP-712 domain matches
+await approveAgent(signTypedDataAsync, chainId);
+
+// Now exchange is ready to use
+if (agentReady && exchange) {
+  await exchange.placeOrder(/* ... */);
+}
+```
 
 ### 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:
+Once authenticated, the `exchange` object from `useHypurrConnect()` is a fully functional `ExchangeClient` from `@hfunlabs/hyperliquid`. Use it for any L1 action:
 
 ```tsx
-const { exchange, agentReady } = useHypurrConnect();
+const { exchange } = useHypurrConnect();
 
 // Place an order (works identically for Telegram and EOA users)
 if (exchange) {
@@ -167,6 +186,74 @@ if (exchange) {
 }
 ```
 
+### Multi-Wallet Management (Telegram)
+
+Telegram users can have multiple wallets. The library exposes the full wallet list and lets you switch the active wallet — the `exchange` client and `user` automatically update.
+
+```tsx
+const {
+  wallets,
+  selectedWalletId,
+  selectWallet,
+  createWallet,
+  deleteWallet,
+  refreshWallets,
+} = useHypurrConnect();
+
+// List wallets
+wallets.map((w) => (
+  <button
+    key={w.id}
+    onClick={() => selectWallet(w.id)}
+    style={{ fontWeight: w.id === selectedWalletId ? "bold" : "normal" }}
+  >
+    {w.name || w.ethereumAddress}
+  </button>
+));
+
+// Create a new wallet
+const newWallet = await createWallet("Trading");
+
+// Delete a wallet (auto-selects another if the deleted one was active)
+await deleteWallet(walletId);
+```
+
+#### Wallet Packs & Labels
+
+Organize watched wallets into named packs with labels:
+
+```tsx
+const {
+  packs,
+  createWalletPack,
+  addPackLabel,
+  modifyPackLabel,
+  removePackLabel,
+} = useHypurrConnect();
+
+// Create a pack
+const packId = await createWalletPack("Whales");
+
+// Add a labeled wallet to the pack
+await addPackLabel({
+  walletAddress: "0x...",
+  walletLabel: "Big trader",
+  packId,
+});
+
+// Rename a label
+await modifyPackLabel({
+  walletLabelOld: "Big trader",
+  walletLabelNew: "Whale #1",
+  packId,
+});
+
+// Remove a label from the pack
+await removePackLabel({ walletLabel: "Whale #1", packId });
+```
+
+All wallet management functions automatically refresh the wallet list from the server after mutations.
+
 ## API Reference
 
 ### Components
@@ -179,7 +266,7 @@ if (exchange) {
 </HypurrConnectProvider>
 ```
 
-Context provider that manages all auth state, gRPC clients, exchange clients, and balance tracking. Must wrap any component that uses `useHypurrConnect`.
+Context provider that manages all auth state, gRPC clients, and exchange clients. Must wrap any component that uses `useHypurrConnect`.
 
 #### `LoginModal`
 
@@ -200,31 +287,38 @@ Returns the full auth and exchange state. Throws if used outside `HypurrConnectP
 
 ### `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   |
+| Property           | Type                                                                      | Description                                                      |
+| ------------------ | ------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `user`             | `HypurrUser \| null`                                                      | Current authenticated user (reflects selected wallet)            |
+| `isLoggedIn`       | `boolean`                                                                 | Whether a user is authenticated                                  |
+| `isLoading`        | `boolean`                                                                 | Whether auth is in progress                                      |
+| `error`            | `string \| null`                                                          | Last auth or dead-agent error message                            |
+| `authMethod`       | `AuthMethod`                                                              | `"telegram"`, `"eoa"`, or `null`                                 |
+| `exchange`         | `ExchangeClient \| null`                                                  | Hyperliquid exchange client for L1 actions                       |
+| `wallets`          | `HyperliquidWallet[]`                                                     | All wallets for the Telegram user (empty for EOA)                |
+| `selectedWalletId` | `number`                                                                  | ID of the currently active wallet                                |
+| `selectWallet`     | `(walletId: number) => void`                                              | Switch the active wallet                                         |
+| `createWallet`     | `(name: string) => Promise<HyperliquidWallet>`                            | Create a new wallet (Telegram only)                              |
+| `deleteWallet`     | `(walletId: number) => Promise<void>`                                     | Delete a wallet (Telegram only)                                  |
+| `refreshWallets`   | `() => void`                                                              | Re-fetch wallets and packs from the server                       |
+| `packs`            | `TelegramChatWalletPack[]`                                                | Wallet packs for the Telegram user                               |
+| `createWalletPack` | `(name: string) => Promise<number>`                                       | Create a wallet pack; returns the new pack ID                    |
+| `addPackLabel`     | `(params) => Promise<void>`                                               | Add a labeled wallet to a pack                                   |
+| `modifyPackLabel`  | `(params) => Promise<void>`                                               | Rename a label within a pack                                     |
+| `removePackLabel`  | `(params) => Promise<void>`                                               | Remove a label from a pack                                       |
+| `loginModalOpen`   | `boolean`                                                                 | Whether the login modal is visible                               |
+| `openLoginModal`   | `() => void`                                                              | Show the login modal                                             |
+| `closeLoginModal`  | `() => void`                                                              | Hide the login modal                                             |
+| `connectEoa`       | `(address: \`0x\${string}\`) => void`                                     | Connect EOA wallet (sync, no signing)                            |
+| `approveAgent`     | `(signTypedDataAsync: SignTypedDataFn, chainId: number) => Promise<void>` | Approve a named agent key (async, triggers wallet prompt)        |
+| `logout`           | `() => void`                                                              | Clear all auth state and localStorage                            |
+| `agent`            | `StoredAgent \| null`                                                     | Current agent key (EOA flow only)                                |
+| `agentReady`       | `boolean`                                                                 | Whether the exchange client can sign (true for TG, or EOA+agent) |
+| `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
 
@@ -268,6 +362,34 @@ interface StoredAgent {
   privateKey: `0x${string}`;
   address: `0x${string}`;
   approvedAt: number; // Timestamp when approved on-chain
+  validUntil: number; // Epoch ms from extraAgents; agent is invalid after this
+}
+```
+
+#### `HyperliquidWallet`
+
+Re-exported from `hypurr-grpc`:
+
+```typescript
+interface HyperliquidWallet {
+  id: number;
+  name: string;
+  ethereumAddress: string;
+  isAgent: boolean;
+  isReadOnly: boolean;
+  // ... plus balances, movements, sessions
+}
+```
+
+#### `TelegramChatWalletPack`
+
+Re-exported from `hypurr-grpc`:
+
+```typescript
+interface TelegramChatWalletPack {
+  id: number;
+  telegramChatId: number;
+  name: string;
 }
 ```
 

package/dist/index.d.ts

@@ -3,6 +3,10 @@ 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';
+import { HyperliquidWallet } from 'hypurr-grpc/ts/hypurr/wallet';
+export { HyperliquidWallet } from 'hypurr-grpc/ts/hypurr/wallet';
+import { TelegramChatWalletPack } from 'hypurr-grpc/ts/hypurr/user';
+export { TelegramChatWalletPack } from 'hypurr-grpc/ts/hypurr/user';
 
 interface HypurrConnectConfig {
     grpcTimeout?: number;
@@ -29,11 +33,15 @@ interface HypurrUser {
     photoUrl?: string;
     authMethod: AuthMethod;
     telegramId?: string;
+    hfunScore?: number;
+    reputationScore?: number;
 }
 interface StoredAgent {
     privateKey: `0x${string}`;
     address: `0x${string}`;
     approvedAt: number;
+    /** Epoch ms from the `extraAgents` response; agent is invalid after this time. */
+    validUntil: number;
 }
 type SignTypedDataFn = (params: {
     domain: Record<string, unknown>;
@@ -51,18 +59,36 @@ interface HypurrConnectState {
     error: string | null;
     authMethod: AuthMethod;
     exchange: ExchangeClient<any> | null;
-    usdcBalance: string | null;
-    usdcBalanceLoading: boolean;
-    refreshBalance: () => void;
+    wallets: HyperliquidWallet[];
+    selectedWalletId: number;
+    selectWallet: (walletId: number) => void;
+    createWallet: (name: string) => Promise<HyperliquidWallet>;
+    deleteWallet: (walletId: number) => Promise<void>;
+    refreshWallets: () => void;
+    packs: TelegramChatWalletPack[];
+    createWalletPack: (name: string) => Promise<number>;
+    addPackLabel: (params: {
+        walletAddress: string;
+        walletLabel: string;
+        packId: number;
+    }) => Promise<void>;
+    modifyPackLabel: (params: {
+        walletLabelOld: string;
+        walletLabelNew: string;
+        packId: number;
+    }) => Promise<void>;
+    removePackLabel: (params: {
+        walletLabel: string;
+        packId: number;
+    }) => Promise<void>;
     loginModalOpen: boolean;
     openLoginModal: () => void;
     closeLoginModal: () => void;
-    loginTelegram: (data: TelegramLoginData) => void;
-    loginEoa: (address: `0x${string}`) => void;
+    connectEoa: (address: `0x${string}`) => void;
+    approveAgent: (signTypedDataAsync: SignTypedDataFn, chainId: number) => Promise<void>;
     logout: () => void;
     agent: StoredAgent | null;
     agentReady: boolean;
-    approveAgent: (signTypedDataAsync: SignTypedDataFn) => Promise<void>;
     clearAgent: () => void;
     botId: string;
     authDataMap: Record<string, string>;