@owlyfi/privy-onboarding
v0.0.1
Published
Privy guest onboarding primitives and optional React UI for Owly products.
Readme
@owlyfi/privy-onboarding
Privy-based guest onboarding primitives for React, with an optional localized UI. The package creates a guest identity only after a user action, then creates or resumes one embedded EVM wallet and one embedded Solana wallet under the same identity. Hosts remain responsible for routes, application sessions, transactions, funding, and authorization.
Release version: 0.0.1. This package targets React and Next.js applications. No open-source license grant is included.
Install
Install version 0.0.1 with its exact Privy peer, a supported React version, and Privy's current bundler closure. These commands use the same dependency lifecycle policy as the compatibility matrix:
npm install --ignore-scripts @owlyfi/[email protected] @privy-io/[email protected] [email protected] [email protected] @solana/[email protected] @solana-program/[email protected] @solana-program/[email protected] @solana-program/[email protected] @solana/[email protected] @stripe/[email protected]
pnpm add --ignore-scripts @owlyfi/[email protected] @privy-io/[email protected] [email protected] [email protected] @solana/[email protected] @solana-program/[email protected] @solana-program/[email protected] @solana-program/[email protected] @solana/[email protected] @stripe/[email protected]
yarn add --mode=skip-build @owlyfi/[email protected] @privy-io/[email protected] [email protected] [email protected] @solana/[email protected] @solana-program/[email protected] @solana-program/[email protected] @solana-program/[email protected] @solana/[email protected] @stripe/[email protected]
bun add --ignore-scripts @owlyfi/[email protected] @privy-io/[email protected] [email protected] [email protected] @solana/[email protected] @solana-program/[email protected] @solana-program/[email protected] @solana-program/[email protected] @solana/[email protected] @stripe/[email protected]The tarball is standard ESM and does not require Bun in consumer applications.
The Solana and Stripe packages satisfy peers reached from Privy 3.42.0's main ESM entry, even for an EVM-only Provider + UI build. Stripe.js 1.54.2 is the latest 1.x release compatible with @stripe/[email protected]'s declared ^1.46.0 peer. This package now exposes EVM and Solana onboarding. It does not expose Stripe or funding behavior. These packages can be removed only after a validated Privy or bundler version no longer resolves that upstream module graph.
This package has no install lifecycle script. The tested commands disable dependency build scripts because pnpm 12 otherwise stops on unapproved builds in Privy's transitive graph, and the matrix does not execute upstream native websocket or telemetry/version-check scripts. Their JavaScript fallbacks are sufficient for these browser builds. If an application separately needs a native dependency's build output, approve and run that dependency's lifecycle script according to the package manager's policy.
React setup
import { OnboardingProvider } from '@owlyfi/privy-onboarding/react';
import { OnboardingPanel } from '@owlyfi/privy-onboarding/ui';
import { en } from '@owlyfi/privy-onboarding/locales';
import '@owlyfi/privy-onboarding/styles.css';
export function WalletOnboarding() {
return (
<OnboardingProvider config={{ appId: import.meta.env.VITE_PRIVY_APP_ID }}>
<OnboardingPanel messages={en} />
</OnboardingProvider>
);
}For Next.js App Router, put OnboardingProvider in a Client Component and import the stylesheet from the root layout. The source repository includes runnable Next.js and Vite examples that reference the retained local tarball.
Applications that already render Privy's provider should use OnboardingBridge inside that provider. Do not nest the package provider and bridge.
Multi-chain wallets
walletChains defaults to ['ethereum', 'solana']. One explicit create/resume action provisions the missing embedded wallets sequentially, always with createAdditional: false. A partial failure keeps the identity and existing wallets; retry only creates the missing chain. Existing Guest accounts with an EVM wallet can use Continue creating wallet to add Solana.
<OnboardingProvider config={{
appId: import.meta.env.VITE_PRIVY_APP_ID,
walletChains: ['ethereum', 'solana'],
}}>
<OnboardingPanel messages={en} />
</OnboardingProvider>- For the previous EVM-only behavior, explicitly use
walletChains: ['ethereum']. Solana-only apps use['solana']. - Order sets the initial chain preference. Multiple wallets on that chain still require an explicit selection.
actions.selectWallet(key)changes the active wallet and invalidates the previous scope. state.ownedWalletscontains authenticated wallet ownership for configured chains.state.connectedWalletsalone never proves ownership.AccountReady.walletis the selected wallet; it does not represent every wallet in the account.WalletRefis discriminated bychainType; narrow it before treatingaddressas an EVM address. Solana addresses are case-sensitive. EVM keys retain their previous format.- EVM networks such as Ethereum, Base and BNB Chain share the EVM address. Network configuration remains
privyOptions.supportedChains/defaultChain; these are not separate wallets. Solana uses a separate address and key. openExportWallet()exports the selected embedded wallet through the matching official Privy dialog.openExportWallet({ walletKey })targets an explicitly owned, connected embedded wallet without changing selection. Unknown, external, disconnected, or no-longer-owned targets are rejected. Each wallet has its own private key. Account protection retains the same DID and both wallets.- External-wallet login authenticates the selected external wallet; it does not create an embedded pair. A restored external-only member keeps this behavior.
getEthereumProvider() only works for a selected EVM wallet; it rejects a Solana selection with UNSUPPORTED_OPERATION. Solana signing remains in Privy's official useWallets / transaction hooks from @privy-io/react-auth/solana, without another transaction API in this package. Match both the selected address and wallet kind when choosing a connected Solana instance: Privy's embedded Standard Wallet has features['privy:'] and isPrivyWallet === true; another connection at the same address may be external. Capture state.scopeKey, check actions.isCurrentScope(scopeKey) before dispatch and after asynchronous results, and discard stale results. These guards cannot undo a transaction already submitted by the host.
For Solana transaction workflows, pass the host's RPC configuration through privyOptions.solana.rpcs. Creation and export do not require this package to send a transaction. Privy's Solana integration and migration guide.
Unified backup entry
AccountPanel (including the one inside OnboardingPanel) opens the package-owned WalletBackupDialog. It displays the named network groups, each wallet address and private key, and one eligible recovery-phrase source in a single custom window. Each secret stays hidden until the user clicks Show; Copy is a separate explicit action. This component does not open the official Privy export window. Privy may still request authentication or MFA, during which the custom window is temporarily hidden.
import { WalletBackupDialog } from '@owlyfi/privy-onboarding/ui';
// Inside an OnboardingProvider, with host-owned open state:
<WalletBackupDialog messages={messages} open={backupOpen}
onClose={() => setBackupOpen(false)} />The default labels show Robinhood Chain · BNB Smart Chain · Base for the shared Ethereum-compatible wallet, and Solana for its separate wallet. Labels describe address/key compatibility; they do not configure RPCs or enable trading/funding. Customize the complete locale messages for other products. Robinhood Chain mainnet is documented at Connecting to Robinhood Chain.
Custom export supports connected, currently owned, non-imported Privy unified wallets (recoveryMethod: privy-v2 with a wallet ID). Other wallets display an unsupported message. A single recovery-phrase field appears only when there is exactly one eligible Ethereum wallet with a known wallet index. Before display, each private key must reproduce its wallet address; a phrase must pass BIP-39 validation and reproduce its source Ethereum address using the standard BIP-44 address-index path. Other derivations fail closed. A shared phrase restores only wallets derived from it; this UI does not claim that separately created or imported wallets share a backup.
Opening, copying or closing the dialog does not prove that a backup was saved. The dialog uses the native modal focus trap, restores focus when closed, and never starts an export on mount. Existing openExportWallet() behavior remains available as the legacy official export action for hosts with their own entry UI. Consumers maintaining complete OnboardingMessages must include the expanded backup message group.
Security boundary: this custom UI decrypts secrets in the browser, so scripts running in the host page can access plaintext. Do not mount it under session recording or content-capture instrumentation; masking attributes are defense in depth, not isolation. No secret is sent to a business backend, shared controller state, package logs, telemetry or browser persistence. The package requests encrypted export directly from Privy using user authorization and an ephemeral, non-extractable recipient key; no App Secret is used. Requests have a 30-second timeout and no automatic retries.
Revealed buffers and DOM text are cleared on Hide, close, account/ownership changes, document hiding, unmount, or after one minute. Pending results are scoped, cancelled and discarded when stale. JavaScript strings and cryptographic-library internal copies cannot be guaranteed to be physically wiped immediately. Explicitly copied secrets remain in the system clipboard. These are intentional tradeoffs of the user-approved custom UI.
The official browser export endpoint integration and any app-specific restrictions still require real-app acceptance. Synthetic tests validate encryption, address matching, cancellation and cleanup; they do not establish that a particular Privy app permits this flow. Test only with disposable wallets, and never include secrets in diagnostic reports.
Existing PrivyProvider / Bridge
The host must disable both automatic creators and enable matching external connectors. Keep the same chain configuration on the Bridge:
import { PrivyProvider } from '@privy-io/react-auth';
import { toSolanaWalletConnectors } from '@privy-io/react-auth/solana';
import { OnboardingBridge } from '@owlyfi/privy-onboarding/react';
const connectors = toSolanaWalletConnectors();
// Inside a client component:
<PrivyProvider appId={appId} config={{
appearance: { walletChainType: 'ethereum-and-solana' },
embeddedWallets: {
ethereum: { createOnLogin: 'off' },
solana: { createOnLogin: 'off' },
},
externalWallets: { solana: { connectors } },
}}>
<OnboardingBridge config={{ appId, walletChains: ['ethereum', 'solana'] }}>
{children}
</OnboardingBridge>
</PrivyProvider>Entrypoints
@owlyfi/privy-onboarding: server-safe types, configuration, and normalized errors@owlyfi/privy-onboarding/react: provider, bridge, and hooks@owlyfi/privy-onboarding/ui: optional components@owlyfi/privy-onboarding/locales: typed English and Chinese messages@owlyfi/privy-onboarding/styles.css: explicitly imported scoped styles
There is no /funding entrypoint in P1. Authentication may use Privy interfaces; wallet backup uses the custom package dialog described above. Closing a dialog does not confirm a saved backup.
Development
bun install --frozen-lockfile
bun run typecheck
bun run test
bun run build
bun run check:package
bun run test:consumerstest:consumers creates one tarball under artifacts/, records its SHA-256 digest, and installs that exact file in isolated npm, pnpm, Yarn PnP, and Bun consumers. Each consumer typechecks and production-builds both the Vite and Next no-Stripe fixture. The Next build uses its webpack builder because Next 16's default Turbopack builder cannot resolve next/package.json from the tested Yarn PnP filesystem.
Dashboard requirements and known validation limits are recorded in docs/dashboard-setup.md and docs/compatibility.md.
