@lifi/perps-types 0.2.0-alpha.0 → 1.0.1

package/src/action.ts

@@ -1,42 +1,47 @@
-import type { MarginMode, OrderType } from './enums.js'
-import {
-  type ActionType,
-  type OrderSide,
-  type OrderStatus,
-  type TimeInForce,
-  type TriggerCondition,
+import type { AcceptTermsParams } from './acceptTerms.js'
+import type {
+  ActionType,
+  MarginMode,
+  OrderSide,
+  OrderStatus,
+  OrderType,
+  TimeInForce,
+  TriggerCondition,
 } from './enums.js'
-import type { Address, Hex, PerpsTypedData } from './typedData.js'
-import type { AssetIdentity, AssetDisplay } from './asset.js'
-
-// ActionStep variants (create → sign → execute). The SDK picks the variant
-// from the provider's `signingMethod` on `/providers`:
-//   Eip712   — EIP-712 typed data + ECDSA signature
-//   WasmBlob — WASM signer output ({txType, txInfo, txHash})
-//   EvmTx    — plain EVM transaction
+import type { MarketDisplay, MarketRef } from './market.js'
+import type { Address, Hex } from './primitives.js'
+import type { PerpsTypedData } from './typedData.js'
+import type { VoteParams } from './vote.js'
+
+/** @public */
 export interface Eip712ActionStep {
   action: ActionType
   typedData: PerpsTypedData
 }
 
+/** @public */
 export interface WasmBlobActionStep {
   action: ActionType
   wasmSignParams: Record<string, unknown>
 }
 
+/** @public */
 export interface EvmTxActionStep {
   action: ActionType
   txParams: Record<string, unknown>
 }
 
+/** @public */
 export type ActionStep = Eip712ActionStep | WasmBlobActionStep | EvmTxActionStep
 
+/** @public */
 export interface Eip712SignedActionStep {
   action: ActionType
   typedData: PerpsTypedData
   signature: Hex
 }
 
+/** @public */
 export interface WasmBlobSignedActionStep {
   action: ActionType
   wasmSignParams: Record<string, unknown>
@@ -47,17 +52,20 @@ export interface WasmBlobSignedActionStep {
   }
 }
 
+/** @public */
 export interface EvmTxSignedActionStep {
   action: ActionType
   txParams: Record<string, unknown>
   txHash: string
 }
 
+/** @public */
 export type SignedActionStep =
   | Eip712SignedActionStep
   | WasmBlobSignedActionStep
   | EvmTxSignedActionStep
 
+/** @public */
 export type ActionResult =
   | {
       action: ActionType
@@ -70,15 +78,13 @@ export type ActionResult =
       error: string
     }
 
-// ---------------------------------------------------------------------------
-// Shared data types
-// ---------------------------------------------------------------------------
-
+/** @public */
 export interface TriggerOrderInput {
   triggerPrice: string
   limitPrice?: string
 }
 
+/** @public */
 export interface ModifyOrderInput {
   id: string
   price?: string
@@ -87,9 +93,10 @@ export interface ModifyOrderInput {
   limitPrice?: string
 }
 
+/** @public */
 export interface Order {
   orderId: string
-  asset: AssetDisplay
+  market: MarketDisplay
   side: OrderSide
   type: OrderType
   price?: string
@@ -103,36 +110,22 @@ export interface Order {
   triggerPrice?: string
   triggerCondition?: TriggerCondition
   status: OrderStatus
-  /**
-   * Human-readable English sentence describing *why* the order ended in a
-   * terminal non-FILLED state (e.g. slippage exceeded, reduce-only would
-   * not reduce, expiry). Populated only when the provider exposes a
-   * specific cancellation/rejection reason; `undefined` for non-terminal
-   * statuses, plain `filled`, and bare cancels/rejects with no actionable
-   * detail.
-   */
+  /** Human-readable reason for a terminal non-FILLED status; undefined when no actionable detail. */
   statusReason?: string
   averagePrice?: string
   createdAt: string
   updatedAt: string
 }
 
-// ---------------------------------------------------------------------------
-// Per-action param types
-// ---------------------------------------------------------------------------
-
+/** @public */
 export interface PlaceOrderParams {
-  asset: AssetIdentity
+  market: MarketRef
   side: OrderSide
   type?: OrderType
   size: string
   price?: string
   leverage?: number
-  /**
-   * Margin mode to use for the position. When omitted, the backend falls back
-   * to the provider's default (currently CROSS for both Hyperliquid and
-   * Lighter). Callers should set this explicitly when they need ISOLATED.
-   */
+  /** Omitted falls back to the provider's default (currently CROSS). */
   marginMode?: MarginMode
   reduceOnly?: boolean
   timeInForce?: TimeInForce
@@ -141,43 +134,46 @@ export interface PlaceOrderParams {
   stopLoss?: TriggerOrderInput
 }
 
+/** @public */
 export interface PlaceTriggerOrderParams {
-  asset: AssetIdentity
+  market: MarketRef
   side: OrderSide
   takeProfit?: TriggerOrderInput
   stopLoss?: TriggerOrderInput
 }
 
+/** @public */
 export interface CancelOrderParams {
   ids: string[]
 }
 
+/** @public */
 export interface ModifyOrderParams {
   modifications: ModifyOrderInput[]
 }
 
+/** @public */
 export interface UpdateLeverageParams {
-  asset: AssetIdentity
+  market: MarketRef
   leverage: number
-  /**
-   * Margin mode to use for the position. When omitted, the backend falls back
-   * to the provider's default (currently CROSS for both Hyperliquid and
-   * Lighter). Callers should set this explicitly when they need ISOLATED.
-   */
+  /** Omitted falls back to the provider's default (currently CROSS). */
   marginMode?: MarginMode
 }
 
+/** @public */
 export interface UpdatePositionMarginParams {
-  asset: AssetIdentity
+  market: MarketRef
   action: 'add' | 'remove'
   amount: string
 }
 
+/** @public */
 export interface WithdrawalParams {
   destination: Address
   amount: string
 }
 
+/** @public */
 export interface DepositParams {
   /** Amount of the token to deposit (human-readable, e.g. "100.5"). */
   amount: string
@@ -187,35 +183,23 @@ export interface DepositParams {
   chainId: number
 }
 
+/** @public */
 export interface ApproveAgentParams {
   agentAddress: string
   agentTtlMs?: number
 }
 
-/**
- * Params for `ActionType.ACCOUNT_MODE` — switch the account's operating
- * mode (e.g. HL abstraction variant, Lighter UTA / Simple). The string
- * is opaque per-provider; the authoritative enumeration of valid values
- * lives on the descriptor's `Param.values` array (see
- * `ProviderActionDescriptor` in `providers.ts`). The SDK and backend are
- * responsible for validating `mode` against that array — `@lifi/perps-types`
- * intentionally does not encode the per-provider value list here, so a
- * provider can add a new mode without a types release.
- */
+/** @public */
 export interface AccountModeParams {
   mode: string
 }
 
-/**
- * Params for `ActionType.ACCOUNT_TYPE` — switch the account's fee/latency
- * tier (e.g. Lighter standard / premium). Providers without tiering omit
- * the action entirely; the descriptor's `Param.values` array enumerates
- * the valid tiers for providers that do support it.
- */
+/** @public */
 export interface AccountTypeParams {
   tier: string
 }
 
+/** @public */
 export interface SendAssetParams {
   collateral: string
   sourceDex: string
@@ -223,10 +207,7 @@ export interface SendAssetParams {
   amount: string
 }
 
-// ---------------------------------------------------------------------------
-// ActionParamsMap — compile-time type resolution for SDK
-// ---------------------------------------------------------------------------
-
+/** @public */
 export interface CancelAllOrdersParams {
   /** 0=immediate (cancel GTC), 1=scheduled, 2=abort scheduled */
   timeInForce: number
@@ -234,33 +215,28 @@ export interface CancelAllOrdersParams {
   timestampMs?: number
 }
 
+/** @public */
 export interface RegisterApiKeyParams {
   /** The API key slot index to register (0-255). Reusing a fixed slot overwrites the old key. */
   apiKeyIndex: number
+  /**
+   * The SDK's currently-stored Lighter public key for this slot, if any. The
+   * backend returns `[]` (already satisfied) only when this equals the
+   * on-chain pubkey at the slot; otherwise it stages a ChangePubKey blob so
+   * the slot can be (re-)registered. Omit when the SDK has no local key.
+   */
+  knownPublicKey?: string
 }
 
-/**
- * Params for `ActionType.APPROVE_READ_ONLY_TOKEN` — mint a long-lived
- * read-only token Lighter recognises for query-only access (positions,
- * fills, balances). The token format on the wire is
- * `ro:{accountIndex}:{scope}:{expiry}:{rand}`; this type carries only the
- * inputs needed to construct that token, not the token itself.
- *
- * `expirySeconds` is the absolute unix-seconds expiry. Lighter constrains
- * the lifetime to a minimum of 1 day and a maximum of 10 years from now;
- * the SDK and backend are responsible for enforcing those bounds.
- *
- * `scope` mirrors Lighter's documented `single | all` literal:
- * - `'single'` — token authorises read access to one account only.
- * - `'all'` — token authorises read access to every account owned by the
- *   signer. Default for the perps stack today.
- */
+/** @public */
 export interface ApproveReadOnlyTokenParams {
   accountIndex: number
+  /** Absolute unix-seconds expiry. Lighter requires lifetime between 1 day and 10 years. */
   expirySeconds: number
   scope: 'single' | 'all'
 }
 
+/** @public */
 export interface ActionParamsMap {
   [ActionType.APPROVE_AGENT]: ApproveAgentParams
   [ActionType.APPROVE_BUILDER_FEE]: Record<string, never>
@@ -279,17 +255,11 @@ export interface ActionParamsMap {
   [ActionType.REGISTER_API_KEY]: RegisterApiKeyParams
   [ActionType.APPROVE_READ_ONLY_TOKEN]: ApproveReadOnlyTokenParams
   [ActionType.DEPOSIT]: DepositParams
+  [ActionType.META_VOTE]: VoteParams
+  [ActionType.META_ACCEPT_TERMS]: AcceptTermsParams
 }
 
-// ---------------------------------------------------------------------------
-// Request / Response types
-// ---------------------------------------------------------------------------
-
-/**
- * Distributed discriminated request shape: selecting an `action` literal
- * narrows `params` to exactly the matching entry in `ActionParamsMap`.
- * Mapped over `ActionType` so a new action automatically yields a new branch.
- */
+/** @public */
 export type CreateActionRequest = {
   [K in ActionType]: {
     provider: string
@@ -300,15 +270,12 @@ export type CreateActionRequest = {
   }
 }[ActionType]
 
+/** @public */
 export interface CreateActionResponse {
   actions: ActionStep[]
 }
 
-/**
- * Distributed discriminated execute-request shape: narrowing on `action`
- * pins the action kind to a single `ActionType`; `actions` is the
- * already-discriminated `SignedActionStep[]` union above.
- */
+/** @public */
 export type ExecuteActionRequest = {
   [K in ActionType]: {
     provider: string
@@ -319,6 +286,7 @@ export type ExecuteActionRequest = {
   }
 }[ActionType]
 
+/** @public */
 export interface ExecuteActionResponse {
   results: ActionResult[]
 }

package/src/asset.ts

@@ -1,88 +1,25 @@
-export interface FundingInfo {
-  rate: string
-  nextFundingTime: number
-}
-
-export interface AssetIdentity {
-  assetId: string // provider's canonical identity: "BTC", "xyz:PURR", "@142"
-  market: string // market category from /providers.markets: "hyperliquid", "xyz", "spot"
-}
-
-export interface Asset extends AssetIdentity {
-  displaySymbol: string // UI base name: "BTC", "PURR"; spot keeps full pair: "PURR/USDC"
-  displayQuote: string | null // quote asset for perps: "USDC", "USDH"; null for spot
-  displayName?: string // future: "Bitcoin", "Ethereum"
+/**
+ * Underlying token/registry entry. The base entity of the perps taxonomy:
+ * a tradable unit referenced by markets (as base/quote legs) and held by
+ * accounts (as balances). NOT a market — see {@link BaseMarket}.
+ * @public
+ */
+export interface Asset {
+  providerId: string
+  /**
+   * The asset's own provider-native id. Lighter: numeric `asset_id`, stringified.
+   * Hyperliquid spot: the venue token index (`spotMeta.tokens[].index`, the
+   * value HL carries in a balance's `token` field) — identical to that token's
+   * spot `Market.baseAsset.id`, so a held balance resolves to its market by
+   * identity. NEVER the coin symbol (that is `displaySymbol`).
+   */
+  id: string
+  displaySymbol: string
   logoURI: string
-  szDecimals: number
-  maxLeverage: number
-  onlyIsolated: boolean
-  isMarginCollateral?: boolean
-  funding: FundingInfo
-  openInterest?: string
-  volume24h?: string
-  prevDayPrice?: string
-  markPrice: string
-}
-
-export type AssetDisplay = Pick<
-  Asset,
-  'assetId' | 'market' | 'displaySymbol' | 'displayQuote'
->
-
-export interface AssetPrice {
-  assetId: string
-  price: string
+  displayName?: string
 }
 
+/** @public */
 export interface AssetsResponse {
   assets: Asset[]
 }
-
-export interface PricesResponse {
-  prices: AssetPrice[]
-}
-
-export interface Candle {
-  t: number
-  o: string
-  h: string
-  l: string
-  c: string
-  v: string
-}
-
-export interface OhlcvResponse {
-  provider: string
-  assetId: string
-  interval: string
-  candles: Candle[]
-}
-
-export type OhlcvInterval =
-  | '1m'
-  | '3m'
-  | '5m'
-  | '15m'
-  | '30m'
-  | '1h'
-  | '2h'
-  | '4h'
-  | '8h'
-  | '12h'
-  | '1d'
-  | '3d'
-  | '1w'
-  | '1M'
-
-export interface OrderbookLevel {
-  price: string
-  size: string
-}
-
-export interface OrderbookResponse {
-  provider: string
-  assetId: string
-  bids: OrderbookLevel[]
-  asks: OrderbookLevel[]
-  timestamp: number
-}

package/src/enums.ts

@@ -1,3 +1,4 @@
+/** @public */
 export enum PerpsErrorCode {
   // Base errors (2000-2009)
   DefaultError = 2000,
@@ -10,6 +11,7 @@ export enum PerpsErrorCode {
   // Auth errors (2010-2019)
   SignatureInvalid = 2010,
   AgentUnauthorized = 2011,
+  TermsNotAccepted = 2012,
 
   // Trading errors (2020-2039)
   ExchangeRejected = 2020,
@@ -32,11 +34,13 @@ export enum PerpsErrorCode {
   RouteNotFound = 2060,
 }
 
+/** @public */
 export enum OrderSide {
   BUY = 'BUY',
   SELL = 'SELL',
 }
 
+/** @public */
 export enum OrderType {
   MARKET = 'MARKET',
   LIMIT = 'LIMIT',
@@ -47,16 +51,19 @@ export enum OrderType {
   TRIGGER_ONLY = 'TRIGGER_ONLY',
 }
 
+/** @public */
 export enum PositionSide {
   LONG = 'LONG',
   SHORT = 'SHORT',
 }
 
+/** @public */
 export enum MarginMode {
   ISOLATED = 'ISOLATED',
   CROSS = 'CROSS',
 }
 
+/** @public */
 export enum TimeInForce {
   GTC = 'GTC',
   IOC = 'IOC',
@@ -64,6 +71,7 @@ export enum TimeInForce {
   GTT = 'GTT',
 }
 
+/** @public */
 export enum OrderStatus {
   PENDING = 'PENDING',
   OPEN = 'OPEN',
@@ -75,6 +83,7 @@ export enum OrderStatus {
   TRIGGERED = 'TRIGGERED',
 }
 
+/** @public */
 export enum FillStatus {
   FILLED = 'FILLED',
   PARTIALLY_FILLED = 'PARTIALLY_FILLED',
@@ -82,25 +91,17 @@ export enum FillStatus {
   REJECTED = 'REJECTED',
 }
 
+/** @public */
 export enum LiquidityRole {
   MAKER = 'maker',
   TAKER = 'taker',
 }
 
+/** @public */
 export enum ActionType {
   APPROVE_AGENT = 'approveAgent',
   APPROVE_BUILDER_FEE = 'approveBuilderFee',
-  /**
-   * Generic account-level operating mode (e.g. Hyperliquid abstraction
-   * variants, Lighter UTA / Simple). HL maps it to the appropriate
-   * EIP-712 typed-data builder internally.
-   */
   ACCOUNT_MODE = 'accountMode',
-  /**
-   * Generic account-level fee/latency tier (e.g. Lighter standard /
-   * premium). Providers that have no tiering (Hyperliquid) omit this
-   * action from their descriptor list.
-   */
   ACCOUNT_TYPE = 'accountType',
   SEND_ASSET = 'sendAsset',
   WITHDRAWAL = 'withdrawal',
@@ -115,24 +116,32 @@ export enum ActionType {
   REGISTER_API_KEY = 'registerApiKey',
   APPROVE_READ_ONLY_TOKEN = 'approveReadOnlyToken',
   DEPOSIT = 'deposit',
+  /** Provider-independent: sent with the `META_PROVIDER` sentinel, not a real provider key. */
+  META_VOTE = 'metaVote',
+  /** Provider-independent: sent with the `META_PROVIDER` sentinel, not a real provider key. */
+  META_ACCEPT_TERMS = 'metaAcceptTerms',
 }
 
+/** @public */
 export enum TriggerCondition {
   ABOVE = 'ABOVE',
   BELOW = 'BELOW',
 }
 
+/** @public */
 export enum TriggerOrderType {
   TAKE_PROFIT = 'TAKE_PROFIT',
   STOP_LOSS = 'STOP_LOSS',
 }
 
+/** @public */
 export enum TriggerOrderStatus {
   WAITING = 'WAITING',
   TRIGGERED = 'TRIGGERED',
   CANCELLED = 'CANCELLED',
 }
 
+/** @public */
 export enum ActivityType {
   DEPOSIT = 'DEPOSIT',
   WITHDRAWAL = 'WITHDRAWAL',
@@ -141,6 +150,7 @@ export enum ActivityType {
   TRANSFER = 'TRANSFER',
 }
 
+/** @public */
 export enum FillClassification {
   OPENED_LONG = 'Opened Long',
   OPENED_SHORT = 'Opened Short',
@@ -156,31 +166,38 @@ export enum FillClassification {
   SPOT_SELL = 'Spot Sell',
 }
 
+/** @public */
 export enum LiquidationClassification {
   LIQUIDATED = 'Liquidated',
 }
 
+/** @public */
 export enum FundingClassification {
   FUNDING = 'Funding',
 }
 
+/** @public */
 export enum TransferClassification {
   DEPOSIT = 'Deposit',
   WITHDRAWAL = 'Withdrawal',
+  TRANSFER = 'Transfer',
 }
 
+/** @public */
 export type ActivityClassification =
   | FillClassification
   | LiquidationClassification
   | FundingClassification
   | TransferClassification
 
+/** @public */
 export enum PerpsSigner {
   USER = 'USER',
   AGENT = 'AGENT',
   API_KEY = 'API_KEY',
 }
 
+/** @public */
 export enum SigningMethod {
   EIP712 = 'eip712',
   WASM_BLOB = 'wasmBlob',

package/src/errors.ts

@@ -1,5 +1,6 @@
 import type { PerpsErrorCode } from './enums.js'
 
+/** @public */
 export interface PerpsErrorBody {
   code: PerpsErrorCode
   tool?: string

package/src/index.ts

@@ -1,8 +1,23 @@
-export * from './typedData.js'
-export * from './enums.js'
-export * from './providers.js'
-export * from './asset.js'
-export * from './action.js'
+/**
+ * `@lifi/perps-types` — shared cross-provider type surface for the perps SDK:
+ * account/order/market shapes, action params, enums, error codes, provider
+ * descriptors, subscriptions, and EIP-712 typed-data structures.
+ *
+ * @packageDocumentation
+ * @public
+ */
+
+export * from './acceptTerms.js'
 export * from './account.js'
+export * from './action.js'
+export * from './asset.js'
+export * from './enums.js'
 export * from './errors.js'
+export * from './market.js'
+export * from './meta.js'
+export * from './primitives.js'
+export * from './providers.js'
+export * from './quote.js'
 export * from './subscriptions.js'
+export * from './typedData.js'
+export * from './vote.js'