orderly-sdk-dex-architecture

Orderly Network：SDK DEX 架构

使用 Orderly Network Components SDK 设计和搭建完整 DEX 应用的综合指南。以下所有示例均与最新参考模板保持一致（SDK 3.1.x）。

适用场景

• 搭建新的 DEX 项目
• 了解 Provider 层级
• 配置网络设置和链筛选器
• 设置 TradingView 图表
• 了解 Provider 配置

前提条件

• 已安装 Node.js 20+（由 package.json 中的 engines 强制要求）
• 已安装 Orderly SDK 软件包（参见 orderly-sdk-install-dependency）
• 使用 TypeScript 的 React 18+ 项目
• Vite 7+ 构建工具

概述

本技能涵盖构建可用于生产环境的 DEX 所需的完整架构：

• 项目结构和设置（源目录为 app/，而非 src/）
• 通过 Vite .env 和 import.meta.env 配置
• Provider 层级和配置
• 网络配置 — 主网/测试网、链筛选器、默认链
• TradingView 图表设置 — 图表库文件
• 路由和页面组件
• 构建和部署（基础路径、SPA 输出）

关键配置：每个 DEX 都必须具备：

1. brokerId — 你的 Orderly 经纪商 ID（默认值为 "demo"）
2. networkId — "mainnet" 或 "testnet"
3. 正确设置与网络匹配的钱包连接器
4. public/tradingview/ 中的 TradingView 图表库（用于图表功能）

项目结构

my-dex/
├── public/
│   ├── favicon.webp
│   ├── locales/               # i18n translations
│   │   └── extend/            # Custom translations
│   ├── pnl/                   # PnL share poster backgrounds
│   └── tradingview/           # TradingView library (REQUIRED for charts)
│       ├── chart.css          # Custom chart styles
│       └── charting_library/  # TradingView charting library files
├── app/                       # <-- source root (NOT src/)
│   ├── main.tsx               # Entry point — mounts React (router + providers)
│   ├── App.tsx                # Root layout (provider + <Outlet/>)
│   ├── components/
│   │   ├── orderlyProvider/   # SDK provider setup
│   │   │   ├── index.tsx      # Main provider wrapper
│   │   │   ├── walletConnector.tsx
│   │   │   ├── privyConnector.tsx
│   │   │   └── orderlyLocaleProvider.tsx
│   │   ├── ErrorBoundary.tsx
│   │   └── LoadingSpinner.tsx
│   ├── pages/                 # route components
│   │   ├── perp/              # trading (index + [symbol])
│   │   ├── portfolio/
│   │   ├── markets/
│   │   ├── leaderboard/
│   │   ├── rewards/
│   │   ├── vaults/
│   │   ├── swap/
│   │   └── points/
│   ├── utils/
│   │   ├── config.tsx         # App configuration (nav, scaffold props)
│   │   ├── walletConfig.ts    # Wallet connectors
│   │   ├── theme-config.ts    # resolveDexThemeConfig()
│   │   ├── trading-view-config.ts
│   │   ├── symbol-filter.ts   # createSymbolDataAdapter()
│   │   └── base-path.ts       # withBasePath() helper
│   └── styles/
│       └── index.css          # Global styles + Tailwind
├── .env                       # Environment configuration (VITE_* vars read via import.meta.env)
├── index.html
├── package.json
├── tailwind.config.ts
├── tsconfig.json              # paths alias: "@/*": ["./app/*"]
└── vite.config.ts

配置

OrderlyAppProvider 和钱包连接器需要从你的应用中获取一些值，其中最重要的是：

值	SDK 属性	说明
经纪商 ID	brokerId	你的 Orderly 经纪商 ID；默认值为 "demo"
网络	networkId	"mainnet" 或 "testnet"
链列表	chainFilter	{ mainnet?: [{id}], testnet?: [{id}] }（不能是扁平格式）
默认链	defaultChain	{ mainnet: { id } }
主题	themes	主题数组（参见 orderly-sdk-theming）
标志	appIcons	AppLogos（参见 orderly-sdk-theming）

这些值的来源由你的应用自行决定——可以是静态配置模块、.env，或其他方式。参考模板通过 import.meta.env.VITE_* 使用 Vite .env（在构建时内联）：

# .env (reference template keys — one possible config source)
VITE_ORDERLY_BROKER_ID=your_broker_id        # unset => "demo" broker
VITE_ORDERLY_BROKER_NAME=Your DEX Name
VITE_DEFAULT_CHAIN=42161
VITE_ORDERLY_MAINNET_CHAINS=42161,10,8453
VITE_ORDERLY_TESTNET_CHAINS=421614,84532
VITE_PRIVY_APP_ID=                           # set ONLY to use Privy (see wallet-connection)
VITE_WALLETCONNECT_PROJECT_ID=               # required for WalletConnect / mobile wallets
VITE_RESTRICTED_REGIONS=                     # comma-separated ISO codes (see orderly-one-dex)
VITE_ORDERLY_THEME_CONFIG=                   # JSON theme array (see orderly-sdk-theming)

无需使用 config.js / window.__RUNTIME_CONFIG__。 只有在多实例部署中，同一构建需要使用不同配置时，运行时配置间接层才有意义——这是 Orderly One 的需求（参见 orderly-one-dex）。对于普通 DEX，.env（或静态配置模块）就足够了。

入口 — app/main.tsx

// app/main.tsx
import React, { lazy } from 'react';
import ReactDOM from 'react-dom/client';
import { HelmetProvider } from 'react-helmet-async';
import { createBrowserRouter, RouterProvider } from 'react-router-dom';
import App from './App';
import './styles/index.css';

// ... lazy page imports ...

const router = createBrowserRouter(
  [
    /* routes */
  ],
  {
    basename: import.meta.env.BASE_URL || '/',
  }
);

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <HelmetProvider>
      <RouterProvider router={router} />
    </HelmetProvider>
  </React.StrictMode>
);

Provider 层级

SDK 要求 Provider 按特定顺序嵌套。OrderlyLocaleProvider（国际化）包裹所有内容；钱包连接器（或 Privy）包裹 OrderlyAppProvider。

OrderlyLocaleProvider (i18n)
└── Suspense
    └── WalletConnectorProvider  (or PrivyConnectorProvider)
        └── OrderlyAppProvider
            ├── (internal) AppConfigProvider
            ├── (internal) OrderlyThemeProvider   ← uses the `themes` prop
            ├── (internal) OrderlyConfigProvider (from hooks)
            ├── (internal) AppStateProvider
            ├── (internal) UILocaleProvider
            ├── (internal) TooltipProvider
            ├── (internal) ModalProvider
            └── Your App

TooltipProvider 和 ModalProvider 由 OrderlyAppProvider 内部管理。无需自行添加它们。

OrderlyAppProvider 属性

核心 Provider（@orderly.network/react-app）。主要属性：

属性	类型	说明
brokerId	string	你的 Broker ID（默认使用 "demo"）
brokerName	string	显示名称
networkId	"mainnet" | "testnet"	当前网络
chainFilter	{ mainnet?: [{id}]; testnet?: [{id}] }	限制可切换的链（不是扁平的 ID 数组）
defaultChain	{ mainnet: { id } }	初始链
themes	主题数组	参见 orderly-sdk-theming
appIcons	AppLogos	Logo（参见 orderly-sdk-theming）
dataAdapter	适配器	自定义交易对数据适配器
onChainChanged	(chainId, { isTestnet }) => void	用户切换链时触发
restrictedInfo	{ customRestrictedRegions?: string[] }	地理限制（参见 orderly-one-dex）

TooltipProvider、ModalProvider、AppConfigProvider、OrderlyThemeProvider、OrderlyConfigProvider 和 AppStateProvider 均由 OrderlyAppProvider 内部挂载。请勿自行添加。

最简 Provider

Provider 的嵌套顺序为：i18n（OrderlyLocaleProvider）→ 钱包连接器 → OrderlyAppProvider。从你的应用传入中性的配置值（来源不限）：

// app/components/orderlyProvider/index.tsx
import { ReactNode, useCallback } from 'react';
import { OrderlyAppProvider } from '@orderly.network/react-app';
import type { NetworkId } from '@orderly.network/types';
import { OrderlyLocaleProvider } from './orderlyLocaleProvider';
import { WalletConnector } from './walletConnector';

export function OrderlyProvider({ children }: { children: ReactNode }) {
  const networkId: NetworkId = 'mainnet'; // from your config

  const onChainChanged = useCallback((_chainId: number, { isTestnet }: { isTestnet: boolean }) => {
    // flip networkId + reload on mainnet <-> testnet switches
  }, []);

  return (
    <OrderlyLocaleProvider>
      <WalletConnector networkId={networkId}>
        <OrderlyAppProvider
          brokerId={brokerId} // from your config
          brokerName={brokerName}
          networkId={networkId}
          themes={themes} // see orderly-sdk-theming
          appIcons={appIcons}
          chainFilter={{ mainnet: [{ id: 42161 }, { id: 10 }] }} // optional
          defaultChain={{ mainnet: { id: 42161 } }} // optional
          onChainChanged={onChainChanged}
        >
          {children}
        </OrderlyAppProvider>
      </WalletConnector>
    </OrderlyLocaleProvider>
  );
}

chainFilter 的格式为 { mainnet?: [{id}], testnet?: [{id}] }——不是扁平的 ID 数组。defaultChain 的格式为 { mainnet: { id } }。需要社交登录时，将 WalletConnector 替换为 Privy 连接器（参见 orderly-sdk-wallet-connection）。

钱包连接器设置

WalletConnectorProvider（@orderly.network/wallet-connector）包裹 OrderlyAppProvider。evmInitial 和 solanaInitial 都是必需配置的属性——它们包含钱包网络和钱包列表，因此真实的 DEX 应传入这些属性，而不是省略。传入 undefined 可禁用其中一方：

// app/components/orderlyProvider/walletConnector.tsx
import { ReactNode } from 'react';
import { WalletConnectorProvider } from '@orderly.network/wallet-connector';
import { WalletAdapterNetwork } from '@solana/wallet-adapter-base';
import type { NetworkId } from '@orderly.network/types';
import { getEvmInitialConfig, getSolanaWallets } from '@/utils/walletConfig';

const WalletConnector = ({
  children,
  networkId,
  disableEvm,
  disableSolana,
}: {
  children: ReactNode;
  networkId: NetworkId;
  disableEvm?: boolean; // from your config
  disableSolana?: boolean; // from your config
}) => (
  <WalletConnectorProvider
    evmInitial={disableEvm ? undefined : getEvmInitialConfig()}
    solanaInitial={
      disableSolana
        ? undefined
        : {
            network:
              networkId === 'mainnet' ? WalletAdapterNetwork.Mainnet : WalletAdapterNetwork.Devnet,
            wallets: getSolanaWallets(networkId),
          }
    }
  >
    {children}
  </WalletConnectorProvider>
);
export default WalletConnector;

WalletConnectorProvider（Solana 网络）和 OrderlyAppProvider 中的 networkId 必须一致。有关 evmInitial / solanaInitial 的结构和 Privy 连接器，请参见 orderly-sdk-wallet-connection。

网络配置

支持的网络

主网链（生产环境）

链	链 ID	说明
Arbitrum	42161	主要主网链
Optimism	10	OP 主网
Base	8453	Base 主网
Ethereum	1	Ethereum 主网
Solana	N/A	Solana 主网

测试网链（开发环境）

链	链 ID	说明
Arbitrum Sepolia	421614	主要测试网链
Base Sepolia	84532	Base 测试网
Solana Devnet	901901901	Solana Devnet

链筛选器

限制用户可以切换的链。chainFilter 是一个以网络为键的对象，每个值都是 { id } 数组：

// from VITE_ORDERLY_MAINNET_CHAINS="42161,10,8453"
//   => { mainnet: [{ id: 42161 }, { id: 10 }, { id: 8453 }] }
// from VITE_DEFAULT_CHAIN="42161"
//   => defaultChain = { mainnet: { id: 42161 } }

应用根组件

// app/App.tsx
import { Outlet } from 'react-router-dom';
import OrderlyProvider from '@/components/orderlyProvider';

export default function App() {
  return (
    <OrderlyProvider>
      <Outlet />
    </OrderlyProvider>
  );
}

HelmetProvider 和 RouterProvider 位于 main.tsx 中（参见配置）。完整模板会在此处添加 SEO <Helmet> 和 HTTPS 警告。

TradingView 图表设置（图表必需）

重要：TradingView 图表库必须手动添加到你的 public/tradingview/ 文件夹中（不会通过 npm 分发）。

必需的文件结构

public/
└── tradingview/
    ├── chart.css                    # Optional: custom chart styling
    └── charting_library/            # REQUIRED: TradingView library
        ├── charting_library.js      # Main library script
        ├── charting_library.d.ts
        └── ... (other library files)

如何获取 TradingView 库

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

TradingView 配置

TradingPage 接受一个 tradingViewConfig。在模板中，它由 createTradingViewConfig(source) 生成（完整的颜色配置请参见 orderly-sdk-theming）；内联配置如下：

<TradingPage
  symbol={symbol}
  tradingViewConfig={{
    scriptSRC: '/tradingview/charting_library/charting_library.js',
    library_path: '/tradingview/charting_library/',
    customCssUrl: '/tradingview/chart.css',
    colorConfig: { upColor: '#26a69a', downColor: '#ef5350' },
  }}
/>

Tailwind 配置

// tailwind.config.ts
import type { Config } from 'tailwindcss';

export default {
  // content globs point at app/, NOT src/. No preset, no custom brand colors.
  content: ['./app/**/{**,.client,.server}/**/*.{js,jsx,ts,tsx}'],
  theme: {
    extend: {
      fontFamily: { sans: ['Inter', 'ui-sans-serif', 'system-ui', 'sans-serif'] },
    },
  },
  plugins: [],
} satisfies Config;

/* app/styles/index.css */
@import '@orderly.network/ui/dist/styles.css';
@tailwind base;
@tailwind components;
@tailwind utilities;

Vite 配置

钱包连接器 / Solana 包使用 Node 内置模块（Buffer、crypto、stream）。仅为 这三个模块添加 polyfill，不要添加 util 或 globals（它们会导致构建失败）。部分依赖使用 CommonJS，必须通过 vite-plugin-cjs-interop 进行互操作。路径别名通过 vite-tsconfig-paths 从 tsconfig.json 获取（无需手动配置 resolve.alias）。

npm install -D vite-plugin-node-polyfills vite-plugin-cjs-interop vite-tsconfig-paths

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import tsconfigPaths from 'vite-tsconfig-paths';
import { cjsInterop } from 'vite-plugin-cjs-interop';
import { nodePolyfills } from 'vite-plugin-node-polyfills';

export default defineConfig(() => ({
  base: process.env.PUBLIC_PATH || '/', // base path for sub-path deploys
  plugins: [
    react(),
    tsconfigPaths(), // reads "@/*" from tsconfig.json
    cjsInterop({ dependencies: ['bs58', '@coral-xyz/anchor', 'lodash'] }),
    nodePolyfills({ include: ['buffer', 'crypto', 'stream'] }), // NO util, NO globals
  ],
  build: { outDir: 'build/client' },
  optimizeDeps: { include: ['react', 'react-dom', 'react-router-dom'] },
}));

tsconfig.json 路径别名：

{ "compilerOptions": { "paths": { "@/*": ["./app/*"] } } }

生产环境检查清单

• 在 .env 中配置 Broker ID（或有意使用 "demo"）
• 在 .env 中配置 WalletConnect 项目 ID（用于移动钱包）
• 将 TradingView 库放入 public/tradingview/（如果使用图表）
• 在 .env 中设置链过滤器 / 默认链
• 自定义品牌（徽标、网站图标、主题——请参见 orderly-sdk-theming）
• 错误跟踪（Sentry 等）
• 集成分析工具
• 启用 SSL/HTTPS
• 为子路径部署设置 PUBLIC_PATH

相关技能

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