@sodax/skills 2.2.0 → 2.3.0-rc.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +7 -7
- package/README.md +5 -5
- package/package.json +4 -4
- package/skills/sodax-build/SKILL.md +1 -1
- package/skills/sodax-build/knowledge/README.md +1 -1
- package/skills/sodax-build/knowledge/feature-catalog.md +4 -0
- package/skills/sodax-build/knowledge/glossary.md +1 -0
- package/skills/sodax-build/knowledge/handoff.md +3 -0
- package/skills/sodax-build/knowledge/interview-guide.md +1 -0
- package/skills/sodax-dapp-kit/auxiliary-services/SKILL.md +4 -1
- package/skills/sodax-dapp-kit/bridge/SKILL.md +1 -1
- package/skills/sodax-dapp-kit/integration/knowledge/architecture.md +18 -4
- package/skills/sodax-dapp-kit/integration/knowledge/features/auxiliary-services.md +23 -1
- package/skills/sodax-dapp-kit/integration/knowledge/features/bridge.md +8 -0
- package/skills/sodax-dapp-kit/integration/knowledge/features/leverage-yield.md +5 -3
- package/skills/sodax-dapp-kit/integration/knowledge/features/swap.md +24 -0
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/bridge.md +2 -0
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/leverage-yield.md +1 -0
- package/skills/sodax-dapp-kit/integration/knowledge/recipes/swap.md +141 -1
- package/skills/sodax-dapp-kit/integration/knowledge/reference/hooks-index.md +8 -0
- package/skills/sodax-dapp-kit/integration/knowledge/reference/public-api.md +1 -1
- package/skills/sodax-dapp-kit/integration/knowledge/reference/querykey-conventions.md +8 -0
- package/skills/sodax-dapp-kit/leverage-yield/SKILL.md +3 -3
- package/skills/sodax-dapp-kit/swap/SKILL.md +3 -3
- package/skills/sodax-sdk/bridge/SKILL.md +3 -1
- package/skills/sodax-sdk/integration/knowledge/architecture.md +1 -1
- package/skills/sodax-sdk/integration/knowledge/features/bridge-api.md +5 -3
- package/skills/sodax-sdk/integration/knowledge/features/bridge.md +8 -0
- package/skills/sodax-sdk/integration/knowledge/features/leverage-yield.md +25 -2
- package/skills/sodax-sdk/integration/knowledge/features/swap.md +72 -2
- package/skills/sodax-sdk/integration/knowledge/features/swaps-api.md +56 -2
- package/skills/sodax-sdk/integration/knowledge/reference/error-codes.md +27 -1
- package/skills/sodax-sdk/integration/knowledge/reference/public-api.md +30 -1
- package/skills/sodax-sdk/leverage-yield/SKILL.md +3 -2
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/architecture.md +1 -1
- package/skills/sodax-sdk/migration-v1-to-v2/knowledge/reference/sodax-config.md +9 -1
- package/skills/sodax-sdk/swap/SKILL.md +3 -1
- package/skills/sodax-sdk/swaps-api/SKILL.md +3 -2
- package/skills/sodax-wallet-sdk-core/evm/SKILL.md +2 -1
- package/skills/sodax-wallet-sdk-core/integration/knowledge/README.md +1 -1
- package/skills/sodax-wallet-sdk-core/integration/knowledge/features/evm.md +6 -0
- package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/interfaces.md +4 -1
- package/skills/sodax-wallet-sdk-core/migration-v1-to-v2/knowledge/README.md +1 -1
- package/skills/sodax-wallet-sdk-react/SKILL.md +5 -3
- package/skills/sodax-wallet-sdk-react/integration/knowledge/README.md +2 -1
- package/skills/sodax-wallet-sdk-react/integration/knowledge/ai-rules.md +2 -0
- package/skills/sodax-wallet-sdk-react/integration/knowledge/architecture.md +10 -6
- package/skills/sodax-wallet-sdk-react/integration/knowledge/examples/05-privy-email-login.tsx +157 -0
- package/skills/sodax-wallet-sdk-react/integration/knowledge/examples/README.md +1 -0
- package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/privy-email-login.md +111 -0
- package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/api-surface.md +14 -0
- package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/chain-support.md +1 -1
- package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/README.md +1 -1
- package/skills/sodax-wallet-sdk-react/privy/SKILL.md +53 -0
- package/skills/sodax-wallet-sdk-react/wallet-modal/SKILL.md +1 -0
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
'use client';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Email login with Privy — adds "Email (Privy)" (connector id `privy`) to the EVM wallet list.
|
|
5
|
+
* The user types an email, enters Privy's one-time code and gets an embedded EVM wallet that signs
|
|
6
|
+
* like any other wallet.
|
|
7
|
+
*
|
|
8
|
+
* Before running:
|
|
9
|
+
* - `pnpm add @privy-io/react-auth` (3.40 or newer) — an optional peer of `@sodax/wallet-sdk-react`.
|
|
10
|
+
* - Create an app at https://dashboard.privy.io: enable Email login and Ethereum embedded wallets,
|
|
11
|
+
* and allow this origin (`http://localhost:<port>` plus every deployed and preview URL).
|
|
12
|
+
*
|
|
13
|
+
* Next.js App Router: keep this whole file client-side (`'use client'` above). React refuses to pass
|
|
14
|
+
* `privy()`'s value from a Server Component.
|
|
15
|
+
*
|
|
16
|
+
* For Privy-only data (the user's email, key export) use Privy's own hooks such as `usePrivy()`
|
|
17
|
+
* below `SodaxWalletProvider` — see `../recipes/privy-email-login.md`.
|
|
18
|
+
*/
|
|
19
|
+
|
|
20
|
+
import { type ReactNode, useEffect, useRef, useState } from 'react';
|
|
21
|
+
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
|
|
22
|
+
import {
|
|
23
|
+
SodaxWalletProvider,
|
|
24
|
+
type SodaxWalletConfig,
|
|
25
|
+
useWalletModal,
|
|
26
|
+
useXAccount,
|
|
27
|
+
useXConnection,
|
|
28
|
+
useXConnectors,
|
|
29
|
+
useXDisconnect,
|
|
30
|
+
useXSignMessage,
|
|
31
|
+
} from '@sodax/wallet-sdk-react';
|
|
32
|
+
import { PRIVY_CONNECTOR_ID, privy } from '@sodax/wallet-sdk-react/privy';
|
|
33
|
+
import { ChainKeys } from '@sodax/types';
|
|
34
|
+
|
|
35
|
+
const queryClient = new QueryClient();
|
|
36
|
+
|
|
37
|
+
const walletConfig: SodaxWalletConfig = {
|
|
38
|
+
EVM: {
|
|
39
|
+
ssr: true,
|
|
40
|
+
chains: {
|
|
41
|
+
[ChainKeys.SONIC_MAINNET]: { rpcUrl: 'https://rpc.soniclabs.com' },
|
|
42
|
+
[ChainKeys.BASE_MAINNET]: { rpcUrl: 'https://mainnet.base.org' },
|
|
43
|
+
},
|
|
44
|
+
// The App ID is public. An unset env var only warns and leaves "Email (Privy)" out; privy() never throws.
|
|
45
|
+
privy: privy({ appId: process.env.NEXT_PUBLIC_PRIVY_APP_ID ?? '' }),
|
|
46
|
+
},
|
|
47
|
+
};
|
|
48
|
+
|
|
49
|
+
export function App() {
|
|
50
|
+
return (
|
|
51
|
+
<QueryClientProvider client={queryClient}>
|
|
52
|
+
<SodaxWalletProvider config={walletConfig}>
|
|
53
|
+
<EmailLogin />
|
|
54
|
+
</SodaxWalletProvider>
|
|
55
|
+
</QueryClientProvider>
|
|
56
|
+
);
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
function EmailLogin() {
|
|
60
|
+
const modal = useWalletModal();
|
|
61
|
+
const connectors = useXConnectors({ xChainType: 'EVM' });
|
|
62
|
+
const account = useXAccount({ xChainType: 'EVM' });
|
|
63
|
+
const connection = useXConnection({ xChainType: 'EVM' });
|
|
64
|
+
const disconnect = useXDisconnect();
|
|
65
|
+
|
|
66
|
+
const privyConnector = connectors.find(c => c.id === PRIVY_CONNECTOR_ID);
|
|
67
|
+
|
|
68
|
+
// Privy's own login dialog owns the screen while it is connecting
|
|
69
|
+
if (modal.state.kind === 'connecting' && modal.state.connector.id === PRIVY_CONNECTOR_ID) {
|
|
70
|
+
return null;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
if (account.address) {
|
|
74
|
+
return (
|
|
75
|
+
<div>
|
|
76
|
+
<code>{account.address}</code>
|
|
77
|
+
{connection?.xConnectorId === PRIVY_CONNECTOR_ID && <span> (email wallet)</span>}
|
|
78
|
+
<button type="button" onClick={() => disconnect({ xChainType: 'EVM' })}>
|
|
79
|
+
Disconnect
|
|
80
|
+
</button>
|
|
81
|
+
<SignInDialog />
|
|
82
|
+
</div>
|
|
83
|
+
);
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
if (!privyConnector) {
|
|
87
|
+
return <p>Email login not configured — set NEXT_PUBLIC_PRIVY_APP_ID</p>;
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
return (
|
|
91
|
+
<div>
|
|
92
|
+
<button type="button" onClick={() => modal.selectWallet(privyConnector)}>
|
|
93
|
+
Log in with email
|
|
94
|
+
</button>
|
|
95
|
+
{/* Closing Privy's dialog lands here with a user-rejection error */}
|
|
96
|
+
{modal.state.kind === 'error' && <p>Login failed: {modal.state.error.message}</p>}
|
|
97
|
+
</div>
|
|
98
|
+
);
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/** A dialog of your own that signs while open: Privy's confirmation screen appears on top of it. */
|
|
102
|
+
function SignInDialog() {
|
|
103
|
+
const [open, setOpen] = useState(false);
|
|
104
|
+
const signMessage = useXSignMessage();
|
|
105
|
+
|
|
106
|
+
if (!open) {
|
|
107
|
+
return (
|
|
108
|
+
<button type="button" onClick={() => setOpen(true)}>
|
|
109
|
+
Sign in to the app
|
|
110
|
+
</button>
|
|
111
|
+
);
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
return (
|
|
115
|
+
<OutsideClickDialog onClose={() => setOpen(false)}>
|
|
116
|
+
<p>Sign a message to prove you own this wallet.</p>
|
|
117
|
+
<button
|
|
118
|
+
type="button"
|
|
119
|
+
disabled={signMessage.isPending}
|
|
120
|
+
onClick={() => signMessage.mutate({ xChainType: 'EVM', message: 'Sign in to my SODAX app' })}
|
|
121
|
+
>
|
|
122
|
+
Sign
|
|
123
|
+
</button>
|
|
124
|
+
{signMessage.data && <code>{String(signMessage.data)}</code>}
|
|
125
|
+
</OutsideClickDialog>
|
|
126
|
+
);
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
/** True for events inside Privy's screens (login, confirmations, MFA), which render outside your components. */
|
|
130
|
+
function isInPrivyDialog(target: EventTarget | null): boolean {
|
|
131
|
+
return target instanceof Element && target.closest('#privy-dialog') !== null;
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
/**
|
|
135
|
+
* Closes on a click outside itself — except a click on Privy's screens, which would otherwise close it
|
|
136
|
+
* mid-signature. Radix / shadcn equivalent on `DialogContent` or `SheetContent`:
|
|
137
|
+
* `onInteractOutside={event => { if (isInPrivyDialog(event.target)) event.preventDefault(); }}`
|
|
138
|
+
*/
|
|
139
|
+
function OutsideClickDialog({ onClose, children }: { onClose: () => void; children: ReactNode }) {
|
|
140
|
+
const ref = useRef<HTMLDivElement>(null);
|
|
141
|
+
|
|
142
|
+
useEffect(() => {
|
|
143
|
+
const onPointerDown = (event: PointerEvent) => {
|
|
144
|
+
const target = event.target;
|
|
145
|
+
if (!(target instanceof Node) || ref.current?.contains(target) || isInPrivyDialog(target)) return;
|
|
146
|
+
onClose();
|
|
147
|
+
};
|
|
148
|
+
document.addEventListener('pointerdown', onPointerDown);
|
|
149
|
+
return () => document.removeEventListener('pointerdown', onPointerDown);
|
|
150
|
+
}, [onClose]);
|
|
151
|
+
|
|
152
|
+
return (
|
|
153
|
+
<div ref={ref} role="dialog" aria-modal="true">
|
|
154
|
+
{children}
|
|
155
|
+
</div>
|
|
156
|
+
);
|
|
157
|
+
}
|
|
@@ -10,6 +10,7 @@ For narrative + step-by-step explanation, see [`../recipes/`](../recipes/). Exam
|
|
|
10
10
|
| [`02-multi-chain-modal.tsx`](./02-multi-chain-modal.tsx) | Headless wallet modal with chain → connector → connecting flow | ~120 |
|
|
11
11
|
| [`03-nextjs-app-router.tsx`](./03-nextjs-app-router.tsx) | Next.js 15 App Router setup (SSR + `'use client'`) | ~60 |
|
|
12
12
|
| [`04-walletconnect-setup.tsx`](./04-walletconnect-setup.tsx) | WalletConnect connector setup (with optional single-wallet filter) | ~50 |
|
|
13
|
+
| [`05-privy-email-login.tsx`](./05-privy-email-login.tsx) | Privy email login (`EVM.privy`), hiding the modal during Privy's login, a dialog that survives Privy's screens. Also needs `@privy-io/react-auth` 3.40+ | ~150 |
|
|
13
14
|
|
|
14
15
|
## Conventions
|
|
15
16
|
|
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
# Recipe: Email Login with Privy (EVM only)
|
|
2
|
+
|
|
3
|
+
Add an **"Email (Privy)"** entry to the EVM wallet list: the user logs in with an email one-time code and gets a Privy embedded wallet that signs like any other EVM wallet. Opt-in, behind the `@sodax/wallet-sdk-react/privy` sub-path.
|
|
4
|
+
|
|
5
|
+
**Depends on:** [`setup.md`](./setup.md) · **Full file:** [`examples/05-privy-email-login.tsx`](../examples/05-privy-email-login.tsx)
|
|
6
|
+
|
|
7
|
+
You write the code. The user owns the Privy app and receives the email code, so step 0 asks them first and the [Verification](#verification) hands them the login test.
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## 0. Ask the user before coding
|
|
12
|
+
|
|
13
|
+
1. **Trade-offs.** Tell them (full text in the [package guide](https://github.com/gosodax/sodax-sdks/blob/main/packages/wallet-sdk-react/docs/WALLET_PRIVY.md)): Privy custodies access, so no signing is possible while Privy is unreachable; addresses belong to their Privy app; a user who loses their email loses the wallet; their Privy app is billed per signature.
|
|
14
|
+
2. **Their Privy App ID.** If they have none, give them this checklist for dashboard.privy.io:
|
|
15
|
+
- Create an app and copy its App ID.
|
|
16
|
+
- Enable **Email** login and **Ethereum embedded wallets**. The SDK shows email login only.
|
|
17
|
+
- Allow every origin the app runs on: `http://localhost:<port>`, production, and each preview URL. Wildcards such as `https://*.vercel.app` are refused, and Privy requires https except on `localhost` / `127.0.0.1` — a dev server opened by LAN IP fails with "Embedded wallet is only available over HTTPS".
|
|
18
|
+
- To test without an inbox, enable test accounts (`test-XXXX@privy.io` with a fixed code).
|
|
19
|
+
3. **Privy's confirmation screens (`showWalletUIs`).** With them on, Privy confirms every signature and transaction, and a transaction's hash arrives only after Privy has waited for the receipt and the user has closed its success screen. `false` returns the hash right after broadcast and leaves the app's own review step as the only confirmation. Unset follows the dashboard.
|
|
20
|
+
4. **Shared devices (`disconnectBehavior`).** `'logout'` (default) signs the user out of Privy on disconnect, so the next connect needs a new code; `'detach'` keeps the Privy session for anyone using that browser.
|
|
21
|
+
5. **App already on Privy?** If it mounts its own `PrivyProvider` only for email login and the embedded wallet, remove that provider, pass the same `appId` to `privy()` and skip the install (its `@privy-io/react-auth` must be 3.40 or newer). If it needs its own Privy configuration — other login methods, other chains, or a Privy session that must outlive a wallet disconnect — do not add `EVM.privy`: the SDK cannot use a provider the app mounts, and Privy allows only one.
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## 1. Install the peer and store the App ID
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
pnpm add @privy-io/react-auth
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
- `@privy-io/react-auth` is an optional peer of `@sodax/wallet-sdk-react` — it is not installed automatically. It must be 3.40 or newer.
|
|
32
|
+
- **The App ID is public:** it ships in the browser bundle. Keep it in a public env var (`NEXT_PUBLIC_PRIVY_APP_ID` on Next.js, `VITE_PRIVY_APP_ID` on Vite). Unlike a SODAX API key, it needs no backend proxy.
|
|
33
|
+
- **npm / yarn:** Privy needs the app's top-level `viem` at 2.44 or newer; an older one fails at import with `does not provide an export named 'tempoModerato'`. pnpm is not affected.
|
|
34
|
+
- **Monorepo:** make the app and the SDK resolve one copy of `@privy-io/react-auth` (Vite: `resolve.dedupe: ['@privy-io/react-auth']`), or `usePrivy()` reads a different context than the provider the SDK mounts.
|
|
35
|
+
- **Content-Security-Policy:** if the site sends one, allow `https://auth.privy.io` in `connect-src`, `frame-src` and `child-src`.
|
|
36
|
+
- webpack warnings about `@farcaster/mini-app-solana` and a "Critical dependency" in `ox` are harmless for EVM-only use.
|
|
37
|
+
|
|
38
|
+
---
|
|
39
|
+
|
|
40
|
+
## 2. Pass `privy()` as `EVM.privy`
|
|
41
|
+
|
|
42
|
+
```typescript
|
|
43
|
+
'use client'; // Next.js App Router: privy()'s value cannot cross from a Server Component
|
|
44
|
+
|
|
45
|
+
import { type SodaxWalletConfig } from '@sodax/wallet-sdk-react';
|
|
46
|
+
import { privy } from '@sodax/wallet-sdk-react/privy';
|
|
47
|
+
import { ChainKeys } from '@sodax/types';
|
|
48
|
+
|
|
49
|
+
const walletConfig: SodaxWalletConfig = {
|
|
50
|
+
EVM: {
|
|
51
|
+
chains: { [ChainKeys.BASE_MAINNET]: { rpcUrl: 'https://mainnet.base.org' } },
|
|
52
|
+
// An unset env var only logs a warning and leaves "Email (Privy)" out; privy() never throws.
|
|
53
|
+
privy: privy({ appId: process.env.NEXT_PUBLIC_PRIVY_APP_ID ?? '' }),
|
|
54
|
+
},
|
|
55
|
+
};
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
`useXConnectors({ xChainType: 'EVM' })` now includes a connector with `id === 'privy'` (`PRIVY_CONNECTOR_ID`). **No UI changes required.** Options: `appId` (required), `clientId` (a Privy app client, for per-environment settings), `defaultChain` (an EVM `ChainKey`, default Sonic), `showWalletUIs` and `disconnectBehavior` (the user's answers from step 0), `appearance`, `legal`. If Privy cannot start (plain-http origin other than localhost, malformed app id, a second `PrivyProvider`), the app keeps running and picking "Email (Privy)" fails with the cause.
|
|
59
|
+
|
|
60
|
+
---
|
|
61
|
+
|
|
62
|
+
## 3. Read the Privy user (optional)
|
|
63
|
+
|
|
64
|
+
The SDK mounts `PrivyProvider` around the app, so Privy's own hooks work in child components. Render them only while the EVM wallet is the Privy one:
|
|
65
|
+
|
|
66
|
+
```tsx
|
|
67
|
+
// @ai-snippets-skip — imports the optional peer @privy-io/react-auth, which this package does not install
|
|
68
|
+
import { usePrivy } from '@privy-io/react-auth';
|
|
69
|
+
import { useXConnection } from '@sodax/wallet-sdk-react';
|
|
70
|
+
|
|
71
|
+
export function PrivyEmail() {
|
|
72
|
+
const connection = useXConnection({ xChainType: 'EVM' });
|
|
73
|
+
return connection?.xConnectorId === 'privy' ? <Email /> : null;
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
function Email() {
|
|
77
|
+
const { user } = usePrivy();
|
|
78
|
+
return <span>{user?.email?.address}</span>;
|
|
79
|
+
}
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
---
|
|
83
|
+
|
|
84
|
+
## Anti-patterns
|
|
85
|
+
|
|
86
|
+
- **Writing `privy: { appId }`.** The value must come from `privy()` — the import is what adds Privy's code to the bundle; a plain object is skipped with a warning.
|
|
87
|
+
- **Importing `privy` from `@sodax/wallet-sdk-react`.** It lives only on the `/privy` sub-path.
|
|
88
|
+
- **Calling `privy()` in a Server Component.** Its value belongs to the browser's copy of the SDK and React refuses to serialize it; build the config in a `'use client'` file.
|
|
89
|
+
- **Mounting a second `PrivyProvider`.** Privy allows one; for an app that already has one, see *App already on Privy?* above.
|
|
90
|
+
- **Adding `@privy-io/wagmi`.** Not used — it replaces wagmi's connector list and would remove MetaMask and WalletConnect.
|
|
91
|
+
- **Custom modal stacking.** While Privy's login dialog is open, `useWalletModal` is `connecting`; render nothing when `state.connector.id === 'privy'`, as for `'walletConnect'`.
|
|
92
|
+
- **Letting a modal dialog close on Privy's screens.** Privy renders login, confirmation and MFA screens in `#privy-dialog`, outside the app's components; an open modal dialog (confirm-swap, wallet sheet) treats a click there as an outside click and closes mid-transaction. Ignore outside interactions whose target is inside `#privy-dialog` (Radix: `onInteractOutside` → `event.preventDefault()`).
|
|
93
|
+
- **Promising the same address across apps.** An address belongs to the Privy app: another `appId` gives the same email a different wallet. Sharing needs the same `appId` with both origins allowed; Privy's Global Wallets are not supported.
|
|
94
|
+
|
|
95
|
+
---
|
|
96
|
+
|
|
97
|
+
## Verification
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
# 1. Type check and the production build (a missing peer fails the build with "Module not found")
|
|
101
|
+
pnpm tsc --noEmit && pnpm build
|
|
102
|
+
|
|
103
|
+
# 2. privy() comes from the sub-path and sits on the EVM slot
|
|
104
|
+
grep -rn "@sodax/wallet-sdk-react/privy" <user-src>
|
|
105
|
+
grep -rn "privy: privy(" <user-src>
|
|
106
|
+
|
|
107
|
+
# 3. Nothing the SDK already provides — expect no matches
|
|
108
|
+
grep -rn "@privy-io/wagmi\|<PrivyProvider" <user-src>
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
4. **Hand to the user** (you cannot receive the email code): run the app on an allowed origin, pick "Email (Privy)" in the wallet list, sign in with a test account, and check that the address appears and is still connected after a reload. Then run one small SODAX action — a quote, then a swap of about $1 — which signs through `useWalletProvider` like MetaMask, with no Privy-specific call.
|
|
@@ -99,6 +99,7 @@ Adapter-field types (only chains with React adapters):
|
|
|
99
99
|
| `EvmAdapterFields` | type |
|
|
100
100
|
| `SolanaAdapterFields` | type |
|
|
101
101
|
| `SuiAdapterFields` | type |
|
|
102
|
+
| `PrivySource` | type — opaque value of `EvmAdapterFields.privy`; only `privy()` from the `/privy` sub-path creates one |
|
|
102
103
|
|
|
103
104
|
### Hook option / result types
|
|
104
105
|
|
|
@@ -135,6 +136,18 @@ import { IconHanaXConnector } from '@sodax/wallet-sdk-react/xchains/icon';
|
|
|
135
136
|
|---|---|
|
|
136
137
|
| `/xchains/stellar` | Re-exports `StellarXService` + `StellarWalletsKitXConnector` (the concrete connector wrapping `@creit.tech/stellar-wallets-kit`). |
|
|
137
138
|
|
|
139
|
+
---
|
|
140
|
+
|
|
141
|
+
## Privy email login — `import { X } from '@sodax/wallet-sdk-react/privy'`
|
|
142
|
+
|
|
143
|
+
Opt-in; the only entry that loads the optional peer `@privy-io/react-auth` (3.40+). See [`recipes/privy-email-login.md`](../recipes/privy-email-login.md).
|
|
144
|
+
|
|
145
|
+
| Symbol | Kind | Notes |
|
|
146
|
+
|---|---|---|
|
|
147
|
+
| `privy` | function `(options: PrivyOptions) => PrivySource` | Value for `EVM.privy`. Never throws: bad input warns and leaves the entry out |
|
|
148
|
+
| `PrivyOptions` | type | `appId` (required), `clientId?`, `defaultChain?` (EVM `ChainKey`, default Sonic), `showWalletUIs?`, `disconnectBehavior?` (`'logout'` \| `'detach'`, default `'logout'`), `appearance?`, `legal?` |
|
|
149
|
+
| `PRIVY_CONNECTOR_ID` | value `'privy'` | The connector id / `xConnectorId` of "Email (Privy)" |
|
|
150
|
+
|
|
138
151
|
If unsure what a sub-path exports, check the published `dist/`:
|
|
139
152
|
|
|
140
153
|
```bash
|
|
@@ -149,6 +162,7 @@ grep -E '^export' node_modules/@sodax/wallet-sdk-react/dist/xchains/<chain>/inde
|
|
|
149
162
|
|---|---|
|
|
150
163
|
| `react` | `>= 19` |
|
|
151
164
|
| `@tanstack/react-query` | `5.x` |
|
|
165
|
+
| `@privy-io/react-auth` | optional — only with `EVM.privy`; 3.40 or newer (older versions are left out with a warning) |
|
|
152
166
|
|
|
153
167
|
`@tanstack/react-query` is required at runtime — `<QueryClientProvider>` must wrap `<SodaxWalletProvider>`. v1 mounted one internally; v2 does not.
|
|
154
168
|
|
|
@@ -28,7 +28,7 @@ EVM is the only family with multiple networks under one connection — wagmi mai
|
|
|
28
28
|
|
|
29
29
|
| Slot | Config fields | Notes |
|
|
30
30
|
|---|---|---|
|
|
31
|
-
| `EVM` | `ssr?, reconnectOnMount?, initialState?, walletConnect?, connectors?, chains` | `chains` keyed by `ChainKey` → `{ rpcUrl?, defaults? }` |
|
|
31
|
+
| `EVM` | `ssr?, reconnectOnMount?, initialState?, persistKey?, walletConnect?, privy?, connectors?, chains` | `chains` keyed by `ChainKey` → `{ rpcUrl?, defaults? }` |
|
|
32
32
|
| `SOLANA` | `autoConnect?, connectors?, chains` | `chains` keyed by `ChainKey` → `{ rpcUrl?, defaults? }` |
|
|
33
33
|
| `SUI` | `network?, connectors?, chains?` | `network: 'mainnet' \| 'testnet'` |
|
|
34
34
|
| `BITCOIN` | extends `BitcoinRpcConfig` + `{ defaults?, connectors? }` | Pass `{}` for SDK defaults |
|
|
@@ -44,6 +44,6 @@ If you are letting a coding agent drive the migration, point it at [`ai-rules.md
|
|
|
44
44
|
|
|
45
45
|
## Getting help
|
|
46
46
|
|
|
47
|
-
If you hit a v1 pattern not covered in `reference/` or `recipes/`, please [open an issue](https://github.com/
|
|
47
|
+
If you hit a v1 pattern not covered in `reference/` or `recipes/`, please [open an issue](https://github.com/gosodax/sodax-sdks/issues) with the v1 code snippet — we'll add it to the docs.
|
|
48
48
|
|
|
49
49
|
For internal SODAX maintainers: see `../CLAUDE.md` for architecture context.
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: sodax-wallet-sdk-react-privy
|
|
3
|
+
description: 'Granular skill for @sodax/wallet-sdk-react v2 email login with Privy only — the privy field on the EVM slot of SodaxWalletConfig, built with privy() from the @sodax/wallet-sdk-react/privy sub-path, which adds an "Email (Privy)" embedded wallet next to MetaMask and WalletConnect. Use when a React dapp wants email onboarding on EVM — e.g. "add email login", "log in with email", "Privy", "embedded wallet", "email wallet", "Privy app id". INTEGRATION only: email login is new in v2, so there is no v1 setup to port. Links into the parent sodax-wallet-sdk-react knowledge tree. EVM only; for the connect UI itself use the connect / wallet-modal skills.'
|
|
4
|
+
license: MIT
|
|
5
|
+
metadata:
|
|
6
|
+
version: '0.0.1'
|
|
7
|
+
author: sodax
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Email login with Privy (`wallet-sdk-react` granular skill)
|
|
11
|
+
|
|
12
|
+
Granular skill for the `privy` field on the `EVM` slot of `SodaxWalletConfig`. Source-of-truth reference lives in the parent broad skill's knowledge tree; this file is the focused workflow only.
|
|
13
|
+
|
|
14
|
+
## Step 1 — Clarify with user before coding
|
|
15
|
+
|
|
16
|
+
You write the code; the user owns the Privy app and receives the email code. Ask:
|
|
17
|
+
|
|
18
|
+
1. **Do they have a Privy App ID?** If not, give them the dashboard checklist in step 0 of the recipe (Email login, Ethereum embedded wallets, allowed origins, test accounts).
|
|
19
|
+
2. **Do they accept the trade-offs?** Privy custodies access (no signing while it is down), addresses belong to their Privy app, a lost email is a lost wallet, and the app is billed per signature.
|
|
20
|
+
3. **`showWalletUIs` and `disconnectBehavior`?** Both change the UX; the recipe's step 0 explains each choice.
|
|
21
|
+
4. **Does the app already mount a `PrivyProvider`?** Then follow the recipe's *App already on Privy?* branch.
|
|
22
|
+
|
|
23
|
+
## Integration workflow (new v2 code)
|
|
24
|
+
|
|
25
|
+
1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md) — DO / DON'T (read first).
|
|
26
|
+
2. [`../integration/knowledge/recipes/setup.md`](../integration/knowledge/recipes/setup.md) — prerequisite: provider mounted with the `EVM` slot.
|
|
27
|
+
3. [`../integration/knowledge/recipes/privy-email-login.md`](../integration/knowledge/recipes/privy-email-login.md) — install the peer, add `privy: privy({ appId })`, verify. Whole-file starter: [`../integration/knowledge/examples/05-privy-email-login.tsx`](../integration/knowledge/examples/05-privy-email-login.tsx).
|
|
28
|
+
4. Lookups → [`../integration/knowledge/reference/api-surface.md`](../integration/knowledge/reference/api-surface.md) (`privy`, `PrivyOptions`, `PRIVY_CONNECTOR_ID`).
|
|
29
|
+
|
|
30
|
+
### Privy-specific anti-patterns
|
|
31
|
+
|
|
32
|
+
- **Writing `privy: { appId }` or importing `privy` from the main entry.** The value must come from `privy()` on the `@sodax/wallet-sdk-react/privy` sub-path.
|
|
33
|
+
- **Hiding the App ID behind a backend.** It is public; only SODAX API keys need a proxy.
|
|
34
|
+
- **Adding `@privy-io/wagmi` or a second `PrivyProvider`.** The SDK mounts Privy itself.
|
|
35
|
+
- Full list → the recipe's *Anti-patterns*.
|
|
36
|
+
|
|
37
|
+
## Migration workflow (port v1 → v2)
|
|
38
|
+
|
|
39
|
+
None: email login is new in v2. Finish the broad skill's migration first, then add Privy with the integration workflow above.
|
|
40
|
+
|
|
41
|
+
## Verification
|
|
42
|
+
|
|
43
|
+
1. `pnpm tsc --noEmit` and the production build pass.
|
|
44
|
+
2. `privy: privy({ appId })` sits on the `EVM` slot, imported from `@sodax/wallet-sdk-react/privy`.
|
|
45
|
+
3. The user confirms what you cannot test (the email code): "Email (Privy)" appears, a test-account login shows an address that survives a reload, and a small SODAX action signs.
|
|
46
|
+
|
|
47
|
+
## Related skills (same family)
|
|
48
|
+
|
|
49
|
+
- [`../wallet-modal/SKILL.md`](../wallet-modal/SKILL.md) — a custom modal renders nothing while Privy's own dialog is open.
|
|
50
|
+
- [`../connect/SKILL.md`](../connect/SKILL.md) — the connect button / connector discovery hooks.
|
|
51
|
+
- [`../walletconnect/SKILL.md`](../walletconnect/SKILL.md) — the other optional EVM wallet source.
|
|
52
|
+
|
|
53
|
+
For multi-feature work, load the broad [`sodax-wallet-sdk-react` skill](../SKILL.md).
|
|
@@ -50,5 +50,6 @@ Granular skill for the headless multi-chain modal + connection-flow + batch hook
|
|
|
50
50
|
|
|
51
51
|
- [`../connect/SKILL.md`](../connect/SKILL.md) — a plain connect/disconnect button + account reads (no modal).
|
|
52
52
|
- [`../walletconnect/SKILL.md`](../walletconnect/SKILL.md) — add Fireblocks / Ledger / mobile wallets to the modal.
|
|
53
|
+
- [`../privy/SKILL.md`](../privy/SKILL.md) — add "Email (Privy)"; render nothing while Privy's own dialog is open.
|
|
53
54
|
|
|
54
55
|
For multi-feature work, load the broad [`sodax-wallet-sdk-react` skill](../SKILL.md).
|