Orderly Network：SDK 钱包连接

一份全面的指南，介绍如何在 Orderly Network DEX 应用中集成钱包连接功能，同时支持 EVM（以太坊、Arbitrum 等）与 Solana 钱包。

适用场景

• 为新 DEX 设置钱包连接
• 支持多种钱包类型（MetaMask、Phantom 等）
• 实现链切换功能
• 管理认证状态

前置条件

• 已安装 Orderly SDK 相关包
• 已配置 Provider（参见 orderly-sdk-dex-architecture）
• 已安装钱包相关包（@web3-onboard/*、@solana/wallet-adapter-*）

概述

Orderly Network 支持 跨链交易（omnichain trading），即用户可连接来自多个区块链生态的钱包：

• EVM 链：以太坊、Arbitrum、Optimism、Base、Polygon、BSC、Avalanche 等
• Solana：主网（Mainnet）与开发网（Devnet）

SDK 提供统一的钱包连接层，抽象不同生态间的差异。

钱包连接器包（Wallet Connector Package）

注意：@orderly.network/wallet-connector 包开箱即用，内置合理默认配置。solanaInitial 与 evmInitial 属性均为可选。

# 主连接器包
npm install @orderly.network/wallet-connector

# 可选：EVM 钱包包（用于自定义钱包配置，如 WalletConnect）
npm install @web3-onboard/injected-wallets @web3-onboard/walletconnect

# 可选：Solana 钱包包（用于自定义 Solana 钱包配置）
npm install @solana/wallet-adapter-base @solana/wallet-adapter-wallets

必需依赖项汇总

架构

┌──────────────────────────────────────────────────────────────┐
│                    WalletConnectorProvider                   │
│  ┌───────────────────────────────────────────────────────┐   │
│  │                   SolanaProvider                      │   │
│  │  (ConnectionProvider + WalletProvider + ModalProvider)│   │
│  │  ┌───────────────────────────────────────────────┐    │   │
│  │  │                   InitEvm                     │    │   │
│  │  │  (Web3OnboardProvider for EVM wallets)        │    │   │
│  │  │  ┌─────────────────────────────────────────┐  │    │   │
│  │  │  │                  Main                   │  │    │   │
│  │  │  │  (WalletConnectorContext - 统一 API)    │  │    │   │
│  │  │  │  ┌─────────────────────────────────┐    │  │    │   │
│  │  │  │  │         Your App                │    │  │    │   │
│  │  │  │  └─────────────────────────────────┘    │  │    │   │
│  │  │  └─────────────────────────────────────────┘  │    │   │
│  │  └───────────────────────────────────────────────┘    │   │
│  └───────────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────────┘

基础配置

重要提示：WalletConnectorProvider（Solana 网络）与 OrderlyAppProvider 中的 networkId 必须保持一致。

1. WalletConnectorProvider

使用 WalletConnectorProvider 包裹您的应用。

最小化配置（使用默认值）：

import { WalletConnectorProvider } from '@orderly.network/wallet-connector';
import { OrderlyAppProvider } from '@orderly.network/react-app';
import type { NetworkId } from '@orderly.network/types';

function App() {
  const networkId: NetworkId = 'mainnet';

  return (
    
      
        
      
    
  );
}

自定义配置（显式指定钱包配置）：

import { WalletConnectorProvider } from '@orderly.network/wallet-connector';
import { WalletAdapterNetwork } from '@solana/wallet-adapter-base';
import { OrderlyAppProvider } from '@orderly.network/react-app';
import type { NetworkId } from '@orderly.network/types';

function App() {
  const networkId: NetworkId = 'mainnet';

  return (
    
      
        
      
    
  );
}

2. 配置 EVM 钱包

import injectedOnboard from '@web3-onboard/injected-wallets';
import walletConnectOnboard from '@web3-onboard/walletconnect';
import binanceWallet from '@binance/w3w-blocknative-connector';

export function getEvmWallets() {
  const walletConnectProjectId = 'YOUR_WALLETCONNECT_PROJECT_ID';

  return [
    // 注入式钱包（MetaMask、Rabby、Coinbase 等）
    injectedOnboard(),

    // Binance Web3 Wallet
    binanceWallet({ options: { lng: 'en' } }),

    // WalletConnect（用于移动端钱包）
    walletConnectOnboard({
      projectId: walletConnectProjectId,
      qrModalOptions: { themeMode: 'dark' },
      dappUrl: window.location.origin,
    }),
  ];
}

3. 配置 Solana 钱包

import { WalletAdapterNetwork } from '@solana/wallet-adapter-base';
import {
  PhantomWalletAdapter,
  SolflareWalletAdapter,
  LedgerWalletAdapter,
} from '@solana/wallet-adapter-wallets';

export function getSolanaWallets(networkId: 'mainnet' | 'testnet') {
  return [new PhantomWalletAdapter(), new SolflareWalletAdapter(), new LedgerWalletAdapter()];
}

使用钱包连接功能

访问钱包上下文

SDK 提供统一的 WalletConnectorContext：

import { useContext } from 'react';
import { WalletConnectorContext } from '@orderly.network/hooks';

function WalletStatus() {
  const {
    connect, // 连接钱包函数
    disconnect, // 断开钱包函数
    connecting, // 布尔值：是否正在连接中
    wallet, // 已连接的钱包信息
    connectedChain, // 当前链信息
    setChain, // 切换链函数
    namespace, // "evm" | "solana" | null
  } = useContext(WalletConnectorContext);

  return (
    

      {wallet ? (
        <>
          
已连接：{wallet.accounts[0].address}
          
链：{connectedChain?.id}
          断开连接
        
      ) : (
         connect({ chainId: 42161 })}>连接钱包
      )}
    
  );
}

连接至特定链

const { connect } = useContext(WalletConnectorContext);

// 连接至 EVM 链（Arbitrum）
await connect({ chainId: 42161 });

// 连接至 Solana
await connect({ chainId: 900900900 }); // Solana 主网

切换链

const { setChain, connectedChain } = useContext(WalletConnectorContext);

// 切换至 Optimism
await setChain({ chainId: '0xa' }); // EVM 链 ID 的十六进制格式

// 切换至 Base
await setChain({ chainId: '0x2105' });

账户状态机

完成钱包连接后，用户需完成 Orderly 账户初始化流程：

NotConnected (0) → Connected (1) → NotSignedIn (2) → SignedIn (3)
                                              ↓
                                        EnableTrading (5)

使用 useAccount Hook

import { useAccount, AccountStatusEnum } from '@orderly.network/hooks';

function AccountStatus() {
  const { account, state, createOrderlyKey, createAccount, disconnect } = useAccount();

  switch (state.status) {
    case AccountStatusEnum.NotConnected:
      return ;

    case AccountStatusEnum.Connected:
      return  createAccount()}>创建 Orderly 账户;

    case AccountStatusEnum.NotSignedIn:
      return  createOrderlyKey()}>启用交易;

    case AccountStatusEnum.SignedIn:
      return ;
  }
}

钱包连接 UI 组件

WalletConnectorWidget

预构建的钱包连接 UI：

import { WalletConnectorWidget, WalletConnectorModalId } from '@orderly.network/ui-connector';
import { modal } from '@orderly.network/ui';

// 显示钱包连接弹窗
function ConnectButton() {
  return  modal.show(WalletConnectorModalId)}>连接钱包;
}

AuthGuard

包裹需要身份认证的内容：

import { AuthGuard } from '@orderly.network/ui-connector';

function TradingPage() {
  return (
    }>
      
    
  );
}

useAuthGuard Hook

import { useAuthGuard } from '@orderly.network/ui-connector';

function TradeButton() {
  const { isAuthenticated, triggerAuth } = useAuthGuard();

  const handleClick = () => {
    if (!isAuthenticated) {
      triggerAuth();
      return;
    }
    // 执行交易逻辑
  };

  return 交易;
}

支持的链

EVM 主网链

EVM 测试网链

Solana

链过滤

限制用户可连接的链范围：

处理链变更

 {
    console.log(`已切换至链 ${chainId}`);

    // 若从主网切换至测试网，则刷新页面
    if (isTestnet && networkId === "mainnet") {
      localStorage.setItem("network", "testnet");
      window.location.reload();
    }
  }}
>

Privy 集成（替代方案）

如需支持社交登录，请使用 Privy：

npm install @orderly.network/wallet-connector-privy

import { WalletConnectorPrivy } from "@orderly.network/wallet-connector-privy";


  
    
  

错误处理

import { useEventEmitter } from '@orderly.network/hooks';

function WalletErrorHandler() {
  const ee = useEventEmitter();

  useEffect(() => {
    const handleError = (error: { message: string }) => {
      toast.error(error.message);
    };

    ee.on('wallet:connect-error', handleError);

    return () => {
      ee.off('wallet:connect-error', handleError);
    };
  }, [ee]);

  return null;
}

最佳实践

1. 执行操作前检查钱包连接状态

const { wallet } = useContext(WalletConnectorContext);
if (!wallet) {
  modal.show(WalletConnectorModalId);
  return;
}

2. 使用 AuthGuard 保护敏感内容

3. 处理网络不匹配情况

const { connectedChain } = useContext(WalletConnectorContext);
const expectedChainId = networkId === 'mainnet' ? 42161 : 421614;

if (connectedChain?.id !== expectedChainId) {
  return ;
}

4. 持久化网络选择

const NETWORK_KEY = 'orderly_network_id';

function getNetworkId(): NetworkId {
  return (localStorage.getItem(NETWORK_KEY) as NetworkId) || 'mainnet';
}

相关技能

• orderly-sdk-dex-architecture — Provider 初始化与配置
• orderly-sdk-install-dependency — 钱包包安装
• orderly-sdk-trading-workflows — 交易功能实现
• orderly-sdk-debugging — 钱包问题排查
• orderly-api-authentication — 认证流程解析