Wallet Services
Provide a great user experience by choosing the right wallet for your use case.
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.
Updated 2 months ago