Integrating your decentralized application (DApp) with blockchain networks and user wallets is a fundamental step in creating a seamless Web3 experience. This guide provides a structured approach to connecting your application with Starknet and other compatible Web3 wallets, ensuring secure transactions and user interactions. Whether you are building a new DApp or enhancing an existing one, these steps will help you establish a reliable connection to the blockchain ecosystem.
Installation and Initial Setup
To begin the integration process, ensure your development environment is prepared with the necessary tools. The first step involves installing the required package via npm, which provides the essential functions for wallet connectivity.
Before initiating any wallet connection, you must create a user interface object. This object will handle subsequent operations such as connecting wallets and sending transactions. The initialization process requires specific parameters to tailor the interface to your application's needs.
Request Parameters
dappMetaData: An object containing metadata about your DApp.
- name: A string representing your application's name. Note that this is not used as a unique identifier.
- icon: A URL string pointing to your application's icon. The image must be in PNG or ICO format (SVG is not supported). For optimal results, use a URL that points to a 180x180px PNG icon.
actionsConfiguration: An object to configure the behavior during transaction processes.
- modals: An array or string defining the display mode for notification interfaces during transactions. Options include 'before', 'success', 'error', or 'all'. The default value is 'before'.
- returnStrategy: A string that specifies the deep link return strategy for app wallets after a user signs or rejects a request. For example, in Telegram, you can configure it as
tg://resolve. - tmaReturnUrl: A string used in Telegram Mini Wallet to define the deep link return strategy after a user signs or rejects a request. Options include 'back' (closes the wallet and displays the DApp), 'none' (no action taken), or a custom deep link. The default is 'back'.
uiPreferences: An object for customizing the user interface.
- theme: The theme of the interface, which can be THEME.DARK, THEME.LIGHT, or "SYSTEM".
- language: A string to set the language of the interface. Supported values include "en_US", "ru_RU", "zh_CN", and several others. The default is "en_US".
Return Value
The initialization function returns an instance of OKXUniversalConnectUI, which is used for subsequent wallet interactions.
Example Code Snippet
Connecting a Wallet
Establishing a connection to a user's wallet is crucial for obtaining their wallet address, which serves as an identifier and is necessary for signing transactions. This step ensures that your DApp can interact securely with the blockchain on behalf of the user.
Request Parameters
connectParams: An object of type ConnectParams containing the following properties.
namespaces: A record where the key is a namespace string (e.g., "starknet" for Starknet-related chains) and the value is a ConnectNamespace object. This specifies the required chains for connection. Currently, only "starknet:mainnet" is supported. If any requested chain is not supported by the wallet, the connection will be rejected.
- chains: An array of chain IDs.
- defaultChain: An optional string specifying the default chain.
optionalNamespaces: Similar to namespaces, but for optional connection information. If a requested chain is not supported, the connection may still proceed.
- chains: An array of chain IDs.
- defaultChain: An optional string for the default chain.
sessionConfig: An object for session configuration.
- redirect: A string specifying the redirect URL after a successful connection. For Telegram Mini Apps, this can be set to a Telegram deep link like "tg://resolve".
Return Value
The function returns a Promise that resolves to an object containing:
- topic: A string representing the session identifier.
- namespaces: A record of successfully connected namespace information.
- chains: An array of connected chain IDs.
- accounts: An array of connected account addresses.
- methods: An array of methods supported by the wallet for the current namespace.
- defaultChain: An optional string for the default chain of the session.
- sessionConfig: Optional session configuration.
dappInfo: An object containing DApp information.
- name: The DApp name.
- icon: The DApp icon URL.
- redirect: An optional redirect parameter after connection.
👉 Explore more strategies for wallet integration
Preparing a Transaction
To prepare a transaction, you need to create an instance of OKXStarknetProvider. This object is constructed by passing the OKXUniversalProvider instance, which facilitates transaction handling and interaction with the Starknet network.
Retrieving Account Information
Once connected, your DApp may need to retrieve details about the user's account, such as their wallet address and public key. This information is essential for transaction signing and user identification.
Request Parameters
- chainId: A string specifying the chain to query, e.g., "starknet:mainnet".
Return Value
Returns an object with:
- address: The wallet address as a string.
- pubKey: The public key as a string.
Example Code Snippet
Signing a Message
Message signing is a common operation in DApps, used for authentication and verifying user intent. This process involves generating a signature for a specific message using the user's private key.
Request Parameters
- signerAddress: A string representing the wallet address of the signer.
- typedData: An object containing the message to be signed, formatted according to specific requirements.
- chain: An optional string specifying the chain on which to execute the method.
Return Value
Returns a Promise that resolves to an array of two strings [r, v], representing the signature components.
Example Code Snippet
Signing and Broadcasting a Transaction
Sending a transaction involves signing it with the user's private key and broadcasting it to the blockchain network. This process ensures that the transaction is executed and recorded on the distributed ledger.
Request Parameters
- signerAddress: A string representing the wallet address.
- transaction: An object containing the transaction details, formatted appropriately.
- chainId: An optional string specifying the chain for signing and execution.
Return Value
Returns a Promise that resolves to a string representing the transaction hash.
Example Code Snippet
Disconnecting a Wallet
Properly disconnecting a wallet is important for maintaining security and session management. This action terminates the current session and removes associated data. If you need to switch wallets, always disconnect the current one first.
Event Handling
DApps often need to respond to various events, such as changes in wallet connection or transaction statuses. Implementing event listeners allows your application to react dynamically to these changes.
Error Codes and Handling
During wallet connection, transaction processing, or disconnection, various errors may occur. Understanding these error codes helps in debugging and providing a smooth user experience.
Common Errors
| Error Code | Description |
|---|---|
| UNKNOWN_ERROR | An unexpected error occurred. |
| ALREADY_CONNECTED_ERROR | The wallet is already connected. |
| NOT_CONNECTED_ERROR | The wallet is not connected. |
| USER_REJECTS_ERROR | The user rejected the request. |
| METHOD_NOT_SUPPORTED | The requested method is not supported. |
| CHAIN_NOT_SUPPORTED | The requested chain is not supported. |
| WALLET_NOT_SUPPORTED | The wallet is not supported. |
| CONNECTION_ERROR | A connection error occurred. |
👉 Get advanced methods for error resolution
Frequently Asked Questions
How do I update my OKX App for DApp integration?
Ensure your OKX App is updated to version 6.98.0 or later. This version includes the necessary features and security patches for seamless integration with Starknet and other Web3 wallets.
What should I do if the wallet connection fails?
First, verify that the chain IDs and namespaces in your connect parameters are correct. Ensure the wallet supports the requested chains. If the problem persists, check for any error codes and refer to the handling guidelines.
Can I customize the UI language and theme?
Yes, during initialization, you can set the language and theme preferences. Supported languages include English, Chinese, Russian, and others, while themes can be dark, light, or system default.
How do I handle user rejection of a transaction?
Your application should gracefully handle the USER_REJECTS_ERROR code. Inform the user that the transaction was not approved and provide options to retry or cancel the operation.
What is the purpose of the returnStrategy parameter?
This parameter defines the behavior after a user signs or rejects a request in app wallets. It is particularly useful in environments like Telegram, where deep links can enhance user experience.
Are there any limitations on the icon format for dappMetaData?
Yes, the icon must be in PNG or ICO format, with a recommended size of 180x180px. SVG icons are not supported due to compatibility constraints.