[Writer] Add Privy signer migration guides (React + JWT auth)#1230
[Writer] Add Privy signer migration guides (React + JWT auth)#1230avarobinson merged 14 commits intomainfrom
Conversation
🔗 Preview Mode
|
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 0fe1f72171
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
🔍 Link CheckStatus: ❌ Failed Summary
Broken links (19) — click to expandErrors per inputErrors in ./content/wallets/wallet-integrations/privy/signer-migration-overview.mdx
Errors in ./content/wallets/wallet-integrations/privy/react-migration.mdx
Errors in ./content/wallets/wallet-integrations/privy/jwt-auth-migration.mdx
Errors in ./content/api-reference/arbitrum-nova/arbitrum-nova-deprecation-notice.mdx
|
|
|
||
| ### 5a. Integrate Privy auth (server-side) | ||
|
|
||
| When selecting "Server side" in the Privy dashboard JWT configuration (Step 2a), Privy accepts JWTs directly from your backend. Your server exchanges the user's JWT for a Privy session via the REST API. |
There was a problem hiding this comment.
what's the reasoning behind recommending that? I thought it was to do it more securely (end to end encrypted), but it seems like this is just recommending they take 'custody' of the private key to migrate it themselves?
There was a problem hiding this comment.
Fair point — the original framing made it sound like server-side was the 'more secure' path, which isn't accurate since it does mean your server briefly holds the plaintext key. Reworked the section to be explicit: use the client-side path by default, only reach for server-side if you have a specific reason to do the import from the backend (e.g. attaching policies/owners at import time). Also replaced 'Server-side path' with 'Server-side path (import only)' in the heading so readers can't miss the scope.
| const user = await getUserFromDB(userId); | ||
|
|
||
| if (!user.signer_migrated) { | ||
| // 1. Export private key from Alchemy (Follow the steps from 4c) |
There was a problem hiding this comment.
step 4c is for the client. as far as I'm aware we have no customers authenticating a JWT signer on the backend and we do not support this
There was a problem hiding this comment.
This was the big one — thanks for catching it. Rewrote the whole server-side section to reflect that AlchemyWebSigner + JWT auth is browser-only and we don't support a backend Alchemy JWT signer auth. New flow: 1) client authenticates with Alchemy and calls exportPrivateKeyEncrypted against a public key your server owns, 2) client POSTs the ciphertext to your server, 3) server decrypts and calls privy.wallets().import(...). Added a at the top of the section making this explicit, and updated the 'Security considerations' section to match.
…options, clarify server-side JWT path - react-migration: drop cookieToInitialState references; switch to createOnLogin "off" during migration (removes custom wallet creation plugin) - react-migration: remove unnecessary 'Function, not hook' distinction and cookieToInitialState row from hook mapping - react-migration: move Info callout with deeper links below the bullet list - react-migration: passkey migration supports anonymous too - react-migration: use mode: 'redirect' (popup was never effective) - react-migration: load Alchemy API key from env var + add security Warning - react-migration: drop skipOrgVerification prop from the docs - react-migration: update FAQ to match simplified provider setup - jwt-auth-migration: explain new-user flow when createOnLogin is 'off' - jwt-auth-migration: fold redundant 4c 'Authenticate with Alchemy' into 4b; renumber subsequent steps - jwt-auth-migration: reframe server-side path as import-only (Alchemy JWT signer auth is client-only/unsupported on backend); show client export -> encrypted handoff -> server import
| |---|---| | ||
| | `useSignerStatus().isConnected` | `usePrivy().authenticated` | | ||
| | `useAuthModal().openAuthModal()` | `usePrivy().login()` | | ||
| | `useLogout()` | `usePrivy().logout` | |
There was a problem hiding this comment.
| | `useLogout()` | `usePrivy().logout` | | |
| | `useLogout()` | `usePrivy().logout()` | |
consistency
There was a problem hiding this comment.
Fixed: Added the parens — usePrivy().logout() now matches the other rows in the table. Commit: 3d7b2b2
| Wire Privy wallets to Alchemy's transaction infrastructure so gasless transactions, batching, and all your existing flows work again. This uses Alchemy SDK v5 with Wallet APIs. | ||
|
|
||
| * The client defaults to EIP-7702, which delegates the Privy wallet to a smart wallet at send time. | ||
| * If you were previously using ERC-4337 (with assets directly in smart accounts), see the EIP-7702 guide for non-7702 mode. You'll need to add an additional call to `wallet_requestAccount` before sending. |
There was a problem hiding this comment.
we should actually link to non-7702 guide here
There was a problem hiding this comment.
Fixed: Replaced the generic "EIP-7702 guide for non-7702 mode" link with a direct link to the non-7702 mode section: /wallets/transactions/using-eip-7702#how-to-use-non-7702-mode. Commit: 3d7b2b2
| ); | ||
| ``` | ||
|
|
||
| <Warning>Never commit your Alchemy API key to source control. Load it from an environment variable (for example `NEXT_PUBLIC_ALCHEMY_API_KEY` in Next.js) and restrict the key to the correct apps, networks, and origins from the [Alchemy Dashboard](https://dashboard.alchemy.com/).</Warning> |
There was a problem hiding this comment.
technically it's best for the api key to be secured on the backend
There was a problem hiding this comment.
Fixed: Strengthened the Warning — it now explicitly notes that for production apps the best practice is to keep the API key on the backend and proxy Alchemy requests through it rather than exposing it in the client bundle at all. Commit: 3d7b2b2
- Retitle React guide to clarify signer-only migration - Move Prerequisites to top of guide - Add React-only callout in intro - Condense Privy dashboard setup steps (remove redundant step, use current nav naming) - Fix usePrivy().logout() -> add parens for consistency - Link non-7702 mode guide directly (with anchor) - Note that chain can be any viem chain - Split migration SDK install so @account-kit/react/infra only install when not already present - Combine @account-kit/infra imports onto one line - Strengthen API key warning: recommend backend proxy for production - Polish Step 4 intro wording - Remove duplicate 'Redeploy app' step from cutover sequence - Use 'each wallet independently' instead of 'each chain independently' in FAQ - Link specific Privy JWT setup page in jwt-auth-migration.mdx
| ### 3a. Install | ||
|
|
||
| ```bash | ||
| npm install @privy-io/alchemy-migration @account-kit/react @account-kit/infra |
There was a problem hiding this comment.
Remove the note to install @account-kit/react. We only need to install the migration pakage.
- Revert provider setup to original implementation: restore custom wallet creation plugin with createOnLogin set to 'users-without-wallets' (comment 3118799901). - Clarify Step 2c chain note: import chain(s) from viem/chains, ensure the chain is enabled on your Alchemy app, and confirm it supports Gas Manager sponsorship (comment 3118681754). - Remove the note about installing @account-kit/react and @account-kit/infra in Step 3a. The migration SDK is the only required install (comment 3118815590).
|
Thanks for the review, @avarobinson! Addressed all three in feee767 on
Ready for another pass when you have a minute. |
Top-level migration landing page that sits above the React and JWT migration guides. Covers: - What migration looks like for developers and end users - Prerequisites (Alchemy keys + policy, Privy app, current auth setup) - Edge cases: EIP-7702 vs. pure ERC-4337 (requestAccount + sma-b), non-MAv2 account types (stay on @account-kit/smart-contracts), legacy session keys on Wallet APIs - High-level end-to-end flow linking to the React and JWT sub-guides Adds the new page to content/docs.yml as the first entry in the Privy section so developers land here before drilling into the sub-guides.
|
|
||
| See the [Use existing session keys](/wallets/reference/wallet-apis-session-keys/legacy-session-keys) reference for the full guide. | ||
|
|
||
| ## What to expect — end-to-end flow |
There was a problem hiding this comment.
Move the what to expect above the edge cases and above prereqs
There was a problem hiding this comment.
Consolidate this with the earlier for developers flow to keep it short
There was a problem hiding this comment.
Done in 33ef77f. Consolidated What-to-expect with the former "For developers" overview into a single short block so the page doesn't repeat itself.
There was a problem hiding this comment.
Done in 6f9cb80. Added the same <Note> directly under the Info callout on the JWT guide, mirroring the React guide's wording and pointing to the overview's Edge cases section.
| * **No seed phrases, no manual steps.** The migration SDK (React) or your JWT handoff runs invisibly on the user's first login after the switch. | ||
| * **Users sign in once with their original method** (email OTP, Google, passkey, etc.) to authorize the key transfer, then continue as usual. | ||
|
|
||
| ## Prerequisites |
There was a problem hiding this comment.
Part of the prereqs should be users confirming which type of migration they need and which edge cases apply - e.g. confirm using 7702 or 4337, confirm correct account type, find migration guide.
There was a problem hiding this comment.
Done in 6f9cb80. Added a third bullet in Step 2 alongside the 7702/4337 bullets: if the app uses a smart account other than MAv2 (Light Account, MAv1, Simple Account, custom), stop here and stay on the lower-level SDK. Links to the overview's account-type edge case and the choosing-a-smart-account reference.
|
|
||
| 1. **Call `requestAccount` before `prepareCalls` / `sendCalls`.** Pass `creationHint: { accountType: "sma-b" }` to create (or look up) the dedicated smart contract account for your signer. If you previously used this owner in 7702 mode, the `creationHint` is required so a separate smart wallet is created for that owner. | ||
| 2. **Pass the returned account address as `account` on `sendCalls`** (or as `from` on the `wallet_prepareCalls` JSON-RPC request). If you skip this, the Wallet APIs fall back to 7702 mode against the signer address. | ||
| 3. **Cache and reuse the returned address.** The smart contract account address is stable for a given signer — you don't need to call `requestAccount` before every transaction. Storing it alongside your user record keeps the first-send latency low. |
There was a problem hiding this comment.
Remove step 3 and 4 here - keep it lightweight.
There was a problem hiding this comment.
Done in 6f9cb80. Added a <Note> directly under the existing Info callout pointing to the signer migration overview so devs confirm account type (MAv2) and connection type (7702 vs 4337) before starting.
|
|
||
| ### Account type — non-MAv2 users | ||
|
|
||
| Wallet APIs only support Modular Account v2 (as the 7702 delegation target and as the `sma-b` smart contract account). If your current app uses a different smart account implementation, you can't drop onto Wallet APIs as-is — you need to stay on the lower-level SDK for those users. |
There was a problem hiding this comment.
| Wallet APIs only support Modular Account v2 (as the 7702 delegation target and as the `sma-b` smart contract account). If your current app uses a different smart account implementation, you can't drop onto Wallet APIs as-is — you need to stay on the lower-level SDK for those users. | |
| Wallet APIs only support Modular Account v2. If your current app already uses a different smart account implementation, you need to stay on the lower-level SDK for those users. |
There was a problem hiding this comment.
Done in 33ef77f. The old 5-step detailed Steps block was stripped down to a short 2-step summary pointing devs to the sub-guides for the actual code — nothing in the overview is copy-pasteable anymore.
| 2. **Do not move sending to `@alchemy/wallet-apis`** for users whose existing accounts aren't MAv2. Instead, continue using `@account-kit/smart-contracts` with the client that matches your account type — for example, [`createLightAccountAlchemyClient`](/wallets/smart-contracts/other-accounts/light-account/getting-started) for Light Account or [`createModularAccountV2Client`](/wallets/smart-contracts/modular-account-v2/overview) for MAv2. Pass the Privy-backed `LocalAccount` as the `signer`. | ||
| 3. **New users can start on MAv2.** If you want new sign-ups to land on MAv2 + Wallet APIs, branch in your app so only legacy users hit the account-kit client path, and everyone else goes through `@alchemy/wallet-apis`. | ||
|
|
||
| See [Choosing a smart account](/wallets/smart-contracts/choosing-a-smart-account) for the account implementations available in the lower-level SDK. |
There was a problem hiding this comment.
| See [Choosing a smart account](/wallets/smart-contracts/choosing-a-smart-account) for the account implementations available in the lower-level SDK. |
There was a problem hiding this comment.
Done in 33ef77f. Session keys section is now a single sentence + link to the legacy session keys reference. Dropped the requirements list.
|
|
||
| See [Choosing a smart account](/wallets/smart-contracts/choosing-a-smart-account) for the account implementations available in the lower-level SDK. | ||
|
|
||
| ### Session keys |
There was a problem hiding this comment.
Keep this section short - dont list requirements. Just link to the guide for using legacy session keys
There was a problem hiding this comment.
Done in 33ef77f. The trailing "See [Choosing a smart account]…" line was removed as part of the non-MAv2 section simplification.
|
|
||
| ## What to expect — end-to-end flow | ||
|
|
||
| At a high level, every migration follows the same shape. The sub-guides fill in each step. |
There was a problem hiding this comment.
keep this overview simple so developers don't try to implement things listed
There was a problem hiding this comment.
Done in 33ef77f. Non-MAv2 edge case now reads exactly: "Wallet APIs only support Modular Account v2. If your current app already uses a different smart account implementation, you need to stay on the lower-level SDK for those users." Dropped the long migration-path bullet list.
|
|
||
| ## What migration looks like | ||
|
|
||
| ### For developers |
There was a problem hiding this comment.
Default the overview to explain the react package path (don't note JWT in each step). JWT auth should be a special/edge case.
There was a problem hiding this comment.
Done in 33ef77f. First prereq is now "Confirm your migration path" with a checklist (7702 vs 4337, MAv2 vs other, React vs JWT guide) pointing to the Edge cases section below so devs self-identify their path before starting.
| Wire Privy wallets to Alchemy's transaction infrastructure so gasless transactions, batching, and all your existing flows work again. This uses Alchemy SDK v5 with Wallet APIs. | ||
|
|
||
| * The client defaults to EIP-7702, which delegates the Privy wallet to a smart wallet at send time. | ||
| * If you were previously using ERC-4337 (with assets directly in smart accounts), see the [non-7702 mode guide](/wallets/transactions/using-eip-7702#how-to-use-non-7702-mode). You'll need to add an additional call to `wallet_requestAccount` before sending. |
There was a problem hiding this comment.
Add a note here to continue to use low level SDK if you're not using MAv2 or different account type as well
There was a problem hiding this comment.
Done in 33ef77f. The overview now defaults to the React path in the intro callout (labeled "the default path"), and JWT is called out as a special case. The What-to-expect steps describe only the React packages; JWT is referenced only via a pointer to the JWT sub-guide.
|
|
||
| This guide is for developers who authenticate users with Alchemy Signer using **JWT (JSON Web Token) authentication** and need to migrate to Privy. | ||
|
|
||
| <Info>If you use standard auth methods (email, Google, passkeys) with the React SDK, use the [React migration guide](/wallets/wallet-integrations/privy/react-migration) instead.</Info> |
There was a problem hiding this comment.
Also we should add notes to the top of each migration guide that points to the overview so developers ensure they are using the correct account type and connection to avoid problems
There was a problem hiding this comment.
Done in 33ef77f. Merged the old "For developers" flow into a single short What-to-expect section with a 2-step summary (auth swap + key migration). No more duplication.
|
|
||
| After completing this migration, users will log in with Privy (wallet addresses are preserved, assets are maintained) and transactions will continue to be sent and sponsored by Alchemy. | ||
|
|
||
| <Info>This guide is for **React** apps. For non-React frameworks, [reach out](mailto:support@alchemy.com) for support. If you authenticate users with JWT (JSON Web Token) authentication instead of standard auth methods, use the [JWT auth migration guide](/wallets/wallet-integrations/privy/jwt-auth-migration) instead.</Info> |
There was a problem hiding this comment.
Also we should add notes to the top of each migration guide that points to th overview so developers ensure they are using the correct account type and connection to avoid problems
There was a problem hiding this comment.
Done in 33ef77f. New section order is: intro callout → What to expect → Prerequisites → Edge cases.
- Reorder: intro → What to expect → Prerequisites → Edge cases - Consolidate dev flow + What to expect into one short 2-step summary - Default to React path; JWT referenced as special case only - Prerequisites now include a 'confirm your setup' checklist - Shorten non-MAv2 edge case to brief language - Strip implementation-level detail from the overview Steps so devs follow the sub-guides - Trim session keys section to one sentence + link
- React + JWT guides now point to the overview so devs confirm account type (MAv2) and connection type (7702 vs 4337) before starting - React guide adds a bullet in Step 2 telling non-MAv2 users to stay on the lower-level SDK
Existing @account-kit/react users may not realize 7702 is only the default in the new @alchemy/wallet-apis package. Reframe the overview so migrating users understand the default changed between SDK versions. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
5 participants
Adds 2 new documentation pages under the Wallets > Privy section for signer migration:
content/wallets/wallet-integrations/privy/react-migration.mdx): Step-by-step guide to migrate embedded wallets from Alchemy Account Kit to Privy using the React migration SDKcontent/wallets/wallet-integrations/privy/jwt-auth-migration.mdx): Guide for developers using JWT authentication, covering both client-side and server-side migration pathsBoth pages are added to the nav under a new 'Signer migration' group within the Privy section.
Linear: DOCS-42