Integrating Web3 wallets is a crucial step for any decentralized application (DApp) aiming to interact with blockchain networks. For developers working within ecosystems like Telegram, providing a seamless user experience is paramount. This guide focuses on utilizing a provided UI interface to connect wallets, sign transactions, and manage user sessions efficiently for Solana-compatible chains.
Getting Started with UI Integration
To begin the integration process, ensure your OKX App is updated to version 6.90.1 or later. The primary method for integrating the connection functionality into your DApp is through the npm package manager. This allows for a straightforward setup and initialization process.
Before initiating any wallet connection, you must first create a UI interface object. This object is essential for subsequent operations, such as connecting to a wallet, sending transactions, and managing user interactions. Proper initialization sets the foundation for a smooth user experience.
Initialization Parameters
When initializing the UI connector, several parameters must be configured to tailor the experience to your DApp's needs:
dappMetaData (object): This provides basic information about your application.
- name (string): The name of your DApp. Note that this is not used as a unique identifier.
- icon (string): A URL pointing to your application's icon. The image must be in a supported format like PNG or ICO (SVG is not supported). For best results, use a URL that points to a 180x180px PNG icon.
actionsConfiguration (object): This object controls the behavior of modal dialogs and return strategies.
- modals: Defines when reminder interfaces are shown during a transaction process. Options include
'before','success','error', an array of these values, or'all'. The default is'before'. - returnStrategy: Specifies the deep link return strategy for the app wallet after a user signs or rejects a request. For Telegram integrations, this can be configured to
tg://resolve. - tmaReturnUrl: Specifically for the Telegram Mini Wallet, this sets the return strategy after a user signs or rejects a request. Use
'back'to close the wallet and return to the DApp,'none'to take no action, or a custom deep link. The default is'back'.
- modals: Defines when reminder interfaces are shown during a transaction process. Options include
uiPreferences (object): This allows you to customize the look and feel of the interface.
- theme: Sets the visual theme. Options include
THEME.DARK,THEME.LIGHT, or"SYSTEM"to match the user's device settings. - language: Sets the interface language. Supported codes include
"en_US","zh_CN", and many others, with"en_US"set as the default.
- theme: Sets the visual theme. Options include
The initialization function returns an OKXUniversalConnectUI object, which is your main interface for all subsequent wallet operations.
Connecting to a Wallet
The core function of the UI is to connect a user's wallet to your DApp. This process retrieves the user's wallet address, which serves as a unique identifier and is necessary for signing transactions.
The connection request requires a connectParams object, which contains namespaces and chain information.
namespaces: This is essential information required for the connection. For Solana-compatible chains, the key must be
"solana". The connection will be rejected if the wallet does not support any of the chains listed in this required section.- chains: An array of chain IDs you wish to connect to.
- defaultChain (optional): Specifies a default chain from the list.
optionalNamespaces: This contains optional connection information. Again, use the
"solana"key for Solana-based chains. If the wallet does not support these optional chains, the connection can still be established successfully.- chains: An array of optional chain IDs.
- defaultChain (optional): Specifies a default chain from the optional list.
Upon a successful connection, the function returns a Promise containing a session object with detailed information, including a unique session topic, the connected namespaces, accounts, supported methods, and your DApp's metadata.
👉 Explore more connection strategies
Connecting and Signing in One Step
For a more integrated workflow, you can request to connect a wallet and sign a message simultaneously. The signature result is returned via a callback in a "connect_signResponse" event.
This method uses the same connectParams object detailed in the previous section. Additionally, it requires a signRequest parameter, which is an array containing a single request object (only one method is supported at a time for this combined operation).
- method: The name of the signing method to call. For Solana, this is typically
"solana_signMessage". - chainId: The ID of the chain where the signing method should be executed. This chain must be included in the
namespacesfrom theconnectParams. - params: The parameters required by the specific signing method.
The return value is identical to the standard connect function, providing the full session details upon success.
Checking Wallet Connection Status
You can check whether a wallet is currently connected to your DApp at any time. This is useful for updating your UI's state based on connection status—for example, to show a "Connect Wallet" button or a "Disconnect" button.
This function simply returns a boolean value (true or false), indicating the current connection state without providing any additional session details.
Preparing and Sending Transactions
To initiate transactions, you first create an OKXSolanaProvider object by passing your initialized OKXUniversalProviderUI object to its constructor. This provider object is then used to call various methods for signing and sending transactions. The behavior of modal dialogs during these operations is controlled by the actionsConfiguration.mode setting you defined during initialization.
Signing a Message
Requesting a signature is a common operation for verifying ownership of a wallet address.
Parameters:
- message (string): The message data that needs to be signed.
- chain (string): The chain ID on which the signature should be executed. This is recommended when multiple chains are connected and is mandatory in such cases.
Return Value: A Promise that resolves to an object containing:
publicKey: The wallet's public address.signature: The resulting signature as aUint8Array.
Signing a Single Transaction
This method is used to sign a single transaction object without immediately broadcasting it to the network.
Parameters:
- transaction: The transaction object to be signed (
TransactionorVersionedTransaction). - chain (string): The relevant chain ID.
- transaction: The transaction object to be signed (
- Return Value: A Promise that resolves to the signed transaction object.
Signing Multiple Transactions
This method allows you to sign an array of multiple transaction objects in a single request.
Parameters:
- transactions: An array of transaction objects (
TransactionorVersionedTransaction). - chain (string): The relevant chain ID.
- transactions: An array of transaction objects (
- Return Value: A Promise that resolves to an array of the signed transaction objects.
Signing and Broadcasting a Transaction
This is a convenient method to both sign a transaction and immediately broadcast it to the network for execution.
Parameters:
- transaction: The transaction object to be signed and sent.
- chain (string): The relevant chain ID.
- Return Value: A Promise that resolves to a string, which is the transaction hash (txid) of the broadcasted transaction.
Retrieving Wallet Account Information
You can fetch the connected wallet's account information for the specified chain.
Parameters:
- chain (string, optional): The chain ID for which to retrieve the wallet address. If omitted, the first connected SVM address is used by default.
Return Value: An object containing:
address: The wallet's address string.publicKey: The wallet's public key object.
Disconnecting a Wallet
It is good practice to provide users with the ability to disconnect their wallet from your DApp. This function terminates the current session and clears any associated data. If you need to switch connected wallets, you should always disconnect the current wallet first.
Handling Events and Errors
The UI integration emits various events throughout its lifecycle, such as session updates and response callbacks. These events allow you to react dynamically to changes in the connection state or user actions.
Similarly, operations may sometimes fail due to user rejection or other issues. The system provides a set of error codes to help diagnose and handle these failures gracefully. For a detailed list of specific events and error codes, please refer to the general documentation for EVM-compatible chains, as the principles and codes are shared across implementations.
Frequently Asked Questions
What is the minimum OKX App version required for this UI integration?
You need to ensure your OKX App is updated to version 6.90.1 or a later release to access all the necessary features for a seamless DApp integration and wallet connection process.
How do I customize the language and theme of the wallet connection interface?
During the initialization of the UI connector, you can set the language and theme properties within the uiPreferences object. This allows you to offer a localized and visually consistent experience for your users across different regions.
Can a user connect if their wallet doesn't support one of my DApp's required chains?
No, the connection will be rejected. The namespaces parameter defines mandatory chains. If a user's wallet does not support any chain in this list, the connection request will fail. Use the optionalNamespaces parameter for chains that are nice to have but not required.
What is the difference between 'returnStrategy' and 'tmaReturnUrl'?
The returnStrategy parameter applies to the standard app wallet and defines where the user is directed after an action. The tmaReturnUrl is specifically for the Telegram Mini App (TMA) environment and controls the return behavior within the Telegram client, such as closing the wallet and returning to the DApp.
What should I do if a transaction signing fails?
The integration will return a specific error code. Your DApp's frontend should be designed to catch these errors and handle them appropriately, such as by displaying a user-friendly message explaining the reason for the failure (e.g., user rejection, insufficient gas).
Is it possible to sign a message without first establishing a wallet connection?
The combined connectAndSign method allows you to request a connection and a signature in a single step. However, a session is still established as part of this process. For standalone signing, a connection must already be active.