orderly-sdk-dex-architecture

Orderly Network：SDK DEX アーキテクチャ

Orderly Network Components SDK を使用して、完全な DEX アプリケーションを設計し、スキャフォールディングするための包括的なガイドです。以下のすべての例は、最新のリファレンステンプレート（SDK 3.1.x）に準拠しています。

使用する場面

• 新しい DEX プロジェクトをセットアップする
• プロバイダー階層を理解する
• ネットワーク設定とチェーンフィルターを構成する
• TradingView チャートをセットアップする
• プロバイダーの構成を理解する

前提条件

• Node.js 20+ がインストールされていること（package.json の engines で必須）
• Orderly SDK パッケージがインストールされていること（orderly-sdk-install-dependency を参照）
• TypeScript を使用した React 18+ プロジェクト
• Vite 7+ ビルドツール

概要

このスキルでは、本番環境に対応した DEX を構築するための完全なアーキテクチャを取り上げます。

• プロジェクト構成とセットアップ（ソースディレクトリは src/ ではなく app/ です）
• Vite .env と import.meta.env による構成
• プロバイダー階層と構成
• ネットワーク構成 — mainnet/testnet、チェーンフィルター、デフォルトチェーン
• 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__ は不要です。 実行時構成を介する方法が適しているのは、1 つのビルドを異なる構成で再利用するマルチインスタンスデプロイの場合だけです。これは 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>
);

プロバイダー階層

SDK では、プロバイダーを特定の順序でネストする必要があります。OrderlyLocaleProvider（i18n）がすべてをラップし、その内側でウォレットコネクター（または 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 の Props

コアプロバイダー（@orderly.network/react-app）です。主な Props：

Prop	Type	Notes
brokerId	string	ブローカー ID（デフォルトは "demo"）
brokerName	string	表示名
networkId	"mainnet" | "testnet"	アクティブなネットワーク
chainFilter	{ mainnet?: [{id}]; testnet?: [{id}] }	切り替え可能なチェーンを制限します（フラットな ID 配列ではありません）
defaultChain	{ mainnet: { id } }	初期チェーン
themes	theme array	orderly-sdk-theming を参照してください
appIcons	AppLogos	ロゴ（orderly-sdk-theming を参照してください）
dataAdapter	adapter	カスタムシンボルデータアダプター
onChainChanged	(chainId, { isTestnet }) => void	ユーザーがチェーンを切り替えたときに呼び出されます
restrictedInfo	{ customRestrictedRegions?: string[] }	地域制限（orderly-one-dex を参照してください）

TooltipProvider、ModalProvider、AppConfigProvider、OrderlyThemeProvider、OrderlyConfigProvider、AppStateProvider はすべて OrderlyAppProvider によって内部でマウントされます。自分で追加しないでください。

最小構成の 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 はどちらも設定用の Props です。ウォレットネットワークとウォレットリストを指定するため、実際の 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;

networkId は WalletConnectorProvider（Solana ネットワーク）と OrderlyAppProvider の間で一致している必要があります。evmInitial／solanaInitial の形式と Privy コネクターについては、orderly-sdk-wallet-connection を参照してください。

ネットワーク設定

サポート対象のネットワーク

メインネットチェーン（本番環境）

Chain	Chain ID	Description
Arbitrum	42161	主要なメインネットチェーン
Optimism	10	OP メインネット
Base	8453	Base メインネット
Ethereum	1	Ethereum メインネット
Solana	N/A	Solana メインネット

テストネットチェーン（開発環境）

Chain	Chain ID	Description
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）を使用します。ポリフィルを追加するのはこの 3 つだけにしてください。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 でブローカー ID を設定する（または意図的に "demo" を使用する）
• .env で WalletConnect プロジェクト ID を設定する（モバイルウォレット用）
• public/tradingview/ に 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 - よくある問題のトラブルシューティング