@orbs-network/spot-react 0.0.46 → 0.0.48

package/.cursor/rules

@@ -1,831 +0,0 @@
-# @orbs-network/spot-react Integration Guide
-
-## Overview
-`@orbs-network/spot-react` is a React component library for building Spot trading interfaces (TWAP, Limit, Stop-Loss, Take-Profit orders) on EVM chains.
-
-## Installation
-```bash
-npm install @orbs-network/spot-react
-# or
-pnpm add @orbs-network/spot-react
-```
-
-## Required Peer Dependencies
-- react ^18.0.0 || ^19.0.0
-- react-dom ^18.0.0 || ^19.0.0
-
-## Core Setup Pattern
-
-### 1. Wrap your trading UI with SpotProvider
-
-```tsx
-import { 
-  SpotProvider, 
-  Module, 
-  Partners,
-  Components,
-  Token,
-  useSrcTokenPanel,
-  useDstTokenPanel,
-  // ... other hooks
-} from "@orbs-network/spot-react";
-
-function TradingPage() {
-  // Get wallet connection (wagmi example)
-  const { address, chainId } = useAccount();
-  const { data: walletClient } = useWalletClient();
-  
-  // Your token selection state
-  const [srcToken, setSrcToken] = useState<Token>();
-  const [dstToken, setDstToken] = useState<Token>();
-  
-  // Fetch balances (wei strings)
-  const srcBalance = useBalance(srcToken?.address); // "1000000000000000000"
-  const dstBalance = useBalance(dstToken?.address);
-  
-  // Fetch USD prices for 1 token
-  const srcUsd1Token = useUSDPrice(srcToken?.address); // "1850.50"
-  const dstUsd1Token = useUSDPrice(dstToken?.address);
-  
-  // Calculate market reference price (expected output for input amount)
-  const marketReferencePrice = useMarketPrice(srcToken, dstToken);
-  
-  // Settings
-  const slippage = 0.05; // 5%
-  
-  // Callbacks for order lifecycle events
-  const callbacks = useOrderCallbacks();
-  
-  return (
-    <SpotProvider
-      partner={Partners.Quick}           // Your partner ID
-      chainId={chainId}
-      module={Module.TWAP}               // TWAP | LIMIT | STOP_LOSS | TAKE_PROFIT
-      priceProtection={slippage}
-      minChunkSizeUsd={5}
-      
-      // Token data
-      srcToken={srcToken}
-      dstToken={dstToken}
-      srcBalance={srcBalance}
-      dstBalance={dstBalance}
-      srcUsd1Token={srcUsd1Token}
-      dstUsd1Token={dstUsd1Token}
-      
-      // Market price - CRITICAL: This should be the expected output amount
-      // for the typed input amount, not just a 1:1 ratio
-      marketReferencePrice={marketReferencePrice}
-      
-      // Wallet
-      account={address}
-      provider={walletClient?.transport}
-      
-      // UI Components (required)
-      components={{
-        Button: YourButton,
-        Tooltip: YourTooltip,
-        TokenLogo: YourTokenLogo,
-        Spinner: <YourSpinner />,
-      }}
-      
-      // Optional
-      callbacks={callbacks}
-      refetchBalances={() => refetchBalances()}
-      useToken={useTokenByAddress}       // Hook to get token by address
-      fees={0.25}                         // Fee percentage
-    >
-      <YourTradingUI />
-    </SpotProvider>
-  );
-}
-```
-
-### 2. Token Type Definition
-```tsx
-type Token = {
-  address: string;      // Contract address
-  symbol: string;       // Token symbol (e.g., "ETH")
-  decimals: number;     // Token decimals (e.g., 18)
-  logoUrl: string;      // Logo image URL
-};
-
-// Example conversion from your Currency type:
-const parseToSpotToken = (currency?: Currency): Token | undefined => {
-  if (!currency) return undefined;
-  return {
-    address: currency.address,
-    decimals: currency.decimals,
-    symbol: currency.symbol,
-    logoUrl: currency.logoUrl,
-  };
-};
-```
-
-### 3. Required UI Components
-
-```tsx
-// Button Component
-type ButtonProps = {
-  children: ReactNode;
-  onClick: () => void;
-  disabled?: boolean;
-  loading?: boolean;
-  style?: CSSProperties;
-  allowClickWhileLoading?: boolean;
-};
-
-const SpotButton = (props: ButtonProps) => {
-  return (
-    <Button isLoading={props.loading} onClick={props.onClick} disabled={props.disabled}>
-      {props.children}
-    </Button>
-  );
-};
-
-// Tooltip Component
-type TooltipProps = {
-  children?: ReactNode;
-  tooltipText?: string;
-};
-
-const SpotTooltip = (props: TooltipProps) => {
-  if (!props.tooltipText) return null;
-  return (
-    <Tooltip>
-      <TooltipTrigger>{props.children || <InfoIcon />}</TooltipTrigger>
-      <TooltipContent>{props.tooltipText}</TooltipContent>
-    </Tooltip>
-  );
-};
-
-// Token Logo Component
-type TokenLogoProps = {
-  token?: Token;
-  size?: number;
-  className?: string;
-};
-
-const SpotTokenLogo = ({ token }: TokenLogoProps) => {
-  return <Avatar src={token?.logoUrl ?? ""} />;
-};
-```
-
----
-
-## Using the Hooks
-
-### Token Panel Hooks
-
-#### `useSrcTokenPanel` / `useDstTokenPanel`
-Controls the source (sell) and destination (buy) token inputs.
-
-```tsx
-const TokenPanel = ({ isSrcToken }: { isSrcToken: boolean }) => {
-  const srcTokenPanel = useSrcTokenPanel();
-  const dstTokenPanel = useDstTokenPanel();
-  const panel = isSrcToken ? srcTokenPanel : dstTokenPanel;
-  
-  return (
-    <div>
-      <input
-        value={panel.value}
-        onChange={(e) => panel.onChange(e.target.value)}
-        disabled={!isSrcToken}  // Only src is editable
-      />
-      {panel.isLoading && <Spinner />}
-    </div>
-  );
-};
-```
-
-#### `useTypedSrcAmount`
-Get the current typed source amount.
-
-```tsx
-const Listener = () => {
-  const { amount } = useTypedSrcAmount();
-  
-  useEffect(() => {
-    // Sync with your app state
-    setInputAmount(amount ?? "");
-  }, [amount]);
-  
-  return null;
-};
-```
-
-### Order Configuration Hooks
-
-#### `useTradesPanel` (TWAP only)
-Configure number of trades for TWAP orders.
-
-```tsx
-const TradesPanel = () => {
-  const { totalTrades, onChange, label, tooltip, error } = useTradesPanel();
-  
-  return (
-    <Card error={Boolean(error)}>
-      <Label title={label} tooltip={tooltip} />
-      <div className="flex items-center gap-2">
-        <NumericInput
-          value={totalTrades?.toString() ?? ""}
-          onChange={(val) => onChange(Number(val))}
-        />
-        <span>Trades</span>
-      </div>
-    </Card>
-  );
-};
-```
-
-#### `useDurationPanel`
-Configure order expiration duration.
-
-```tsx
-import { DEFAULT_DURATION_OPTIONS } from "@orbs-network/spot-react";
-// Options: [{ text: "Minutes", value: 60 }, { text: "Hours", value: 3600 }, { text: "Days", value: 86400 }]
-
-const DurationPanel = () => {
-  const { duration, onInputChange, onUnitSelect, label, tooltip } = useDurationPanel();
-  
-  return (
-    <Card>
-      <Label title={label} tooltip={tooltip} />
-      <div className="flex items-center gap-2">
-        <NumericInput
-          value={duration.value?.toString() ?? ""}
-          onChange={(val) => onInputChange(val)}
-        />
-        <Select
-          value={duration.unit}
-          onChange={(unit) => onUnitSelect(unit)}
-          options={DEFAULT_DURATION_OPTIONS}
-        />
-      </div>
-    </Card>
-  );
-};
-```
-
-#### `useFillDelayPanel` (TWAP only)
-Configure delay between individual trades.
-
-```tsx
-const FillDelayPanel = () => {
-  const { fillDelay, onInputChange, onUnitSelect, label, tooltip } = useFillDelayPanel();
-  
-  return (
-    <Card>
-      <Label title={label} tooltip={tooltip} />
-      <div className="flex items-center gap-2">
-        <NumericInput
-          value={fillDelay.value?.toString() ?? ""}
-          onChange={(val) => onInputChange(val)}
-        />
-        <Select
-          value={fillDelay.unit}
-          onChange={(unit) => onUnitSelect(unit)}
-          options={DEFAULT_DURATION_OPTIONS}
-        />
-      </div>
-    </Card>
-  );
-};
-```
-
-### Price Hooks
-
-#### `useLimitPricePanel`
-Configure limit price for orders.
-
-```tsx
-const LimitPricePanel = () => {
-  const {
-    price,              // Current price value
-    onChange,           // Update price
-    percentage,         // Percentage from market price
-    onPercentageChange, // Update via percentage
-    usd,                // USD value
-    isLimitPrice,       // Is limit price enabled
-    toggleLimitPrice,   // Toggle on/off
-    onReset,            // Reset to market price
-    isLoading,
-    toToken,            // Destination token
-    label,
-    tooltip,
-  } = useLimitPricePanel();
-
-  return (
-    <div>
-      <div className="flex items-center gap-2">
-        {/* Toggle for non-LIMIT modules */}
-        <Switch checked={isLimitPrice} onCheckedChange={toggleLimitPrice} />
-        <Label title={label} tooltip={tooltip} />
-        {isLimitPrice && <button onClick={onReset}>Set to default</button>}
-      </div>
-      
-      {isLimitPrice && (
-        <div className="flex gap-2">
-          <div>
-            <span>{toToken?.symbol}</span>
-            <NumericInput value={price} onChange={onChange} isLoading={isLoading} />
-            <span>${usd}</span>
-          </div>
-          <NumericInput
-            value={percentage}
-            onChange={onPercentageChange}
-            suffix="%"
-            allowNegative
-          />
-        </div>
-      )}
-    </div>
-  );
-};
-```
-
-#### `useTriggerPricePanel` (Stop-Loss / Take-Profit only)
-Configure trigger price for conditional orders.
-
-```tsx
-const TriggerPricePanel = () => {
-  const {
-    price,
-    onChange,
-    percentage,
-    onPercentageChange,
-    onReset,
-    toToken,
-    usd,
-    label,
-    tooltip,
-  } = useTriggerPricePanel();
-
-  return (
-    <div>
-      <Label title={label} tooltip={tooltip} />
-      <button onClick={onReset}>Set to default</button>
-      <PriceInput
-        symbol={toToken?.symbol}
-        value={price}
-        onChange={onChange}
-        percentage={percentage}
-        onPercentageChange={onPercentageChange}
-        usd={usd}
-      />
-    </div>
-  );
-};
-```
-
-#### `useInvertTradePanel`
-Invert the price display direction.
-
-```tsx
-const PricesHeader = () => {
-  const { onInvert, isInverted, fromToken, isMarketPrice } = useInvertTradePanel();
-  
-  return (
-    <div className="flex items-center justify-between">
-      <span>
-        {isInverted ? "Buy " : "Sell "}
-        {fromToken?.symbol} {isMarketPrice ? "at best rate" : "at rate"}
-      </span>
-      {!isMarketPrice && (
-        <button onClick={onInvert}>
-          <ArrowLeftRightIcon />
-        </button>
-      )}
-    </div>
-  );
-};
-```
-
-### Validation
-
-#### `useInputErrors`
-Get current validation errors.
-
-```tsx
-const InputsErrorPanel = () => {
-  const error = useInputErrors();
-  // Returns: { type: InputErrors, value: string | number, message: string } | null
-  
-  if (!error) return null;
-  
-  return (
-    <div className="bg-destructive/50 p-2 rounded-md">
-      <AlertTriangleIcon />
-      <p>{error.message}</p>
-    </div>
-  );
-};
-
-// Available error types:
-enum InputErrors {
-  EMPTY_LIMIT_PRICE,
-  MAX_CHUNKS,
-  MIN_CHUNKS,
-  MIN_TRADE_SIZE,
-  MAX_FILL_DELAY,
-  MIN_FILL_DELAY,
-  MAX_ORDER_DURATION,
-  MIN_ORDER_DURATION,
-  MISSING_LIMIT_PRICE,
-  STOP_LOSS_TRIGGER_PRICE_GREATER_THAN_MARKET_PRICE,
-  TRIGGER_LIMIT_PRICE_GREATER_THAN_TRIGGER_PRICE,
-  TAKE_PROFIT_TRIGGER_PRICE_LESS_THAN_MARKET_PRICE,
-  EMPTY_TRIGGER_PRICE,
-  INSUFFICIENT_BALANCE,
-  MAX_ORDER_SIZE,
-}
-```
-
-### Order Submission
-
-#### `useSubmitOrderPanel`
-Full control over order submission flow.
-
-```tsx
-const SubmitSwap = () => {
-  const {
-    onSubmit,        // Call to submit order
-    onOpenModal,     // Call when opening confirmation modal  
-    onCloseModal,    // Call when closing modal
-    isLoading,       // Submission in progress
-    isSuccess,       // Order created successfully
-    isFailed,        // Order creation failed
-    parsedError,     // Error details { message, code }
-    orderId,         // Created order ID
-    status,          // SwapStatus enum
-    reset,           // Reset swap state
-  } = useSubmitOrderPanel();
-  
-  const [isOpen, setIsOpen] = useState(false);
-
-  const handleOpen = () => {
-    setIsOpen(true);
-    onOpenModal();  // Important: call this to prepare state
-  };
-
-  const handleClose = () => {
-    setIsOpen(false);
-    onCloseModal(); // Important: call this to cleanup
-  };
-
-  return (
-    <Dialog open={isOpen} onOpenChange={handleClose}>
-      <SubmitButton onClick={handleOpen} />
-      <DialogContent>
-        {parsedError ? (
-          <ErrorView error={parsedError} onClose={handleClose} />
-        ) : (
-          <Components.SubmitOrderPanel 
-            reviewDetails={
-              <Button onClick={onSubmit} isLoading={isLoading}>
-                Create Order
-              </Button>
-            }
-          />
-        )}
-      </DialogContent>
-    </Dialog>
-  );
-};
-```
-
-#### `useSubmitOrderButton`
-Just the button state (simpler).
-
-```tsx
-const SubmitButton = ({ onClick }: { onClick: () => void }) => {
-  const { disabled, text, loading } = useSubmitOrderButton();
-  // text: "Place Order" | "Enter Amount" | "Insufficient Funds" | "No Liquidity"
-  
-  return (
-    <Button onClick={onClick} disabled={disabled} isLoading={loading}>
-      {text}
-    </Button>
-  );
-};
-```
-
-### Order History
-
-#### `useOrderHistoryPanel`
-Display and filter order history.
-
-```tsx
-import { Components, OrderStatus, SelectMeuItem } from "@orbs-network/spot-react";
-
-const OrdersPanel = () => {
-  const {
-    orders,              // { all: Order[], open: Order[], completed: Order[], ... }
-    selectedOrder,       // Currently selected order details
-    onSelectStatus,      // Filter by status
-    statuses,            // Available status filters
-    selectedStatus,      // Current filter
-    onHideSelectedOrder, // Go back to list
-  } = useOrderHistoryPanel();
-
-  const handleSelectStatus = (item: SelectMeuItem) => {
-    onSelectStatus(item.value === "all" ? undefined : item.value as OrderStatus);
-  };
-
-  return (
-    <div>
-      <header>
-        {selectedOrder && (
-          <button onClick={onHideSelectedOrder}>
-            <ArrowLeftIcon />
-          </button>
-        )}
-        <h2>{selectedOrder?.title ?? `Orders (${orders.all?.length})`}</h2>
-      </header>
-      
-      {!selectedOrder && (
-        <Select
-          value={selectedStatus}
-          onChange={handleSelectStatus}
-          options={statuses}
-        />
-      )}
-      
-      {/* Pre-built Orders component */}
-      <Components.Orders />
-    </div>
-  );
-};
-```
-
-### Other Useful Hooks
-
-#### `useDisclaimerPanel`
-Show module-specific disclaimer.
-
-```tsx
-const Disclaimer = () => {
-  const message = useDisclaimerPanel();
-  // Returns: { text: string, url: string } | null
-  
-  if (!message) return null;
-  
-  return (
-    <div>
-      <InfoIcon />
-      <p>
-        {message.text}{" "}
-        <a href={message.url} target="_blank">Learn more</a>
-      </p>
-    </div>
-  );
-};
-```
-
-#### `useTranslations`
-Get translated strings.
-
-```tsx
-const t = useTranslations();
-
-// Usage:
-t("placeOrder")      // "Place Order"
-t("enterAmount")     // "Enter Amount"
-t("insufficientFunds") // "Insufficient Funds"
-t("noLiquidity")     // "No Liquidity"
-// ... many more keys
-```
-
-#### `useFormatNumber`
-Format numbers with proper locale.
-
-```tsx
-const { value: formatted } = useFormatNumber({ value: "1234.5678", decimalScale: 2 });
-// "1,234.57"
-```
-
-#### `usePartnerChains`
-Get supported chains for current partner.
-
-```tsx
-const chains = usePartnerChains();
-// [1, 137, 56, ...]
-```
-
-#### `useAddresses`
-Get contract addresses for current config.
-
-```tsx
-const addresses = useAddresses();
-// { twap: "0x...", exchange: "0x...", ... }
-```
-
----
-
-## Callbacks Reference
-
-Set up callbacks to handle order lifecycle events:
-
-```tsx
-const useOrderCallbacks = () => {
-  const toastRef = useRef<number>(null);
-  
-  return {
-    // Wrap ETH -> WETH
-    onWrapRequest: () => {
-      toastRef.current = toast.loading("Wrapping ETH...");
-    },
-    onWrapSuccess: ({ txHash, explorerUrl, amount }) => {
-      toast.success("Wrapped ETH", {
-        id: toastRef.current,
-        action: <a href={explorerUrl}>View</a>,
-      });
-    },
-    
-    // Token Approval
-    onApproveRequest: () => {
-      toast.loading("Approving token...");
-    },
-    onApproveSuccess: ({ txHash, explorerUrl, token, amount }) => {
-      toast.success(`Approved ${token.symbol}`);
-    },
-    
-    // Order Signing
-    onSignOrderRequest: () => {
-      toast.loading("Creating order...", { description: "Proceed in wallet" });
-    },
-    onSignOrderSuccess: (signature) => {
-      // Signature received
-    },
-    onSignOrderError: (error) => {
-      toast.error("Failed to sign order");
-    },
-    
-    // Order Created
-    onOrderCreated: (order) => {
-      toast.success(`Order created: ${order.srcTokenSymbol} → ${order.dstTokenSymbol}`);
-    },
-    
-    // Order Filled
-    onOrderFilled: (order) => {
-      toast.success("Order filled!");
-    },
-    
-    // Order Progress
-    onOrdersProgressUpdate: (orders) => {
-      // Orders updated (useful for live progress)
-    },
-    
-    // Errors
-    onSubmitOrderFailed: ({ message, code }) => {
-      toast.error(`Failed: ${code}`);
-    },
-    onSubmitOrderRejected: () => {
-      toast.error("Order rejected");
-    },
-    
-    // Cancel
-    onCancelOrderRequest: (orders) => {
-      toast.loading("Cancelling order...");
-    },
-    onCancelOrderSuccess: ({ orders, txHash, explorerUrl }) => {
-      toast.success("Order cancelled");
-    },
-    onCancelOrderFailed: (error) => {
-      toast.error("Cancel failed");
-    },
-    
-    // Clipboard
-    onCopy: () => {
-      toast.success("Copied to clipboard");
-    },
-  };
-};
-```
-
----
-
-## Pre-built Components
-
-```tsx
-import { Components } from "@orbs-network/spot-react";
-
-// Submit order panel with steps display (wrap → approve → sign)
-<Components.SubmitOrderPanel 
-  reviewDetails={
-    <div>
-      <Switch label="Accept Disclaimer" />
-      <Button onClick={onSubmit}>Create Order</Button>
-    </div>
-  }
-/>
-
-// Orders list with details view
-<Components.Orders />
-```
-
----
-
-## Market Reference Price
-
-**CRITICAL**: The `marketReferencePrice.value` should be the expected output amount (in wei) for the current input amount, NOT a 1:1 price ratio.
-
-### Option 1: Use a DEX aggregator quote
-```tsx
-const useMarketReferencePrice = () => {
-  const { trade, isLoading } = useDexQuote(srcToken, dstToken, inputAmountWei);
-  
-  return {
-    value: trade?.outAmount,  // Expected output in wei
-    isLoading,
-    noLiquidity: !trade && !isLoading,
-  };
-};
-```
-
-### Option 2: Calculate from USD prices (synthetic)
-```tsx
-const useMarketReferencePrice = () => {
-  const srcUSD = useUSDPrice(srcToken?.address);  // Price for 1 token
-  const dstUSD = useUSDPrice(dstToken?.address);
-  const inputAmountUI = toAmountUI(inputAmountWei, srcToken?.decimals);
-  
-  const outputAmountWei = useMemo(() => {
-    if (!srcUSD || !dstUSD || !inputAmountUI) return undefined;
-    const outputUI = (srcUSD / dstUSD) * parseFloat(inputAmountUI);
-    return toAmountWei(outputUI.toString(), dstToken?.decimals);
-  }, [srcUSD, dstUSD, inputAmountUI]);
-  
-  return {
-    value: outputAmountWei,
-    isLoading: !srcUSD || !dstUSD,
-    noLiquidity: false,
-  };
-};
-```
-
----
-
-## Module-Specific UI
-
-```tsx
-const ModuleInputs = ({ module }: { module: Module }) => {
-  if (module === Module.TWAP) {
-    return (
-      <>
-        <TradesPanel />      {/* Number of trades */}
-        <FillDelayPanel />   {/* Delay between trades */}
-      </>
-    );
-  }
-  
-  // LIMIT, STOP_LOSS, TAKE_PROFIT
-  return <DurationPanel />;  {/* Order expiration */}
-};
-
-const PricePanels = ({ module }: { module: Module }) => {
-  return (
-    <>
-      {/* Show trigger price for conditional orders */}
-      {(module === Module.STOP_LOSS || module === Module.TAKE_PROFIT) && (
-        <TriggerPricePanel />
-      )}
-      
-      {/* Limit price (optional for TWAP, required for LIMIT) */}
-      <LimitPricePanel />
-    </>
-  );
-};
-```
-
----
-
-## Integration Checklist
-
-1. [ ] Install package and peer dependencies
-2. [ ] Create Button, Tooltip, TokenLogo, Spinner components
-3. [ ] Set up wallet connection (wagmi recommended)
-4. [ ] Implement token fetching/selection
-5. [ ] Implement balance fetching (wei strings)
-6. [ ] Implement USD price fetching (price for 1 token)
-7. [ ] Implement market reference price (output amount for input)
-8. [ ] Wrap trading UI with SpotProvider
-9. [ ] Build token panels with `useSrcTokenPanel`/`useDstTokenPanel`
-10. [ ] Build order config UI based on module type
-11. [ ] Build price panels with `useLimitPricePanel`/`useTriggerPricePanel`
-12. [ ] Add validation display with `useInputErrors`
-13. [ ] Build submission flow with `useSubmitOrderPanel`
-14. [ ] Build orders history with `useOrderHistoryPanel`
-15. [ ] Set up callbacks for toast notifications
-16. [ ] Import styles: `import "@orbs-network/spot-react/styles.css"`
-
----
-
-## Styles
-
-Import the default stylesheet:
-```tsx
-import "@orbs-network/spot-react/styles.css";
-```
-
-Or customize with your own CSS targeting the component classes.