Integrating a Source Wallet with Hibit DEX

Overview

This guide provides developers with the essential steps to integrate any source wallet (such as Kasware) with the Hibit DEX. The core of this integration is the Hibit Identity Number (HIN). A HIN is the unique on-chain identity assigned to any wallet that interacts with the Hibit ecosystem. It is a mandatory prerequisite for performing any DEX operations on the Hibit Chain.

The process involves using the Hibit SDK to register the wallet, securely establish a proxy key for signing transactions, and retrieve the HIN. Once these components are in place, the source wallet can seamlessly execute trades on the Hibit DEX.

---

Integration Flow: From Source Wallet to DEX Trading

The end-to-end process can be broken down into four main stages: wallet registration, HIN retrieval, proxy key setup, and finally, DEX trading.

Text-Based Flowchart

Here is a high-level visual of the integration workflow:

[User's Source Wallet (e.g., Kasware)]
       |
       v
[Step 1: Register Wallet]
   - Inject the wallet's API via `setWalletApi(...)`.
   - Call `walletRegister(...)` to sign a message and register on-chain.
       |
       v
[Step 2: Retrieve HIN]
   - Wait ~5 seconds for on-chain finality.
   - Call `getRegisteredWalletInfo(...)` to fetch the wallet's unique HIN.
       |
       v
[Step 3: Set Up Proxy Key]
   - Generate an ECDSA keypair locally.
   - Call `resetProxyKey(...)` to sign a message and upload the strongly encrypted key to Hibit Chain.
       |
       v
[Step 4: Store and Manage Proxy Key]
   - Store the proxy private key ciphertext returned by `resetProxyKey`.
   - Use `getProxyKeypair()` for on-demand recovery and local decryption if the local copy is lost.
       |
       v
[Ready: Trade on Hibit DEX]

Step-by-Step Guide

1. Register Your Source Wallet

To begin, the user's wallet must be registered with the Hibit Chain.

• Inject the Wallet API: The Hibit SDK needs to request a signature from the user's wallet to authorize the registration. Before calling the registration function, you must inject the wallet's API (e.g., the Kasware wallet API) into the SDK by calling setWalletApi(...).

• Register the Wallet: Call the walletRegister(input: WalletRegisterInput): Promise<void> function. This prompts the user to sign a registration message via their wallet, which is then submitted to the Hibit Chain.

2. Retrieve Your HIN (Hibit Identity Number)

Once the registration transaction is confirmed on-chain, the wallet is assigned a HIN.

• Wait for Finality: Allow approximately 5 seconds for the transaction to achieve on-chain finality.

• Fetch the HIN: Call getRegisteredWalletInfo(walletAddress) with the user's public wallet address. This function returns the registration details, including the newly assigned HIN.

3. Set Up Your Proxy Key

A proxy key is an operational key used for signing day-to-day transactions without requiring the user's main wallet signature for every action.

• Generate a Local Keypair: First, generate a new ECDSA keypair within your local application environment.

• Set the Proxy Key: Call the resetProxyKey(...) function. This process is designed for high security:

  1. Your application will use the local private key to sign a specific, fixed message.

  2. This signature acts as a password to strongly encrypt your new proxy private key.

  3. The encrypted proxy private key is then uploaded to the Hibit Chain. This ensures your key is securely stored and can only be decrypted by you.

4. Store and Manage Your Proxy Key

Proper management of the proxy key is essential for continuous operation.

• Store the Encrypted Key: The resetProxyKey(...) function returns the ciphertext of the proxy private key. You should store this ciphertext locally for immediate use.

• Recover if Lost: If your application loses the local copy of the key, you can easily recover it by calling getProxyKeypair(). This function fetches the encrypted key from the chain, and your application can then decrypt it locally for use.

Ready for Trading: With the HIN and the proxy key in place, the integration is complete, and the wallet is fully equipped to trade on the Hibit DEX.

---

Additional Hibit SDK Notes

• Withdraw Assets: The SDK now includes a withdraw(...) endpoint, allowing you to programmatically withdraw assets via the API.

• Track Withdrawal Status: You can monitor the status of an ongoing withdrawal by calling getWithdrawDetails() with the transaction hash returned by the withdraw() function.

• WebSocket Support: WebSocket support is not yet available in the current OpenAPI but is planned for a future release.