@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
2. Installation
3. Peer Dependencies
4. API Surface
5. Getting Started
6. Configuration & Environment
7. Development
8. Testing Ideas
9. Known Gaps
10. 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

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

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

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

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

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

<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

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.