NextJS V2 Migration Guide

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

Migration Steps

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:

npm install @okto_web3/react-sdk next-auth

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.

NEXT_PUBLIC_CLIENT_PRIVATE_KEY = YOUR_OKTO_CLIENT_PRIVATE_KEY
NEXT_PUBLIC_CLIENT_SWA = YOUR_OKTO_CLIENT_SWA
NEXT_PUBLIC_ENVIRONMENT = sandbox # or production
 
AUTH_SECRET = YOUR_AUTH_SECRET # Generate using: openssl rand -base64 32
 
# Google OAuth credentials (Required only if using Google Sign-In)
GOOGLE_CLIENT_SECRET = YOUR_GOOGLE_CLIENT_SECRET
GOOGLE_CLIENT_ID = YOUR_GOOGLE_CLIENT_ID

3. Configure Google Authentication

import NextAuth from "next-auth";
import GoogleProvider from "next-auth/providers/google";
import type { AuthOptions } from "next-auth";
 
export const authOptions: AuthOptions = {
  secret: process.env.AUTH_SECRET,
  providers: [
    GoogleProvider({ // Configure Google Provider
      clientId: process.env.GOOGLE_CLIENT_ID!, // From .env
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!, // From .env
    }),
  ],
  session: {
    strategy: "jwt",
  },
  callbacks: {
    async jwt({ token, user, account }) {
      if (account) {
        token.id_token = account.id_token;
      }
      return token;
    },
    async session({ session, token }) {
      //@ts-ignore
      session.id_token = token.id_token;
      return session;
    },
  },
};
 
const handler = NextAuth(authOptions);
 
export { handler as GET, handler as POST };

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.

"use client";
import { SessionProvider } from "next-auth/react";
import { Hex, Hash, OktoProvider } from "@okto_web3/react-sdk";
import React from "react";
 
type Env = 'sandbox' | 'production';
 
const config = {
    environment: (process.env.NEXT_PUBLIC_ENVIRONMENT || 'sandbox') as Env,
    clientPrivateKey: process.env.NEXT_PUBLIC_CLIENT_PRIVATE_KEY as Hash,
    clientSWA: process.env.NEXT_PUBLIC_CLIENT_SWA as Hex,
};
 
function AppProvider({ children, session }) {
return (
    <SessionProvider session={session}>
    <OktoProvider config={config}>
        {children}
    </OktoProvider>
    </SessionProvider>
);
}
 
export default AppProvider;

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.

// Using Google OAuth
async function handleGoogleLogin(credentialResponse: any) {
    try {
        const user = await oktoClient.loginUsingOAuth({
            idToken: credentialResponse.credential,
            provider: "google",
        });
        console.log("Login successful:", user);
    } catch (error) {
        console.error("Login failed:", error);
    }
}

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).

SDK Function Migration References

Explorer Functions

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.

V2 Functions