@nadohq/engine-client 0.1.0-alpha.1

package/src/EngineWebClient.ts

@@ -0,0 +1,72 @@
+import { EngineBaseClient } from './EngineBaseClient';
+import {
+  EngineServerIpBlockResponse,
+  GetEngineIpBlockStatusResponse,
+  GetEngineTimeResponse,
+} from './types';
+
+/**
+ * Queries that talk directly to web, _not_ the engine. Placing here in the `engine-client` as we don't have enough
+ * use cases to justify a separate package
+ */
+export class EngineWebClient extends EngineBaseClient {
+  /**
+   * Determines the IP block status for the current client
+   */
+  async getIpBlockStatus(): Promise<GetEngineIpBlockStatusResponse> {
+    return (
+      this.axiosInstance
+        // Use the /time endpoint and listen to 403 responses
+        .get(`${this.opts.url}/ip`, {
+          // Allow all statuses
+          validateStatus: () => true,
+          // IP checks go through Cloudflare, which uses allow-origin as *, so withCredentials needs to be false
+          withCredentials: false,
+        })
+        .then((res) => {
+          if (res.status !== 403) {
+            return null;
+          }
+          const resData = res.data as EngineServerIpBlockResponse;
+
+          if (!resData.blocked) {
+            return null;
+          }
+
+          return resData.reason === 'ip_query_only' ? 'query_only' : 'blocked';
+        })
+    );
+  }
+
+  /**
+   * Determines whether a client needs to complete the cloudflare JS challenge to interact with the API
+   *
+   * @return true if the client needs to complete the JS challenge at '/challenge', false otherwise
+   */
+  async getRequiresCloudflareAuth(): Promise<boolean> {
+    // We use a generic endpoint and check for the CF challenge header
+    // Note: this uses a CORS set to the relevant frontend endpoint (ex. testnet.vertexprotocol.com) so it will NOT
+    // work from other domains
+    return this.axiosInstance
+      .get(`${this.opts.url}/cf-check`, {
+        // Allow all statuses
+        validateStatus: () => true,
+      })
+      .then((res) => {
+        if (res.status !== 403) {
+          return false;
+        }
+
+        return res.headers['cf-mitigated'] === 'challenge';
+      });
+  }
+
+  /**
+   * Retrieves current server epoch in milliseconds
+   */
+  async getTime(): Promise<GetEngineTimeResponse> {
+    return this.axiosInstance
+      .get(`${this.opts.url}/time`)
+      .then((res) => res.data as GetEngineTimeResponse);
+  }
+}

package/src/endpoints.ts

@@ -0,0 +1,21 @@
+import { ChainEnv } from '@nadohq/contracts';
+
+export const ENGINE_CLIENT_ENDPOINTS: Record<ChainEnv, string> = {
+  local: 'http://localhost:80',
+  arbitrumTestnet: 'https://gateway.sepolia-test.vertexprotocol.com/v1',
+  arbitrum: 'https://gateway.prod.vertexprotocol.com/v1',
+};
+
+export const ENGINE_WS_CLIENT_ENDPOINTS: Record<ChainEnv, string> = {
+  local: 'ws://localhost:80',
+  arbitrumTestnet: 'wss://gateway.sepolia-test.vertexprotocol.com/v1/ws',
+  arbitrum: 'wss://gateway.prod.vertexprotocol.com/v1/ws',
+};
+
+export const ENGINE_WS_SUBSCRIPTION_CLIENT_ENDPOINTS: Record<ChainEnv, string> =
+  {
+    local: 'ws://localhost:80',
+    arbitrumTestnet:
+      'wss://gateway.sepolia-test.vertexprotocol.com/v1/subscribe',
+    arbitrum: 'wss://gateway.prod.vertexprotocol.com/v1/subscribe',
+  };

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './types';
+export * from './EngineClient';
+export * from './endpoints';
+export * from './utils';

package/src/types/EngineServerFailureError.ts

@@ -0,0 +1,12 @@
+import { EngineServerQueryFailureResponse } from './serverQueryTypes';
+import { EngineServerExecuteFailureResult } from './serverExecuteTypes';
+
+export class EngineServerFailureError extends Error {
+  constructor(
+    readonly responseData:
+      | EngineServerQueryFailureResponse
+      | EngineServerExecuteFailureResult,
+  ) {
+    super();
+  }
+}

package/src/types/clientExecuteTypes.ts

@@ -0,0 +1,118 @@
+import {
+  EIP712BurnVlpParams,
+  EIP712CancelOrdersParams,
+  EIP712CancelProductOrdersParams,
+  EIP712IsolatedOrderParams,
+  EIP712LinkSignerParams,
+  EIP712LiquidateSubaccountParams,
+  EIP712MintVlpParams,
+  EIP712OrderParams,
+  EIP712TransferQuoteParams,
+  EIP712WithdrawCollateralParams,
+} from '@nadohq/contracts';
+import { EngineServerExecuteSuccessResult } from './serverExecuteTypes';
+
+/**
+ * Either verifying address or signature must be provided;
+ * If signature is not provided, the verifying address with the engine signer will be used to sign.
+ */
+export type SignatureParams =
+  | {
+      // Endpoint address for all executes except order placement
+      verifyingAddr: string;
+      chainId: number;
+    }
+  | {
+      signature: string;
+    };
+
+type WithoutNonce<T extends { nonce: unknown }> = Omit<T, 'nonce'>;
+
+type WithSpotLeverage<T> = T & {
+  spotLeverage?: boolean;
+};
+
+export type WithSignature<T> = T & {
+  signature: string;
+};
+
+// Params associated with all engine executes
+export type WithBaseEngineExecuteParams<T> = SignatureParams &
+  Omit<T, 'nonce'> & {
+    nonce?: string;
+  };
+
+export type EngineOrderParams = WithoutNonce<EIP712OrderParams>;
+
+export type EnginePlaceOrderParams = WithBaseEngineExecuteParams<{
+  id?: number;
+  productId: number;
+  order: EngineOrderParams;
+  // If not given, engine defaults to true (leverage/borrow enabled)
+  spotLeverage?: boolean;
+}>;
+
+export type EngineIsolatedOrderParams = WithoutNonce<EIP712IsolatedOrderParams>;
+
+export type EnginePlaceIsolatedOrderParams = WithBaseEngineExecuteParams<{
+  id?: number;
+  productId: number;
+  order: EngineIsolatedOrderParams;
+  // Whether the cross subaccount can borrow quote for the margin transfer into the isolated subaccount. If not given, engine defaults to true.
+  borrowMargin?: boolean;
+}>;
+
+export type EngineLiquidateSubaccountParams =
+  WithBaseEngineExecuteParams<EIP712LiquidateSubaccountParams>;
+
+export type EngineWithdrawCollateralParams = WithBaseEngineExecuteParams<
+  WithSpotLeverage<EIP712WithdrawCollateralParams>
+>;
+
+export type EngineCancelOrdersParams =
+  WithBaseEngineExecuteParams<EIP712CancelOrdersParams>;
+
+export type EngineCancelAndPlaceParams = {
+  cancelOrders: EngineCancelOrdersParams;
+  placeOrder: EnginePlaceOrderParams;
+};
+
+export type EngineCancelProductOrdersParams =
+  WithBaseEngineExecuteParams<EIP712CancelProductOrdersParams>;
+
+export type EngineLinkSignerParams =
+  WithBaseEngineExecuteParams<EIP712LinkSignerParams>;
+
+export type EngineTransferQuoteParams =
+  WithBaseEngineExecuteParams<EIP712TransferQuoteParams>;
+
+export type EngineMintVlpParams = WithBaseEngineExecuteParams<
+  WithSpotLeverage<EIP712MintVlpParams>
+>;
+
+export type EngineBurnVlpParams =
+  WithBaseEngineExecuteParams<EIP712BurnVlpParams>;
+
+export interface EngineExecuteRequestParamsByType {
+  burn_vlp: EngineBurnVlpParams;
+  cancel_and_place: EngineCancelAndPlaceParams;
+  cancel_orders: EngineCancelOrdersParams;
+  cancel_product_orders: EngineCancelProductOrdersParams;
+  link_signer: EngineLinkSignerParams;
+  liquidate_subaccount: EngineLiquidateSubaccountParams;
+  mint_vlp: EngineMintVlpParams;
+  place_isolated_order: EnginePlaceIsolatedOrderParams;
+  place_order: EnginePlaceOrderParams;
+  transfer_quote: EngineTransferQuoteParams;
+  withdraw_collateral: EngineWithdrawCollateralParams;
+}
+
+export type EnginePlaceOrderResult =
+  EngineServerExecuteSuccessResult<'place_order'> & {
+    orderParams: EIP712OrderParams;
+  };
+
+export type EnginePlaceIsolatedOrderResult =
+  EngineServerExecuteSuccessResult<'place_isolated_order'> & {
+    orderParams: EIP712IsolatedOrderParams;
+  };

package/src/types/clientQueryTypes.ts

@@ -0,0 +1,267 @@
+import {
+  BalanceHealthContributions,
+  BalanceSide,
+  EIP712OrderParams,
+  GetAllMarketsResponse,
+  GetSubaccountSummaryParams,
+  HealthGroup,
+  OrderExpirationType,
+  PerpBalanceWithProduct,
+  ProductEngineType,
+  SignedEIP712OrderParams,
+  SpotBalanceWithProduct,
+  Subaccount,
+  SubaccountSummaryResponse,
+} from '@nadohq/contracts';
+import { BigDecimal } from '@nadohq/utils';
+import {
+  EngineServerNoncesParams,
+  EngineServerTimeResponse,
+} from './serverQueryTypes';
+
+export type GetEngineSubaccountSummaryResponse = SubaccountSummaryResponse;
+
+export type GetEngineSubaccountSummaryParams = GetSubaccountSummaryParams;
+
+export type GetEngineIsolatedPositionsParams = Subaccount;
+
+export interface SubaccountIsolatedPosition {
+  subaccount: Subaccount;
+  healths: BalanceHealthContributions;
+  quoteBalance: SpotBalanceWithProduct;
+  baseBalance: PerpBalanceWithProduct;
+}
+
+export type GetEngineIsolatedPositionsResponse = SubaccountIsolatedPosition[];
+
+export type SubaccountTx = {
+  type: 'apply_delta';
+  tx: SubaccountProductDeltaTx;
+};
+
+export interface SubaccountProductDeltaTx {
+  productId: number;
+  amountDelta: BigDecimal;
+  vQuoteDelta: BigDecimal;
+}
+
+export interface GetEngineContractsResponse {
+  chainId: number;
+  endpointAddr: string;
+  /**
+   * Address for the orderbook contract, with the product ID being the index
+   */
+  orderbookAddrs: string[];
+}
+
+export type GetEngineEstimatedSubaccountSummaryParams =
+  GetSubaccountSummaryParams & {
+    txs: SubaccountTx[];
+  };
+
+export type GetEngineNoncesParams = EngineServerNoncesParams;
+
+export interface GetEngineNoncesResponse {
+  orderNonce: string;
+  txNonce: string;
+}
+
+export interface GetEngineSymbolsParams {
+  productType?: ProductEngineType;
+  productIds?: number[];
+}
+
+export interface EngineSymbolsResponse {
+  // mapping of product symbol to symbols info
+  symbols: Record<string, EngineSymbol>;
+}
+
+export interface EngineSymbol {
+  type: ProductEngineType;
+  productId: number;
+  symbol: string;
+  priceIncrement: BigDecimal;
+  sizeIncrement: BigDecimal;
+  minSize: BigDecimal;
+  minDepth: BigDecimal;
+  maxSpreadRate: BigDecimal;
+  makerFeeRate: BigDecimal;
+  takerFeeRate: BigDecimal;
+  longWeightInitial: BigDecimal;
+  longWeightMaintenance: BigDecimal;
+}
+
+export type GetEngineAllMarketsResponse = GetAllMarketsResponse;
+
+export interface GetEngineHealthGroupsResponse {
+  healthGroups: HealthGroup[];
+}
+
+export interface GetEngineOrderParams {
+  productId: number;
+  digest: string;
+}
+
+export interface EngineOrder extends Subaccount {
+  productId: number;
+  price: BigDecimal;
+  // Amount initially requested
+  totalAmount: BigDecimal;
+  // Amount still unfilled
+  unfilledAmount: BigDecimal;
+  expiration: BigDecimal;
+  // Margin being transferred for the order, will be null if not an iso order
+  margin: BigDecimal | null;
+  nonce: string;
+  digest: string;
+  orderParams: EIP712OrderParams;
+  placementTime: number;
+  orderType: OrderExpirationType;
+}
+
+export type GetEngineOrderResponse = EngineOrder;
+
+export interface ValidateSignedEngineOrderParams {
+  productId: number;
+  signedOrder: SignedEIP712OrderParams;
+}
+
+export interface ValidateEngineOrderParams {
+  productId: number;
+  orderbookAddr: string;
+  chainId: number;
+  order: EIP712OrderParams;
+}
+
+export interface ValidateEngineOrderResponse {
+  productId: number;
+  valid: boolean;
+}
+
+export interface GetEngineSubaccountOrdersParams extends Subaccount {
+  productId: number;
+}
+
+export interface EngineSubaccountOrders {
+  productId: number;
+  orders: EngineOrder[];
+}
+
+export type GetEngineSubaccountOrdersResponse = EngineSubaccountOrders;
+
+export interface GetEngineSubaccountProductOrdersParams extends Subaccount {
+  productIds: number[];
+}
+
+export interface GetEngineSubaccountProductOrdersResponse {
+  productOrders: EngineSubaccountOrders[];
+}
+
+export type GetEngineSubaccountFeeRatesParams = Subaccount;
+
+export interface SubaccountOrderFeeRates {
+  maker: BigDecimal;
+  taker: BigDecimal;
+}
+
+export interface GetEngineSubaccountFeeRatesResponse {
+  // By Product ID
+  orders: Record<number, SubaccountOrderFeeRates>;
+  withdrawal: Record<number, BigDecimal>;
+  liquidationSequencerFee: BigDecimal;
+  healthCheckSequencerFee: BigDecimal;
+  takerSequencerFee: BigDecimal;
+}
+
+export interface EnginePriceTickLiquidity {
+  price: BigDecimal;
+  liquidity: BigDecimal;
+}
+
+export interface GetEngineMarketLiquidityParams {
+  productId: number;
+  // The minimum depth in base price ticks (i.e. per side
+  depth: number;
+}
+
+export interface GetEngineMarketLiquidityResponse {
+  bids: EnginePriceTickLiquidity[];
+  asks: EnginePriceTickLiquidity[];
+}
+
+export interface GetEngineMarketPriceParams {
+  productId: number;
+}
+
+export interface EngineMarketPrice {
+  productId: number;
+  bid: BigDecimal;
+  ask: BigDecimal;
+}
+
+export type GetEngineMarketPriceResponse = EngineMarketPrice;
+
+export interface GetEngineMarketPricesParams {
+  productIds: number[];
+}
+
+export interface GetEngineMarketPricesResponse {
+  marketPrices: EngineMarketPrice[];
+}
+
+export interface GetEngineMaxOrderSizeParams extends Subaccount {
+  price: BigDecimal;
+  productId: number;
+  // Note: When `reduceOnly` is true, `side` must be opposite of the current position, otherwise it returns 0.
+  side: BalanceSide;
+  // If not given, engine defaults to true (leverage/borrow enabled) for spot
+  // Do not pass this for perp products
+  spotLeverage?: boolean;
+  // If not given, engine defaults to false. If true, the max order size will be capped to the subaccount's current position size;
+  // If no position exists, it will return 0.
+  reduceOnly?: boolean;
+}
+
+export type GetEngineMaxOrderSizeResponse = BigDecimal;
+
+export interface GetEngineMaxWithdrawableParams extends Subaccount {
+  productId: number;
+  // If not given, engine defaults to true (leverage/borrow enabled)
+  spotLeverage?: boolean;
+}
+
+export type GetEngineMaxWithdrawableResponse = BigDecimal;
+
+export type GetEngineTimeResponse = EngineServerTimeResponse;
+
+export type GetEngineLinkedSignerParams = Subaccount;
+
+export interface GetEngineLinkedSignerResponse {
+  signer: string;
+}
+
+export type GetEngineInsuranceResponse = BigDecimal;
+
+export interface EngineMinDepositRate {
+  productId: number;
+  minDepositRate: BigDecimal;
+}
+
+export interface GetEngineMinDepositRatesResponse {
+  minDepositRates: Record<number, EngineMinDepositRate>;
+}
+
+/**
+ * Given an IP, backend will either:
+ * - Allow queries only through archive / engine (query_only)
+ * - Block all requests (blocked)
+ * - Allow all requests (null)
+ */
+export type GetEngineIpBlockStatusResponse = 'query_only' | 'blocked' | null;
+
+export interface GetEngineMaxMintVlpAmountParams extends Subaccount {
+  // If not given, engine defaults to true (leverage/borrow enabled)
+  spotLeverage?: boolean;
+}
+
+export type GetEngineMaxMintVlpAmountResponse = BigDecimal;

package/src/types/index.ts

@@ -0,0 +1,8 @@
+export * from './clientQueryTypes';
+export * from './clientExecuteTypes';
+export * from './serverQueryTypes';
+export * from './serverQueryModelTypes';
+export * from './serverExecuteTypes';
+export * from './serverSubscriptionTypes';
+export * from './serverSubscriptionEventTypes';
+export * from './EngineServerFailureError';

package/src/types/serverExecuteTypes.ts

@@ -0,0 +1,138 @@
+import {
+  EIP712BurnVlpValues,
+  EIP712IsolatedOrderParams,
+  EIP712LinkSignerValues,
+  EIP712LiquidateSubaccountValues,
+  EIP712MintVlpValues,
+  EIP712OrderCancellationValues,
+  EIP712OrderParams,
+  EIP712OrderValues,
+  EIP712ProductOrdersCancellationValues,
+  EIP712TransferQuoteValues,
+  EIP712WithdrawCollateralValues,
+  SignedTx,
+} from '@nadohq/contracts';
+import { EngineServerOrderResponse } from './serverQueryTypes';
+
+export interface EngineServerPlaceOrderResponse {
+  digest: string;
+}
+
+export interface EngineServerCancelOrdersResponse {
+  cancelled_orders: EngineServerOrderResponse[];
+}
+
+export interface EngineServerExecuteResponseDataByType {
+  burn_vlp: null;
+  cancel_and_place: EngineServerPlaceOrderResponse;
+  cancel_orders: EngineServerCancelOrdersResponse;
+  cancel_product_orders: EngineServerCancelOrdersResponse;
+  link_signer: null;
+  liquidate_subaccount: null;
+  mint_vlp: null;
+  place_isolated_order: EngineServerPlaceOrderResponse;
+  place_order: EngineServerPlaceOrderResponse;
+  transfer_quote: null;
+  withdraw_collateral: null;
+}
+
+export interface EngineServerExecuteSuccessResult<
+  T extends EngineServerExecuteRequestType = EngineServerExecuteRequestType,
+> {
+  status: 'success';
+  data: EngineServerExecuteResponseDataByType[T];
+  signature: string;
+  request_type: EngineServerExecuteResultRequestType;
+  // NOTE: `id` is excluded from the response to avoid parsing issues.
+  // type of `id` on the backend is `u64` which can overflow until we introduce proper parsing on the SDK.
+}
+
+export interface EngineServerExecuteFailureResult {
+  status: 'failure';
+  signature: string;
+  error: string;
+  error_code: number;
+  request_type: EngineServerExecuteResultRequestType;
+}
+
+export type EngineServerExecuteResult<
+  T extends EngineServerExecuteRequestType = EngineServerExecuteRequestType,
+> = EngineServerExecuteSuccessResult<T> | EngineServerExecuteFailureResult;
+
+type EngineServerExecuteResultRequestType = {
+  [K in keyof EngineServerExecuteRequestByType]: `execute_${K}`;
+}[keyof EngineServerExecuteRequestByType];
+
+export interface EngineServerPlaceOrderParams {
+  id: number | null;
+  product_id: number;
+  order: EIP712OrderValues;
+  // Bytes
+  signature: string;
+  // Engine defaults this to true
+  spot_leverage: boolean | null;
+}
+
+export interface EngineServerPlaceIsolatedOrderParams {
+  id: number | null;
+  product_id: number;
+  isolated_order: EIP712OrderValues;
+  // Bytes
+  signature: string;
+  // Engine defaults this to false
+  borrow_margin: boolean | null;
+}
+
+export type EngineServerCancelOrdersParams = SignedTx<
+  Omit<EIP712OrderCancellationValues, 'productIds'> & {
+    // number[] is technically assignable to "Bytes", so we need to override the ByteFieldsToHex result here
+    productIds: number[];
+  }
+>;
+
+export type EngineServiceCancelAndPlaceParams = Omit<
+  EngineServerCancelOrdersParams,
+  'tx' | 'signature'
+> & {
+  cancel_tx: EngineServerCancelOrdersParams['tx'];
+  cancel_signature: EngineServerCancelOrdersParams['signature'];
+  place_order: EngineServerPlaceOrderParams;
+};
+
+type WithSpotLeverage<T> = T & {
+  spot_leverage: boolean | null;
+};
+
+export interface EngineServerExecuteRequestByType {
+  burn_vlp: SignedTx<EIP712BurnVlpValues>;
+  cancel_and_place: EngineServiceCancelAndPlaceParams;
+  cancel_orders: EngineServerCancelOrdersParams;
+  cancel_product_orders: SignedTx<
+    Omit<EIP712ProductOrdersCancellationValues, 'productIds'> & {
+      // number[] is technically assignable to "Bytes", so we need to override the ByteFieldsToHex result here
+      productIds: number[];
+    }
+  >;
+  link_signer: SignedTx<EIP712LinkSignerValues>;
+  liquidate_subaccount: SignedTx<EIP712LiquidateSubaccountValues>;
+  mint_vlp: WithSpotLeverage<SignedTx<EIP712MintVlpValues>>;
+  place_isolated_order: EngineServerPlaceIsolatedOrderParams;
+  place_order: EngineServerPlaceOrderParams;
+  transfer_quote: SignedTx<EIP712TransferQuoteValues>;
+  withdraw_collateral: WithSpotLeverage<
+    SignedTx<EIP712WithdrawCollateralValues>
+  >;
+}
+
+export type EngineServerExecuteRequestType =
+  keyof EngineServerExecuteRequestByType;
+
+export interface EngineServerExecutePlaceOrderPayload {
+  payload: EngineServerExecuteRequestByType['place_order'];
+  orderParams: EIP712OrderParams;
+}
+
+export interface EngineServerExecutePlaceIsolatedOrderPayload {
+  payload: EngineServerExecuteRequestByType['place_isolated_order'];
+  orderParams: EIP712IsolatedOrderParams;
+}