zkLogin wallet Next.js Tutorial

How to build your first zkLogin app

Suggest Edits

Overview

This tutorial will help you build your first zkLogin app! We've created a sample project that makes it very easy to get started with our zkLogin wallet API.

The app uses Shinami Gas Station to sponsor transactions alongside Shinami's zkLogin wallet service. Sponsoring your users' transactions allows you to remove friction and create a smoother UX. This is especially useful for zkLogin wallets because when you create one for a user, the user will not have any SUI in the wallet to pay for gas.

The tutorial requires a Shinami account. If you don't have one, get started on our free tier today!

Steps

1. Create a Shinami Gas Station fund on testnet

See our Gas Station Guide for how to set up a fund on Testnet and add free Sui to it if you don't have one.

2. Create two Shinami API access keys

You'll need two Shinami API access keys: a Node Service Testnet key, and a Testnet access key with rights to all services. When you create a key with Node Service rights, you assign a max QPS and max number of WebSocket connections the key is allowed. You can change a key's values later by clicking on the + next to the key in Access Keys table to open the key editor. When you create an access key with Gas Station rights, you link it to a Gas Station fund. All requests for sponsorship using the key draw Sui from that fund. So, you'll link this key to the gas station Testnet fund you created in step one. Wallet Service keys are actually network agnostic as one key works across all networks. Here's an example setting up a key with Testnet rights to all services:

3. Set up a developer account with Twitch, Google, or Facebook

See information on how to set up a developer account with the OAuth providers currently supported here. Our example app currently supports a subset of what Mysten supports: Twitch, Google, and Facebook. For the example below, we've used Twitch.

The redirect URL to set up in the Twitch developer console is http://localhost:3000/auth/twitch. You'll also need to copy the Client ID value that Twitch provides as we proceed with the tutorial:

4. Download and configure the sample project

This project is located on github. You can use npm, Yarn, or pnpm to bootstrap the example:

npx create-next-app --example https://github.com/shinamicorp/shinami-typescript-sdk/tree/main/examples/nextjs-zklogin my-zklogin-app

yarn create next-app --example https://github.com/shinamicorp/shinami-typescript-sdk/tree/main/examples/nextjs-zklogin my-zklogin-app

pnpm create next-app --example https://github.com/shinamicorp/shinami-typescript-sdk/tree/main/examples/nextjs-zklogin my-zklogin-app

Next, you need to set up the local variables for the project. In the root directory of the project - my-zklogin-app unless you change the name - create a .env.local file (e.g. with > touch .env.local on the command line).

You'll need four pieces of information to fill in the file:

  1. Generate a session secret, e.g. with openssl rand -hex 32 on the command line. Example output is bdd51e3b307c7cdae48c3dd2ce83f5e7a0b6db10fdeea0b4d5990f857c156dd7 (but don't share your secrets!)
  2. The Client ID from your OAuth developer console. Using the Twitch example above, we have 2bc0920c90ufn0adomxlca3pldbdpo
  3. The Node service Testnet access key you created. Let's imagine it's sui_testnet_def456. This is too short for a real key. Also, do not expose your keys!
  4. The Testnet access key you created with rights to Node Service, Wallet Services, and Gas Station. Let's imagine it's sui_testnet_def456. Again: too short for a real key and keep your keys secret.

Open the file and fill in those values. We've included the address of a Move package we've deployed to testnet so that your sample project can interact with it, via the environmental variable EXAMPLE_MOVE_PACKAGE_ID.

# OAuth application configs. Configure the ones you want to support. They'll serve as both the auth
# mechanism for this app and transaction signing mechanism (zkLogin). Note that if you have multiple
# providers configured, the same person will be considered a different user for each provider they
# log in with (with different zkLogin wallets), even if they may share the same email.
#
# Refer to this link for instructions on setting up these OAuth applications:
# https://docs.sui.io/concepts/cryptography/zklogin#configure-a-developer-account-with-openid-provider
#
# NEXT_PUBLIC_GOOGLE_CLIENT_ID=''
# NEXT_PUBLIC_FACEBOOK_CLIENT_ID=''
NEXT_PUBLIC_TWITCH_CLIENT_ID='2bc0920c90ufn0adomxlca3pldbdpo'

# Example command to generate random secrets:
#   openssl rand -hex 32
#
IRON_SESSION_SECRET='95ff013906691ff55c43895c1542044ef48a492babcd06402a2e20f87ea422f3'

# Obtain your Shinami access keys from https://app.shinami.com.
# The example code uses Shinami node, gas station, and wallet services by default to provide the
# most seamless experience. However, you can also choose to use other providers by making some small
# adjustments.
#
SHINAMI_SUPER_ACCESS_KEY='sui_testnet_abc123'
NEXT_PUBLIC_SHINAMI_NODE_ACCESS_KEY='sui_testnet_def456'

# 'devnet', 'testnet', or 'mainnet'
NEXT_PUBLIC_SUI_NETWORK='testnet'

# This example package is deployed on testnet.
# Source code: https://github.com/shinamicorp/shinami-typescript-sdk/tree/main/move_example
EXAMPLE_MOVE_PACKAGE_ID='0xd8f042479dcb0028d868051bd53f0d3a41c600db7b14241674db1c2e60124975'

5. Run and interact with the app

Now, you can run the project! On the command line, run npm run dev . Then, visit http://localhost:3000 in your browser and you'll be greeted with prompt to sign in.

Click "Sign in", and you'll see your options. For this example we'll see the following for Twitch:

After clicking "Authorize" and waiting a few seconds for the request to complete, you should be successfully logged in and see:

Now, click "Sui calculator". You'll see:

When you enter values and click "Calculate on Sui", behind the scenes we're:

  1. Calling a function in the testnet move module denoted by EXAMPLE_MOVE_PACKAGE_ID in the .env.local file.
  2. Using the Shinami Gas Station testnet fund linked to the SHINAMI_SUPER_ACCESS_KEY you provided to sponsor the transaction.

Assuming you have sufficient funds, enter 1 + 2, click "Calculate on Sui" and wait a few seconds. During the processing, you'll see output like the following in the terminal window running the project: Preparing add tx for zkLogin wallet 0x6a7b07da9d2c210bbbe044dbe222225ae20dd4584a4d8ee9a804839f8256ea3c. Then, shortly thereafter, you'll see the result and the associated transaction digest (your digest will be different):

Clicking on the transaction digest link will take you to the transaction in the SuiVision explorer. As expected, this transaction digest will be listed for a brief time under the in-flight transactions of your gas station fund:

Finally, click the back button in your browser and then click on "My zkLogin wallet address":

It takes you to the SuiVision explorer and shows you the zkLogin wallet address that was created when you logged into Twitch. After clicking on the "Transaction Blocks" tab, we can see that the transaction digest above - which taught us that 1 + 2 = 3 ! - was sent by this address:

You've just successfully used a zkLogin app to create a zkLogin wallet and execute a sponsored transaction with it!

If you click "Sign out" in your localhost tab and then sign in via the same OAuth provider, you'll have the same zkLogin wallet address. Signing in with a different OAuth provider will create a different address (one per provider, see more info in our zkLogin wallet API doc).

Updated 7 days ago