@nadohq/client 0.1.0-alpha.1

package/src/apis/spot/types.ts

@@ -0,0 +1,44 @@
+import {
+  EngineBurnVlpParams,
+  EngineMintVlpParams,
+  EngineTransferQuoteParams,
+  EngineWithdrawCollateralParams,
+} from '@nadohq/engine-client';
+import { BigDecimalish } from '@nadohq/utils';
+import { OptionalSignatureParams, OptionalSubaccountOwner } from '../types';
+
+export type ProductIdOrTokenAddress =
+  | {
+      productId: number;
+    }
+  | {
+      tokenAddress: string;
+    };
+
+type TokenQueryParams = {
+  address: string;
+} & ProductIdOrTokenAddress;
+
+export type ApproveAllowanceParams = ProductIdOrTokenAddress & {
+  amount: BigDecimalish;
+};
+
+export type GetTokenWalletBalanceParams = TokenQueryParams;
+
+export type GetTokenAllowanceParams = TokenQueryParams;
+
+export type WithdrawCollateralParams = OptionalSignatureParams<
+  OptionalSubaccountOwner<EngineWithdrawCollateralParams>
+>;
+
+export type TransferQuoteParams = OptionalSignatureParams<
+  OptionalSubaccountOwner<EngineTransferQuoteParams>
+>;
+
+export type MintVlpParams = OptionalSignatureParams<
+  OptionalSubaccountOwner<EngineMintVlpParams>
+>;
+
+export type BurnVlpParams = OptionalSignatureParams<
+  OptionalSubaccountOwner<EngineBurnVlpParams>
+>;

package/src/apis/subaccount/SubaccountExecuteAPI.ts

@@ -0,0 +1,32 @@
+import { BaseNadoAPI } from '../base';
+import { LinkSignerParams, LiquidateSubaccountParams } from './types';
+
+export class SubaccountExecuteAPI extends BaseNadoAPI {
+  /**
+   * Liquidates a subaccount
+   *
+   * @param params
+   */
+  async liquidateSubaccount(params: LiquidateSubaccountParams) {
+    return this.context.engineClient.liquidateSubaccount({
+      ...params,
+      subaccountOwner: this.getSubaccountOwnerIfNeeded(params),
+      verifyingAddr: params.verifyingAddr ?? this.getEndpointAddress(),
+      chainId: this.getWalletClientChainIdIfNeeded(params),
+    });
+  }
+
+  /**
+   * Links a signer to a subaccount to allow them to sign transactions on behalf of the subaccount
+   *
+   * @param params
+   */
+  async linkSigner(params: LinkSignerParams) {
+    return this.context.engineClient.linkSigner({
+      ...params,
+      subaccountOwner: this.getSubaccountOwnerIfNeeded(params),
+      verifyingAddr: params.verifyingAddr ?? this.getEndpointAddress(),
+      chainId: this.getWalletClientChainIdIfNeeded(params),
+    });
+  }
+}

package/src/apis/subaccount/SubaccountQueryAPI.ts

@@ -0,0 +1,78 @@
+import {
+  getSubaccountSummary,
+  GetSubaccountSummaryParams,
+} from '@nadohq/contracts';
+import {
+  GetEngineEstimatedSubaccountSummaryParams,
+  GetEngineIsolatedPositionsParams,
+  GetEngineSubaccountFeeRatesParams,
+  GetEngineSubaccountSummaryParams,
+} from '@nadohq/engine-client';
+import {
+  GetIndexerLinkedSignerParams,
+  GetIndexerReferralCodeParams,
+} from '@nadohq/indexer-client';
+import { BaseNadoAPI } from '../base';
+
+export class SubaccountQueryAPI extends BaseNadoAPI {
+  /**
+   * Returns a comprehensive summary for a subaaccount, including its balances and health
+   *
+   * @see {@link getSubaccountSummary:CONTRACTS | getSubaccountSummary}
+   */
+  async getSubaccountSummary(params: GetSubaccountSummaryParams) {
+    return getSubaccountSummary(this.paramsWithContracts(params));
+  }
+
+  /**
+   * Gets the subaccount state according to the offchain engine
+   * @param params
+   */
+  async getEngineSubaccountSummary(params: GetEngineSubaccountSummaryParams) {
+    return this.context.engineClient.getSubaccountSummary(params);
+  }
+
+  /**
+   * Gets the estimated subaccount state from offchain engine after a series of proposed txs
+   * @param params
+   */
+  async getEngineEstimatedSubaccountSummary(
+    params: GetEngineEstimatedSubaccountSummaryParams,
+  ) {
+    return this.context.engineClient.getEstimatedSubaccountSummary(params);
+  }
+
+  /**
+   * Gets the isolated positions for a subaccount
+   * @param params
+   */
+  async getIsolatedPositions(params: GetEngineIsolatedPositionsParams) {
+    return this.context.engineClient.getIsolatedPositions(params);
+  }
+
+  /**
+   * Queries engine to get subaccount fee rates
+   * @param params
+   */
+  async getSubaccountFeeRates(params: GetEngineSubaccountFeeRatesParams) {
+    return this.context.engineClient.getSubaccountFeeRates(params);
+  }
+
+  /**
+   * Retrieves the current signer and link signer rate limit from the indexer
+   * @param params
+   */
+  async getSubaccountLinkedSignerWithRateLimit(
+    params: GetIndexerLinkedSignerParams,
+  ) {
+    return this.context.indexerClient.getLinkedSignerWithRateLimit(params);
+  }
+
+  /**
+   * Retrieves referral code for an address
+   * @param params
+   */
+  async getReferralCode(params: GetIndexerReferralCodeParams) {
+    return this.context.indexerClient.getReferralCode(params);
+  }
+}

package/src/apis/subaccount/index.ts

@@ -0,0 +1,44 @@
+import { createDeterministicLinkedSignerPrivateKey } from '@nadohq/contracts';
+import { WalletNotProvidedError } from '@nadohq/utils';
+import { Mixin } from 'ts-mixer';
+import { privateKeyToAccount } from 'viem/accounts';
+import { SubaccountExecuteAPI } from './SubaccountExecuteAPI';
+import { SubaccountQueryAPI } from './SubaccountQueryAPI';
+import { CreateStandardLinkedSignerResult } from './types';
+
+export * from './types';
+
+export class SubaccountAPI extends Mixin(
+  SubaccountExecuteAPI,
+  SubaccountQueryAPI,
+) {
+  /**
+   * Given the current context, create a "standard" link signer Account for the subaccount
+   * The "standard" linked signer private key is deterministically generated so that the frontend running on
+   * different clients can have a consistent private key for the subaccount linked signer.
+   *
+   * @param subaccountName
+   */
+  async createStandardLinkedSigner(
+    subaccountName: string,
+  ): Promise<CreateStandardLinkedSignerResult> {
+    const walletClient = this.context.walletClient;
+
+    if (!walletClient) {
+      throw new WalletNotProvidedError();
+    }
+
+    const privateKey = await createDeterministicLinkedSignerPrivateKey({
+      chainId: walletClient.chain.id,
+      endpointAddress: this.getEndpointAddress(),
+      walletClient,
+      subaccountName,
+      subaccountOwner: walletClient.account.address,
+    });
+
+    return {
+      privateKey,
+      account: privateKeyToAccount(privateKey),
+    };
+  }
+}

package/src/apis/subaccount/types.ts

@@ -0,0 +1,16 @@
+import { AccountWithPrivateKey } from '@nadohq/contracts';
+import {
+  EngineLinkSignerParams,
+  EngineLiquidateSubaccountParams,
+} from '@nadohq/engine-client';
+import { OptionalSignatureParams, OptionalSubaccountOwner } from '../types';
+
+export type LinkSignerParams = OptionalSignatureParams<
+  OptionalSubaccountOwner<EngineLinkSignerParams>
+>;
+
+export type LiquidateSubaccountParams = OptionalSignatureParams<
+  OptionalSubaccountOwner<EngineLiquidateSubaccountParams>
+>;
+
+export type CreateStandardLinkedSignerResult = AccountWithPrivateKey;

package/src/apis/types.ts

@@ -0,0 +1,11 @@
+export type OptionalSubaccountOwner<T> = Omit<T, 'subaccountOwner'> & {
+  subaccountOwner?: string;
+};
+
+export type OptionalSignatureParams<T> = Omit<
+  T,
+  'verifyingAddr' | 'chainId'
+> & {
+  verifyingAddr?: string;
+  chainId?: number;
+};

package/src/apis/ws/WebSocketExecuteAPI.ts

@@ -0,0 +1,70 @@
+import { EIP712OrderParams } from '@nadohq/contracts';
+import {
+  EngineExecuteRequestParamsByType,
+  WithSignature,
+} from '@nadohq/engine-client';
+import { BaseNadoAPI } from '../base';
+
+/**
+ * Builds execute messages as expected by the server to send over Websocket.
+ * @example nadoClient.ws.execute.buildPlaceOrderMessage(...)
+ */
+export class WebSocketExecuteAPI extends BaseNadoAPI {
+  /**
+   * Builds ws message for the `liquidate_subaccount` execute action.
+   * @param params LiquidateSubaccount params.
+   * @returns `liquidate_subaccount` execute message
+   */
+  async buildLiquidateSubaccountMessage(
+    params: EngineExecuteRequestParamsByType['liquidate_subaccount'],
+  ) {
+    return this.context.engineClient.payloadBuilder.buildLiquidateSubaccountPayload(
+      params,
+    );
+  }
+
+  /**
+   * Builds ws message for the `withdraw_collateral` execute action.
+   * @param params WithdrawCollateral params.
+   * @returns `liquidate_subaccount` execute message
+   */
+  async buildWithdrawCollateralMessage(
+    params: EngineExecuteRequestParamsByType['withdraw_collateral'],
+  ) {
+    return this.context.engineClient.payloadBuilder.buildWithdrawCollateralPayload(
+      params,
+    );
+  }
+
+  /**
+   * Builds ws message for the `place_order` execute action.
+   * @param params PlaceOrder params.
+   * @returns `place_order` execute message
+   */
+  buildPlaceOrderMessage(
+    params: WithSignature<
+      EngineExecuteRequestParamsByType['place_order'] & {
+        order: EIP712OrderParams;
+      }
+    >,
+  ) {
+    return this.context.engineClient.payloadBuilder.buildPlaceOrderPayloadSync(
+      params,
+    );
+  }
+
+  /**
+   * Builds ws message for the `cancel_orders` execute action.
+   * @param params PlaceOrder params.
+   * @returns `cancel_orders` execute message
+   */
+  buildCancelOrdersMessage(
+    params: WithSignature<
+      EngineExecuteRequestParamsByType['cancel_orders'] & { nonce: string }
+    >,
+  ) {
+    return this.context.engineClient.payloadBuilder.buildCancelOrdersPayloadSync(
+      params,
+    );
+  }
+}

package/src/apis/ws/WebSocketQueryAPI.ts

@@ -0,0 +1,25 @@
+import {
+  EngineServerQueryRequest,
+  EngineServerQueryRequestByType,
+  EngineServerQueryRequestType,
+} from '@nadohq/engine-client';
+import { BaseNadoAPI } from '../base';
+
+/**
+ * Builds query messages as expected by the server to send over Websocket.
+ * @example nadoClient.ws.query.buildQueryMessage('all_products', {})
+ */
+export class WebSocketQueryAPI extends BaseNadoAPI {
+  /**
+   * Builds a query request message as expected by the server via Websocket.
+   * @param requestType
+   * @param params
+   * @returns query request message.
+   */
+  public buildQueryMessage<TRequestType extends EngineServerQueryRequestType>(
+    requestType: TRequestType,
+    params: EngineServerQueryRequestByType[TRequestType],
+  ): EngineServerQueryRequest<TRequestType> {
+    return this.context.engineClient.getQueryRequest(requestType, params);
+  }
+}

package/src/apis/ws/WebSocketSubscriptionAPI.ts

@@ -0,0 +1,62 @@
+import {
+  EngineServerSubscriptionRequest,
+  EngineServerSubscriptionRequestByType,
+  EngineServerSubscriptionRequestType,
+  EngineServerSubscriptionStream,
+  EngineServerSubscriptionStreamParamsByType,
+  EngineServerSubscriptionStreamParamsType,
+} from '@nadohq/engine-client';
+import { BaseNadoAPI } from '../base';
+
+/**
+ * Builds subscription messages as expected by the server to send over Websocket.
+ *
+ * @example
+ * const tradeSubscriptionParams = nadoClient.ws.subscription.buildSubscriptionParams('trade', ...);
+ * const tradeSubscriptionMessage = nadoClient.ws.subscription.buildSubscriptionMessage(
+ *    'subscribe', tradeSubscriptionParams);
+ */
+export class WebSocketSubscriptionAPI extends BaseNadoAPI {
+  /**
+   * Builds a subscription request message as expected by the server via Websocket.
+   * @param requestType name of request to build message for.
+   * @param id identifier to associate messages with responses.
+   * @param params request message params.
+   * @returns subscription request message.
+   */
+  public buildSubscriptionMessage<
+    TRequestType extends EngineServerSubscriptionRequestType,
+  >(
+    id: number,
+    requestType: TRequestType,
+    params: EngineServerSubscriptionRequestByType[TRequestType],
+  ): EngineServerSubscriptionRequest<TRequestType> {
+    return {
+      id,
+      method: requestType,
+      ...params,
+    };
+  }
+
+  /**
+   * Builds a subscription stream param as expected by the server via Websocket.
+   * @param streamType name of stream to build params for.
+   * @param params
+   * @returns subscription stream params.
+   */
+  public buildSubscriptionParams<
+    TStreamType extends EngineServerSubscriptionStreamParamsType,
+  >(
+    streamType: TStreamType,
+    params: EngineServerSubscriptionStreamParamsByType[TStreamType],
+  ): {
+    stream: EngineServerSubscriptionStream<TStreamType>;
+  } {
+    return {
+      stream: {
+        type: streamType,
+        ...params,
+      },
+    };
+  }
+}

package/src/apis/ws/index.ts

@@ -0,0 +1,21 @@
+import { NadoClientContext } from '../../context';
+import { BaseNadoAPI } from '../base';
+import { WebSocketExecuteAPI } from './WebSocketExecuteAPI';
+import { WebSocketQueryAPI } from './WebSocketQueryAPI';
+import { WebSocketSubscriptionAPI } from './WebSocketSubscriptionAPI';
+
+/**
+ * Builds ws messages as expected by the server to send over Websocket.
+ */
+export class WebsocketAPI extends BaseNadoAPI {
+  readonly query: WebSocketQueryAPI;
+  readonly execute: WebSocketExecuteAPI;
+  readonly subscription: WebSocketSubscriptionAPI;
+
+  constructor(context: NadoClientContext) {
+    super(context);
+    this.query = new WebSocketQueryAPI(context);
+    this.execute = new WebSocketExecuteAPI(context);
+    this.subscription = new WebSocketSubscriptionAPI(context);
+  }
+}

package/src/client.ts

@@ -0,0 +1,67 @@
+import { WalletClientWithAccount } from '@nadohq/contracts';
+import { MarketAPI } from './apis/market';
+import { PerpAPI } from './apis/perp';
+import { SpotAPI } from './apis/spot';
+import { SubaccountAPI } from './apis/subaccount';
+import { WebsocketAPI } from './apis/ws';
+import { createClientContext, NadoClientContext } from './context';
+
+/**
+ * Client for querying and executing against Nado Clearinghouse.
+ * Usually not instantiated directly. Instead, use {@link createNadoClient:CLIENT}.
+ */
+export class NadoClient {
+  context!: NadoClientContext;
+  market!: MarketAPI;
+  subaccount!: SubaccountAPI;
+  spot!: SpotAPI;
+  perp!: PerpAPI;
+  ws!: WebsocketAPI;
+
+  constructor(context: NadoClientContext) {
+    this.setupFromContext(context);
+  }
+
+  /**
+   * Sets the linked signer for the client. Set to null to revert to the chain signer.
+   * @param linkedSignerWalletClient
+   */
+  setLinkedSigner(linkedSignerWalletClient: WalletClientWithAccount | null) {
+    // This is a bit ugly, but works for now
+    this.context.linkedSignerWalletClient =
+      linkedSignerWalletClient ?? undefined;
+    this.context.engineClient.setLinkedSigner(linkedSignerWalletClient);
+    this.context.triggerClient.setLinkedSigner(linkedSignerWalletClient);
+  }
+
+  /**
+   * Sets the WalletClient for the client. Will cause a full reload of the current context.
+   * @param walletClient
+   */
+  setWalletClient(walletClient: NadoClientContext['walletClient']) {
+    const newContext = createClientContext(
+      {
+        contractAddresses: this.context.contractAddresses,
+        engineEndpoint: this.context.engineClient.opts.url,
+        indexerEndpoint: this.context.indexerClient.opts.url,
+        triggerEndpoint: this.context.triggerClient.opts.url,
+      },
+      {
+        walletClient,
+        // No need to call setLinkedSigner as this property doesn't change
+        linkedSignerWalletClient: this.context.linkedSignerWalletClient,
+        publicClient: this.context.publicClient,
+      },
+    );
+    this.setupFromContext(newContext);
+  }
+
+  private setupFromContext(context: NadoClientContext) {
+    this.context = context;
+    this.market = new MarketAPI(context);
+    this.subaccount = new SubaccountAPI(context);
+    this.spot = new SpotAPI(context);
+    this.perp = new PerpAPI(context);
+    this.ws = new WebsocketAPI(context);
+  }
+}

package/src/context.ts

@@ -0,0 +1,165 @@
+import {
+  ChainEnv,
+  NADO_ABIS,
+  NADO_DEPLOYMENTS,
+  NadoContractName,
+  NadoContracts,
+  NadoDeploymentAddresses,
+  WalletClientWithAccount,
+} from '@nadohq/contracts';
+import { ENGINE_CLIENT_ENDPOINTS, EngineClient } from '@nadohq/engine-client';
+import {
+  INDEXER_CLIENT_ENDPOINTS,
+  IndexerClient,
+} from '@nadohq/indexer-client';
+import {
+  TRIGGER_CLIENT_ENDPOINTS,
+  TriggerClient,
+} from '@nadohq/trigger-client';
+import { getContract, PublicClient } from 'viem';
+
+/**
+ * Context required to use the Nado client.
+ */
+export interface NadoClientContext {
+  publicClient: PublicClient;
+  walletClient?: WalletClientWithAccount;
+  // If provided, this is used to sign engine transactions instead of the account associated with walletClient
+  linkedSignerWalletClient?: WalletClientWithAccount;
+  contracts: NadoContracts;
+  contractAddresses: NadoDeploymentAddresses;
+  engineClient: EngineClient;
+  indexerClient: IndexerClient;
+  triggerClient: TriggerClient;
+}
+
+/**
+ * Args for creating a context
+ */
+interface NadoClientContextOpts {
+  contractAddresses: NadoDeploymentAddresses;
+  engineEndpoint: string;
+  indexerEndpoint: string;
+  triggerEndpoint: string;
+}
+
+/**
+ * Args for signing configuration for creating a context
+ */
+export type CreateNadoClientContextAccountOpts = Pick<
+  NadoClientContext,
+  'walletClient' | 'linkedSignerWalletClient' | 'publicClient'
+>;
+
+export type CreateNadoClientContextOpts = NadoClientContextOpts | ChainEnv;
+
+/**
+ * Utility function to create client context from options
+ *
+ * @param opts
+ * @param accountOpts
+ */
+export function createClientContext(
+  opts: CreateNadoClientContextOpts,
+  accountOpts: CreateNadoClientContextAccountOpts,
+): NadoClientContext {
+  const {
+    contractAddresses,
+    engineEndpoint,
+    indexerEndpoint,
+    triggerEndpoint,
+  } = ((): NadoClientContextOpts => {
+    // Custom options
+    if (typeof opts === 'object') {
+      return opts;
+    }
+
+    const chainEnv = opts;
+    return {
+      contractAddresses: NADO_DEPLOYMENTS[chainEnv],
+      engineEndpoint: ENGINE_CLIENT_ENDPOINTS[chainEnv],
+      indexerEndpoint: INDEXER_CLIENT_ENDPOINTS[chainEnv],
+      triggerEndpoint: TRIGGER_CLIENT_ENDPOINTS[chainEnv],
+    };
+  })();
+  const { publicClient, walletClient, linkedSignerWalletClient } = accountOpts;
+
+  return {
+    walletClient,
+    linkedSignerWalletClient,
+    publicClient,
+    contracts: {
+      querier: getNadoContract({
+        contractAddresses,
+        contractName: 'querier',
+        walletClient,
+        publicClient,
+      }),
+      clearinghouse: getNadoContract({
+        contractAddresses,
+        contractName: 'clearinghouse',
+        walletClient,
+        publicClient,
+      }),
+      endpoint: getNadoContract({
+        contractAddresses,
+        contractName: 'endpoint',
+        walletClient,
+        publicClient,
+      }),
+      spotEngine: getNadoContract({
+        contractAddresses,
+        contractName: 'spotEngine',
+        walletClient,
+        publicClient,
+      }),
+      perpEngine: getNadoContract({
+        contractAddresses,
+        contractName: 'perpEngine',
+        walletClient,
+        publicClient,
+      }),
+      withdrawPool: getNadoContract({
+        contractAddresses,
+        contractName: 'withdrawPool',
+        walletClient,
+        publicClient,
+      }),
+    },
+    contractAddresses,
+    engineClient: new EngineClient({
+      url: engineEndpoint,
+      walletClient,
+      linkedSignerWalletClient,
+    }),
+    indexerClient: new IndexerClient({
+      url: indexerEndpoint,
+      walletClient,
+    }),
+    triggerClient: new TriggerClient({
+      url: triggerEndpoint,
+      walletClient,
+      linkedSignerWalletClient,
+    }),
+  };
+}
+
+interface GetNadoContractParams<T extends NadoContractName> {
+  contractAddresses: NadoDeploymentAddresses;
+  contractName: T;
+  walletClient?: WalletClientWithAccount;
+  publicClient: PublicClient;
+}
+
+function getNadoContract<T extends NadoContractName>({
+  contractAddresses,
+  contractName,
+  walletClient,
+  publicClient,
+}: GetNadoContractParams<T>): NadoContracts[T] {
+  return getContract({
+    address: contractAddresses[contractName],
+    abi: NADO_ABIS[contractName],
+    client: walletClient ?? publicClient,
+  }) as NadoContracts[T];
+}

package/src/createNadoClient.ts

@@ -0,0 +1,20 @@
+import { NadoClient } from './client';
+import {
+  createClientContext,
+  CreateNadoClientContextAccountOpts,
+  CreateNadoClientContextOpts,
+} from './context';
+
+/**
+ * Creates a Nado client from given options.
+ * {@label CLIENT}
+ *
+ * @param opts
+ * @param accountOpts
+ */
+export function createNadoClient(
+  opts: CreateNadoClientContextOpts,
+  accountOpts: CreateNadoClientContextAccountOpts,
+): NadoClient {
+  return new NadoClient(createClientContext(opts, accountOpts));
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+export * from './createNadoClient';
+export * from './client';
+export * from './context';
+
+export * from './apis/market';
+export * from './apis/perp';
+export * from './apis/spot';
+export * from './apis/subaccount';
+
+// Subpackage exports
+export * from '@nadohq/utils';
+export * from '@nadohq/contracts';
+export * from '@nadohq/engine-client';
+export * from '@nadohq/indexer-client';
+export * from '@nadohq/trigger-client';