From e37409faf5213ab1d791e2276175737238d31319 Mon Sep 17 00:00:00 2001 From: Wuzhong Date: Thu, 7 May 2026 15:31:13 +0800 Subject: [PATCH] SDK V3 update, adding in plugin skills --- README.md | 21 ++- skills/orderly-onboarding/SKILL.md | 6 +- .../orderly-sdk-install-dependency/SKILL.md | 30 +++- skills/orderly-sdk-plugins/SKILL.md | 165 ++++++++++++++++++ skills/orderly-sdk-react-hooks/SKILL.md | 2 +- 5 files changed, 207 insertions(+), 17 deletions(-) create mode 100644 skills/orderly-sdk-plugins/SKILL.md diff --git a/README.md b/README.md index b92f657..8df03fd 100644 --- a/README.md +++ b/README.md @@ -119,6 +119,7 @@ npx skills add OrderlyNetwork/skills --skill orderly-onboarding -g | | `orderly-sdk-page-components` | Pre-built page components (TradingPage, Portfolio, Markets) | | | `orderly-sdk-theming` | CSS variable theming and customization | | | `orderly-sdk-trading-workflows` | End-to-end trading flows (connect → deposit → trade → withdraw) | +| | `orderly-sdk-plugins` | Create, integrate, and debug SDK plugins, interceptors, and layout customization | | **Platform** | `orderly-sdk-wallet-connection` | Wallet integration for EVM and Solana chains | | | `orderly-sdk-debugging` | Debug and troubleshoot SDK errors | | | `orderly-one-dex` | Create and manage custom DEX with Orderly One API | @@ -146,6 +147,7 @@ npx @orderly.network/mcp-server init --client **IMPORTANT**: A functional DEX requires BOTH the Orderly packages AND the wallet connector dependencies. The `@orderly.network/wallet-connector` package needs `@web3-onboard/*` packages for EVM wallets and `@solana/wallet-adapter-*` packages for Solana wallets. -> > **Note**: `@orderly.network/hooks` is included as a transitive dependency via `@orderly.network/react-app` — you do not need to install it separately for most DEX projects. Only install it directly if you are using the hooks-only integration path without `react-app`. ```bash @@ -35,10 +33,10 @@ npm install @orderly.network/react-app \ @orderly.network/wallet-connector \ @orderly.network/i18n -# REQUIRED: EVM wallet support (MetaMask, WalletConnect, etc.) +# Optional: EVM wallet support for custom wallet configuration npm install @web3-onboard/injected-wallets @web3-onboard/walletconnect -# REQUIRED: Solana wallet support (Phantom, Solflare, etc.) +# Optional: Solana wallet support for custom wallet configuration npm install @solana/wallet-adapter-base @solana/wallet-adapter-wallets ``` @@ -72,7 +70,6 @@ Complete, pre-built page components with full functionality. | `@orderly.network/affiliate` | Referral/affiliate program page | `AffiliatePage` | | `@orderly.network/trading-leaderboard` | Trading competition leaderboard | `LeaderboardPage` | | `@orderly.network/trading-rewards` | Trading rewards program page | `TradingRewardsPage` | -| `@orderly.network/trading-points` | Trading points/merits program page | `TradingPointsPage` | ```bash npm install @orderly.network/trading @orderly.network/portfolio @orderly.network/markets @@ -130,11 +127,26 @@ Individual UI modules for custom integrations. These are dependencies of `@order | `@orderly.network/ui-connector` | Wallet connect button & modal | `ConnectWalletButton` | | `@orderly.network/ui-tradingview` | TradingView chart wrapper | `TradingViewChart` | | `@orderly.network/ui-notification` | Notification center | `NotificationWidget` | +| `@orderly.network/layout-core` | Trading layout strategy protocol | `LayoutHost`, `LayoutStrategy`, `TRADING_PANEL_IDS`, `getTradingPanelIds` | +| `@orderly.network/layout-split` | Split-pane trading layout plugin | `registerLayoutSplitPlugin`, `getDefaultSplitPresets` | +| `@orderly.network/layout-grid` | Grid trading layout plugin | `registerLayoutGridPlugin` | +| `@orderly.network/plugin-core` | SDK plugin and interceptor helpers | `createInterceptor`, plugin/interceptor types | ```bash npm install @orderly.network/ui-scaffold @orderly.network/ui-order-entry ``` +### Plugin and Layout Customization + +Install these when building extension plugins, injected widgets, or custom trading layouts: + +```bash +npm install @orderly.network/plugin-core \ + @orderly.network/layout-core \ + @orderly.network/layout-split \ + @orderly.network/layout-grid +``` + ## Low-Level Packages For advanced customization or non-React environments. @@ -282,10 +294,10 @@ All `@orderly.network/*` packages should use the same version to ensure compatib ```json { "dependencies": { - "@orderly.network/react-app": "^2.8.0", - "@orderly.network/trading": "^2.8.0", - "@orderly.network/hooks": "^2.8.0", - "@orderly.network/ui": "^2.8.0" + "@orderly.network/react-app": "^3.0.2", + "@orderly.network/trading": "^3.0.2", + "@orderly.network/hooks": "^3.0.2", + "@orderly.network/ui": "^3.0.2" } } ``` diff --git a/skills/orderly-sdk-plugins/SKILL.md b/skills/orderly-sdk-plugins/SKILL.md new file mode 100644 index 0000000..892cf8c --- /dev/null +++ b/skills/orderly-sdk-plugins/SKILL.md @@ -0,0 +1,165 @@ +--- +name: orderly-sdk-plugins +description: Create, integrate, and debug Orderly SDK plugins, interceptors, widget plugins, page plugins, and custom trading layout plugins. +--- + +# Orderly Network: SDK Plugins + +Use this skill when an agent needs to extend the Orderly Components SDK beyond normal page/component props: injected widgets, custom trading controls, plugin packages, or split/grid layout customization. + +## When to Use + +- Creating a new Orderly plugin package +- Injecting a widget into an existing SDK component +- Customizing the desktop trading layout +- Integrating `registerXxxPlugin()` into a host DEX +- Finding supported interceptor target paths + +## Core Concepts + +Orderly SDK plugins are npm packages that export a register function. The host calls that function and passes the result into the SDK plugin provider. + +| Plugin Type | How It Integrates | Typical Use | +| ----------- | ----------------- | ----------- | +| Page | Host mounts it as a normal route | Campaigns, dashboards, custom pages | +| Widget | Intercepts a supported target path | Buttons, analytics panels, custom order-entry sections | +| Layout | Intercepts `Trading.Layout.Desktop` | Split/grid/pro trading layouts | + +Only SDK components declared as injectable can be intercepted. Do not invent target names. Use the SDK inspector or AI docs exact lookup to verify target paths. + +## Required Packages + +```bash +npm install @orderly.network/plugin-core @orderly.network/ui @orderly.network/hooks + +# For layout plugins +npm install @orderly.network/layout-core @orderly.network/layout-split @orderly.network/layout-grid +``` + +## Agent Workflow + +1. Determine the plugin type: Page, Widget, or Layout. +2. Verify the target path before coding. + - Prefer `orderly_docs_get_component` for exact targets such as `Trading.OrderEntry.SubmitSection`. + - Use `orderly_docs_get_component_doc` for examples after the exact entity is found. + - Use `orderly_docs_get_workflow` with `plugin-create` or `plugin-integration` for generated guidance. +3. Create a globally unique plugin ID. + - IDs must match `/^[a-zA-Z][a-zA-Z0-9]*$/`. + - No hyphens, underscores, dots, or leading digits. +4. Build the smallest verifiable behavior first. +5. Register the plugin in the host app in deterministic order. +6. Verify the target renders once and does not duplicate or remount unexpectedly. + +## Widget Plugin Example + +Use hooks inside a React wrapper component returned from the interceptor. Do not call hooks directly in the outer interceptor function. + +```tsx +import { createInterceptor, type OrderlySDK } from "@orderly.network/plugin-core"; +import { useOrderEntry } from "@orderly.network/hooks"; + +export function registerBuySellPlugin() { + return (SDK: OrderlySDK) => + SDK.registerPlugin({ + id: "BuySellPlugin", + name: "Buy Sell Plugin", + version: "1.0.0", + orderlyVersion: ">=3.0.0", + interceptors: [ + createInterceptor("Trading.OrderEntry.SubmitSection", (Original, props) => { + const Wrapper = () => { + const symbol = (props as { symbol?: string }).symbol ?? "PERP_BTC_USDC"; + const { submit, setValue } = useOrderEntry(symbol); + + return ( +
+ + +
+ ); + }; + + return ; + }), + ], + }); +} +``` + +## Host Integration + +Wrap the trading app or relevant subtree with the plugin provider and pass invoked register functions. + +```tsx +import { OrderlyPluginProvider } from "@orderly.network/plugin-core"; +import { TradingPage } from "@orderly.network/trading"; +import { registerBuySellPlugin } from "./plugins/buySell"; + +export function PerpPage() { + return ( + + + + ); +} +``` + +If the app already has a provider-level `plugins` prop or wrapper, add the register function there instead of creating nested ownership. + +## Layout Plugins + +Layout plugins target only the trading desktop layout today. + +```tsx +import { OrderlyPluginProvider } from "@orderly.network/plugin-core"; +import { registerLayoutSplitPlugin } from "@orderly.network/layout-split"; +import { registerLayoutGridPlugin } from "@orderly.network/layout-grid"; + + + +; + + + +; +``` + +Hosts can also pass layout props directly to `TradingPage` when they want ownership without plugin registration: + +```tsx + createDefaultMyLayout(getTradingPanelIds())} + storageKey="my_trading_layout" +/> +``` + +## Failure Recovery + +| Problem | Action | +| ------- | ------ | +| Plugin is not visible | Verify provider wiring, invoked register function, and exact target spelling | +| Target does not match | Check SDK inspector or `orderly_docs_get_component`; fallback to nearest supported target | +| Hooks error | Move hook calls into a wrapper component returned by the interceptor | +| Duplicate rendering | Check provider nesting and plugin registration order | +| Layout does not apply | Confirm the host is not already passing `layoutStrategy` / `getInitialLayout` | +| Missing exact anchor | Document the unsupported target, use nearest parent/adjacent target, or fork SDK to add `injectable` | + +## Guardrails + +- Never log private keys, seeds, API secrets, or signed payload secrets from plugins. +- Use `Decimal` from `@orderly.network/utils` for financial amounts. +- Confirm network and chain before initiating wallet signing or trading actions. +- Prefer exact AI-docs lookups over semantic guesses for target paths, component props, hooks, and package surfaces. + +## Related Skills + +- **orderly-sdk-dex-architecture** - Provider hierarchy and DEX structure +- **orderly-sdk-page-components** - TradingPage and page module usage +- **orderly-sdk-react-hooks** - Hooks available inside plugin wrapper components +- **orderly-ui-components** - Base and trading UI component usage diff --git a/skills/orderly-sdk-react-hooks/SKILL.md b/skills/orderly-sdk-react-hooks/SKILL.md index 4e0de4f..dfcb8e0 100644 --- a/skills/orderly-sdk-react-hooks/SKILL.md +++ b/skills/orderly-sdk-react-hooks/SKILL.md @@ -31,7 +31,7 @@ yarn add @orderly.network/hooks @orderly.network/types ## Setup ```typescript -import { OrderlyAppProvider } from '@orderly.network/react'; +import { OrderlyAppProvider } from '@orderly.network/react-app'; import { QueryClient, QueryClientProvider } from '@tanstack/react-query'; const queryClient = new QueryClient();