@dydxprotocol/v4-client-js 0.30.0

package/src/clients/constants.ts

@@ -0,0 +1,204 @@
+import { PageRequest } from '@dydxprotocol/dydxjs/src/codegen/cosmos/base/query/v1beta1/pagination';
+import Long from 'long';
+
+import { BroadcastOptions } from './types';
+
+export * from '../lib/constants';
+
+// Chain ID
+export const DEV_CHAIN_ID = 'dydxprotocol-testnet';
+export const STAGING_CHAIN_ID = 'dydxprotocol-testnet';
+export const TESTNET_CHAIN_ID = 'dydx-testnet-2';
+
+// ------------ API URLs ------------
+export enum IndexerApiHost {
+  DEV = 'https://indexer.v4dev.dydx.exchange',
+  STAGING = 'https://indexer.v4staging.dydx.exchange',
+  TESTNET = 'https://indexer.v4testnet2.dydx.exchange',
+  // TODO: Add MAINNET
+}
+
+export enum IndexerWSHost {
+  DEV = 'wss://indexer.v4dev.dydx.exchange/v4/ws',
+  STAGING = 'wss://indexer.v4staging.dydx.exchange/v4/ws',
+  TESTNET = 'wss://indexer.v4testnet2.dydx.exchange/v4/ws',
+  // TODO: Add MAINNET
+}
+
+export enum FaucetApiHost {
+  DEV = 'https://faucet.v4dev.expotrading.com',
+  STAGING = 'https://faucet.v4staging.dydx.exchange',
+  TESTNET = 'https://faucet.v4testnet2.dydx.exchange',
+}
+
+export enum ValidatorApiHost {
+  DEV = 'https://validator.v4dev.dydx.exchange',
+  STAGING = 'https://validator.v4staging.dydx.exchange',
+  TESTNET = 'https://validator.v4testnet2.dydx.exchange',
+  // TODO: Add MAINNET
+}
+
+// ------------ Network IDs ------------
+
+export enum NetworkId {
+  DEV = 'dydxprotocol-testnet',
+  STAGING = 'dydxprotocol-testnet',
+  TESTNET = 'dydx-testnet-2',
+  // TODO: Add MAINNET
+}
+export const NETWORK_ID_MAINNET: string | null = null;
+export const NETWORK_ID_TESTNET: string = 'dydxprotocol-testnet';
+
+// ------------ Market Statistic Day Types ------------
+export enum MarketStatisticDay {
+  ONE = '1',
+  SEVEN = '7',
+  THIRTY = '30',
+}
+
+// ------------ Order Types ------------
+// This should match OrderType in Abacus
+export enum OrderType {
+  LIMIT = 'LIMIT',
+  MARKET = 'MARKET',
+  STOP_LIMIT = 'STOP_LIMIT',
+  TAKE_PROFIT_LIMIT = 'TAKE_PROFIT',
+  STOP_MARKET = 'STOP_MARKET',
+  TAKE_PROFIT_MARKET = 'TAKE_PROFIT_MARKET',
+}
+
+// ------------ Order Side ------------
+// This should match OrderSide in Abacus
+export enum OrderSide {
+  BUY = 'BUY',
+  SELL = 'SELL',
+}
+
+// ------------ Order TimeInForce ------------
+// This should match OrderTimeInForce in Abacus
+export enum OrderTimeInForce {
+  GTT = 'GTT',
+  IOC = 'IOC',
+  FOK = 'FOK',
+}
+
+// ------------ Order Execution ------------
+// This should match OrderExecution in Abacus
+export enum OrderExecution {
+  DEFAULT = 'DEFAULT',
+  IOC = 'IOC',
+  FOK = 'FOK',
+  POST_ONLY = 'POST_ONLY',
+}
+
+// ------------ Order Status ------------
+// This should match OrderStatus in Abacus
+export enum OrderStatus {
+  BEST_EFFORT_OPENED = 'BEST_EFFORT_OPENED',
+  OPEN = 'OPEN',
+  FILLED = 'FILLED',
+  BEST_EFFORT_CANCELED = 'BEST_EFFORT_CANCELED',
+  CANCELED = 'CANCELED',
+}
+
+export enum TickerType {
+  PERPETUAL = 'PERPETUAL',  // Only PERPETUAL is supported right now
+}
+
+export enum PositionStatus {
+  OPEN = 'OPEN',
+  CLOSED = 'CLOSED',
+  LIQUIDATED = 'LIQUIDATED',
+}
+
+// ----------- Time Period for Sparklines -------------
+
+export enum TimePeriod {
+  ONE_DAY = 'ONE_DAY',
+  SEVEN_DAYS = 'SEVEN_DAYS',
+}
+
+// ------------ API Defaults ------------
+export const DEFAULT_API_TIMEOUT: number = 3_000;
+
+export const MAX_MEMO_CHARACTERS: number = 256;
+
+// Querying
+export const PAGE_REQUEST: PageRequest = {
+  key: new Uint8Array(),
+  offset: new Long(0),
+  limit: new Long(-1),
+  countTotal: true,
+  reverse: false,
+};
+
+export class IndexerConfig {
+    public restEndpoint: string;
+    public websocketEndpoint: string;
+
+    constructor(restEndpoint: string,
+      websocketEndpoint: string) {
+      this.restEndpoint = restEndpoint;
+      this.websocketEndpoint = websocketEndpoint;
+    }
+}
+
+export class ValidatorConfig {
+  public restEndpoint: string;
+  public chainId: string;
+  public broadcastOptions?: BroadcastOptions;
+
+  constructor(
+    restEndpoint: string,
+    chainId: string,
+    broadcastOptions?: BroadcastOptions,
+  ) {
+    if ((restEndpoint?.endsWith('/'))) {
+      this.restEndpoint = restEndpoint.slice(0, -1);
+    }
+    this.restEndpoint = restEndpoint;
+    this.chainId = chainId;
+    this.broadcastOptions = broadcastOptions;
+  }
+}
+
+export class Network {
+  constructor(
+    public env: string,
+    public indexerConfig: IndexerConfig,
+    public validatorConfig: ValidatorConfig,
+  ) {}
+
+  static dev(): Network {
+    const indexerConfig = new IndexerConfig(
+      IndexerApiHost.DEV,
+      IndexerWSHost.DEV,
+    );
+    const validatorConfig = new ValidatorConfig(ValidatorApiHost.DEV, DEV_CHAIN_ID);
+    return new Network('dev', indexerConfig, validatorConfig);
+  }
+
+  static staging(): Network {
+    const indexerConfig = new IndexerConfig(
+      IndexerApiHost.STAGING,
+      IndexerWSHost.STAGING,
+    );
+    const validatorConfig = new ValidatorConfig(ValidatorApiHost.STAGING, STAGING_CHAIN_ID);
+    return new Network('staging', indexerConfig, validatorConfig);
+  }
+
+  static testnet(): Network {
+    const indexerConfig = new IndexerConfig(
+      IndexerApiHost.TESTNET,
+      IndexerWSHost.TESTNET,
+    );
+    const validatorConfig = new ValidatorConfig(ValidatorApiHost.TESTNET, TESTNET_CHAIN_ID);
+    return new Network('testnet', indexerConfig, validatorConfig);
+  }
+
+  // TODO: Add mainnet(): Network
+
+  getString(): string {
+    return this.env;
+  }
+}

package/src/clients/faucet-client.ts

@@ -0,0 +1,27 @@
+import { Response } from './lib/axios';
+import RestClient from './modules/rest';
+
+export class FaucetClient extends RestClient {
+  /**
+     * @description For staging and testnet only, add USDC to an subaccount
+     *
+     * @returns The HTTP response.
+     */
+  public async fill(
+    address: string,
+    subaccountNumber: number,
+    amount: number,
+  ): Promise<Response> {
+    const uri = '/faucet/tokens';
+
+    return this.post(
+      uri,
+      {},
+      {
+        address,
+        subaccountNumber,
+        amount,
+      },
+    );
+  }
+}

package/src/clients/helpers/chain-helpers.ts

@@ -0,0 +1,208 @@
+import Long from 'long';
+
+import {
+  OrderType, OrderSide, OrderTimeInForce, OrderExecution,
+} from '../constants';
+import { Order_ConditionType, Order_Side, Order_TimeInForce } from '../modules/proto-includes';
+import { OrderFlags } from '../types';
+
+export function round(input: number, base: number): number {
+  return Math.floor(input / base) * base;
+}
+
+export function calculateQuantums(
+  size: number,
+  atomicResolution: number,
+  stepBaseQuantums: number,
+): Long {
+  const rawQuantums = size * 10 ** (-1 * atomicResolution);
+  const quantums = round(rawQuantums, stepBaseQuantums);
+  // stepBaseQuantums functions as minimum order size
+  const result = Math.max(quantums, stepBaseQuantums);
+  return Long.fromNumber(result);
+}
+
+export function calculateSubticks(
+  price: number,
+  atomicResolution: number,
+  quantumConversionExponent: number,
+  subticksPerTick: number,
+): Long {
+  const QUOTE_QUANTUMS_ATOMIC_RESOLUTION = -6;
+  const exponent = atomicResolution - quantumConversionExponent - QUOTE_QUANTUMS_ATOMIC_RESOLUTION;
+  const rawSubticks = price * 10 ** exponent;
+  const subticks = round(rawSubticks, subticksPerTick);
+  const result = Math.max(subticks, subticksPerTick);
+  return Long.fromNumber(result);
+}
+
+export function calculateSide(side: OrderSide): Order_Side {
+  return side === OrderSide.BUY ? Order_Side.SIDE_BUY : Order_Side.SIDE_SELL;
+}
+
+export function calculateTimeInForce(
+  type: OrderType,
+  timeInForce?: OrderTimeInForce,
+  execution?: OrderExecution,
+  postOnly?: boolean,
+): Order_TimeInForce {
+  switch (type) {
+    case OrderType.MARKET:
+      return Order_TimeInForce.TIME_IN_FORCE_IOC;
+
+    case OrderType.LIMIT:
+      switch (timeInForce) {
+        case OrderTimeInForce.GTT:
+          if (postOnly == null) {
+            throw new Error('postOnly must be set if order type is LIMIT and timeInForce is GTT');
+          }
+          return postOnly
+            ? Order_TimeInForce.TIME_IN_FORCE_POST_ONLY
+            : Order_TimeInForce.TIME_IN_FORCE_UNSPECIFIED;
+
+        case OrderTimeInForce.FOK:
+          return Order_TimeInForce.TIME_IN_FORCE_FILL_OR_KILL;
+
+        case OrderTimeInForce.IOC:
+          return Order_TimeInForce.TIME_IN_FORCE_IOC;
+
+        default:
+          throw new Error('Unexpected code path: timeInForce');
+      }
+
+    case OrderType.STOP_LIMIT:
+    case OrderType.TAKE_PROFIT_LIMIT:
+      if (execution == null) {
+        throw new Error('execution must be set if order type is STOP_LIMIT or TAKE_PROFIT_LIMIT');
+      }
+      switch (execution) {
+        case OrderExecution.DEFAULT:
+          return Order_TimeInForce.TIME_IN_FORCE_UNSPECIFIED;
+
+        case OrderExecution.POST_ONLY:
+          return Order_TimeInForce.TIME_IN_FORCE_POST_ONLY;
+
+        case OrderExecution.FOK:
+          return Order_TimeInForce.TIME_IN_FORCE_FILL_OR_KILL;
+
+        case OrderExecution.IOC:
+          return Order_TimeInForce.TIME_IN_FORCE_IOC;
+
+        default:
+          throw new Error('Unexpected code path: timeInForce');
+      }
+
+    case OrderType.STOP_MARKET:
+    case OrderType.TAKE_PROFIT_MARKET:
+      if (execution == null) {
+        throw new Error('execution must be set if order type is STOP_MARKET or TAKE_PROFIT_MARKET');
+      }
+      switch (execution) {
+        case OrderExecution.DEFAULT:
+          throw new Error('Execution value DEFAULT not supported for STOP_MARKET or TAKE_PROFIT_MARKET');
+
+        case OrderExecution.POST_ONLY:
+          throw new Error('Execution value POST_ONLY not supported for STOP_MARKET or TAKE_PROFIT_MARKET');
+
+        case OrderExecution.FOK:
+          return Order_TimeInForce.TIME_IN_FORCE_FILL_OR_KILL;
+
+        case OrderExecution.IOC:
+          return Order_TimeInForce.TIME_IN_FORCE_IOC;
+
+        default:
+          throw new Error('Unexpected code path: timeInForce');
+      }
+
+    default:
+      throw new Error('Unexpected code path: timeInForce');
+  }
+}
+
+export function calculateOrderFlags(type: OrderType, timeInForce?: OrderTimeInForce): OrderFlags {
+  switch (type) {
+    case OrderType.MARKET:
+      return OrderFlags.SHORT_TERM;
+
+    case OrderType.LIMIT:
+      if (timeInForce === undefined) {
+        throw new Error('timeInForce must be set if orderType is LIMIT');
+      }
+      if (timeInForce === OrderTimeInForce.GTT) {
+        return OrderFlags.LONG_TERM;
+      } else {
+        return OrderFlags.SHORT_TERM;
+      }
+
+    case OrderType.STOP_LIMIT:
+    case OrderType.TAKE_PROFIT_LIMIT:
+    case OrderType.STOP_MARKET:
+    case OrderType.TAKE_PROFIT_MARKET:
+      return OrderFlags.CONDITIONAL;
+
+    default:
+      throw new Error('Unexpected code path: orderFlags');
+  }
+}
+
+export function calculateClientMetadata(orderType: OrderType): number {
+  switch (orderType) {
+    case OrderType.MARKET:
+      return 1;
+
+    default:
+      return 0;
+  }
+}
+
+export function calculateConditionType(orderType: OrderType): Order_ConditionType {
+  switch (orderType) {
+    case OrderType.LIMIT:
+      return Order_ConditionType.CONDITION_TYPE_UNSPECIFIED;
+
+    case OrderType.MARKET:
+      return Order_ConditionType.CONDITION_TYPE_UNSPECIFIED;
+
+    case OrderType.STOP_LIMIT:
+    case OrderType.STOP_MARKET:
+      return Order_ConditionType.CONDITION_TYPE_STOP_LOSS;
+
+    case OrderType.TAKE_PROFIT_LIMIT:
+    case OrderType.TAKE_PROFIT_MARKET:
+      return Order_ConditionType.CONDITION_TYPE_TAKE_PROFIT;
+
+    default:
+      return Order_ConditionType.CONDITION_TYPE_UNSPECIFIED;
+  }
+}
+
+export function calculateConditionalOrderTriggerSubticks(
+  orderType: OrderType,
+  atomicResolution: number,
+  quantumConversionExponent: number,
+  subticksPerTick: number,
+  triggerPrice?: number,
+): Long {
+  switch (orderType) {
+    case OrderType.LIMIT:
+    case OrderType.MARKET:
+      return Long.fromNumber(0);
+
+    case OrderType.STOP_LIMIT:
+    case OrderType.STOP_MARKET:
+    case OrderType.TAKE_PROFIT_LIMIT:
+    case OrderType.TAKE_PROFIT_MARKET:
+      if (triggerPrice === undefined) {
+        throw new Error('triggerPrice must be set if orderType is STOP_LIMIT, STOP_MARKET, TAKE_PROFIT_LIMIT, or TAKE_PROFIT_MARKET');
+      }
+      return calculateSubticks(
+        triggerPrice,
+        atomicResolution,
+        quantumConversionExponent,
+        subticksPerTick,
+      );
+
+    default:
+      return Long.fromNumber(0);
+  }
+}

package/src/clients/helpers/request-helpers.ts

@@ -0,0 +1,13 @@
+export function generateQueryPath(url: string, params: {}): string {
+  const definedEntries = Object.entries(params)
+    .filter(([_key, value]: [string, unknown]) => value !== undefined);
+
+  if (!definedEntries.length) {
+    return url;
+  }
+
+  const paramsString = definedEntries.map(
+    ([key, value]: [string, unknown]) => `${key}=${value}`,
+  ).join('&');
+  return `${url}?${paramsString}`;
+}

package/src/clients/indexer-client.ts

@@ -0,0 +1,39 @@
+import { IndexerConfig, DEFAULT_API_TIMEOUT } from './constants';
+import AccountClient from './modules/account';
+import MarketsClient from './modules/markets';
+
+/**
+ * @description Client for Indexer
+ */
+export class IndexerClient {
+    public readonly config: IndexerConfig;
+    readonly apiTimeout: number;
+    readonly _markets: MarketsClient;
+    readonly _account: AccountClient;
+
+    constructor(config: IndexerConfig, apiTimeout?: number) {
+      this.config = config;
+      this.apiTimeout = apiTimeout ?? DEFAULT_API_TIMEOUT;
+
+      this._markets = new MarketsClient(config.restEndpoint);
+      this._account = new AccountClient(config.restEndpoint);
+    }
+
+    /**
+     * @description Get the public module, used for interacting with public endpoints.
+     *
+     * @returns The public module
+     */
+    get markets(): MarketsClient {
+      return this._markets;
+    }
+
+    /**
+     * @description Get the private module, used for interacting with private endpoints.
+     *
+     * @returns The private module
+     */
+    get account(): AccountClient {
+      return this._account;
+    }
+}

package/src/clients/lib/axios/axiosRequest.ts

@@ -0,0 +1,44 @@
+import axios, { AxiosRequestConfig } from 'axios';
+
+import { Data } from '../../types';
+import {
+  AxiosServerError,
+  AxiosError,
+} from './errors';
+import { RequestMethod } from './types';
+
+export interface Response {
+  status: number,
+  data: Data,
+  headers: {},
+}
+
+async function axiosRequest(options: AxiosRequestConfig): Promise<Response> {
+  try {
+    return await axios(options);
+  } catch (error) {
+    // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
+    if (error.isAxiosError) {
+      // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
+      if (error.response) {
+        throw new AxiosServerError(error.response, error);
+      }
+      throw new AxiosError(`Axios: ${error.message}`, error);
+    }
+    throw error;
+  }
+}
+
+export function request(
+  url: string,
+  method: RequestMethod = RequestMethod.GET,
+  body?: unknown | null,
+  headers: {} = {},
+): Promise<Response> {
+  return axiosRequest({
+    url,
+    method,
+    data: body,
+    headers,
+  });
+}

package/src/clients/lib/axios/errors.ts

@@ -0,0 +1,46 @@
+import {
+  WrappedError,
+} from '../errors';
+
+interface AxiosOriginalError extends Error {
+  isAxiosError: true;
+  toJSON(): {};
+}
+
+interface AxiosErrorResponse {
+  status: number,
+  statusText: string,
+  data: {},
+}
+
+/**
+ * @description An error thrown by axios.
+ *
+ * Depending on your use case, if logging errors, you may want to catch axios errors and sanitize
+ * them to remove the request and response objects, or sensitive fields. For example:
+ *
+ *   this.originalError = _.omit(originalError.toJSON(), 'config')
+ */
+export class AxiosError extends WrappedError {}
+
+/**
+ * @description Axios error with response error fields.
+ */
+export class AxiosServerError extends AxiosError {
+    public readonly status: number;
+    public readonly statusText: string;
+    public readonly data: {};
+
+    constructor(
+      response: AxiosErrorResponse,
+      originalError: AxiosOriginalError,
+    ) {
+      super(
+        `${response.status}: ${response.statusText} - ${JSON.stringify(response.data, null, 2)}`,
+        originalError,
+      );
+      this.status = response.status;
+      this.statusText = response.statusText;
+      this.data = response.data;
+    }
+}

package/src/clients/lib/axios/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Simple handling of axios requests and errors.
+ */
+
+export * from './axiosRequest';
+export * from './errors';
+export * from './types';

package/src/clients/lib/axios/types.ts

@@ -0,0 +1,6 @@
+export enum RequestMethod {
+  POST = 'POST',
+  PUT = 'PUT',
+  GET = 'GET',
+  DELETE = 'DELETE',
+}

package/src/clients/lib/errors.ts

@@ -0,0 +1,70 @@
+import {
+  BroadcastTxSyncResponse,
+} from '@cosmjs/tendermint-rpc/build/tendermint37';
+
+/**
+ * An edge-case was hit in the client that should never have been reached.
+ */
+export class UnexpectedClientError extends Error {
+  constructor(
+  ) {
+    super('An unexpected error occurred on the client');
+    this.name = 'UnexpectedClientError';
+  }
+}
+
+/**
+ * An error occurred during the broadcasting process.
+ */
+export class BroadcastErrorObject extends Error {
+  result: BroadcastTxSyncResponse;
+  code: number;
+  codespace?: string;
+
+  constructor(
+    message: string,
+    result: BroadcastTxSyncResponse,
+  ) {
+    super(message);
+    this.name = 'BroadcastError';
+    this.result = result;
+    this.code = result.code;
+    this.codespace = result.codespace;
+  }
+}
+
+/**
+ * User error occurred during a client operation.
+ */
+export class UserError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'UserError';
+  }
+}
+
+/**
+ * @description Base class for custom errors.
+ */
+export class CustomError extends Error {
+  constructor(message: string) {
+    super(message);
+    // Set a more specific name. This will show up in e.g. console.log.
+    this.name = this.constructor.toString();
+  }
+}
+
+/**
+ * @description Base class for a custom error which wraps another error.
+ */
+export class WrappedError extends CustomError {
+    public readonly originalError: Error;
+
+    constructor(
+      message: string,
+      originalError: Error,
+    ) {
+      super(message);
+      this.originalError = originalError;
+    }
+}

package/src/clients/lib/registry.ts

@@ -0,0 +1,30 @@
+import { GeneratedType, Registry } from '@cosmjs/proto-signing';
+import { defaultRegistryTypes } from '@cosmjs/stargate';
+import {
+  MsgPlaceOrder,
+  MsgCancelOrder,
+} from '@dydxprotocol/dydxjs/src/codegen/dydxprotocol/clob/tx';
+import {
+  MsgWithdrawFromSubaccount,
+  MsgDepositToSubaccount,
+} from '@dydxprotocol/dydxjs/src/codegen/dydxprotocol/sending/transfer';
+import {
+  MsgCreateTransfer,
+} from '@dydxprotocol/dydxjs/src/codegen/dydxprotocol/sending/tx';
+
+export const registry: ReadonlyArray<[string, GeneratedType]> = [];
+export function generateRegistry(): Registry {
+  return new Registry([
+    // clob
+    ['/dydxprotocol.clob.MsgPlaceOrder', MsgPlaceOrder as GeneratedType],
+    ['/dydxprotocol.clob.MsgCancelOrder', MsgCancelOrder as GeneratedType],
+
+    // sending
+    ['/dydxprotocol.sending.MsgCreateTransfer', MsgCreateTransfer as GeneratedType],
+    ['/dydxprotocol.sending.MsgWithdrawFromSubaccount', MsgWithdrawFromSubaccount as GeneratedType],
+    ['/dydxprotocol.sending.MsgDepositToSubaccount', MsgDepositToSubaccount as GeneratedType],
+
+    // default types
+    ...defaultRegistryTypes,
+  ]);
+}