@moon-x/react-sdk 0.1.0

package/README.md

@@ -0,0 +1,241 @@
+# @moon-x/react-sdk
+
+React SDK for [MoonX](https://moonx.com) — embedded wallets with passkey-protected MPC signing for Ethereum and Solana, drop-in auth UI flows, and headless wallet methods.
+
+```sh
+npm install @moon-x/react-sdk
+# or
+pnpm add @moon-x/react-sdk
+```
+
+## Quick start
+
+Wrap your app with `MoonKeyProvider` and import the CSS bundle once:
+
+```tsx
+import { MoonKeyProvider, mainnet, sepolia } from "@moon-x/react-sdk";
+import "@moon-x/react-sdk/style.css";
+
+export default function App() {
+  return (
+    <MoonKeyProvider
+      publishableKey={process.env.NEXT_PUBLIC_MOONKEY_PUBLISHABLE_KEY!}
+      config={{
+        appearance: {
+          accentColor: "#6366f1",
+          backgroundColor: "#ffffff",
+        },
+        defaultChain: mainnet,
+        supportedChains: [mainnet, sepolia],
+      }}
+    >
+      <YourApp />
+    </MoonKeyProvider>
+  );
+}
+```
+
+Open the auth modal and read user state:
+
+```tsx
+import { useMoonKey } from "@moon-x/react-sdk";
+
+function LoginButton() {
+  const { ready, isAuthenticated, user, start, logout } = useMoonKey();
+
+  if (!ready) return null;
+  if (isAuthenticated) {
+    return <button onClick={() => logout()}>Sign out ({user?.id})</button>;
+  }
+  return <button onClick={() => start?.()}>Sign in</button>;
+}
+```
+
+Sign a message with one of the user's wallets:
+
+```tsx
+import { useWallets } from "@moon-x/react-sdk";
+import { useSignMessage } from "@moon-x/react-sdk/ethereum";
+
+function SignDemo() {
+  const { wallets } = useWallets();
+  const { signMessage } = useSignMessage();
+
+  const onSign = async () => {
+    const wallet = wallets.find((w) => w.wallet_type === "ethereum");
+    if (!wallet) return;
+    const { signature } = await signMessage({
+      message: "Hello world",
+      wallet,
+      options: { uiOptions: { showWalletUI: true } }, // opens the modal
+    });
+    console.log(signature);
+  };
+
+  return <button onClick={onSign}>Sign</button>;
+}
+```
+
+## Configuration
+
+`MoonKeyProvider` accepts `publishableKey` (required) plus a `config` object:
+
+| Field | Type | Purpose |
+|---|---|---|
+| `appearance` | `AuthAppearance` | High-level theming — `accentColor`, `backgroundColor`, `displayMode` (`"light" \| "dark" \| "auto"`), `logo`, `loginHeaderTitle`, `borderRadius`, `fontFamily`. |
+| `loginMethods` | `("email" \| "google" \| "apple" \| "wallet")[]` | Which auth methods to show in the modal. |
+| `walletChainType` | `"ethereum" \| "solana" \| "ethereum-or-solana"` | Which wallet type to create at signup. |
+| `defaultChain` / `supportedChains` | `Chain` / `Chain[]` | EVM chain config — top-level, **not nested under `ethereum`**. `Chain` is viem's type; common chains are re-exported by this package. |
+| `solana.rpcs` | `{ [cluster]: { rpc, rpcSubscriptions? } }` | Solana RPC endpoints per cluster. |
+| `walletConnect.projectId` | `string` | WalletConnect v2 project ID for external-wallet flows. |
+| `emailConfig`, `passkeyEnrollConfig`, `signMessageConfig`, `signTransactionConfig`, `sendTransactionConfig`, `exportKeyConfig` | various | Per-flow UI overrides — titles, button text, etc. |
+| `security.assertionCacheTtlMs` | `number` | Parent-side passkey-assertion cache TTL in milliseconds. **Defaults to `0` (no cache — every sensitive op forces a fresh biometric).** Set to a positive value (e.g. `5 * 60 * 1000`) to opt into a warm window where routine ops skip the OS picker. See [Security: assertion cache + `requireFreshAssertion`](#security-assertion-cache--requirefreshassertion) below for the trade-off. |
+| `theme` | `MoonKeyThemeConfig` | Low-level token overrides — fine-grained color palette, full borderRadius scale. Most apps don't need this; `appearance` is the recommended surface. |
+
+## Hooks
+
+### Authentication & user state
+
+| Hook | What it does |
+|---|---|
+| `useMoonKey()` | The big one. `{ ready, isAuthenticated, user, start, logout, setAppearance, getSessionTokens, refreshUser, ... }` + every SDK method on the same instance. |
+| `useUser()` | Just `{ user, refreshUser }`. Re-subscribes to user changes. |
+| `useLoginWithEmail({ onComplete?, onError? })` | Headless email-OTP. Returns `{ state, sendCode, loginWithCode, reset }`. `state` is a discriminated union: `idle` / `sending` / `awaiting-code` / `verifying` / `complete` / `error`. |
+| `useLoginWithOAuth()` | Google + Apple flows. Returns `{ state, loginWithOAuth, reset }`. |
+| `useLogout()` | `{ logout }` — also clears local storage + iframe session. |
+
+### Passkeys
+
+| Hook | What it does |
+|---|---|
+| `usePasskeyStatus()` | `{ status, refresh }`. `status.passkeys` lists the user's enrolled passkeys with provider labels (e.g. `"1Password on Chrome"`). |
+| `useRegisterPasskey()` | First-time passkey enrollment for a user who signed in via OTP/OAuth without one. |
+| `useAddPasskey()` | Add an additional passkey to an authenticated user. |
+| `useRemovePasskey()` | Remove a passkey by its credential ID. |
+
+### Wallets
+
+| Hook | What it does |
+|---|---|
+| `useWallets()` | `{ wallets, loading }` — both Ethereum and Solana, fetched once on mount. |
+| `useCreateWallet()` | Mint a new MPC wallet. Pass `{ walletType: "ethereum" \| "solana" }`. |
+| `useImportKey()` | Two-mode: headless if you pass a key, modal-driven if you don't. |
+| `useConnectWallet()` | External-wallet flow (MetaMask, Phantom, WalletConnect) for both chains. |
+| `useAttachOAuth()` / `useDetachOAuth()` | Link / unlink an OAuth provider on an existing user. |
+
+### Per-chain signing — `/ethereum` and `/solana` subpaths
+
+Chain-aware hooks live under subpaths so they don't pull in the other chain's adapters if you only use one:
+
+```tsx
+import { useSignMessage, useSignTransaction, useSendTransaction } from "@moon-x/react-sdk/ethereum";
+import { useSignMessage as useSignSolanaMessage } from "@moon-x/react-sdk/solana";
+```
+
+**Ethereum hooks:**
+- `useSignMessage` — EIP-191 `personal_sign`. Returns `{ signature: "0x..." }`.
+- `useSignTransaction` — Signs an EIP-1559 tx. Returns `{ signature, serializedSigned, hash }`.
+- `useSignTypedData` — EIP-712. Returns `{ signature: "0x..." }`.
+- `useSignHash` — Raw ECDSA digest sign (Privy parity — `secp256k1_sign`).
+- `useSign7702Authorization` — EIP-7702 delegation auth.
+- `useSendTransaction` — Sign + broadcast via the configured RPC.
+- `useGetBalance` — Native token balance.
+
+**Solana hooks:**
+- `useSignMessage` — Ed25519 signature.
+- `useSignTransaction` — Signs a serialized base58 tx. Returns `{ signedTransaction: Uint8Array }`.
+- `useSendTransaction` — Sign + broadcast.
+- `useGetBalance` — Lamport balance.
+
+Every signing hook accepts `options.uiOptions.showWalletUI` to toggle modal vs headless mode. With UI, the user sees the message/transaction in a modal and the biometric prompt fires only on the Sign tap. Headless skips the modal entirely.
+
+Every signing hook also accepts a top-level `requireFreshAssertion?: boolean` flag. When `true`, that single call bypasses any parent-side assertion cache and forces a fresh biometric — useful for high-value transactions in an otherwise-warm flow. See [Security](#security-assertion-cache--requirefreshassertion) below.
+
+### Security: assertion cache + `requireFreshAssertion`
+
+MoonX's parent-side assertion cache holds the WebAuthn assertion result (`userHandleB64url` — the AES-GCM key that wraps the user's DEK) in JS memory for an integrator-configured TTL. Within that window, routine wallet ops skip the OS passkey picker.
+
+**The default is `assertionCacheTtlMs: 0` — no cache.** Every sensitive op fires a fresh biometric and the raw userHandle never lingers in the parent JS heap past the moment of use. This is the safe posture: a parent-page XSS can't lift a cached key because there is no cache.
+
+Integrators who want a warm-UX trade-off opt back in:
+
+```tsx
+<MoonKeyProvider
+  publishableKey={pk}
+  config={{ security: { assertionCacheTtlMs: 5 * 60 * 1000 } }}
+>
+  ...
+</MoonKeyProvider>
+```
+
+With the cache on, parent-coresident JS (including XSS) can drive cached ops without re-prompting for the duration of the window. The TTL bounds the exposure but doesn't eliminate it. Pick the trade-off deliberately.
+
+Per-call escape hatch — works regardless of the global setting:
+
+```tsx
+await signTransaction({
+  transaction: tx,
+  wallet,
+  requireFreshAssertion: true,   // force a fresh biometric for THIS op
+});
+```
+
+Sensitive lifecycle ops (`exportKey`, `addPasskey`, `removePasskey`) ignore the cache unconditionally — they always re-prompt.
+
+### Theming
+
+The simplest path is `appearance`:
+
+```tsx
+<MoonKeyProvider
+  config={{
+    appearance: {
+      accentColor: "#6366f1",
+      backgroundColor: "#0f172a",
+      displayMode: "dark",
+      borderRadius: "md",            // "none" | "sm" | "md" | "lg" — or { sm, md, lg }
+      fontFamily: "Inter, sans-serif",
+      logo: "https://example.com/logo.svg",
+    },
+  }}
+>
+```
+
+You can dynamically update appearance at runtime — useful for light/dark mode toggles:
+
+```tsx
+const { setAppearance } = useMoonKey();
+setAppearance({ displayMode: colorScheme });
+```
+
+For finer control (overriding derived tokens like `accentDark`, `background2`, etc.), pass a `theme: MoonKeyThemeConfig`. The merge order is: base theme → `appearance` derivations → explicit `theme` overrides.
+
+## EVM chain helpers
+
+The package re-exports gas / RPC utilities that work with any viem `Chain`:
+
+```ts
+import {
+  getEvmGasPrice,
+  getEvmMaxPriorityFeePerGas,
+  getEvmNonce,
+  estimateEvmGas,
+  estimateEvmGasReserve,
+  getRpcUrl,
+  setChainRpcUrl,
+  getChainById,
+  getDefaultChain,
+  isChainSupported,
+  validateChainConfig,
+} from "@moon-x/react-sdk";
+```
+
+Useful when you need a pre-flight gas reserve estimate, want to override an RPC URL at runtime, or are building a custom chain-picker.
+
+## React Native
+
+For React Native apps, use [`@moon-x/react-native-sdk`](https://www.npmjs.com/package/@moon-x/react-native-sdk) — same hook shape with a WebView-backed transport.
+
+## License
+
+MIT.

package/dist/base-wallet-CzJLpndu.d.mts

@@ -0,0 +1,119 @@
+import { PublicWallet } from '@moon-x/core/types';
+
+interface BaseWallet {
+    id: string;
+    type: "solana" | "ethereum";
+    address: string;
+    isConnected: boolean;
+}
+interface BaseUIOptions {
+    title?: string;
+    description?: string;
+    buttonText?: string;
+    showWalletUI?: boolean;
+}
+interface BaseSignMessageParams {
+    message: string;
+    wallet: BaseWallet;
+    options?: {
+        uiOptions?: BaseUIOptions;
+    };
+}
+interface BaseSignMessageResult {
+    signature: Uint8Array;
+    signedMessage?: Uint8Array;
+}
+interface BaseSignTransactionParams {
+    transaction: Uint8Array | string;
+    wallet: BaseWallet;
+    options?: {
+        uiOptions?: BaseUIOptions;
+    };
+}
+interface BaseSignTransactionResult {
+    signature: Uint8Array;
+    signedTransaction: Uint8Array | string;
+}
+interface BaseSendTransactionParams {
+    transaction: Uint8Array | string;
+    wallet: BaseWallet;
+    rpcUrl: string;
+    options?: {
+        uiOptions?: BaseUIOptions;
+        commitment?: string;
+        encoding?: string;
+        replaceRecentBlockhash?: boolean;
+        sigVerify?: boolean;
+        minContextSlot?: number;
+        innerInstructions?: boolean;
+        accounts?: any[];
+        network?: string;
+    };
+}
+interface BaseSendTransactionResult {
+    signature: Uint8Array;
+    transactionHash: string;
+    walletAddress: string;
+}
+interface BaseGetBalanceParams {
+    wallet: BaseWallet;
+}
+interface BaseGetBalanceResult {
+    balance: string;
+    balanceInSOL?: string;
+    balanceInETH?: string;
+    walletAddress: string;
+}
+interface BaseGetTokenAccountsParams {
+    wallet: PublicWallet;
+    rpcUrl?: string;
+    options?: any;
+}
+interface BaseWalletHooks {
+    useCreateWallet: (callbacks?: {
+        onSuccess?: (result: {
+            wallet: PublicWallet;
+        }) => void;
+        onError?: (error: Error) => void;
+    }) => {
+        createWallet: (options?: {
+            createAdditional?: boolean;
+            walletIndex?: number;
+        }) => Promise<{
+            wallet: PublicWallet;
+        }>;
+    };
+    useWallets: () => {
+        wallets: BaseWallet[];
+        loading: boolean;
+        error?: Error;
+        refetch: () => void;
+    };
+    useSignMessage: () => {
+        signMessage: (params: BaseSignMessageParams) => Promise<BaseSignMessageResult>;
+        loading: boolean;
+        error?: Error;
+    };
+    useSignTransaction: () => {
+        signTransaction: (params: BaseSignTransactionParams) => Promise<BaseSignTransactionResult>;
+        loading: boolean;
+        error?: Error;
+    };
+    useSendTransaction: () => {
+        sendTransaction: (params: BaseSendTransactionParams) => Promise<BaseSendTransactionResult>;
+        loading: boolean;
+        error?: Error;
+    };
+    useGetBalance: () => {
+        getBalance: (params: BaseGetBalanceParams) => Promise<BaseGetBalanceResult>;
+        loading: boolean;
+        error?: Error;
+    };
+    useGetTokenAccounts: () => {
+        getTokenAccounts: (params: BaseGetTokenAccountsParams) => Promise<any>;
+        loading: boolean;
+        error?: Error;
+    };
+}
+
+export type { BaseWalletHooks as B };

package/dist/base-wallet-CzJLpndu.d.ts

@@ -0,0 +1,119 @@
+import { PublicWallet } from '@moon-x/core/types';
+
+interface BaseWallet {
+    id: string;
+    type: "solana" | "ethereum";
+    address: string;
+    isConnected: boolean;
+}
+interface BaseUIOptions {
+    title?: string;
+    description?: string;
+    buttonText?: string;
+    showWalletUI?: boolean;
+}
+interface BaseSignMessageParams {
+    message: string;
+    wallet: BaseWallet;
+    options?: {
+        uiOptions?: BaseUIOptions;
+    };
+}
+interface BaseSignMessageResult {
+    signature: Uint8Array;
+    signedMessage?: Uint8Array;
+}
+interface BaseSignTransactionParams {
+    transaction: Uint8Array | string;
+    wallet: BaseWallet;
+    options?: {
+        uiOptions?: BaseUIOptions;
+    };
+}
+interface BaseSignTransactionResult {
+    signature: Uint8Array;
+    signedTransaction: Uint8Array | string;
+}
+interface BaseSendTransactionParams {
+    transaction: Uint8Array | string;
+    wallet: BaseWallet;
+    rpcUrl: string;
+    options?: {
+        uiOptions?: BaseUIOptions;
+        commitment?: string;
+        encoding?: string;
+        replaceRecentBlockhash?: boolean;
+        sigVerify?: boolean;
+        minContextSlot?: number;
+        innerInstructions?: boolean;
+        accounts?: any[];
+        network?: string;
+    };
+}
+interface BaseSendTransactionResult {
+    signature: Uint8Array;
+    transactionHash: string;
+    walletAddress: string;
+}
+interface BaseGetBalanceParams {
+    wallet: BaseWallet;
+}
+interface BaseGetBalanceResult {
+    balance: string;
+    balanceInSOL?: string;
+    balanceInETH?: string;
+    walletAddress: string;
+}
+interface BaseGetTokenAccountsParams {
+    wallet: PublicWallet;
+    rpcUrl?: string;
+    options?: any;
+}
+interface BaseWalletHooks {
+    useCreateWallet: (callbacks?: {
+        onSuccess?: (result: {
+            wallet: PublicWallet;
+        }) => void;
+        onError?: (error: Error) => void;
+    }) => {
+        createWallet: (options?: {
+            createAdditional?: boolean;
+            walletIndex?: number;
+        }) => Promise<{
+            wallet: PublicWallet;
+        }>;
+    };
+    useWallets: () => {
+        wallets: BaseWallet[];
+        loading: boolean;
+        error?: Error;
+        refetch: () => void;
+    };
+    useSignMessage: () => {
+        signMessage: (params: BaseSignMessageParams) => Promise<BaseSignMessageResult>;
+        loading: boolean;
+        error?: Error;
+    };
+    useSignTransaction: () => {
+        signTransaction: (params: BaseSignTransactionParams) => Promise<BaseSignTransactionResult>;
+        loading: boolean;
+        error?: Error;
+    };
+    useSendTransaction: () => {
+        sendTransaction: (params: BaseSendTransactionParams) => Promise<BaseSendTransactionResult>;
+        loading: boolean;
+        error?: Error;
+    };
+    useGetBalance: () => {
+        getBalance: (params: BaseGetBalanceParams) => Promise<BaseGetBalanceResult>;
+        loading: boolean;
+        error?: Error;
+    };
+    useGetTokenAccounts: () => {
+        getTokenAccounts: (params: BaseGetTokenAccountsParams) => Promise<any>;
+        loading: boolean;
+        error?: Error;
+    };
+}
+
+export type { BaseWalletHooks as B };