@nadohq/engine-client 0.1.0-alpha.1

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@nadohq/engine-client",
+  "version": "0.1.0-alpha.1",
+  "type": "module",
+  "sideEffects": false,
+  "description": "> TODO: description",
+  "author": "Frank Jia <frank@inkfnd.com>",
+  "homepage": "",
+  "license": "ISC",
+  "source": "./src/index.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": "https://github.com/nadohq/nado-typescript-sdk",
+  "scripts": {
+    "clean": "rm -rf dist && rm -f tsconfig.tsbuildinfo",
+    "build": "tsup",
+    "dev": "tsc -w",
+    "lint": "eslint --cache './**/*.{ts,tsx}'",
+    "lint:fix": "eslint --cache --fix './**/*.{ts,tsx}'",
+    "typecheck": "tsc --noEmit"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "dependencies": {
+    "@nadohq/contracts": "^0.1.0-alpha.1",
+    "@nadohq/utils": "^0.1.0-alpha.1",
+    "axios": "*",
+    "ts-mixer": "*"
+  },
+  "peerDependencies": {
+    "viem": "*"
+  },
+  "devDependencies": {
+    "viem": "*"
+  },
+  "gitHead": "80100d38c43806d1bb57c9139d9577329467d5db"
+}

package/src/EngineBaseClient.ts

@@ -0,0 +1,223 @@
+import {
+  getSignedTransactionRequest,
+  SignableRequestType,
+  SignableRequestTypeToParams,
+  WalletClientWithAccount,
+} from '@nadohq/contracts';
+import { WalletNotProvidedError } from '@nadohq/utils';
+import axios, { AxiosInstance, AxiosResponse } from 'axios';
+import {
+  EngineServerExecuteRequestByType,
+  EngineServerExecuteRequestType,
+  EngineServerExecuteResult,
+  EngineServerExecuteSuccessResult,
+  EngineServerQueryRequest,
+  EngineServerQueryRequestByType,
+  EngineServerQueryRequestType,
+  EngineServerQueryResponse,
+  EngineServerQueryResponseByType,
+  EngineServerQuerySuccessResponse,
+  GetEngineNoncesParams,
+  GetEngineNoncesResponse,
+} from './types';
+import { EngineServerFailureError } from './types/EngineServerFailureError';
+
+export interface EngineClientOpts {
+  // 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;
+}
+
+// Only 1 key can be defined per execute request
+type EngineExecuteRequestBody = Partial<EngineServerExecuteRequestByType>;
+
+type EngineQueryRequestResponse<
+  T extends EngineServerQueryRequestType = EngineServerQueryRequestType,
+> = EngineServerQueryResponse<T>;
+
+/**
+ * Base client for all engine requests
+ */
+export class EngineBaseClient {
+  readonly opts: EngineClientOpts;
+  readonly axiosInstance: AxiosInstance;
+
+  constructor(opts: EngineClientOpts) {
+    this.opts = opts;
+    this.axiosInstance = axios.create({
+      withCredentials: true,
+    });
+  }
+
+  /**
+   * Sets the linked signer for execute 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;
+  }
+
+  public async getTxNonce(address?: string): Promise<string> {
+    const addr = address ?? this.opts.walletClient?.account.address;
+
+    if (!addr) {
+      throw new WalletNotProvidedError();
+    }
+
+    return (
+      await this.getNonces({
+        address: addr,
+      })
+    ).txNonce;
+  }
+
+  public async getNonces(
+    params: GetEngineNoncesParams,
+  ): Promise<GetEngineNoncesResponse> {
+    const baseResp = await this.query('nonces', params);
+
+    return {
+      orderNonce: baseResp.order_nonce,
+      txNonce: baseResp.tx_nonce,
+    };
+  }
+
+  /**
+   * Queries the engine, all query params are stringified into the query string
+   *
+   * @param requestType
+   * @param params
+   * @public
+   */
+  public async query<TRequestType extends EngineServerQueryRequestType>(
+    requestType: TRequestType,
+    params: EngineServerQueryRequestByType[TRequestType],
+  ): Promise<EngineServerQueryResponseByType[TRequestType]> {
+    const request = this.getQueryRequest(requestType, params);
+    const response = await this.axiosInstance.post<EngineQueryRequestResponse>(
+      `${this.opts.url}/query`,
+      request,
+    );
+
+    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<
+      EngineServerQuerySuccessResponse<TRequestType>
+    >;
+
+    return successResponse.data.data;
+  }
+
+  /**
+   * A simple, typechecked fn for constructing a query request in the format expected by the server.
+   *
+   * @param requestType
+   * @param params
+   */
+  public getQueryRequest<TRequestType extends EngineServerQueryRequestType>(
+    requestType: TRequestType,
+    params: EngineServerQueryRequestByType[TRequestType],
+  ): EngineServerQueryRequest<TRequestType> {
+    return {
+      type: requestType,
+      ...params,
+    };
+  }
+
+  /**
+   * POSTs an execute message to the engine and returns the successful response. Throws the failure response wrapped
+   * in an EngineServerFailureError on failure.
+   *
+   * @param requestType
+   * @param params
+   * @public
+   */
+  public async execute<TRequestType extends EngineServerExecuteRequestType>(
+    requestType: TRequestType,
+    params: EngineServerExecuteRequestByType[TRequestType],
+  ): Promise<EngineServerExecuteSuccessResult<TRequestType>> {
+    const reqBody = this.getExecuteRequest(requestType, params);
+    const response = await this.axiosInstance.post<
+      EngineServerExecuteResult<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 EngineServerExecuteSuccessResult<TRequestType>;
+  }
+
+  /**
+   * A simple, typechecked fn for constructing an execute request in the format expected by the server.
+   *
+   * @param requestType
+   * @param params
+   */
+  public getExecuteRequest<TRequestType extends EngineServerExecuteRequestType>(
+    requestType: TRequestType,
+    params: EngineServerExecuteRequestByType[TRequestType],
+  ): EngineExecuteRequestBody {
+    return {
+      [requestType]: params,
+    };
+  }
+
+  /**
+   * Signs a given request with the signer provided to the engine
+   *
+   * @param requestType
+   * @param verifyingContract
+   * @param chainId
+   * @param params
+   * @public
+   */
+  public 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) {
+      throw new WalletNotProvidedError();
+    }
+
+    return getSignedTransactionRequest({
+      chainId,
+      requestParams: params,
+      requestType,
+      walletClient,
+      verifyingContract,
+    });
+  }
+
+  private checkResponseStatus(response: AxiosResponse) {
+    if (response.status !== 200 || !response.data) {
+      throw Error(
+        `Unexpected response from server: ${response.status} ${response.statusText}`,
+      );
+    }
+  }
+
+  private checkServerStatus(
+    response: AxiosResponse<
+      EngineServerExecuteResult | EngineQueryRequestResponse
+    >,
+  ) {
+    if (response.data.status !== 'success') {
+      throw new EngineServerFailureError(response.data);
+    }
+  }
+}

package/src/EngineClient.ts

@@ -0,0 +1,13 @@
+import { Mixin } from 'ts-mixer';
+import { EngineExecuteClient } from './EngineExecuteClient';
+import { EngineQueryClient } from './EngineQueryClient';
+import { EngineWebClient } from './EngineWebClient';
+
+/**
+ * Combined Engine client providing query, execution, and WebSocket functionality for off-chain matching engine communication
+ */
+export class EngineClient extends Mixin(
+  EngineQueryClient,
+  EngineExecuteClient,
+  EngineWebClient,
+) {}

package/src/EngineExecuteBuilder.ts

@@ -0,0 +1,381 @@
+import {
+  EIP712IsolatedOrderParams,
+  EIP712OrderParams,
+  getNadoEIP712Values,
+  getOrderNonce,
+  SignableRequestType,
+  SignableRequestTypeToParams,
+} from '@nadohq/contracts';
+import { EngineBaseClient } from './EngineBaseClient';
+import {
+  EngineExecuteRequestParamsByType,
+  EngineServerExecutePlaceIsolatedOrderPayload,
+  EngineServerExecutePlaceOrderPayload,
+  EngineServerExecuteRequestByType,
+  SignatureParams,
+  WithBaseEngineExecuteParams,
+  WithSignature,
+} from './types';
+
+/**
+ * Builds execute payloads as expected by the server.
+ * @param nonce A nonce is computed when one is not provided.
+ * @param signature A signature is computed when one is not provided.
+ */
+export class EngineExecuteBuilder {
+  readonly engineClient: EngineBaseClient;
+
+  constructor(engineClient: EngineBaseClient) {
+    this.engineClient = engineClient;
+  }
+
+  /**
+   * Builds server payload for the `liquidate_subaccount` execute action.
+   * @param clientParams Client LiquidateSubaccount params.
+   * @returns `liquidate_subaccount` payload
+   */
+  async buildLiquidateSubaccountPayload(
+    clientParams: EngineExecuteRequestParamsByType['liquidate_subaccount'],
+  ): Promise<EngineServerExecuteRequestByType['liquidate_subaccount']> {
+    const nonce = await this.getTxNonceIfNeeded(clientParams);
+    const paramsWithNonce = { ...clientParams, nonce };
+
+    const tx = getNadoEIP712Values('liquidate_subaccount', paramsWithNonce);
+    const signature = await this.getSignatureIfNeeded(
+      'liquidate_subaccount',
+      paramsWithNonce,
+    );
+
+    return {
+      signature,
+      tx,
+    };
+  }
+
+  /**
+   * Builds server payload for the `withdraw_collateral` execute action.
+   * @param clientParams Client WithdrawCollateral params.
+   * @returns `liquidate_subaccount` payload
+   */
+  async buildWithdrawCollateralPayload(
+    clientParams: EngineExecuteRequestParamsByType['withdraw_collateral'],
+  ): Promise<EngineServerExecuteRequestByType['withdraw_collateral']> {
+    const nonce = await this.getTxNonceIfNeeded(clientParams);
+    const paramsWithNonce = { ...clientParams, nonce };
+
+    const signature = await this.getSignatureIfNeeded(
+      'withdraw_collateral',
+      paramsWithNonce,
+    );
+
+    const tx = getNadoEIP712Values('withdraw_collateral', paramsWithNonce);
+    return {
+      signature,
+      tx,
+      spot_leverage: clientParams.spotLeverage ?? null,
+    };
+  }
+
+  /**
+   * Builds server payload for the `place_order` execute action.
+   *
+   * @param clientParams Client PlaceOrder params.
+   * @returns `place_order` payload
+   */
+  async buildPlaceOrderPayload(
+    clientParams: EngineExecuteRequestParamsByType['place_order'],
+  ): Promise<EngineServerExecutePlaceOrderPayload> {
+    const nonce = this.getOrderNonceIfNeeded(clientParams);
+    const orderWithNonce = { ...clientParams.order, nonce };
+
+    const signature = await this.getSignatureIfNeeded('place_order', {
+      // Gets expected type
+      ...clientParams,
+      ...orderWithNonce,
+    });
+
+    return this.buildPlaceOrderPayloadSync({
+      ...clientParams,
+      order: orderWithNonce,
+      signature,
+    });
+  }
+
+  /**
+   * Synchronously builds server payload for the `place_order` execute action.
+   *
+   * @param clientParams Client PlaceOrder params.
+   * @returns `place_order` payload
+   */
+  buildPlaceOrderPayloadSync(
+    clientParams: WithSignature<
+      EngineExecuteRequestParamsByType['place_order'] & {
+        order: EIP712OrderParams;
+      }
+    >,
+  ): EngineServerExecutePlaceOrderPayload {
+    const orderEIP712Values = getNadoEIP712Values(
+      'place_order',
+      clientParams.order,
+    );
+
+    return {
+      payload: {
+        id: clientParams.id ?? null,
+        product_id: clientParams.productId,
+        order: orderEIP712Values,
+        signature: clientParams.signature,
+        spot_leverage: clientParams.spotLeverage ?? null,
+      },
+      orderParams: clientParams.order,
+    };
+  }
+
+  /**
+   * Builds server payload for the `place_isolated_order` execute action.
+   *
+   * @param clientParams Client PlaceIsolatedOrder params.
+   * @returns `place_isolated_order` payload
+   */
+  async buildIsolatedPlaceOrderPayload(
+    clientParams: EngineExecuteRequestParamsByType['place_isolated_order'],
+  ): Promise<EngineServerExecutePlaceIsolatedOrderPayload> {
+    const nonce = this.getOrderNonceIfNeeded(clientParams);
+    const orderWithNonce = { ...clientParams.order, nonce };
+
+    const signature = await this.getSignatureIfNeeded('place_isolated_order', {
+      // Gets expected type
+      ...clientParams,
+      ...orderWithNonce,
+    });
+
+    return this.buildPlaceIsolatedOrderPayloadSync({
+      ...clientParams,
+      order: orderWithNonce,
+      signature,
+    });
+  }
+
+  /**
+   * Synchronously builds server payload for the `place_isolated_order` execute action.
+   *
+   * @param clientParams Client PlaceIsolatedOrder params.
+   * @returns `place_isolated_order` payload
+   */
+  buildPlaceIsolatedOrderPayloadSync(
+    clientParams: WithSignature<
+      EngineExecuteRequestParamsByType['place_isolated_order'] & {
+        order: EIP712IsolatedOrderParams;
+      }
+    >,
+  ): EngineServerExecutePlaceIsolatedOrderPayload {
+    const isolatedOrderEIP712Values = getNadoEIP712Values(
+      'place_isolated_order',
+      clientParams.order,
+    );
+
+    return {
+      payload: {
+        id: clientParams.id ?? null,
+        product_id: clientParams.productId,
+        isolated_order: isolatedOrderEIP712Values,
+        signature: clientParams.signature,
+        borrow_margin: clientParams.borrowMargin ?? null,
+      },
+      orderParams: clientParams.order,
+    };
+  }
+
+  /**
+   * Builds server payload for the `cancel_orders` execute action. As such, requires a signature to be given
+   *
+   * @param clientParams Client CancelOrders params.
+   * @returns `cancel_orders` payload
+   */
+  async buildCancelOrdersPayload(
+    clientParams: EngineExecuteRequestParamsByType['cancel_orders'],
+  ): Promise<EngineServerExecuteRequestByType['cancel_orders']> {
+    const nonce = this.getOrderNonceIfNeeded(clientParams);
+    const paramsWithNonce = { ...clientParams, nonce };
+    const signature = await this.getSignatureIfNeeded(
+      'cancel_orders',
+      paramsWithNonce,
+    );
+
+    return this.buildCancelOrdersPayloadSync({
+      ...paramsWithNonce,
+      signature,
+    });
+  }
+
+  /**
+   * Synchronously builds server payload for the `cancel_orders` execute action.
+   *
+   * @param clientParams Client CancelOrders params.
+   * @returns `cancel_orders` payload
+   */
+  buildCancelOrdersPayloadSync(
+    clientParams: WithSignature<
+      EngineExecuteRequestParamsByType['cancel_orders'] & { nonce: string }
+    >,
+  ): EngineServerExecuteRequestByType['cancel_orders'] {
+    const tx = getNadoEIP712Values('cancel_orders', clientParams);
+
+    return {
+      tx,
+      signature: clientParams.signature,
+    };
+  }
+
+  /**
+   * Builds server payload for the `cancel_product_orders` execute action.
+   * @param clientParams Client CancelProductOrders params.
+   * @returns `cancel_product_orders` payload
+   */
+  async buildCancelProductOrdersPayload(
+    clientParams: EngineExecuteRequestParamsByType['cancel_product_orders'],
+  ): Promise<EngineServerExecuteRequestByType['cancel_product_orders']> {
+    const nonce = this.getOrderNonceIfNeeded(clientParams);
+    const paramsWithNonce = { ...clientParams, nonce };
+
+    const tx = getNadoEIP712Values('cancel_product_orders', paramsWithNonce);
+    const signature = await this.getSignatureIfNeeded(
+      'cancel_product_orders',
+      paramsWithNonce,
+    );
+
+    return {
+      tx,
+      signature,
+    };
+  }
+
+  /**
+   * Builds server payload for the `link_signer` execute action.
+   *
+   * @param clientParams Client LinkSigner params.
+   * @returns `link_signer` payload
+   */
+  async buildLinkSignerPayload(
+    clientParams: EngineExecuteRequestParamsByType['link_signer'],
+  ): Promise<EngineServerExecuteRequestByType['link_signer']> {
+    const nonce = await this.getTxNonceIfNeeded(clientParams);
+    const paramsWithNonce = { ...clientParams, nonce };
+
+    const tx = getNadoEIP712Values('link_signer', paramsWithNonce);
+    const signature = await this.getSignatureIfNeeded(
+      'link_signer',
+      paramsWithNonce,
+    );
+
+    return {
+      tx,
+      signature,
+    };
+  }
+
+  /**
+   * Builds server payload for the `transfer_quote` execute action.
+   *
+   * @param clientParams Client TransferQuote params.
+   * @returns `transfer_quote` payload
+   */
+  async buildTransferQuotePayload(
+    clientParams: EngineExecuteRequestParamsByType['transfer_quote'],
+  ): Promise<EngineServerExecuteRequestByType['transfer_quote']> {
+    const nonce = await this.getTxNonceIfNeeded(clientParams);
+    const paramsWithNonce = { ...clientParams, nonce };
+
+    const tx = getNadoEIP712Values('transfer_quote', paramsWithNonce);
+    const signature = await this.getSignatureIfNeeded(
+      'transfer_quote',
+      paramsWithNonce,
+    );
+
+    return {
+      tx,
+      signature,
+    };
+  }
+
+  /**
+   * Builds server payload for the `mint_vlp` execute action.
+   * @param clientParams Client MintVlp params.
+   * @returns `mint_vlp` payload
+   */
+  async buildMintVlpPayload(
+    clientParams: EngineExecuteRequestParamsByType['mint_vlp'],
+  ): Promise<EngineServerExecuteRequestByType['mint_vlp']> {
+    const nonce = await this.getTxNonceIfNeeded(clientParams);
+    const paramsWithNonce = { ...clientParams, nonce };
+
+    const tx = getNadoEIP712Values('mint_vlp', paramsWithNonce);
+    const signature = await this.getSignatureIfNeeded(
+      'mint_vlp',
+      paramsWithNonce,
+    );
+
+    return {
+      signature,
+      tx,
+      spot_leverage: clientParams.spotLeverage ?? null,
+    };
+  }
+
+  /**
+   * Builds server payload for the `burn_vlp` execute action.
+   * @param clientParams Client BurnVlp params.
+   * @returns `burn_vlp` payload
+   */
+  async buildBurnVlpPayload(
+    clientParams: EngineExecuteRequestParamsByType['burn_vlp'],
+  ): Promise<EngineServerExecuteRequestByType['burn_vlp']> {
+    const nonce = await this.getTxNonceIfNeeded(clientParams);
+    const paramsWithNonce = { ...clientParams, nonce };
+
+    const tx = getNadoEIP712Values('burn_vlp', paramsWithNonce);
+    const signature = await this.getSignatureIfNeeded(
+      'burn_vlp',
+      paramsWithNonce,
+    );
+
+    return {
+      signature,
+      tx,
+    };
+  }
+
+  protected async getSignatureIfNeeded<T extends SignableRequestType>(
+    requestType: T,
+    paramsWithNonce: SignatureParams & SignableRequestTypeToParams[T],
+  ) {
+    if ('signature' in paramsWithNonce) {
+      return paramsWithNonce.signature;
+    }
+
+    return await this.engineClient.sign(
+      requestType,
+      paramsWithNonce.verifyingAddr,
+      paramsWithNonce.chainId,
+      paramsWithNonce,
+    );
+  }
+
+  protected async getTxNonceIfNeeded(
+    params: WithBaseEngineExecuteParams<{ subaccountOwner: string }>,
+  ) {
+    if (params.nonce) {
+      return params.nonce;
+    }
+    return await this.engineClient.getTxNonce(params.subaccountOwner);
+  }
+
+  protected getOrderNonceIfNeeded(
+    params: WithBaseEngineExecuteParams<unknown>,
+  ) {
+    if (params.nonce) {
+      return params.nonce;
+    }
+    return getOrderNonce();
+  }
+}