Wallets
Explore the possibilities Web3 Wallets management in HyperID.
HyperID allows users to Sign-Up and Sign-in using Web3 wallets. Additionally, users can link an arbitrary number of wallets to their accounts, allowing dApps to perform cross-chain operations with these wallets. To connect them, HyperID uses several external providers such as , WalletConnect and Phantom, along with an integrated non-custodial wallet called CyberWallet (MPC based).
When creating an account for a user, HyperID automatically generates one CyberWallet instance for them. This allows dApps to seamlessly integrate users even without Web3 wallets into their workflows which need a user wallet at start.
In general, the HyperID User Flow Modes for wallets, along with its array of options and REST APIs, enables dApps to streamline the integration of wallets into their processes, reducing the complexity of wallet-related business logic within their workflows.
Use cases
HyperID provides dApps with a comprehensive range of requests that address the typical needs of dApps' workflows. They gain the ability to request the user's Web3 wallet address for their workflow and its parameters, to create new web3 wallet or send a Web3 Transactions to the user's connected wallet.
The following are the main types of requests to retrieve web3 wallet in user's SSO session:
Get wallet with signing: This request allows the joining of a wallet to the current HyperID session with verification of the user's ownership of a private key through web3 signing. Typically, dApps utilize these requests to prepare a web3 session for sending transactions on the wallet. It can also be used to grant a user access to dApp's resources that are only available to the owner of a Web3 wallet.
Get wallet fast (without signing): Join a wallet to the current HyperID session without verifying the user's ownership of the crypto wallet's private key. Usually, dApps use these requests to obtain a valid wallet address from the user for checking wallet resources or sending resources on it.
Get last used wallet: This request enables a dApp to automatically retrieve the wallet that was previously used in the last HyperID session for the current application, without requiring manual selection by the user. If the user has not used any wallet for this dApp previously, it will initiate the 'Get wallet' request, which requires manual selection.
Create new wallet: This request creates a new web3 wallet (MPC-based) within the current HyperID account. Currently, it's limited to CyberWallet. In general, dApps use these requests to ensure the creation of a new wallet for their resources, which will be kept separate from the user's existing resources.
HyperID provides the result to the application, and if the request is successful, it maintains the session with the wallet. dApps can utilize this session to initiate transactions and it is always possible to request the user to select another wallet (similar to a 'change wallet' activity).
Additionally, HyperID provides "Wallets REST API" requests to obtain information about user wallets, set service-dependent tags, and more. These requests do not display a UI and do not require user actions, but they can be requested only if the user has previously granted these scopes to the service during authentication in any User Flow.
Integration
The service prompts the user to select, connect or create a Web3 wallet using the User Flow (see reference). The user tokens obtained as a result of completing the User Flow with specific mode and options contain updated information about the wallet.
The received tokens contain information about the connected or created wallet. For details about all the fields, please see the reference.
wallet_address: Web3 wallet address.wallet_family: Chain family (0 - EVM, 1 - Solana).wallet_chain_id: Chain number for EVM chains.wallet_source: Used external provider to connect the wallet.0 - WalletConnect.
1 - Metamask.
2 - Phantom.
3 - CyberWallet.
4 - CyberWallet default address.
is_wallet_verified: Indicates the user's ability to sign transactions with this web3 wallet and provides proof of the user's ownership of the wallet, not just the connection to the public address.1 - The user has the private key of this web3 wallet in the current web context.
0 - The user didn't sign the challenge, and they probably don't have the private key in the current web context.
You can also request the current information about the connected wallet through REST API requests using the tokens obtained in User Flow:
Request user information (see reference).
Token validation request, which additionally sends user information in the response (see reference).
Request to reissue refresh and access tokens using the current refresh token, with the new tokens containing the latest user information (see reference).
During the interaction with the service, the user connects wallets to their account through service User Flow requests and automatically grants access to their information (NOT the on-chain private key). The service can use "Wallets REST API" requests to retrieve the addresses and details of these wallets that have been approved for access by the user.
User Flow Modes
Unlike regular user authentication, these modes aim to obtain from the users the Web3 wallet address chosen by them for this service or even additionally acquire an active session for subsequent transactions/verification of ownership of this Web3 wallet.
The modes are configured by the options described below, which control the level of access, filtering, automatic selection, and so on. Each of these modes has default values for its options that shape the mode's purpose. In other words, intentional adjusting the options, you can bring the behavior of these modes closer to each other to a certain extent.
The default option for these modes is to connect a Web3 wallet without signing by the wallet's private key. Users only need to approve the requested session within the chosen external provider, avoiding the need for additional approval of the signing operation. However, this also means that the service can't be sure whether the user has the block-chain private key for this wallet, and it's possible that the user can't sign transactions on this device.
Typically, this mode is used more frequently because services often only require the user's wallet address to send something there in accordance with their internal business logic.
There are two main modes for authenticating a user and establishing a session with the user's wallet provider.
Wallet Authentication (3)
User authentication with the getting of a Web3 wallet in the shortest number of user steps.
flow_mode=3
Preferably used for signing the user into the service with obtaining their wallet address / wallet provider session. Not suitable for replacing the current wallet with another one in the current SSO session.
Workflow:
The User Flow checks for the presence of an active SSO session. If it doesn't exist, HyperID guides the user through the authentication steps.
If the user has authenticated in their account by connecting a Web3 wallet, that wallet's address will be set in the SSO session.
If there is an active SSO session and it has a connected wallet that is match the configured options, the flow will be completed immediately and HyperID will call the redirectURL with the authentication 'code'.
This means when an active SSO session with a connected wallet already exists in this web context, the service initiator will immediately receive the current web3 wallet address back.
The user will not go through the wallet selection interface at all.
If there is an active SSO session, but session does NOT have a connected wallet, the user will be directed to the wallet selection interface. After connecting a wallet using any of possible method, the user flow will update user's information with chosen web3 wallet and complete its operation by calling the service through the specified redirectURL.
Wallet Change (4)
User authentication if necessary and the mandatory manual selection of a Web3 wallet for this SSO session.
flow_mode=4
It's typically used when a user already has an active SSO session with a connected wallet in the current web context and needs to change the connected wallet to another one. It can be used for initial authentication instead of User Flow mode 3, but it's not recommended due to the mandatory extra step of web3 wallet selection.
Workflow:
The User Flow checks for the presence of an active SSO session. If it doesn't exist, HyperID guides the user through the authentication steps.
Whether there is a connected wallet or not, HyperID will take the user to the web3 wallet selection interface for the current active SSO session.
The user will choose a Web3 wallet from the existing options or connect a new one, or create a new wallet.
After connecting a wallet using any of possible method, the User Flow will update user's information with chosen web3 wallet and complete its operation by calling the service through the specified redirectURL.
User Flow Options
There are several options available to achieve specific behavior in User Flow Modes: Wallet Authentication (3), Wallet Change (4) and Upgrade Guest (6). Each of these options is preconfigured with default values and in some cases they will be just omitted if not applicable.
Options take precedence over each other and may not function if a higher priority option is present. Below, you'll find various combinations of options with different modes.
| Combination Name | Options Values |
|---|---|
| |
| |
| |
| |
| |
|
Create Or Retrieve CyberWallet
Automatically select the default CyberWallet within the user's account for the current SSO session, and if such a wallet does not exist in the account, the User Flow creates a new one.
Options:
| Option Name | Option Value |
|---|---|
wallet_get_mode | 0 |
cyber_wallet_create_mode | 0 |
Workflow:
User Flow checks for an active SSO session. If there is no session, HyperID guides the user through the authentication steps.
It checks for the presence of a CyberWallet Web3 wallet in the current account.
If the user already has a CyberWallet instance:
For modes 3, 4, & 6: User Flow automatically selects the wallet as active in the current SSO session.
For mode 6: User Flow guides the user through the upgrade steps.
If the user doesn't have a CyberWallet instance:
For modes 3, 4, & 6: User Flow automatically creates a new CyberWallet instance and selects the wallet as active in the current SSO session.
For mode 6: User Flow guides the user through the upgrade steps.
User Flow updates the user's information with the automatically chosen CyberWallet and completes its operation by calling the service through the specified redirectURL.
Create CyberWallet
User Flow automatically creates a new CyberWallet instance and selects this wallet within the user's account for the current SSO session. The presence of other CyberWallet instances doesn't matter.
Options:
| Option Name | Option Value |
|---|---|
wallet_get_mode | 0 |
cyber_wallet_create_mode | 1 |
Workflow:
User Flow checks for an active SSO session. If there is no session, HyperID guides the user through the authentication steps.
It creates new instance of CyberWallet and selects the wallet as active in the current SSO session.
For mode 6: User Flow guides the user through the upgrade steps.
User Flow updates the user's information with the automatically chosen CyberWallet and completes its operation by calling the service through the specified redirectURL.
Retrieve Last Used CyberWallet
User Flow selects the CyberWallet instance that was last used by the user in the requester service. If there is no existing CyberWallet instance, HyperID creates a new one. Then it automatically sets the chosen wallet within the user's account for the current SSO session.
Options:
| Option Name | Option Value |
|---|---|
wallet_get_mode | 1 |
Workflow:
User Flow checks for an active SSO session. If there is no session, HyperID guides the user through the authentication steps.
It automatically selects the CyberWallet instance in the following priority order, from high to low:
The last used CyberWallet instance for the current service.
A default CyberWallet in the user's account.
The last used CyberWallet for any other service.
Creates a new CyberWallet instance.
User Flow updates the user's information with the automatically chosen CyberWallet and completes its operation by calling the service through the specified redirectURL.
Retrieve Web3 Wallet (default combination without extra signing)
Requesting a Web3 wallet without confirming the presence of a chain private key. User Flow simply establishes a session with the external wallet provider or selects a CyberWallet instance. The type of selection, whether automatic or manual, depends on the mode being called (3, 4, or 6). It's default combination for User Flow modes.
This is typically used to obtain the address of a Web3 wallet without further Web3 transactions or providing access to sensitive data within the service.
Options:
| Option Name | Option Value |
|---|---|
wallet_get_mode | 2 |
Workflow:
User Flow checks for an active SSO session. If there is no session, HyperID guides the user through the authentication steps.
Manual or automatic selection of web3 wallet within the current user account, it depends on the used 'flow_mode'.
User Flow updates the user's information with the chosen web3 wallet and completes its operation by calling the service through the specified redirectURL.
Retrieve Verified Web3 Wallet (proof of key ownership)
Requesting a Web3 wallet with proof of chain private key ownership for this instance. User Flow establishes a session with the wallet provider and then sends an additional signing request. If the user selects the CyberWallet, no signing request is sent.
Whether 'flow_mode' is set to automatic (3) or manual (4) selection, if the current SSO session has an unverified selected Web3 wallet, User Flow will prompt the manual step of wallet selection. If the manually selected wallet is not a CyberWallet instance or is unverified through a signing request, User Flow will send an extra signing request to the external provider to prove ownership.
Options:
| Option Name | Option Value |
|---|---|
wallet_get_mode | 3 |
Workflow:
User Flow checks for an active SSO session. If there is no session, HyperID guides the user through the authentication steps.
It checks the presence and verification state of a Web3 wallet in the current SSO session. If there is no selected wallet or an unverified wallet is connected to the current session, then:
User Flow shows the step of manually selection a wallet.
If the user selects a non-verified wallet and it's not a CyberWallet instance, User Flow initiates a signature request to the user through the session with an external provider to prove ownership of the on-chain private key.
User Flow updates the user's information with the chosen verified web3 wallet and completes its operation by calling the service through the specified redirectURL.
Retrieve Last Used Wallet
Under construction.
REST API
Under construction.
Last updated
