NextJS V2 Migration Guide
A comprehensive guide for migrating your NextJS application from Okto SDK V1 to Okto SDK V2.
This guide provides a detailed walkthrough for migrating a NextJS application from Okto SDK V1 to Okto SDK V2.
Previously, a streamlined Okto NextJS-based setup was available; however, V2 introduces a traditional Create Next App setup. While the core functionality remains unchanged, V2 adopts a more decentralized architecture, enhancing security and providing comprehensive developer controls.
Key Changes Overview
Area | Changes |
---|---|
Architecture | Moved to a more decentralized system with smart contracts on the Okto chain |
Authentication | OAuth-first approach with session key implementation |
Wallet Management | Automated wallet creation across all enabled chains |
Package Structure | Migration to scoped packages under @okto_web3 namespace |
Migration Steps
Note
This guide assumes that you have already set up a fully functional NextJS dapp using Okto SDK V1.
1. Installing Dependencies
Okto SDK V2 adopts a scoped package structure under the @okto_web3
namespace, providing enhanced access control and enabling private package distribution when required. This approach aligns with modern best practices in package management, ensuring a more organized, and scalable package structure.
Previously, it was okto-sdk-react
; it has now been updated to:
2. Environment Configuration
In Okto V1, only one environment variable was needed: OKTO_CLIENT_API_KEY
. However, in V2, Okto has moved to a decentralized approach where even the client is a smart contract on the Okto chain.
Before you begin, make sure you have:
- Created an account on the Okto Developer Dashboard
- Obtain your API Key (
NEXT_PUBLIC_CLIENT_PRIVATE_KEY
andNEXT_PUBLIC_CLIENT_SWA
) - Enabled the chains and tokens your application will use
- Added your .env file to .gitignore
3. Configure Google Authentication
Note
Configure NextAuth with Google as the authentication provider. The implementation remains the same for both versions within the app/api/auth/[...nextauth]/route.ts
file.
4. OktoProvider Setup
In V1, the provider required OKTO_CLIENT_API_KEY
and buildType
as parameters. In V2, this approach has been simplified by consolidating all necessary values into a single config parameter. This config object now holds the client’s private key
, client SWA
, and environment
, making integration more streamlined and easier to manage.
5. Authentication Implementation
In V1, Okto supports multiple authentication methods, including Google-Auth (GAuth)
, email-OTP
, phone-OTP
, and JWT-custom-auth
. Upon successful authentication, Okto generates an AuthToken, which is used for delegated access.
In V2, Google Authentication (GAuth) is currently the only supported authentication method. Support for other methods, including email OTP, phone OTP, and JWT custom authentication, will be added soon.
- Using Google Authentication (Google OAuth); V2 continues to support direct authentication with Google OAuth, maintaining seamless integration with Google's trusted authentication infrastructure within the Okto React SDK.
Wallet Creation in V2
In V1, wallets had to be manually created using createWallet()
. In V2, after successful authentication:
- A session is created for the user and client, with a default validity of 7 days. However, this duration can be customized as needed
- Wallets are automatically retrieved for the user or created if none exist
- Users automatically have wallets in all enabled chains of the client
- A User SWA (Smart Wallet Address) is created/fetched on/from the Okto chain
- The current session is registered to the user's Smart Wallet Account (SWA).
In V1, the AuthToken was a combination of the user login method and the client API key, providing delegated access to the client. In V2, authentication results in a session key pair that is:
- Generated client-side and unique for each user login and client SWA.
- Acts as the authority for the User SWA within policy limits.
SDK Function Migration References
Explorer Functions
V1 Function | V2 Function | Changes |
---|---|---|
getWallets() | getAccount() | - Now returns enhanced wallet details - Includes network symbol and comprehensive chain data |
getSupportedNetworks() | getChains(oktoClient) | - Renamed for clarity - Retrieves the list of all blockchain networks supported by Okto |
getSupportedTokens() | getTokens(oktoClient) | - Returns supported token list |
getPortfolio() | getPortfolio(oktoClient) | - Now retrieves the user's aggregated portfolio data |
- | getPortfolioActivity(oktoClient) | - Get user's portfolio activity |
- | getPortfolioNFT(oktoClient) | - Get user's NFT portfolio |
- | getNftCollections(oktoClient) | - Retrieves NFT collection metadata |
orderHistory(query) getNftOrderDetails(query) getRawTransactionStatus(query) | getOrdersHistory(oktoClient, filters?) | - All order history functions are now combined into one - Retrieves order history for token transfers, NFT transfers, and raw transactions using filter parameters |
Intent Functions
All intents are available in both abstracted and detailed flows. In the detailed flow, intents can be converted into a user operation (UserOp), signed, and executed on the Okto chain as separate calls. In the abstracted flow, these three steps are combined into a single call for a more seamless experience.
V1 Function | V2 Function | Changes |
---|---|---|
transferTokens(data) | tokenTransfer(oktoClient, data) | - Switched to UserOp-based transfer model - Added transaction simulation - Improved gas optimization options |
transferNft(data) | nftTransfer(oktoClient, data) | - Converted to UserOp-based transfer model - Consolidated multiple NFT functions into one - Added chain compatibility checks |
executeRawTransaction() | evmRawTransaction(oktoClient, data) | - Now creates a UserOp for executing raw EVM transactions. |
V2 Functions
Function | Description |
---|---|
signUserOp(userop) | - Signs user operations - Validates operation parameters - Includes policy checks |
executeUserOp(userop) | - Executes signed operations - Handles transaction bundling |
Migration Support
For additional help: