npm package: @rango-dev/internal-social-wallet
Description: React utilities that bridge Privy’s embedded wallets with Rango’s wallet-core stack. Drop in the provider, wire up config, and you get social login, multi-chain wallet providers, and signer helpers that feel native to your React app.
Latest version: 0.0.2

# @rango-dev/internal-social-wallet

React utilities that bridge Privy’s embedded wallets with Rango’s wallet-core stack. Drop in the provider, wire up config, and you get social login, multi-chain wallet providers, and signer helpers that feel native to your React app.

---

## Table of Contents

1. [Features](#features)
2. [Installation](#installation)
3. [Peer Dependencies](#peer-dependencies)
4. [API Surface](#api-surface)
5. [Getting Started](#getting-started)
6. [Configuration & Environment](#configuration--environment)
7. [Development](#development)
8. [Testing Ideas](#testing-ideas)
9. [Known Gaps](#known-gaps)
10. [FAQ](#faq)

---

## Features

- **Drop-in provider** – `SocialWalletProvider` wraps Privy, exposes supported chain state via React context, and includes sane defaults for embedded EVM + Solana wallets.
- **Multi-namespace hook** – `useSocialWallet` returns a provider map (`evm`, `solana`) backed by `@rango-dev/wallets-core`, handling Privy login, auto-connect, signer instantiation, and error surfacing.
- **Config hook** – `useSocialWalletConfig` allows any component to read/update the supported chains without prop drilling.
- **Helper utilities** – Solana signer wrappers, Privy chain converters, and validation helpers keep chain metadata consistent between Privy and Rango.

---

## Installation

```bash
pnpm add @rango-dev/internal-social-wallet
# or
yarn add @rango-dev/internal-social-wallet
```

Use your workspace package manager if different (`npm`, `bun`, etc.).

---

## Peer Dependencies

Ensure these packages already exist in your app (matching versions to your stack):

- `react`, `react-dom`
- `@privy-io/react-auth`
- `@rango-dev/wallets-core`, `@rango-dev/wallets-shared`
- `@rango-dev/signer-evm`, `@rango-dev/signer-solana`
- `@solana/web3.js`, `@solana/kit`, `bs58`, `rango-types`

---

## API Surface

```ts
import {
  SocialWalletProvider,
  useSocialWallet,
  useSocialWalletConfig,
} from '@rango-dev/internal-social-wallet';
```

- `SocialWalletProvider` – wraps your tree, configures Privy with sane defaults, and accepts a required `appId` prop.
- `useSocialWallet` – returns `{ provider, exportEvmWallet, exportSolanaWallet }`.
- `useSocialWalletConfig` – exposes `{ supportedChains, setSupportedChains }`.

Refer to the source if you need additional helper exports (signers, constants).

---

## Getting Started

### 1. Wrap your app

```tsx
import { SocialWalletProvider } from '@rango-dev/internal-social-wallet';

function App() {
  return (
    <SocialWalletProvider appId={process.env.NEXT_PUBLIC_PRIVY_APP_ID!}>
      <YourRouter />
    </SocialWalletProvider>
  );
}
```

### 2. Configure supported chains

```tsx
import { useEffect } from 'react';
import { useSocialWalletConfig } from '@rango-dev/internal-social-wallet';
import type { BlockchainMeta } from 'rango-types';

const chains: BlockchainMeta[] = [
  /* fetched from backend */
];

function ChainBootstrap() {
  const { setSupportedChains } = useSocialWalletConfig();

  useEffect(() => {
    setSupportedChains(chains);
  }, [chains, setSupportedChains]);

  return null;
}
```

### 3. Consume the wallet provider

```tsx
import { useSocialWallet } from '@rango-dev/internal-social-wallet';

function ConnectButton() {
  const { provider, status } = useSocialWallet();

  const connect = async () => {
    await provider.get('evm')?.connect();
  };

  return (
    <button disabled={status === 'connecting'} onClick={connect}>
      Connect Social Wallet
    </button>
  );
}
```

### 4. Optional: customize Privy config

```tsx
<SocialWalletProvider appId={process.env.NEXT_PUBLIC_PRIVY_APP_ID!} />
```

---

## Configuration & Environment

- `CustomPrivyProvider` defines default Solana RPC URLs in `CustomPrivyProvider.constants.ts`. Override through env variables or inject custom RPCs via props before production.
- Privy login methods currently default to `email`, `google`, `twitter`. To change them, update `providers/customPrivyProvider/CustomPrivyProvider.tsx` (props-based configuration is not yet wired).
- When deploying to multiple environments, align `NEXT_PUBLIC_PRIVY_APP_ID`, RPC URLs, and supported chain metadata so Privy and Rango stay in sync.

---

## Development

```bash
pnpm --filter @rango-dev/internal-social-wallet dev   # tsc --watch
pnpm --filter @rango-dev/internal-social-wallet build # emits dist/
```

Before publishing:

- Verify `package.json` exports target `dist/index.*`.
- Run `pnpm --filter @rango-dev/internal-social-wallet build` to regenerate `dist/`.
- Smoke test the provider in a sandbox app to ensure Privy embeds load correctly.

---

## Testing Ideas

No automated tests ship with this package yet. Suggested coverage:

- `useSocialWallet` connect/disconnect flows (mock Privy, assert provider map).
- `useSocialWalletConfig` state updates propagate to consumers.
- Solana signer wrapper – verifies transaction signing + serialization.
- Error boundaries and fallback UI when Privy is unavailable.

---

## Known Gaps

- `exportEvmWallet` / `exportSolanaWallet` functions are placeholders.
- RPC URLs are hardcoded; externalize them for production.
- First embedded wallet is automatically selected; multi-wallet UX is out of scope for now.

---

## FAQ

**Q: Does this replace traditional wallet adapters?**  
A: No. It complements them by giving Privy-powered embedded wallets that conform to the same wallet-core interface.

**Q: How do I add a new chain?**  
A: Update your backend/source of `BlockchainMeta`, call `setSupportedChains`, and ensure Privy supports the chain ID + namespace.

**Q: Why can’t I connect on Solana?**  
A: Double-check Solana RPC URLs, make sure `@solana/web3.js` is available, and confirm the Privy app has Solana enabled.