Sui Wallet Services - High-Level Guide

Provide a great user experience by choosing the right wallet for your use case.

What's Included?

This guide provides a high-level summary of the benefits of integrating Shinami's Wallet Services into your application. To help you choose the right wallet for your needs, we summarize the similarities and key differences between our app-controlled Invisible Wallets and user-controlled zkLogin wallets. We also show you an image of a transaction flow for each kind of wallet so you can better understand what an integration entails. Finally, we share the developer resources we have for getting up and running with both kinds of wallets.

Shinami Invisible Wallets and zkLogin wallets are on-ramps for Web2 users

Shinami Invisible Wallets and zkLogin wallets both abstract away private key management and signing popups for users. They offer a convenient, on-chain way to store the assets a user obtains through interacting with your app (for example, an NFT representing an in-game character). Additionally, they both pair easily with Shinami Gas Station, which helps you pay the small fees for your users' transactions to mint these assets. This means your users don't have the friction of completing KYC to buy SUI, which can lead Web2-native users to abandon your app.

By comparison, a connected, self-custody wallet - e.g. a connected browser wallet - means users must approve each transaction. This means they don't need to place a lot of trust in the apps they interact with. These wallets are also portable across apps, so that a user can have one address to interact with all the apps they use if desired. However, these wallets require Web3 familiarity that most Web2 users don't have. They require users to manage their private keys through seed-phrases. They also present friction that interrupts a user's engagement with your app, like signing popups.

Invisible Wallets and zkLogin wallets, therefore, offer an on-ramp for Web2-native users onto Web3 applications. They offer ownership that lacks the full user-control of connected, self-custody wallets. In exchange, they allow you to provide the great user experience that Web2 users expect. As users get more comfortable with Web3, you can graduate their assets to full self-custody wallets they control if desired.

Differences between Shinami Invisible Wallets and zkLogin wallets

Below, we have summarized the key differences between the two types of wallets.

Comparison pointShinami Invisible WalletzkLogin Wallet
End-user ownershipUsers have less ownership. That said, in both cases your can offer the user an option to transfer something in their wallet to a self-custody wallet as they gain more Web3 knowledge. Or, you can allow them to list it in an in-app marketplace, etc.Users have more ownership since signing transactions requires a valid JWT obtained from their OAuth login flow (i.e. they have to sign in to Google, etc, first). That said, the user is almost always unaware of the salt and so cannot perform a transaction from the wallet on their own.
User authenticationWorks with your app's existing login flowRequires your app to integrate with one of the supported OpenID providers
User wallet authentication session lengthDetermined by your app's existing logic.Determined by the maxEpoch value you set when initiating the user's OAuth login flow. When the current Sui epoch value surpasses this epoch, you'll need to generate a new ephemeral KeyPair and initiate a new OAuth login flow for the user.
Transaction latencyFastFast, but typically requires an extra backend to frontend roundtrip for obtaining a signature. The signature is obtained quickly, without input from the user.
Integration points requiredBackendFrontend for signing at a minimum, with backend recommended for calling endpoints to generate a zkProof, and to generate, sponsor, and execute each transaction.
What's required for a signature?A (walletId, secret) pair your app manages, along with a salt managed by Shinami.An ephemeral KeyPair generated on your frontend, a valid JWT returned by the user's OAuth login flow that incorporates a nonce generated with the KeyPair, a salt managed by a salt provider such as Shinami, and finally a zkProof attesting the above from a prover such as Shinami. See the full flow here.

Transaction Flow Diagrams

App-controlled Invisible Wallets

Steps of the transaction flow

  1. The user defeats a boss and earns the right to upgrade their hero's stats. They decide how to upgrade them and click "Upgrade."
  2. Your app backend constructs the transaction that will upgrade the user's hero as they chose. It does not contain gas payment information yet.
  3. Your app backend sends one request to Shinami, which conveniently does all of the following:
  4. Sponsor the transaction's gas fee using your Gas Station fund.
  5. Sign the transaction using the Invisible Wallet for the user.
  6. Submit the transaction to the Sui blockchain using Shinami Node Service to update the player's hero NFT.

User-controlled zkLogin Wallets

Steps of the transaction flow

Before the transaction flow, your app previously asked for a zkProof when the user completes their OAuth login flow. This is shown in the box titled "Previously."

Transaction flow steps:

  1. The user defeats a boss and earns the right to upgrade their hero's stats. They decide how to upgrade them and click "Upgrade."
  2. Your app backend constructs a transaction that will upgrade the user's hero as they chose. It does not contain gas payment information yet.
  3. You app backend sends a request to Shinami's Gas Station to sponsor the transaction and generate a sponsor signature.
  4. Your app backend sends a request to the frontend to obtain a signature for the transaction using the user's ephemeral KeyPair.
  5. Your app backend assembles the zkLogin signature for the transaction using the ephemeral KeyPair signature from the frontend and the zkLogin proof you previously obtained for the KeyPair when the user last went through an OAuth login flow.
  6. Your app backend sends a request to Shinami Node Service to execute the transaction to update the player's hero NFT.

Developer resources

App-controlled Invisible Wallets

User-controlled zkLogin wallets