@rango-dev/provider-okx 0.0.0-experimental-936229e8-20251208

package/readme.md

@@ -0,0 +1,78 @@
+# OKX Wallet
+
+OKX Wallet integration for hub.  
+[Homepage](https://www.okx.com/web3) | [Docs](https://www.okx.com/web3/build/docs)
+
+More about implementation status can be found [here](../readme.md).
+
+## Implementation notes/limitations
+
+### Group
+
+#### ✅ Solana
+
+- Fully supported in this integration.
+- No known limitations.
+
+---
+
+#### ⚠️ EVM
+
+Supported networks :
+
+- Ethereum
+- BSC
+- Polygon
+- Fantom
+- Arbitrum
+- Optimism
+- Cronos
+- Boba
+- Gnosis
+- Moonbeam
+- Moonriver
+- Harmony
+- Avalanche C-Chain
+
+#### ⚠️ UTXO Chains
+
+The wallet only supports bitcoin.
+
+#### 🚧 Cosmos
+
+The wallet supports Cosmos, but it is **not implemented** in the current integration.
+
+#### 🚧 TON
+
+The wallet supports TON, but it is **not implemented** in the current integration.
+
+#### 🚧 Sui
+
+The wallet supports Sui, but it is **not implemented** in the current integration.
+
+
+
+### Feature
+
+#### ⚠️ Disconnect
+
+The disconnect function will not work for this wallet, as it attempts to invoke disconnect on the connect method for private key imported wallets.
+If the user disconnects the dApp from the wallet itself, we won't disconnect ourself. But we will get disconnected after refreshing the page.
+If the user connects the wallet to one account, switches to another account, and then disconnects one of the two from the wallet, the dApp automatically switches to the remaining account that wasn’t disconnected.
+
+
+
+Here’s the updated **Switch Account** section with a concise mention that connection order affects switching accounts:
+
+---
+
+#### ⚠️ Switch Account
+
+**Connection order also affects this behavior** depending on which namespace was connected first, some account updates may not propagate correctly across other namespaces. As a result, previously connected namespaces will not update automatically and require a manual disconnect and reconnect to sync the correct account.
+
+Additionally, calling `connect` on a namespace that was already connected does not return the address of the newly selected account. To avoid leaving the user in an inconsistent state, we invoke a full wallet `disconnect` when the user disconnects the wallet from the provider.
+
+
+---
+
+More wallet information can be found in [readme.md](../readme.md).

package/src/builders/utxo.ts

@@ -0,0 +1,48 @@
+import type { OkxBtcAddress } from '../types.js';
+
+import { ActionBuilder } from '@rango-dev/wallets-core';
+import { ChangeAccountSubscriberBuilder } from '@rango-dev/wallets-core/namespaces/common';
+import {
+  type ProviderAPI,
+  utils,
+  type UtxoActions,
+} from '@rango-dev/wallets-core/namespaces/utxo';
+
+export const changeAccountSubscriber = (getInstance: () => ProviderAPI) =>
+  new ChangeAccountSubscriberBuilder<OkxBtcAddress, ProviderAPI, UtxoActions>()
+    .getInstance(getInstance)
+    /*
+     * Okx wallet may call the `changeAccount` event with `null` value
+     * but we shouldn't disconnect in this case.
+     */
+    .onSwitchAccount((event) => {
+      if (!event.payload?.address) {
+        event.preventDefault();
+      }
+    })
+
+    .format(async (_, event) => {
+      return utils.formatAccountsToCAIP(event ? [event.address] : []);
+    })
+    .addEventListener((instance, callback) => {
+      return instance.addListener('accountChanged', callback);
+    })
+    .removeEventListener((instance, callback) => {
+      return instance.removeListener('accountChanged', callback);
+    });
+
+function canEagerConnect(getInstance: () => ProviderAPI) {
+  return new ActionBuilder<UtxoActions, 'canEagerConnect'>(
+    'canEagerConnect'
+  ).action(async () => {
+    const instance = getInstance();
+    try {
+      const accounts = await instance.getAccounts();
+      return !!accounts.length;
+    } catch {
+      return false;
+    }
+  });
+}
+
+export const utxoBuilders = { changeAccountSubscriber, canEagerConnect };

package/src/constants.ts

@@ -0,0 +1,83 @@
+import { type ProviderMetadata } from '@rango-dev/wallets-core';
+import { LegacyNetworks } from '@rango-dev/wallets-core/legacy';
+import { Networks } from '@rango-dev/wallets-shared';
+import {
+  type BlockchainMeta,
+  solanaBlockchain,
+  type TransferBlockchainMeta,
+} from 'rango-types';
+
+import getSigners from './signer.js';
+import { getInstanceOrThrow } from './utils.js';
+
+export const WALLET_ID = 'okx';
+export const OKX_WALLET_SUPPORTED_CHAINS = [
+  LegacyNetworks.ETHEREUM,
+  LegacyNetworks.BSC,
+  LegacyNetworks.POLYGON,
+  LegacyNetworks.FANTOM,
+  LegacyNetworks.ARBITRUM,
+  LegacyNetworks.OPTIMISM,
+  LegacyNetworks.CRONOS,
+  LegacyNetworks.BOBA,
+  LegacyNetworks.GNOSIS,
+  LegacyNetworks.MOONBEAM,
+  LegacyNetworks.MOONRIVER,
+  LegacyNetworks.HARMONY,
+  LegacyNetworks.AVAX_CCHAIN,
+];
+
+export const metadata: ProviderMetadata = {
+  name: 'OKX',
+  icon: 'https://raw.githubusercontent.com/rango-exchange/assets/main/wallets/okx/icon.svg',
+  extensions: {
+    chrome:
+      'https://chrome.google.com/webstore/detail/okx-wallet/mcohilncbfahbmgdjkbpemcciiolgcge',
+    brave:
+      'https://chrome.google.com/webstore/detail/okx-wallet/mcohilncbfahbmgdjkbpemcciiolgcge',
+    firefox: 'https://addons.mozilla.org/en-US/firefox/addon/okexwallet',
+    homepage: 'https://www.okx.com/web3',
+  },
+  properties: [
+    {
+      name: 'namespaces',
+      value: {
+        selection: 'multiple',
+        data: [
+          {
+            label: 'EVM',
+            value: 'EVM',
+            id: 'ETH',
+            getSupportedChains: (allBlockchains: BlockchainMeta[]) =>
+              allBlockchains.filter((blockchainMeta) =>
+                OKX_WALLET_SUPPORTED_CHAINS.includes(
+                  blockchainMeta.name as LegacyNetworks
+                )
+              ),
+          },
+          {
+            label: 'Solana',
+            value: 'Solana',
+            id: 'SOLANA',
+            getSupportedChains: (allBlockchains: BlockchainMeta[]) =>
+              solanaBlockchain(allBlockchains),
+          },
+          {
+            label: 'BTC',
+            value: 'UTXO',
+            id: 'BTC',
+            getSupportedChains: (allBlockchains: BlockchainMeta[]) =>
+              allBlockchains.filter(
+                (chain): chain is TransferBlockchainMeta =>
+                  chain.name === Networks.BTC
+              ),
+          },
+        ],
+      },
+    },
+    {
+      name: 'signers',
+      value: { getSigners: async () => getSigners(getInstanceOrThrow()) },
+    },
+  ],
+};

package/src/legacy/index.ts

@@ -0,0 +1,137 @@
+import type { LegacyProviderInterface } from '@rango-dev/wallets-core/legacy';
+import type {
+  CanEagerConnect,
+  CanSwitchNetwork,
+  Connect,
+  ProviderConnectResult,
+  Subscribe,
+  SwitchNetwork,
+  WalletInfo,
+} from '@rango-dev/wallets-shared';
+import type { BlockchainMeta, SignerFactory } from 'rango-types';
+
+import {
+  canEagerlyConnectToEvm,
+  canSwitchNetworkToEvm,
+  chooseInstance,
+  getEvmAccounts,
+  getSolanaAccounts,
+  Networks,
+  switchNetworkForEvm,
+  WalletTypes,
+} from '@rango-dev/wallets-shared';
+import { isEvmBlockchain } from 'rango-types';
+
+import { OKX_WALLET_SUPPORTED_CHAINS } from '../constants.js';
+import signer from '../signer.js';
+import { okx } from '../utils.js';
+
+const WALLET = WalletTypes.OKX;
+
+export const config = {
+  type: WALLET,
+  defaultNetwork: Networks.ETHEREUM,
+};
+
+export const getInstance = okx;
+export const connect: Connect = async ({ instance, meta }) => {
+  const results: ProviderConnectResult[] = [];
+
+  const evmInstance = chooseInstance(instance, meta, Networks.ETHEREUM);
+
+  if (evmInstance) {
+    const evmResults = await getEvmAccounts(evmInstance);
+    results.push(evmResults);
+  }
+
+  const solanaResults = await getSolanaAccounts(instance);
+
+  results.push(
+    ...(Array.isArray(solanaResults) ? solanaResults : [solanaResults])
+  );
+
+  return results;
+};
+
+export const subscribe: Subscribe = ({ instance, updateAccounts, meta }) => {
+  const ethInstance = chooseInstance(instance, meta, Networks.ETHEREUM);
+  const handleEvmAccountsChanged = async (addresses: string[]) => {
+    const eth_chainId = meta
+      .filter(isEvmBlockchain)
+      .find((blockchain) => blockchain.name === Networks.ETHEREUM)?.chainId;
+
+    updateAccounts(addresses, eth_chainId);
+    const solanaResults = await getSolanaAccounts(instance);
+    const resultsArray = Array.isArray(solanaResults)
+      ? solanaResults
+      : [solanaResults];
+
+    resultsArray.forEach(({ chainId, accounts }) => {
+      updateAccounts(accounts, chainId);
+    });
+  };
+  ethInstance?.on?.('accountsChanged', handleEvmAccountsChanged);
+
+  return () => {
+    ethInstance?.off?.('accountsChanged', handleEvmAccountsChanged);
+  };
+};
+
+export const switchNetwork: SwitchNetwork = async (options) => {
+  const instance = chooseInstance(
+    options.instance,
+    options.meta,
+    options.network
+  );
+  return switchNetworkForEvm({
+    ...options,
+    instance,
+  });
+};
+
+export const canSwitchNetworkTo: CanSwitchNetwork = canSwitchNetworkToEvm;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Provider = any;
+export const getSigners: (provider: Provider) => Promise<SignerFactory> =
+  signer;
+
+export const canEagerConnect: CanEagerConnect = async ({ instance, meta }) => {
+  const evm_instance = chooseInstance(instance, meta, Networks.ETHEREUM);
+  if (evm_instance) {
+    return canEagerlyConnectToEvm({ instance: evm_instance, meta });
+  }
+  return Promise.resolve(false);
+};
+
+export const getWalletInfo: (allBlockChains: BlockchainMeta[]) => WalletInfo = (
+  allBlockChains
+) => ({
+  name: 'OKX',
+  img: 'https://raw.githubusercontent.com/rango-exchange/assets/main/wallets/okx/icon.svg',
+  installLink: {
+    CHROME:
+      'https://chrome.google.com/webstore/detail/okx-wallet/mcohilncbfahbmgdjkbpemcciiolgcge',
+    BRAVE:
+      'https://chrome.google.com/webstore/detail/okx-wallet/mcohilncbfahbmgdjkbpemcciiolgcge',
+    FIREFOX: 'https://addons.mozilla.org/en-US/firefox/addon/okexwallet',
+    DEFAULT: 'https://www.okx.com/web3',
+  },
+  color: 'white',
+  supportedChains: allBlockChains.filter((blockchainMeta) =>
+    OKX_WALLET_SUPPORTED_CHAINS.includes(blockchainMeta.name as Networks)
+  ),
+});
+const buildLegacyProvider: () => LegacyProviderInterface = () => ({
+  config,
+  getInstance,
+  connect,
+  subscribe,
+  switchNetwork,
+  canSwitchNetworkTo,
+  getSigners,
+  getWalletInfo,
+  canEagerConnect,
+});
+
+export { buildLegacyProvider };

package/src/mod.ts

@@ -0,0 +1,12 @@
+import { defineVersions } from '@rango-dev/wallets-core/utils';
+
+import { buildLegacyProvider } from './legacy/index.js';
+import { buildProvider } from './provider.js';
+
+const versions = () =>
+  defineVersions()
+    .version('0.0.0', buildLegacyProvider())
+    .version('1.0.0', buildProvider())
+    .build();
+
+export { versions };

package/src/namespaces/evm.ts

@@ -0,0 +1,73 @@
+import type { EvmActions } from '@rango-dev/wallets-core/namespaces/evm';
+
+import { NamespaceBuilder } from '@rango-dev/wallets-core';
+import {
+  builders as commonBuilders,
+  standardizeAndThrowError,
+} from '@rango-dev/wallets-core/namespaces/common';
+import {
+  actions,
+  builders,
+  utils,
+} from '@rango-dev/wallets-core/namespaces/evm';
+
+import { WALLET_ID } from '../constants.js';
+import { evmOKX } from '../utils.js';
+
+const [changeAccountSubscriber, changeAccountCleanup] = builders
+  .changeAccountSubscriber(evmOKX)
+  /*
+   * Okx wallet may call the `changeAccount` event with `null` value
+   * but we shouldn't disconnect in this case.
+   */
+  .onSwitchAccount((event) => {
+    if (!event.payload.length) {
+      event.preventDefault();
+    }
+  })
+  .format(async (instance, event) => {
+    const chainId = await instance.request({ method: 'eth_chainId' });
+    // The wallet may emit a `null` value in its `sent` event.
+    return utils.formatAccountsToCAIP(event.filter(Boolean), chainId);
+  })
+  .build();
+const connect = builders
+  .connect()
+  .action(actions.connect(evmOKX))
+  .before(changeAccountSubscriber)
+  .or(changeAccountCleanup)
+  .or(standardizeAndThrowError)
+  .build();
+
+const disconnect = commonBuilders
+  .disconnect<EvmActions>()
+  .before(() => {
+    evmOKX().disconnect();
+  })
+  .after(changeAccountCleanup)
+  .build();
+
+const canSwitchNetwork = builders
+  .canSwitchNetwork()
+  .action(actions.canSwitchNetwork())
+  .build();
+
+const canEagerConnect = builders
+  .canEagerConnect()
+  .action(actions.canEagerConnect(evmOKX))
+  .build();
+
+const getChainId = builders
+  .getChainId()
+  .action(actions.getChainId(evmOKX))
+  .build();
+
+const evm = new NamespaceBuilder<EvmActions>('EVM', WALLET_ID)
+  .action(connect)
+  .action(disconnect)
+  .action(canEagerConnect)
+  .action(canSwitchNetwork)
+  .action(getChainId)
+  .build();
+
+export { evm };

package/src/namespaces/solana.ts

@@ -0,0 +1,62 @@
+import type { SolanaActions } from '@rango-dev/wallets-core/namespaces/solana';
+
+import { ActionBuilder, NamespaceBuilder } from '@rango-dev/wallets-core';
+import {
+  builders as commonBuilders,
+  standardizeAndThrowError,
+} from '@rango-dev/wallets-core/namespaces/common';
+import {
+  actions,
+  builders,
+  utils,
+} from '@rango-dev/wallets-core/namespaces/solana';
+
+import { WALLET_ID } from '../constants.js';
+import { solanaOKX } from '../utils.js';
+
+const [changeAccountSubscriber, changeAccountCleanup] = builders
+  .changeAccountSubscriber(solanaOKX)
+  /*
+   * Okx wallet may call the `changeAccount` event with `null` value
+   * but we shouldn't disconnect in this case.
+   */
+  .onSwitchAccount((event) => {
+    if (!event.payload) {
+      event.preventDefault();
+    }
+  })
+  .format(async (_, event) => {
+    // The wallet may emit a `null` value in its `sent` event.
+    return utils.formatAccountsToCAIP(event ? [event] : []);
+  })
+  .build();
+
+const connect = builders
+  .connect()
+  .action(actions.connect(solanaOKX))
+  .before(changeAccountSubscriber)
+  .or(changeAccountCleanup)
+  .or(standardizeAndThrowError)
+  .build();
+
+const disconnect = commonBuilders
+  .disconnect<SolanaActions>()
+  .before(() => {
+    solanaOKX().disconnect();
+  })
+  .after(changeAccountCleanup)
+  .build();
+
+const canEagerConnect = new ActionBuilder<SolanaActions, 'canEagerConnect'>(
+  'canEagerConnect'
+)
+  .action(actions.canEagerConnect(solanaOKX))
+  .build();
+
+const solana = new NamespaceBuilder<SolanaActions>('Solana', WALLET_ID)
+  .action(connect)
+  .action(disconnect)
+  .action(canEagerConnect)
+  .build();
+
+export { solana };

package/src/namespaces/utxo.ts

@@ -0,0 +1,51 @@
+import { NamespaceBuilder } from '@rango-dev/wallets-core';
+import {
+  builders as commonBuilders,
+  standardizeAndThrowError,
+} from '@rango-dev/wallets-core/namespaces/common';
+import {
+  utils,
+  type UtxoActions,
+} from '@rango-dev/wallets-core/namespaces/utxo';
+import { builders } from '@rango-dev/wallets-core/namespaces/utxo';
+
+import { utxoBuilders } from '../builders/utxo.js';
+import { WALLET_ID } from '../constants.js';
+import { bitcoinOKX, getBitcoinAccounts } from '../utils.js';
+
+const [changeAccountSubscriber, changeAccountCleanup] = utxoBuilders
+  .changeAccountSubscriber(bitcoinOKX)
+  .build();
+
+const canEagerConnect = utxoBuilders.canEagerConnect(bitcoinOKX).build();
+
+const connect = builders
+  .connect()
+  .action(async function () {
+    const accountsResult = await getBitcoinAccounts();
+
+    if (!accountsResult?.address) {
+      throw new Error("Couldn't find any address!");
+    }
+    return utils.formatAccountsToCAIP([accountsResult.address]);
+  })
+  .before(changeAccountSubscriber)
+  .or(changeAccountCleanup)
+  .or(standardizeAndThrowError)
+  .build();
+
+const disconnect = commonBuilders
+  .disconnect<UtxoActions>()
+  .before(() => {
+    bitcoinOKX().disconnect();
+  })
+  .after(changeAccountCleanup)
+  .build();
+
+const utxo = new NamespaceBuilder<UtxoActions>('UTXO', WALLET_ID)
+  .action(connect)
+  .action(disconnect)
+  .action(canEagerConnect)
+  .build();
+
+export { utxo };

package/src/provider.ts

@@ -0,0 +1,26 @@
+import { ProviderBuilder } from '@rango-dev/wallets-core';
+
+import { metadata, WALLET_ID } from './constants.js';
+import { evm } from './namespaces/evm.js';
+import { solana } from './namespaces/solana.js';
+import { utxo } from './namespaces/utxo.js';
+import { okx as okxInstance } from './utils.js';
+
+const buildProvider = () =>
+  new ProviderBuilder(WALLET_ID)
+    .init(function (context) {
+      const [, setState] = context.state();
+
+      if (okxInstance()) {
+        setState('installed', true);
+        console.debug('[okx] instance detected.', context);
+      }
+    })
+    .config('metadata', metadata)
+    .add('solana', solana)
+    .add('evm', evm)
+    .add('utxo', utxo)
+
+    .build();
+
+export { buildProvider };

package/src/signer.ts

@@ -0,0 +1,30 @@
+import type { Provider } from './types.js';
+import type { SignerFactory } from 'rango-types';
+
+import {
+  dynamicImportWithRefinedError,
+  getNetworkInstance,
+  Networks,
+} from '@rango-dev/wallets-shared';
+import { DefaultSignerFactory, TransactionType as TxType } from 'rango-types';
+
+import { OKXSolanaSigner } from './signers/solana.js';
+import { OKXUTXOSigner } from './signers/utxo.js';
+
+export default async function getSigners(
+  provider: Provider
+): Promise<SignerFactory> {
+  const ethProvider = getNetworkInstance(provider, Networks.ETHEREUM);
+  const solProvider = getNetworkInstance(provider, Networks.SOLANA);
+  const utxoProvider = getNetworkInstance(provider, Networks.BTC);
+
+  const signers = new DefaultSignerFactory();
+  const { DefaultEvmSigner } = await dynamicImportWithRefinedError(
+    async () => await import('@rango-dev/signer-evm')
+  );
+  signers.registerSigner(TxType.EVM, new DefaultEvmSigner(ethProvider));
+  signers.registerSigner(TxType.SOLANA, new OKXSolanaSigner(solProvider));
+  signers.registerSigner(TxType.TRANSFER, new OKXUTXOSigner(utxoProvider));
+
+  return signers;
+}

package/src/signers/solana.ts

@@ -0,0 +1,25 @@
+import {
+  DefaultSolanaSigner,
+  type SolanaExternalProvider,
+} from '@rango-dev/signer-solana';
+import { SignerError, SignerErrorCode } from 'rango-types';
+
+export class OKXSolanaSigner extends DefaultSolanaSigner {
+  constructor(provider: SolanaExternalProvider) {
+    super(provider);
+  }
+
+  async signMessage(msg: string): Promise<string> {
+    try {
+      const { signature } = await this.provider.request({
+        method: 'signMessage',
+        params: {
+          message: msg,
+        },
+      });
+      return signature;
+    } catch (error) {
+      throw new SignerError(SignerErrorCode.SIGN_TX_ERROR, undefined, error);
+    }
+  }
+}

package/src/signers/utxo.ts

@@ -0,0 +1,57 @@
+import type { ProviderAPI } from '@rango-dev/wallets-core/namespaces/utxo';
+import type { GenericSigner, Transfer } from 'rango-types';
+
+import { Networks } from '@rango-dev/wallets-shared';
+import { SignerError } from 'rango-types';
+
+export class OKXUTXOSigner implements GenericSigner<Transfer> {
+  private provider: ProviderAPI;
+  constructor(provider: ProviderAPI) {
+    this.provider = provider;
+  }
+
+  async signMessage(): Promise<string> {
+    throw SignerError.UnimplementedError('signMessage');
+  }
+
+  async signAndSendTx(tx: Transfer): Promise<{ hash: string }> {
+    const { asset, psbt } = tx;
+    if (!psbt) {
+      throw new Error(
+        'No PSBT found to sign. Ensure a valid PSBT is provided.'
+      );
+    }
+
+    if (asset.blockchain !== Networks.BTC) {
+      throw new Error(
+        `Signing ${asset.blockchain} transaction is not implemented by the signer.`
+      );
+    }
+    // 1. Decode Base64 to hex
+    const psbtHex = Buffer.from(psbt.unsignedPsbtBase64, 'base64').toString(
+      'hex'
+    );
+
+    // 2. Build UniSat inputs
+    const toSignInputs = psbt.inputsToSign.flatMap(
+      ({ address, signingIndexes }) =>
+        signingIndexes.map((index) => ({ index, address }))
+    );
+
+    try {
+      // 3. Sign (& auto-finalize)
+      const signedPsbtHex = await this.provider.signPsbt(psbtHex, {
+        autoFinalized: true,
+        toSignInputs,
+      });
+
+      // 4. Push signed psbt
+      const transactionHash = await this.provider.pushPsbt(signedPsbtHex);
+
+      return { hash: transactionHash };
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } catch (error: any) {
+      throw new Error(error?.message || 'Error during signing transaction');
+    }
+  }
+}