@nadohq/trigger-client 0.1.0-alpha.1

package/src/TriggerClient.ts

@@ -0,0 +1,284 @@
+import {
+  EIP712CancelOrdersParams,
+  EIP712CancelProductOrdersParams,
+  EIP712ListTriggerOrdersParams,
+  EIP712OrderParams,
+  getDefaultRecvTime,
+  getNadoEIP712Values,
+  getOrderNonce,
+  getSignedTransactionRequest,
+  getTriggerOrderNonce,
+  SignableRequestType,
+  SignableRequestTypeToParams,
+  WalletClientWithAccount,
+} from '@nadohq/contracts';
+import { toIntegerString, WalletNotProvidedError } from '@nadohq/utils';
+import axios, { AxiosInstance, AxiosResponse } from 'axios';
+import { mapServerOrderInfo, mapTriggerCriteria } from './dataMappers';
+import {
+  TriggerCancelOrdersParams,
+  TriggerCancelProductOrdersParams,
+  TriggerListOrdersParams,
+  TriggerListOrdersResponse,
+  TriggerOrderInfo,
+  TriggerPlaceOrderParams,
+  TriggerServerExecuteRequestByType,
+  TriggerServerExecuteRequestType,
+  TriggerServerExecuteResult,
+  TriggerServerExecuteSuccessResult,
+  TriggerServerQueryRequestByType,
+  TriggerServerQueryRequestType,
+  TriggerServerQueryResponse,
+  TriggerServerQueryResponseByType,
+  TriggerServerQuerySuccessResponse,
+} from './types';
+import { TriggerServerFailureError } from './types/TriggerServerFailureError';
+
+export interface TriggerClientOpts {
+  // Server URL
+  url: string;
+  // Wallet client for EIP712 signing
+  walletClient?: WalletClientWithAccount;
+  // Linked signer registered through the engine, if provided, execute requests will use this signer
+  linkedSignerWalletClient?: WalletClientWithAccount;
+}
+
+/**
+ * Client for all trigger service requests
+ */
+export class TriggerClient {
+  readonly opts: TriggerClientOpts;
+  readonly axiosInstance: AxiosInstance;
+
+  constructor(opts: TriggerClientOpts) {
+    this.opts = opts;
+    this.axiosInstance = axios.create({ withCredentials: true });
+  }
+
+  /**
+   * Sets the linked signer for requests
+   *
+   * @param linkedSignerWalletClient The linkedSigner to use for all signatures. Set to null to revert to the chain signer
+   */
+  public setLinkedSigner(
+    linkedSignerWalletClient: WalletClientWithAccount | null,
+  ) {
+    this.opts.linkedSignerWalletClient = linkedSignerWalletClient ?? undefined;
+  }
+
+  /*
+  Executes
+   */
+
+  async placeTriggerOrder(params: TriggerPlaceOrderParams) {
+    const orderParams: EIP712OrderParams = {
+      amount: params.order.amount,
+      expiration: params.order.expiration,
+      price: params.order.price,
+      subaccountName: params.order.subaccountName,
+      subaccountOwner: params.order.subaccountOwner,
+      nonce: params.nonce ?? getTriggerOrderNonce(),
+    };
+    const signature = await this.sign(
+      'place_order',
+      params.verifyingAddr,
+      params.chainId,
+      orderParams,
+    );
+
+    const executeParams: TriggerServerExecuteRequestByType['place_order'] = {
+      id: params.id ?? null,
+      order: getNadoEIP712Values('place_order', orderParams),
+      trigger: mapTriggerCriteria(params.triggerCriteria),
+      signature,
+      product_id: params.productId,
+      spot_leverage: params.spotLeverage ?? null,
+      digest: params.digest ?? null,
+    };
+
+    return this.execute('place_order', executeParams);
+  }
+
+  async cancelTriggerOrders(params: TriggerCancelOrdersParams) {
+    const cancelOrdersParams: EIP712CancelOrdersParams = {
+      digests: params.digests,
+      nonce: params.nonce ?? getOrderNonce(),
+      productIds: params.productIds,
+      subaccountName: params.subaccountName,
+      subaccountOwner: params.subaccountOwner,
+    };
+    const tx = getNadoEIP712Values('cancel_orders', cancelOrdersParams);
+
+    const executeParams: TriggerServerExecuteRequestByType['cancel_orders'] = {
+      signature: await this.sign(
+        'cancel_orders',
+        params.verifyingAddr,
+        params.chainId,
+        cancelOrdersParams,
+      ),
+      tx,
+    };
+
+    return this.execute('cancel_orders', executeParams);
+  }
+
+  async cancelProductOrders(params: TriggerCancelProductOrdersParams) {
+    const cancelProductOrdersParams: EIP712CancelProductOrdersParams = {
+      nonce: params.nonce ?? getOrderNonce(),
+      productIds: params.productIds,
+      subaccountName: params.subaccountName,
+      subaccountOwner: params.subaccountOwner,
+    };
+    const tx = getNadoEIP712Values(
+      'cancel_product_orders',
+      cancelProductOrdersParams,
+    );
+
+    const executeParams: TriggerServerExecuteRequestByType['cancel_product_orders'] =
+      {
+        signature: await this.sign(
+          'cancel_product_orders',
+          params.verifyingAddr,
+          params.chainId,
+          cancelProductOrdersParams,
+        ),
+        tx,
+      };
+
+    return this.execute('cancel_product_orders', executeParams);
+  }
+
+  /*
+  Queries
+   */
+  async listOrders(
+    params: TriggerListOrdersParams,
+  ): Promise<TriggerListOrdersResponse> {
+    const signatureParams: EIP712ListTriggerOrdersParams = {
+      // Default to 90 seconds from now if no recvTime is provided
+      recvTime: toIntegerString(params.recvTime ?? getDefaultRecvTime()),
+      subaccountName: params.subaccountName,
+      subaccountOwner: params.subaccountOwner,
+    };
+
+    const tx = getNadoEIP712Values('list_trigger_orders', signatureParams);
+    const signature = await this.sign(
+      'list_trigger_orders',
+      params.verifyingAddr,
+      params.chainId,
+      signatureParams,
+    );
+
+    const queryParams: TriggerServerQueryRequestByType['list_trigger_orders'] =
+      {
+        limit: params.limit,
+        max_update_time: params.maxUpdateTimeInclusive,
+        pending: params.pending,
+        product_id: params.productId,
+        digests: params.digests,
+        signature,
+        tx,
+      };
+
+    const baseResponse = await this.query('list_trigger_orders', queryParams);
+
+    const orders: TriggerOrderInfo[] =
+      baseResponse.orders.map(mapServerOrderInfo);
+
+    return {
+      orders,
+    };
+  }
+
+  /*
+  Base Fns
+   */
+  protected async sign<T extends SignableRequestType>(
+    requestType: T,
+    verifyingContract: string,
+    chainId: number,
+    params: SignableRequestTypeToParams[T],
+  ) {
+    // Use the linked signer if provided, otherwise use the default signer provided to the engine
+    const walletClient =
+      this.opts.linkedSignerWalletClient ?? this.opts.walletClient;
+
+    if (walletClient == null) {
+      throw new WalletNotProvidedError();
+    }
+
+    return getSignedTransactionRequest({
+      chainId,
+      requestParams: params,
+      requestType,
+      walletClient,
+      verifyingContract,
+    });
+  }
+
+  /**
+   * POSTs an execute message to the trigger service and returns the successful response. Throws the failure response wrapped
+   * in an TriggerServerFailureError on failure.
+   *
+   * @param requestType
+   * @param params
+   */
+  protected async execute<TRequestType extends TriggerServerExecuteRequestType>(
+    requestType: TRequestType,
+    params: TriggerServerExecuteRequestByType[TRequestType],
+  ): Promise<TriggerServerExecuteSuccessResult<TRequestType>> {
+    const reqBody = {
+      [requestType]: params,
+    };
+    const response = await this.axiosInstance.post<
+      TriggerServerExecuteResult<TRequestType>
+    >(`${this.opts.url}/execute`, reqBody);
+
+    this.checkResponseStatus(response);
+    this.checkServerStatus(response);
+
+    // checkServerStatus catches the failure result and throws the error, so the cast to the success response is acceptable here
+    return response.data as TriggerServerExecuteSuccessResult<TRequestType>;
+  }
+
+  protected async query<TRequestType extends TriggerServerQueryRequestType>(
+    requestType: TRequestType,
+    params: TriggerServerQueryRequestByType[TRequestType],
+  ): Promise<TriggerServerQueryResponseByType[TRequestType]> {
+    const reqBody = {
+      type: requestType,
+      ...params,
+    };
+    const response = await this.axiosInstance.post<
+      TriggerServerQueryResponse<TRequestType>
+    >(`${this.opts.url}/query`, reqBody);
+
+    this.checkResponseStatus(response);
+    this.checkServerStatus(response);
+
+    // checkServerStatus throws on failure responses so the cast to the success response is acceptable here
+    const successResponse = response as AxiosResponse<
+      TriggerServerQuerySuccessResponse<TRequestType>
+    >;
+
+    return successResponse.data.data;
+  }
+
+  private checkResponseStatus(response: AxiosResponse) {
+    if (response.status !== 200 || !response.data) {
+      throw Error(
+        `Unexpected response from server: ${response.status} ${response.statusText}`,
+      );
+    }
+  }
+
+  private checkServerStatus(
+    response: AxiosResponse<
+      TriggerServerExecuteResult | TriggerServerQueryResponse
+    >,
+  ) {
+    if (response.data.status !== 'success') {
+      throw new TriggerServerFailureError(response.data);
+    }
+  }
+}

package/src/dataMappers.ts

@@ -0,0 +1,124 @@
+import {
+  addDecimals,
+  removeDecimals,
+  toBigDecimal,
+  toIntegerString,
+} from '@nadohq/utils';
+import {
+  TriggerCriteria,
+  TriggerOrder,
+  TriggerOrderInfo,
+  TriggerOrderStatus,
+  TriggerServerOrderInfo,
+  TriggerServerOrderStatus,
+  TriggerServerTriggerCriteria,
+} from './types';
+
+export function mapTriggerServerOrderStatus(
+  status: TriggerServerOrderStatus,
+): TriggerOrderStatus {
+  if (status === 'pending') {
+    return {
+      type: 'pending',
+    };
+  } else if ('cancelled' in status) {
+    return {
+      type: 'cancelled',
+      reason: status.cancelled,
+    };
+  } else if ('internal_error' in status) {
+    return {
+      type: 'internal_error',
+      error: status.internal_error,
+    };
+  } else if ('triggered' in status) {
+    return {
+      type: 'triggered',
+      result: status.triggered,
+    };
+  }
+  throw Error(`Unknown trigger order status: ${JSON.stringify(status)}`);
+}
+
+export function mapTriggerCriteria(
+  criteria: TriggerCriteria,
+): TriggerServerTriggerCriteria {
+  const priceValue = toIntegerString(addDecimals(criteria.triggerPrice));
+  switch (criteria.type) {
+    case 'oracle_price_above':
+      return { price_above: priceValue };
+    case 'oracle_price_below':
+      return { price_below: priceValue };
+    case 'last_price_above':
+      return { last_price_above: priceValue };
+    case 'last_price_below':
+      return { last_price_below: priceValue };
+    case 'mid_price_above':
+      return { mid_price_above: priceValue };
+    case 'mid_price_below':
+      return { mid_price_below: priceValue };
+  }
+}
+
+export function mapServerTriggerCriteria(
+  criteria: TriggerServerTriggerCriteria,
+): TriggerCriteria {
+  if ('price_above' in criteria) {
+    return {
+      type: 'oracle_price_above',
+      triggerPrice: removeDecimals(criteria.price_above),
+    };
+  }
+  if ('price_below' in criteria) {
+    return {
+      type: 'oracle_price_below',
+      triggerPrice: removeDecimals(criteria.price_below),
+    };
+  }
+  if ('last_price_above' in criteria) {
+    return {
+      type: 'last_price_above',
+      triggerPrice: removeDecimals(criteria.last_price_above),
+    };
+  }
+  if ('last_price_below' in criteria) {
+    return {
+      type: 'last_price_below',
+      triggerPrice: removeDecimals(criteria.last_price_below),
+    };
+  }
+  if ('mid_price_above' in criteria) {
+    return {
+      type: 'mid_price_above',
+      triggerPrice: removeDecimals(criteria.mid_price_above),
+    };
+  }
+  if ('mid_price_below' in criteria) {
+    return {
+      type: 'mid_price_below',
+      triggerPrice: removeDecimals(criteria.mid_price_below),
+    };
+  }
+  throw new Error(`Unknown trigger criteria: ${JSON.stringify(criteria)}`);
+}
+
+export function mapServerOrderInfo(
+  info: TriggerServerOrderInfo,
+): TriggerOrderInfo {
+  const { order: serverOrder, status, updated_at } = info;
+  const order: TriggerOrder = {
+    amount: toBigDecimal(serverOrder.order.amount),
+    expiration: toBigDecimal(serverOrder.order.expiration),
+    nonce: serverOrder.order.nonce,
+    price: removeDecimals(toBigDecimal(serverOrder.order.priceX18)),
+    digest: serverOrder.digest,
+    productId: serverOrder.product_id,
+    triggerCriteria: mapServerTriggerCriteria(serverOrder.trigger),
+  };
+  return {
+    serverOrder,
+    order,
+    status: mapTriggerServerOrderStatus(status),
+    updatedAt: updated_at,
+  };
+}

package/src/endpoints.ts

@@ -0,0 +1,7 @@
+import { ChainEnv } from '@nadohq/contracts';
+
+export const TRIGGER_CLIENT_ENDPOINTS: Record<ChainEnv, string> = {
+  local: 'http://localhost:80/trigger',
+  arbitrumTestnet: 'https://trigger.sepolia-test.vertexprotocol.com/v1',
+  arbitrum: 'https://trigger.prod.vertexprotocol.com/v1',
+};

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './TriggerClient';
+export * from './endpoints';

package/src/types/TriggerServerFailureError.ts

@@ -0,0 +1,12 @@
+import { TriggerServerQueryFailureResponse } from './serverQueryTypes';
+import { EngineServerExecuteFailureResult } from '@nadohq/engine-client';
+
+export class TriggerServerFailureError extends Error {
+  constructor(
+    readonly responseData:
+      | TriggerServerQueryFailureResponse
+      | EngineServerExecuteFailureResult,
+  ) {
+    super();
+  }
+}

package/src/types/clientTypes.ts

@@ -0,0 +1,109 @@
+import {
+  EIP712CancelOrdersParams,
+  EIP712CancelProductOrdersParams,
+  Subaccount,
+} from '@nadohq/contracts';
+import {
+  EngineOrderParams,
+  EngineServerExecuteResult,
+} from '@nadohq/engine-client';
+import { BigDecimal, BigDecimalish } from '@nadohq/utils';
+import { TriggerServerOrder } from './serverQueryTypes';
+
+type WithOptionalNonce<T> = Omit<T, 'nonce'> & { nonce?: string };
+
+export type TriggerCriteriaType =
+  | 'oracle_price_above'
+  | 'oracle_price_below'
+  | 'last_price_above'
+  | 'last_price_below'
+  | 'mid_price_above'
+  | 'mid_price_below';
+
+export type TriggerCriteria = {
+  type: TriggerCriteriaType;
+  triggerPrice: BigDecimalish;
+};
+
+export type TriggerOrderStatus =
+  | {
+      type: 'pending';
+    }
+  | {
+      type: 'cancelled';
+      reason: string;
+    }
+  | {
+      type: 'triggered';
+      result: EngineServerExecuteResult;
+    }
+  | {
+      type: 'internal_error';
+      error: string;
+    };
+
+interface SignatureParams {
+  // Orderbook address for placement, endpoint address for cancellation & listing
+  verifyingAddr: string;
+  chainId: number;
+}
+
+/**
+ * Executes
+ */
+
+export interface TriggerPlaceOrderParams extends SignatureParams {
+  id?: number;
+  productId: number;
+  order: EngineOrderParams;
+  triggerCriteria: TriggerCriteria;
+  // If not given, engine defaults to true (leverage/borrow enabled)
+  spotLeverage?: boolean;
+  digest?: string;
+  nonce?: string;
+}
+
+export type TriggerCancelOrdersParams = SignatureParams &
+  WithOptionalNonce<EIP712CancelOrdersParams>;
+
+export type TriggerCancelProductOrdersParams = SignatureParams &
+  WithOptionalNonce<EIP712CancelProductOrdersParams>;
+
+/**
+ * Queries
+ */
+
+export interface TriggerListOrdersParams extends Subaccount, SignatureParams {
+  // In millis, defaults to 90s in the future
+  recvTime?: BigDecimal;
+  // If not given, defaults to all products
+  productId?: number;
+  // Pending trigger orders only, ignores cancelled & triggered orders
+  pending: boolean;
+  // In seconds
+  maxUpdateTimeInclusive?: number;
+  // When provided, the associated trigger orders are returned regardless of other filters
+  digests?: string[];
+  limit?: number;
+}
+
+export interface TriggerOrder {
+  productId: number;
+  triggerCriteria: TriggerCriteria;
+  price: BigDecimal;
+  amount: BigDecimal;
+  expiration: BigDecimal;
+  nonce: string;
+  digest: string;
+}
+
+export interface TriggerOrderInfo {
+  order: TriggerOrder;
+  serverOrder: TriggerServerOrder;
+  status: TriggerOrderStatus;
+  updatedAt: number;
+}
+
+export interface TriggerListOrdersResponse {
+  orders: TriggerOrderInfo[];
+}

package/src/types/index.ts

@@ -0,0 +1,4 @@
+export * from './clientTypes';
+export * from './serverExecuteTypes';
+export * from './serverQueryTypes';
+export * from './TriggerServerFailureError';

package/src/types/serverExecuteTypes.ts

@@ -0,0 +1,63 @@
+import { EIP712OrderValues } from '@nadohq/contracts';
+import {
+  EngineServerExecuteFailureResult,
+  EngineServerExecuteRequestByType,
+  EngineServerExecuteSuccessResult,
+} from '@nadohq/engine-client';
+
+export type TriggerServerTriggerCriteria =
+  // These trigger on fast oracle price
+  | {
+      price_above: string;
+    }
+  | {
+      price_below: string;
+    }
+  // These trigger on last trade price
+  | {
+      last_price_above: string;
+    }
+  | {
+      last_price_below: string;
+    }
+  // These trigger on mid-book price
+  | {
+      mid_price_above: string;
+    }
+  | {
+      mid_price_below: string;
+    };
+
+export interface TriggerServerPlaceOrderParams {
+  id: number | null;
+  product_id: number;
+  order: EIP712OrderValues;
+  trigger: TriggerServerTriggerCriteria;
+  signature: string;
+  digest: string | null;
+  // Trigger service defaults this to true
+  spot_leverage: boolean | null;
+}
+
+export type TriggerServerCancelOrdersParams =
+  EngineServerExecuteRequestByType['cancel_orders'];
+
+export type TriggerServerCancelProductOrdersParams =
+  EngineServerExecuteRequestByType['cancel_product_orders'];
+
+export interface TriggerServerExecuteRequestByType {
+  place_order: TriggerServerPlaceOrderParams;
+  cancel_orders: TriggerServerCancelOrdersParams;
+  cancel_product_orders: TriggerServerCancelProductOrdersParams;
+}
+
+export type TriggerServerExecuteRequestType =
+  keyof TriggerServerExecuteRequestByType;
+
+export type TriggerServerExecuteSuccessResult<
+  T extends TriggerServerExecuteRequestType = TriggerServerExecuteRequestType,
+> = EngineServerExecuteSuccessResult<T>;
+
+export type TriggerServerExecuteResult<
+  T extends TriggerServerExecuteRequestType = TriggerServerExecuteRequestType,
+> = TriggerServerExecuteSuccessResult<T> | EngineServerExecuteFailureResult;

package/src/types/serverQueryTypes.ts

@@ -0,0 +1,83 @@
+import { EIP712ListTriggerOrdersValues, SignedTx } from '@nadohq/contracts';
+import { EngineServerExecuteResult } from '@nadohq/engine-client';
+import { TriggerServerPlaceOrderParams } from './serverExecuteTypes';
+
+export type TriggerServerOrderStatus =
+  | 'pending'
+  | {
+      // Result from sending to engine
+      triggered: EngineServerExecuteResult;
+    }
+  | {
+      // Reason string
+      cancelled: string;
+    }
+  | {
+      // Error message
+      internal_error: string;
+    };
+
+/**
+ * Request types
+ */
+
+export interface TriggerServerListTriggerOrdersParams
+  extends SignedTx<EIP712ListTriggerOrdersValues> {
+  pending: boolean;
+  // If not given, defaults to all products
+  product_id?: number;
+  max_update_time?: number;
+  digests?: string[];
+  limit?: number;
+}
+
+export interface TriggerServerQueryRequestByType {
+  list_trigger_orders: TriggerServerListTriggerOrdersParams;
+}
+
+export type TriggerServerQueryRequestType =
+  keyof TriggerServerQueryRequestByType;
+
+/**
+ * Response types
+ */
+
+export type TriggerServerOrder = TriggerServerPlaceOrderParams & {
+  // Digest is always populated here
+  digest: string;
+};
+
+export interface TriggerServerOrderInfo {
+  order: TriggerServerOrder;
+  status: TriggerServerOrderStatus;
+  updated_at: number;
+}
+
+export interface TriggerServerListTriggerOrdersResponse {
+  orders: TriggerServerOrderInfo[];
+}
+
+export interface TriggerServerQueryResponseByType {
+  list_trigger_orders: TriggerServerListTriggerOrdersResponse;
+}
+
+export interface TriggerServerQuerySuccessResponse<
+  TQueryType extends
+    keyof TriggerServerQueryResponseByType = TriggerServerQueryRequestType,
+> {
+  status: 'success';
+  data: TriggerServerQueryResponseByType[TQueryType];
+}
+
+export interface TriggerServerQueryFailureResponse {
+  status: 'failure';
+  error: string;
+  error_code: number;
+}
+
+export type TriggerServerQueryResponse<
+  TQueryType extends
+    keyof TriggerServerQueryResponseByType = TriggerServerQueryRequestType,
+> =
+  | TriggerServerQuerySuccessResponse<TQueryType>
+  | TriggerServerQueryFailureResponse;