Orderly Network：SDK DEX 架构

一份使用 Orderly Network Components SDK 构建完整去中心化交易所（DEX）应用的架构设计与脚手架搭建指南。

适用场景

• 新建 DEX 项目
• 理解 Provider 层级结构
• 配置网络环境
• 集成 TradingView 图表
• 理解运行时配置机制

前置条件

• 已安装 Node.js 18+
• 已安装 Orderly SDK 包（参见 orderly-sdk-install-dependency）
• 基于 TypeScript 的 React 18+ 项目
• Vite 或其他同类构建工具

概览

本技能涵盖构建生产就绪型 DEX 的完整架构：

• 项目结构与初始化设置
• Provider 层级结构与配置
• 网络配置（必需） — 主网/测试网及支持的链列表
• TradingView 图表配置（启用图表功能时必需） — 图表库文件路径
• 路由与页面组件组织
• 运行时配置机制
• 构建与部署流程

关键配置项：每个 DEX 必须完成以下配置：

1. brokerId — 您的 Orderly broker ID
2. networkId — 取值为 "mainnet" 或 "testnet"
3. 正确配置钱包连接器，并确保其网络与 networkId 一致
4. 将 TradingView 图表库放置于 public/tradingview/ 目录下（启用图表功能时必需）

项目结构

my-dex/
├── public/
│   ├── config.js              # 运行时配置
│   ├── favicon.webp
│   ├── locales/               # i18n 翻译资源
│   │   ├── en.json
│   │   └── extend/            # 自定义翻译
│   ├── pnl/                   # PnL 分享海报背景图
│   │   ├── poster_bg_1.png
│   │   └── poster_bg_2.png
│   └── tradingview/           # TradingView 库（启用图表功能时必需）
│       ├── chart.css          # 自定义图表样式
│       └── charting_library/  # TradingView 图表库文件
├── src/
│   ├── main.tsx               # 入口文件
│   ├── App.tsx                # 根组件（含路由）
│   ├── components/
│   │   ├── orderlyProvider/   # SDK Provider 初始化
│   │   │   ├── index.tsx      # 主 Provider 封装组件
│   │   │   └── walletConnector.tsx
│   │   ├── ErrorBoundary.tsx
│   │   └── LoadingSpinner.tsx
│   ├── pages/
│   │   ├── perp/              # 永续合约交易页
│   │   ├── portfolio/         # 账户资产页
│   │   ├── markets/           # 市场列表页
│   │   └── leaderboard/       # 排行榜页
│   ├── utils/
│   │   ├── config.tsx         # 应用配置逻辑
│   │   ├── walletConfig.ts    # 钱包配置
│   │   ├── runtime-config.ts  # 运行时配置加载器
│   │   └── storage.ts         # 本地存储工具
│   └── styles/
│       └── index.css          # 全局样式 + Tailwind
├── .env                       # 构建时环境变量
├── index.html
├── package.json
├── tailwind.config.ts
├── tsconfig.json
└── vite.config.ts

Provider 层级结构

SDK 要求严格的 Provider 嵌套顺序：

LocaleProvider (i18n)
└── WalletConnectorProvider (或 Privy)
    └── OrderlyAppProvider
        ├── (内部) AppConfigProvider
        ├── (内部) OrderlyThemeProvider
        ├── (内部) OrderlyConfigProvider (来自 hooks)
        ├── (内部) AppStateProvider
        ├── (内部) UILocaleProvider
        ├── (内部) TooltipProvider
        ├── (内部) ModalProvider
        └── Your App

注意：TooltipProvider 与 ModalProvider 由 OrderlyAppProvider 内部自动管理，您无需手动添加。

主 Provider 组件

// src/components/orderlyProvider/index.tsx
import { ReactNode, useCallback, Suspense, lazy } from 'react';
import { OrderlyAppProvider } from '@orderly.network/react-app';
import { LocaleProvider, LocaleCode, defaultLanguages } from '@orderly.network/i18n';
import type { NetworkId } from '@orderly.network/types';
import { useOrderlyConfig } from '@/utils/config';
import { getRuntimeConfig, getRuntimeConfigBoolean } from '@/utils/runtime-config';

const NETWORK_ID_KEY = 'orderly_network_id';

const getNetworkId = (): NetworkId => {
  if (typeof window === 'undefined') return 'mainnet';

  const disableMainnet = getRuntimeConfigBoolean('VITE_DISABLE_MAINNET');
  const disableTestnet = getRuntimeConfigBoolean('VITE_DISABLE_TESTNET');

  if (disableMainnet && !disableTestnet) return 'testnet';
  if (disableTestnet && !disableMainnet) return 'mainnet';

  return (localStorage.getItem(NETWORK_ID_KEY) as NetworkId) || 'mainnet';
};

const WalletConnector = lazy(() => import('./walletConnector'));

const OrderlyProvider = ({ children }: { children: ReactNode }) => {
  const config = useOrderlyConfig();
  const networkId = getNetworkId();

  const onChainChanged = useCallback((_chainId: number, { isTestnet }: { isTestnet: boolean }) => {
    const currentNetworkId = getNetworkId();
    if (
      (isTestnet && currentNetworkId === 'mainnet') ||
      (!isTestnet && currentNetworkId === 'testnet')
    ) {
      const newNetworkId: NetworkId = isTestnet ? 'testnet' : 'mainnet';
      localStorage.setItem(NETWORK_ID_KEY, newNetworkId);
      window.location.reload();
    }
  }, []);

  const onLanguageChanged = (lang: LocaleCode) => {
    const url = new URL(window.location.href);
    if (lang === 'en') {
      url.searchParams.delete('lang');
    } else {
      url.searchParams.set('lang', lang);
    }
    window.history.replaceState({}, '', url.toString());
  };

  return (
    
      }>
        
          
            {children}
          
        
      
    
  );
};

export default OrderlyProvider;

钱包连接器配置

注意：WalletConnectorProvider 上的 solanaInitial 和 evmInitial 属性均为可选。该 Provider 已内置合理默认值，官方模板亦未传入任何 props。仅当需定制钱包行为时才需显式传入。

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

// src/components/orderlyProvider/walletConnector.tsx
import { ReactNode } from 'react';
import { WalletConnectorProvider } from '@orderly.network/wallet-connector';
import type { NetworkId } from '@orderly.network/types';

interface Props {
  children: ReactNode;
  networkId: NetworkId;
}

const WalletConnector = ({ children, networkId }: Props) => {
  return {children};
};

export default WalletConnector;

网络配置（必需）

重要提示：所有 Orderly DEX 必须正确配置网络环境。

支持的网络

主网链（生产环境）

测试网链（开发环境）

Network ID 配置

networkId 属性决定 DEX 连接主网还是测试网。

import type { NetworkId } from '@orderly.network/types';

// networkId 必须为 "mainnet" 或 "testnet"
const networkId: NetworkId = 'mainnet'; // 或 "testnet"

带网络配置的完整 Provider 初始化

运行时配置

使用运行时配置提升部署灵活性：

public/config.js

window.__RUNTIME_CONFIG__ = {
  VITE_ORDERLY_BROKER_ID: 'your_broker_id',
  VITE_ORDERLY_BROKER_NAME: 'Your DEX Name',
  VITE_DISABLE_MAINNET: 'false',
  VITE_DISABLE_TESTNET: 'false',
  VITE_DEFAULT_CHAIN: '42161',
};

运行时配置加载器

// src/utils/runtime-config.ts

export function getRuntimeConfig(key: string): string {
  if (typeof window !== 'undefined' && window.__RUNTIME_CONFIG__?.[key]) {
    return window.__RUNTIME_CONFIG__[key];
  }
  return import.meta.env[key] || '';
}

export function getRuntimeConfigBoolean(key: string): boolean {
  return getRuntimeConfig(key) === 'true';
}

export function getRuntimeConfigArray(key: string): string[] {
  const value = getRuntimeConfig(key);
  if (!value) return [];
  return value
    .split(',')
    .map((s) => s.trim())
    .filter(Boolean);
}

declare global {
  interface Window {
    __RUNTIME_CONFIG__?: Record;
  }
}

应用根组件

// src/App.tsx
import { Outlet } from 'react-router-dom';
import { Suspense } from 'react';
import OrderlyProvider from '@/components/orderlyProvider';
import { LoadingSpinner } from '@/components/LoadingSpinner';
import { ErrorBoundary } from '@/components/ErrorBoundary';

export default function App() {
  return (
    
      
        }>
          
        
      
    
  );
}

TradingView 图表配置（必需）

关键要求：TradingView 图表库必须手动复制至您的 public/tradingview/ 目录中。

必需的文件结构

public/
└── tradingview/
    ├── chart.css                    # 可选：自定义图表样式
    └── charting_library/            # 必需：TradingView 库
        ├── charting_library.js      # 主库脚本
        ├── charting_library.d.ts
        └── ...（其他库文件）

获取 TradingView 库的方法

1. 申请访问权限：https://www.tradingview.com/HTML5-stock-forex-bitcoin-charting-library/
2. 下载 图表库压缩包
3. 复制 charting_library 文件夹至您的 public/tradingview/ 目录

TradingView 配置示例

// 在您的 TradingPage 组件中

Tailwind 配置

tailwind.config.ts

import type { Config } from 'tailwindcss';
import { OUITailwind } from '@orderly.network/ui';

export default {
  content: [
    './index.html',
    './src/**/*.{js,ts,jsx,tsx}',
    './node_modules/@orderly.network/**/*.{js,mjs}',
  ],
  presets: [OUITailwind.preset],
  theme: {
    extend: {},
  },
  plugins: [],
} satisfies Config;

src/styles/index.css

@import '@orderly.network/ui/dist/styles.css';

@tailwind base;
@tailwind components;
@tailwind utilities;

Vite 配置

重要提示：钱包连接器相关包依赖 Node.js 内置模块（如 Buffer），您必须添加 polyfill 支持。

npm install -D vite-plugin-node-polyfills

vite.config.ts

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { nodePolyfills } from 'vite-plugin-node-polyfills';
import path from 'path';

export default defineConfig({
  plugins: [
    react(),
    nodePolyfills({
      include: ['buffer', 'crypto', 'stream', 'util'],
      globals: {
        Buffer: true,
        global: true,
        process: true,
      },
    }),
  ],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
});

上线前检查清单

• Broker ID 已配置
• WalletConnect Project ID（移动端钱包所需）
• 运行时 config.js 已部署
• TradingView 库（若启用图表功能）
• 自定义品牌（Logo、favicon、主题色）
• 错误监控（Sentry 等）
• 数据分析集成
• SSL/HTTPS 已启用

关联技能

• orderly-sdk-install-dependency — SDK 包安装
• orderly-sdk-wallet-connection — 钱包集成细节
• orderly-sdk-page-components — 使用预构建页面组件
• orderly-sdk-trading-workflows — 端到端交易流程实现
• orderly-sdk-theming — UI 外观定制
• orderly-sdk-debugging — 常见问题排查