orderly-sdk-debugging

Orderly Network：SDK 调试

本指南介绍如何调试 Orderly SDK 的运行时行为，包括账户/身份验证状态、数据流、下单及存款/提款失败，以及 SDK 抛出的错误。

本指南涵盖 SDK 自身的运行时功能。对于构建/设置问题（Vite polyfill、CSS 导入、软件包版本），请参阅 orderly-sdk-install-dependency 和 orderly-sdk-dex-architecture；对于接线配置（provider 属性、.env 配置），请参阅 orderly-sdk-dex-architecture。

适用场景

• 调试账户/身份验证状态（“卡在连接中”“未登录”）
• 排查数据未加载的问题（订单簿、持仓、余额）
• 排查订单提交/被拒问题
• 排查存款/提款失败
• 了解 SDK 抛出的错误（ApiError / SDKError）

前置条件

• 已挂载 Orderly SDK providers（来自 @orderly.network/react-app 的 OrderlyAppProvider）
• 熟悉浏览器开发者工具

1. 账户与身份验证状态

SDK 账户会按固定的状态阶梯流转。大多数“什么都不能用”的问题，都是账户卡在 SignedIn 之前。

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

function AccountDebugger() {
  const { state, account } = useAccount();

  // state.status is an AccountStatusEnum (numeric)
  console.log('account state', state.status, AccountStatusEnum[state.status]);
  console.log('accountId', account?.accountId);
}

AccountStatusEnum（来自 @orderly.network/types）

值	名称	含义
-1	EnableTradingWithoutConnected	未连接钱包也启用了交易
0	NotConnected	未连接钱包
1	Connected	已连接钱包，但尚未解析 Orderly 账户
2	NotSignedIn	需要 EIP-712 / Ed25519 签名来创建 Orderly 密钥
3	SignedIn	已完成身份验证——私有数据流/订单可用
4	DisabledTrading	此账户的交易已禁用
5	EnableTrading	已启用交易

身份验证状态阶梯与常见卡点

NotConnected ──connect wallet──▶ Connected ──resolve account──▶ NotSignedIn ──sign──▶ SignedIn

症状	可能的状态	解决方法
私有数据（持仓/余额）为空	< SignedIn	引导用户完成登录（签名）
应用不断提示连接	NotConnected	检查 WalletConnectorProvider 是否已挂载并配置
“签名”始终无法完成	NotSignedIn	钱包拒绝了请求；重新提示用户。密钥在 365 天后过期
订单因未授权而被拒绝	NotSignedIn/Connected	账户必须处于 SignedIn 状态才能提交订单
state.validating 一直为 true	任意	解析账户的网络/请求卡住——检查 WS/网络

useAccount() 返回 { account, state, ... }；state 是一个 AccountState，包含 status: AccountStatusEnum 和 validating: boolean。

2. 数据未加载

公共数据流（订单簿、成交、标记价格）无需身份验证即可使用。私有数据流（持仓、订单、余额、钱包）要求账户处于 SignedIn 状态。如果公共数据显示正常但私有数据为空，请先检查账户状态（§1）。

WebSocket 连接状态

import { useWsStatus, WsNetworkStatus } from '@orderly.network/hooks';

function StreamHealth() {
  const ws = useWsStatus();
  // WsNetworkStatus is string-valued: 'connected' | 'unstable' | 'disconnected'
  return <span>{ws}</span>;
}

WsNetworkStatus	含义
Connected	WS 已连接；数据流正常传输
Unstable	连接已断开，SDK 正在重新连接
Disconnected	连接已丢失且未重新连接——请重新挂载 provider

启动/预加载状态

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

const { done, error } = usePreLoadData();
// done === false for the lifetime of the app = the initial data fetch failed/stalled

检查清单：数据未加载

• useWsStatus() 的状态是 Connected 吗？
• 对于私有数据：state.status >= SignedIn 吗？
• networkId 与预期的链匹配（mainnet 还是 testnet）吗？
• usePreLoadData().done === true 吗？
• 符号字符串完全准确，例如 PERP_ETH_USDC？
• 控制台中没有 SDK 错误（§5）吗？

3. 订单提交错误

useOrderEntry(symbol, options) 会在提交之前提供订单就绪状态和验证信息。检查 metaState 并调用 helper.validate()。

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

function OrderDebugger() {
  const { formattedOrder, metaState, helper, maxQty, estLiqPrice, submit } =
    useOrderEntry('PERP_ETH_USDC');

  // metaState.errors: OrderValidationResult | null  (null = valid)
  // metaState.validated: boolean
  console.log({ ready: metaState.validated && !metaState.errors, maxQty, estLiqPrice });

  async function place() {
    try {
      const res = await submit({ resetOnSuccess: true });
      console.log('ok', res);
    } catch (e) {
      // SDK wraps REST failures in ApiError (see §5)
      console.error('order failed', e);
    }
  }
}

通过 setValue() 设置的字段键包括：side、order_type、order_price、order_quantity、reduce_only、tp_trigger_price、sl_price。提交变更标志由 metaState 驱动／由该 Hook 上的 isMutating 表示——没有 isSubmitting。

读取订单流中的订单状态

import { useOrderStream } from '@orderly.network/hooks';
import { OrderStatus } from '@orderly.network/types';

const [orders] = useOrderStream({ status: OrderStatus.INCOMPLETE });
// OrderStatus: OPEN | NEW | FILLED | PARTIAL_FILLED | CANCELLED | REPLACED | COMPLETED | INCOMPLETE | REJECTED

使用 OrderStatus.INCOMPLETE（而不是字符串 'OPEN'）查询未结订单。订单流中的 REJECTED 条目表示服务端拒绝了已提交的订单——请检查其原因字段。

检查清单：订单未提交／被拒绝

• state.status 是 SignedIn 吗？
• 符号完全准确（PERP_ETH_USDC）吗？
• metaState.errors 为 null（已验证）吗？
• 数量 ≥ 符号最小值（检查 maxQty）吗？
• 限价在标记价格的允许范围内吗？
• 有足够的可用抵押品（useCollateral().freeCollateral）吗？

4. 充值与提现错误

充值（需要先获得 ERC-20 授权）

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

function DepositDebugger() {
  const { balance, allowance, approve, deposit, dst } = useDeposit({
    /* srcChainId, token, ... */
  });

  async function run(amount: string) {
    // allowance must cover amount, else approve first
    if (Number(amount) > Number(allowance)) {
      await approve(amount); // wallet prompt
    }
    await deposit(); // NOTE: deposit() takes NO arguments
  }
}

• approve(amount?) 和 deposit() 都会触发钱包提示；请用 try/catch 包裹。
• deposit() 不接受参数——金额来自 Hook 的 quantity／setQuantity 状态。
• depositFee 是 bigint。

提现

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

const { withdraw, maxAmount, unsettledPnL } = useWithdraw({
  /* srcChainId, token, decimals */
});

await withdraw({
  chainId,
  token,
  amount,
  allowCrossChainWithdraw: true,
  // receiver?: '<optional custom address>'
});

• 使用 maxAmount 作为上限（不要使用已弃用的 availableWithdraw）。
• 未结算的 unsettledPnL 会减少可提现金额——如果提现因余额不足而失败，请检查该值。

读取提现就绪状态

WithdrawStatus（@orderly.network/types）：NotSupported | NotConnected | Unsettle（未结算的 PnL 会阻止提现）| InsufficientBalance | Normal。只有 Normal 状态可提现。

检测用户拒绝／交易金额不足

这些错误来自钱包／链，而非 Orderly API。根据 error.message 进行匹配：

catch (e) {
  const msg = String((e as Error)?.message ?? '');
  if (/reject|denied/i.test(msg))  /* user rejected the wallet prompt */;
  if (/insufficient/i.test(msg))   /* not enough gas/balance on-chain */;
}

5. 读取 SDK 错误

SDK 会从 @orderly.network/types 中抛出两类错误：

• ApiError——REST API 错误。使用 (message: string, code: number) 构造。数值 code 用于标识错误类别；请读取 error.message 获取详情。
• SDKError——客户端侧／SDK 内部错误。

import { ApiError, SDKError } from '@orderly.network/types';

try {
  await someSdkAction();
} catch (e) {
  if (e instanceof ApiError) {
    console.error('API error', e.message /* numeric code lives on the instance */);
  } else if (e instanceof SDKError) {
    console.error('SDK error', e.message);
  }
}

不要对 REST 错误代码表进行硬编码——代码可能会变化。请记录 error.message，并根据实际观察到的代码为对应工作流设置分支。

速率限制

REST -1003 类型的速率限制会以 ApiError 的形式出现。请使用退避策略重试：

async function withRetry<T>(fn: () => Promise<T>, retries = 3, base = 1000): Promise<T> {
  for (let i = 0; ; i++) {
    try {
      return await fn();
    } catch (e) {
      const code = (e as ApiError & { code?: number })?.code;
      if (code === -1003 && i < retries) {
        await new Promise((r) => setTimeout(r, base * 2 ** i));
        continue;
      }
      throw e;
    }
  }
}

5. 检查 Hook 状态

一个简单的日志记录器有助于跨渲染跟踪异步 Hook 输出：

function useDebugHook<T>(name: string, value: T): T {
  useEffect(() => {
    console.log(`[${name}]`, value);
  }, [name, value]);
  return value;
}

记住返回值形状（常见混淆点）

Hook	形状
usePositionStream	3 元组：[positions, calc, { isLoading }]
useCollateral	对象：{ totalCollateral, freeCollateral, availableBalance, ... }
useOrderEntry	对象：{ submit, metaState, helper, setValue, ... }
useAccount	对象：{ account, state, ... }（state.status）
useOrderStream	2 元组：[orders, { total, isLoading, cancelOrder, ... }]

解构时元数不匹配是常见的静默错误（例如，从第一个元素读取 isLoading）。

开发面板

function OrderlyDebugPanel() {
  const { state } = useAccount();
  const ws = useWsStatus();
  // mount this component only while developing (gate it however your app prefers)
  return (
    <div style={{ position: 'fixed', right: 8, bottom: 8, fontSize: 11 }}>
      <div>account: {state.status}</div>
      <div>ws: {ws}</div>
    </div>
  );
}

6. 错误边界

对于组件错误，请使用 SDK 的 ErrorBoundary（@orderly.network/react-app）：

import { ErrorBoundary } from '@orderly.network/react-app';

<ErrorBoundary fallback={<SomethingWentWrong />}>{children}</ErrorBoundary>;

路由级错误（延迟导入失败、抛出的加载器或操作错误）应由路由器的 errorElement 捕获。ErrorBoundary 用于 React 树。

调试清单

无法正常工作 / 应用页面空白

• OrderlyAppProvider 已挂载，且 brokerId / networkId 有效？
• usePreLoadData().done === true？
• useWsStatus() === Connected？

私有数据为空

• state.status 是 SignedIn？
• 所显示链的 networkId 是否正确？
• WS 状态为 Connected？

订单失败

• 已 SignedIn？
• metaState.errors === null？
• 数量 ≥ 最小值，价格在范围内？
• freeCollateral 是否充足？

存款 / 提现失败

• 授权额度是否足以覆盖存款金额（否则调用 approve）？
• withdraw 金额 ≤ maxAmount？
• 是否已考虑 unsettledPnL？
• 钱包提示是否被拒绝？

相关技能

• orderly-sdk-dex-architecture — Provider 配置与接线
• orderly-sdk-wallet-connection — 钱包集成
• orderly-api-authentication — 登录 / 密钥流程
• orderly-sdk-install-dependency — 软件包安装与构建设置