What's in this doc?

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.

Wallet Services overview

What is a wallet?

A wallet represents an address on a blockchain where a user stores things they own (SUI and other tokens, NFTs, etc). Each address has a private key - and for zkLogin wallets a mathematical proof - needed to authorize any action taken by that address. A wallet is the software that securely generates and stores private keys and zero-knowledge proofs and uses them to authorize (sign) actions the user wants to take with that address.

Wallets exist on a spectrum from a hardware wallet that the user has more secure control over but is a lot of a effort to manage and use, to an embedded wallet that the user has less control over but removes all of the friction.

Wallet Type	User Friction	User has the same wallet for multiple apps?	User has to manage their private key and complete signing popups for each transaction?
Connected hardware wallet (e.g. a Ledger wallet)	High	Yes	Yes
Connected browser extension or mobile app wallet (e.g. the Sui Wallet)	Medium	Yes	Yes
Embedded wallet (e.g. a Shinami Invisible Wallet or a zkLogin wallet)	None	No (one per app)	No

Why use an embedded wallet service? To have a frictionless UX.

A connected 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 Web2 users don't have. They require users to download a wallet app and manage their private keys through seed-phrases. They also present friction that interrupts a user's engagement with your app, like signing popups.

By comparison, Shinami Invisible Wallets and zkLogin wallets remove the user burden of private key management and disruptive signing popups. 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. This means your users don't have the friction of completing KYC to buy SUI and then sending it to their wallet, which can lead Web2-native users to abandon your app. Finally, these wallets are tied to your app, meaning a user cannot connect them to another app. This boundary goes both ways, though: another app can't mess with, say, an NFT you give a user.

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.

What is a wallet service?

A wallet service provides the infrastructure you need to

generate a new wallet for each of your users
sign the transactions that represent the actions taken by the user's wallet (e.g. leveling up their game NFT)
(typical, but not required) sponsor and execute those transactions

By using Shinami's Wallet Services, you can focus on building out your app and creating a great user experience. You just interact with our easy-to-use API and we take care of the rest!

Differences between Shinami Invisible Wallets and zkLogin wallets

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

Comparison point	Shinami Invisible Wallet	zkLogin Wallet
End-user ownership	Users 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 authentication	Works with your app's existing login flow. This could be username+password, SSO, magic link or one-time passcodes, no-auth sign-in, etc.	Users sign in with a social sign in provider like Google, Facebook, Twitch, or Apple. Requires your app to integrate with one of the supported OpenID providers
User wallet authentication session length	Determined 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 latency	Fast	Fast, 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 required	Backend	Frontend 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.

Why use Shinami?

Shinami is the leading developer infrastructure provider for the Sui ecosystem. We've been successfully supporting Sui builders since the early days of Sui Mainnet (see our case studies for examples of the success our customers have seen). For an overview of how we compare to Enoki (the main Shinami zkLogin wallet competitor), see our Shinami vs Enoki guide.

Transaction Flow Diagrams

App-controlled Invisible Wallets

Steps of the transaction flow

Before the transaction flow, your app previously created a unique, unchangeable (walletID, secret) pair tied to the user's id in your system and used it to create an Invisible Wallet for the user. This is shown in the box titled "Previously."

Transaction flow steps:

The user defeats a boss and earns the right to upgrade their hero's stats. They decide how to upgrade them and click "Upgrade."
Your app backend constructs the transaction that will upgrade the user's hero as they chose. It does not contain gas payment information yet.
Your app backend sends one request to Shinami, which conveniently does all of the following:
Sponsor the transaction's gas fee using your Gas Station fund.
Sign the transaction using the Invisible Wallet for the user.
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 completed their OAuth login flow. This is shown in the box titled "Previously."

Transaction flow steps:

The user defeats a boss and earns the right to upgrade their hero's stats. They decide how to upgrade them and click "Upgrade."
Your app backend constructs a transaction that will upgrade the user's hero as they chose. It does not contain gas payment information yet.
You app backend sends a request to Shinami's Gas Station to sponsor the transaction and generate a sponsor signature.
Your app backend sends a request to the frontend to obtain a signature for the transaction using the user's ephemeral KeyPair.
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.
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

For a look at the API, see our Invisible Wallet API.
For an end-to-end tutorial, see our Invisible Wallet TypeScript Tutorial.

User-controlled zkLogin wallets

For a look at the API, see our zkLogin wallet API.
For a template to get started creating your first zkLogin app, see our zkLogin wallet Next.js Tutorial.