@dydxprotocol/v4-client-js 0.30.0

package/src/clients/socket-client.ts

@@ -0,0 +1,296 @@
+import WebSocket, { MessageEvent } from 'ws';
+
+import { IndexerConfig } from './constants';
+
+enum OutgoingMessageTypes {
+  PING = 'ping',
+  SUBSCRIBE = 'subscribe',
+  UNSUBSCRIBE = 'unsubscribe',
+}
+
+enum SocketChannels {
+  SUBACCOUNTS = 'v4_subaccounts',
+  ORDERBOOK = 'v4_orderbook',
+  TRADES = 'v4_trades',
+  MARKETS = 'v4_markets',
+  CANDLES = 'v4_candles',
+}
+
+export enum IncomingMessageTypes {
+  CONNECTED = 'connected',
+  SUBSCRIBED = 'subscribed',
+  ERROR = 'error',
+  CHANNEL_DATA = 'channel_data',
+  CHANNEL_BATCH_DATA = 'channel_batch_data',
+  PONG = 'pong',
+}
+
+export enum CandlesResolution {
+  ONE_MINUTE = '1MIN',
+  FIVE_MINUTES = '5MINS',
+  FIFTEEN_MINUTES = '15MINS',
+  THIRTY_MINUTES = '30MINS',
+  ONE_HOUR = '1HOUR',
+  FOUR_HOURS = '4HOURS',
+  ONE_DAY = '1DAY',
+}
+
+export class SocketClient {
+    private url: string;
+    private ws?: WebSocket;
+    private onOpenCallback?: () => void;
+    private onCloseCallback?: () => void;
+    private onMessageCallback?: (event: MessageEvent) => void;
+    private pingInterval: number = 30_000;
+    private lastMessageTime: number = Date.now();
+    private pingIntervalId?: NodeJS.Timeout;
+
+    constructor(
+      config: IndexerConfig,
+      onOpenCallback: () => void,
+      onCloseCallback: ()=> void,
+      onMessageCallback: (event: MessageEvent)=> void,
+    ) {
+      this.url = config.websocketEndpoint;
+      this.onOpenCallback = onOpenCallback;
+      this.onCloseCallback = onCloseCallback;
+      this.onMessageCallback = onMessageCallback;
+    }
+
+    connect(): void {
+      this.ws = new WebSocket(this.url);
+      this.ws.addEventListener('open', this.handleOpen.bind(this));
+      this.ws.addEventListener('close', this.handleClose.bind(this));
+      this.ws.addEventListener('message', this.handleMessage.bind(this));
+    }
+
+    /**
+     * @description Close the websocket connection.
+     *
+     */
+    close(): void {
+      this.ws?.close();
+      this.ws = undefined;
+    }
+
+    /**
+     * @description Send data to the websocket connection.
+     *
+     */
+    send(data: string): void {
+      this.ws?.send(data);
+    }
+
+    private handleOpen(): void {
+      if (this.onOpenCallback) {
+        this.onOpenCallback();
+      }
+      this.restartPingInterval();
+    }
+
+    private handleClose(): void {
+      if (this.onCloseCallback) {
+        this.onCloseCallback();
+      }
+      clearInterval(this.pingIntervalId);
+    }
+
+    private handleMessage(event: MessageEvent): void {
+      if (event.data === 'PING') {
+        this.send('PONG');
+      } else {
+        this.lastMessageTime = Date.now();
+        if (this.onMessageCallback) {
+          this.onMessageCallback(event);
+        }
+      }
+      this.restartPingInterval();
+    }
+
+    private restartPingInterval(): void {
+      clearInterval(this.pingIntervalId);
+      this.pingIntervalId = setInterval(() => {
+        const elapsedTime = Date.now() - this.lastMessageTime;
+        if (elapsedTime > this.pingInterval) {
+          this.send('PING');
+        }
+      }, this.pingInterval);
+    }
+
+    /**
+     * @description Set callback when the socket is opened.
+     *
+     */
+    set onOpen(callback: () => void) {
+      this.onOpenCallback = callback;
+    }
+
+    /**
+     * @description Set callback when the socket is closed.
+     *
+     */
+    set onClose(callback: () => void) {
+      this.onCloseCallback = callback;
+    }
+
+    /**
+     * @description Set callback when the socket receives a message.
+     *
+     */
+    set onMessage(callback: (event: MessageEvent) => void) {
+      this.onMessageCallback = callback;
+    }
+
+    /**
+     * @description Send a subscribe message to the websocket connection.
+     *
+     */
+    subscribe(channel: string, params?: object): void {
+      const message = {
+        type: OutgoingMessageTypes.SUBSCRIBE,
+        channel,
+        ...params,
+      };
+      this.send(JSON.stringify(message));
+    }
+
+    /**
+     * @description Send an unsubscribe message to the websocket connection.
+     *
+     */
+    unsubscribe(channel: string, params?: object): void {
+      const message = {
+        type: OutgoingMessageTypes.UNSUBSCRIBE,
+        channel,
+        ...params,
+      };
+      this.send(JSON.stringify(message));
+    }
+
+    /**
+     * @description Subscribe to markets channel.
+     *
+     */
+    subscribeToMarkets(): void {
+      const channel = SocketChannels.MARKETS;
+      const params = {
+        batched: true,
+      };
+      this.subscribe(channel, params);
+    }
+
+    /**
+     * @description Unsubscribe from markets channel
+     *
+     */
+    unsubscribeFromMarkets(): void {
+      const channel = SocketChannels.MARKETS;
+      this.unsubscribe(channel);
+    }
+
+    /**
+     * @description Subscribe to trade channel
+     * for a specific market.
+     *
+     */
+    subscribeToTrades(market: string): void {
+      const channel = SocketChannels.TRADES;
+      const params = {
+        id: market,
+        batched: true,
+      };
+      this.subscribe(channel, params);
+    }
+
+    /**
+     * @description Unscribed from trade channel
+     * for a specific market.
+     *
+     */
+    unsubscribeFromTrades(market: string): void {
+      const channel = SocketChannels.TRADES;
+      const params = {
+        id: market,
+      };
+      this.unsubscribe(channel, params);
+    }
+
+    /**
+     * @description Subscribe to orderbook channel
+     * for a specific market.
+     *
+     */
+    subscribeToOrderbook(market: string): void {
+      const channel = SocketChannels.ORDERBOOK;
+      const params = {
+        id: market,
+        batched: true,
+      };
+      this.subscribe(channel, params);
+    }
+
+    /**
+     * @description Unsubscribe from orderbook channel
+     * for a specific market.
+     */
+    unsubscribeFromOrderbook(market: string): void {
+      const channel = SocketChannels.ORDERBOOK;
+      const params = {
+        id: market,
+      };
+      this.unsubscribe(channel, params);
+    }
+
+    /**
+     * @description Subscribe to candles channel
+     * for a specific market and resolution.
+     *
+     */
+    subscribeToCandles(market: string, resolution: CandlesResolution): void {
+      const channel = SocketChannels.CANDLES;
+      const params = {
+        id: `${market}/${resolution}`,
+        batched: true,
+      };
+      this.subscribe(channel, params);
+    }
+
+    /**
+     * @description Unsubscribe from candles channel
+     * for a specific market and resolution.
+     */
+    unsubscribeFromCandles(market: string, resolution: CandlesResolution): void {
+      const channel = SocketChannels.CANDLES;
+      const params = {
+        id: `${market}/${resolution}`,
+      };
+      this.unsubscribe(channel, params);
+    }
+
+    /**
+     * @description Subscribe to subaccount channel
+     * for a specific address and subaccount number.
+     */
+    subscribeToSubaccount(address: string, subaccountNumber: number): void {
+      const channel = SocketChannels.SUBACCOUNTS;
+      const subaccountId = `${address}/${subaccountNumber}`;
+      const params = {
+        id: subaccountId,
+      };
+      this.subscribe(channel, params);
+    }
+
+    /**
+     * @description Unsubscribe from subaccount channel
+     * for a specific address and subaccount number.
+     *
+     */
+    unsubscribeFromSubaccount(address: string, subaccountNumber: number): void {
+      const channel = SocketChannels.SUBACCOUNTS;
+      const subaccountId = `${address}/${subaccountNumber}`;
+      const params = {
+        id: subaccountId,
+      };
+      this.unsubscribe(channel, params);
+    }
+}

package/src/clients/subaccount.ts

@@ -0,0 +1,24 @@
+import LocalWallet from './modules/local-wallet';
+
+export class Subaccount {
+    readonly wallet: LocalWallet;
+    // TODO, change address to Wallet object when implementing validator functions
+    readonly subaccountNumber: number;
+
+    constructor(wallet: LocalWallet, subaccountNumber: number = 0) {
+      if (subaccountNumber < 0 || subaccountNumber > 127) {
+        throw new Error('Subaccount number must be between 0 and 127');
+      }
+      this.wallet = wallet;
+      this.subaccountNumber = subaccountNumber;
+    }
+
+    get address(): string {
+      const address = this.wallet.address;
+      if (address !== undefined) {
+        return address;
+      } else {
+        throw new Error('Address not set');
+      }
+    }
+}

package/src/clients/types.ts

@@ -0,0 +1,73 @@
+import { Method } from '@cosmjs/tendermint-rpc';
+import { Order_ConditionType, Order_Side, Order_TimeInForce } from '@dydxprotocol/dydxjs/src/codegen/dydxprotocol/clob/order';
+import BigNumber from 'bignumber.js';
+import Long from 'long';
+
+export type Integer = BigNumber;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type GenericParams = { [name: string]: any };
+
+// TODO: Find a better way.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type Data = any;
+
+export type PartialBy<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+
+// Information for signing a transaction while offline - without sequence.
+export interface PartialTransactionOptions {
+  accountNumber: number;
+  chainId: string;
+}
+
+// Information for signing a transaction while offline.
+export interface TransactionOptions extends PartialTransactionOptions {
+  sequence: number;
+}
+
+// OrderFlags, just a number in proto, defined as enum for convenience
+export enum OrderFlags {
+  SHORT_TERM = 0,
+  LONG_TERM = 64,
+  CONDITIONAL = 32,
+}
+
+export interface IBasicOrder {
+  clientId: number;
+  orderFlags: OrderFlags,
+  clobPairId: number;
+  goodTilBlock?: number;
+  goodTilBlockTime?: number;
+}
+
+export interface IPlaceOrder extends IBasicOrder {
+  side: Order_Side;
+  quantums: Long;
+  subticks: Long;
+  timeInForce: Order_TimeInForce,
+  reduceOnly: boolean;
+  clientMetadata: number;
+  conditionType?: Order_ConditionType,
+  conditionalOrderTriggerSubticks?: Long,
+}
+
+export interface ICancelOrder extends IBasicOrder {
+}
+
+// How long to wait and how often to check when calling Broadcast with
+// Method.BroadcastTxCommit
+export interface BroadcastOptions {
+  broadcastPollIntervalMs: number;
+  broadcastTimeoutMs: number;
+}
+
+// Specify when a broadcast should return:
+// 1. Immediately
+// 2. Once the transaction is added to the memPool
+// 3. Once the transaction is committed to a block
+// See https://docs.cosmos.network/master/run-node/txs.html for more information
+export type BroadcastMode = (
+  Method.BroadcastTxAsync | Method.BroadcastTxSync | Method.BroadcastTxCommit
+);
+
+export * from './modules/proto-includes';

package/src/clients/validator-client.ts

@@ -0,0 +1,74 @@
+import { QueryClient, TxExtension, setupTxExtension } from '@cosmjs/stargate';
+import { Tendermint37Client } from '@cosmjs/tendermint-rpc';
+import Long from 'long';
+import protobuf from 'protobufjs';
+
+import { ValidatorConfig, BROADCAST_POLL_INTERVAL_MS, BROADCAST_TIMEOUT_MS } from './constants';
+import { Get } from './modules/get';
+import { Post } from './modules/post';
+import { TendermintClient } from './modules/tendermintClient';
+
+// Required for encoding and decoding queries that are of type Long.
+// Must be done once but since the individal modules should be usable
+// - must be set in each module that encounters encoding/decoding Longs.
+// Reference: https://github.com/protobufjs/protobuf.js/issues/921
+protobuf.util.Long = Long;
+protobuf.configure();
+
+export class ValidatorClient {
+  public readonly config: ValidatorConfig;
+  private _get?: Get;
+  private _post?: Post;
+
+  /**
+     * @description Connect to a validator client
+     *
+     * @returns The validator client
+     */
+  static async connect(config: ValidatorConfig): Promise<ValidatorClient> {
+    const client = new ValidatorClient(config);
+    await client.initialize();
+    return client;
+  }
+
+  private constructor(
+    config: ValidatorConfig,
+  ) {
+    this.config = config;
+  }
+
+  /**
+     * @description Get the query module, used for retrieving on-chain data.
+     *
+     * @returns The query module
+     */
+  get get(): Get {
+    return this._get!;
+  }
+
+  /**
+     * @description transaction module, used for sending transactions.
+     *
+     * @returns The transaction module
+     */
+  get post(): Post {
+    return this._post!;
+  }
+
+  private async initialize(): Promise<void> {
+    const tendermint37Client: Tendermint37Client = await Tendermint37Client.connect(
+      this.config.restEndpoint,
+    );
+
+    const tendermintClient = new TendermintClient(tendermint37Client, {
+      broadcastPollIntervalMs: BROADCAST_POLL_INTERVAL_MS,
+      broadcastTimeoutMs: BROADCAST_TIMEOUT_MS,
+    });
+    const queryClient: (QueryClient & TxExtension) = QueryClient.withExtensions(
+      tendermint37Client,
+      setupTxExtension,
+    );
+    this._get = new Get(tendermintClient, queryClient);
+    this._post = new Post(this._get!, this.config.chainId);
+  }
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+// Types.
+export * from './types';
+
+// Utility functions.
+export * as utils from './lib/utils';
+export * as validation from './lib/validation';
+export * as onboarding from './lib/onboarding';
+
+export { default as LocalWallet } from './clients/modules/local-wallet';
+export { Subaccount as SubaccountClient } from './clients/subaccount';
+export { CompositeClient } from './clients/composite-client';
+export { IndexerClient } from './clients/indexer-client';
+export { ValidatorClient } from './clients/validator-client';
+export { FaucetClient } from './clients/faucet-client';
+export { SocketClient } from './clients/socket-client';
+export { NetworkOptimizer } from './network_optimizer';
+export { encodeJson } from './lib/helpers';

package/src/lib/constants.ts

@@ -0,0 +1,37 @@
+import { GasPrice, StdFee } from '@cosmjs/stargate';
+
+// Bech32 Prefix
+export const BECH32_PREFIX = 'dydx';
+
+// Broadcast Defaults
+export const BROADCAST_POLL_INTERVAL_MS: number = 300;
+export const BROADCAST_TIMEOUT_MS: number = 8_000;
+
+// API Defaults
+export const API_TIMEOUT_DEFAULT_MS: number = 5_000;
+
+// Default placeholder USDC denom (same as protocol).
+// Precomputed USDC IBC denom.
+export const USDC_DENOM = 'ibc/8E27BA2D5493AF5636760E354E46004562C46AB7EC0CC4C1CA14E9E20E2545B5';
+export const DYDX_DENOM = 'dv4tnt';
+
+// Gas
+// TODO(DEC-1532): Determine why `MsgTransfer` messages return an innaccurate `GasUsed` value
+// from `/simulate`. 2x is quite high for a gas multipler (more standard is 1.1, or 1.3).
+export const GAS_MULTIPLIER: number = 1.4;
+// TODO(CORE-190): Replace 'usdc' with IBC denom after IBC denom is supported in '@cosmjs/stargate'.
+export const GAS_PRICE: GasPrice = GasPrice.fromString('0.1usdc');
+export const GAS_PRICE_DYDX_DENOM: GasPrice = GasPrice.fromString('0.1dv4tnt');
+
+export const ZERO_FEE: StdFee = {
+  amount: [],
+  gas: '0',
+};
+
+// Validation
+export const MAX_UINT_32 = 4_294_967_295;
+export const MAX_SUBACCOUNT_NUMBER = 127;
+
+export const DEFAULT_SEQUENCE: number = 0;
+
+export const SERIALIZED_INT_ZERO: Uint8Array = Uint8Array.from([0x02]);

package/src/lib/errors.ts

@@ -0,0 +1,44 @@
+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';
+  }
+}

package/src/lib/helpers.ts

@@ -0,0 +1,59 @@
+import { toHex } from '@cosmjs/encoding';
+import BigNumber from 'bignumber.js';
+import Long from 'long';
+
+import { PartialTransactionOptions, TransactionOptions } from '../types';
+import { DEFAULT_SEQUENCE } from './constants';
+
+/**
+ * @description Either return undefined or insert default sequence value into
+ * `partialTransactionOptions` if it does not exist.
+ *
+ * @returns undefined or full TransactionOptions.
+ */
+export function convertPartialTransactionOptionsToFull(
+  partialTransactionOptions?: PartialTransactionOptions,
+): TransactionOptions | undefined {
+  if (partialTransactionOptions === undefined) {
+    return undefined;
+  }
+
+  return {
+    sequence: DEFAULT_SEQUENCE,
+    ...partialTransactionOptions,
+  };
+}
+
+/**
+ * @description Strip '0x' prefix from input string. If there is no '0x' prefix, return the original
+ * input.
+ *
+ * @returns input without '0x' prefix or original input if no prefix.
+ */
+export function stripHexPrefix(input: string): string {
+  if (input.indexOf('0x') === 0) {
+    return input.slice(2);
+  }
+
+  return input;
+}
+
+export function encodeJson(object?: Object): string {
+  // eslint-disable-next-line prefer-arrow-callback
+  return JSON.stringify(object, function replacer(_key, value) {
+    // Even though we set the an UInt8Array as the value,
+    // it comes in here as an object with UInt8Array as the buffer property.
+    if (value instanceof BigNumber) {
+      return value.toString();
+    }
+    if (value instanceof Long) {
+      return value.toString();
+    }
+    if (value?.buffer instanceof Uint8Array) {
+      return toHex(value.buffer);
+    } else if (value instanceof Uint8Array) {
+      return toHex(value);
+    }
+    return value;
+  });
+}

package/src/lib/onboarding.ts

@@ -0,0 +1,64 @@
+import { HDKey } from '@scure/bip32';
+import { entropyToMnemonic, mnemonicToSeedSync } from '@scure/bip39';
+import { wordlist } from '@scure/bip39/wordlists/english';
+import { keccak256 } from 'ethereum-cryptography/keccak';
+
+import { stripHexPrefix } from './helpers';
+
+/**
+ * @description Get Mnemonic and priv/pub keys from privateKeyBytes and BIP44 HD path
+ *
+ * @url https://github.com/confio/cosmos-hd-key-derivation-spec#bip44
+ *
+ * @param entropy used to generate mnemonic
+ *
+ * @param path BIP44 HD Path. Default is The Cosmos Hub path
+ *
+ * @throws Error if the hdkey does not exist
+ *
+ * @returns Mnemonic and priv/pub keys
+ */
+export const exportMnemonicAndPrivateKey = (entropy: Uint8Array, path: string = "m/44'/118'/0'/0/0"): {
+  mnemonic: string;
+  privateKey: Uint8Array | null;
+  publicKey: Uint8Array | null;
+} => {
+  const mnemonic = entropyToMnemonic(entropy, wordlist);
+  const seed = mnemonicToSeedSync(mnemonic);
+
+  const hdkey = HDKey.fromMasterSeed(seed);
+  const derivedHdkey = hdkey.derive(path);
+
+  if (!hdkey.privateKey) {
+    throw new Error('null hd key');
+  }
+
+  return {
+    mnemonic,
+    privateKey: derivedHdkey.privateKey,
+    publicKey: derivedHdkey.publicKey,
+  };
+};
+
+/**
+ * @description Get private information for onboarding using an Ethereum Signature.
+ *
+ * @returns Mnemonic and Public/Private HD keys
+ */
+export const deriveHDKeyFromEthereumSignature = (signature: string): {
+  mnemonic: string;
+  privateKey: Uint8Array | null;
+  publicKey: Uint8Array | null;
+} => {
+  const buffer = Buffer.from(stripHexPrefix(signature), 'hex');
+
+  if (buffer.length !== 65) {
+    throw new Error('Signature must be 65 bytes');
+  }
+
+  // Remove the 'v' value by taking only the first 64 bytes of the signature
+  const rsValues = buffer.subarray(0, 64);
+  // Hash the 'r' and 's' values down to 32 bytes (256 bits) using Keccak-256
+  const entropy = keccak256(rsValues);
+  return exportMnemonicAndPrivateKey(entropy);
+};