@velora-dex/sdk 8.0.0

package/src/methods/quote/getQuote.ts

@@ -0,0 +1,131 @@
+import { API_URL, SwapSide } from '../../constants';
+import { constructSearchString } from '../../helpers/misc';
+import type { DeltaPrice } from '../delta/getDeltaPrice';
+import type {
+  ConstructFetchInput,
+  EnumerateLiteral,
+  RequestParameters,
+  OptimalRate,
+} from '../../types';
+
+type TradeMode = 'delta' | 'market' | 'all';
+// enable passing enum value by string
+type SwapSideUnion = EnumerateLiteral<typeof SwapSide>;
+
+export type QuoteParams<M extends TradeMode = TradeMode> = {
+  /** @description Source Token Address */
+  srcToken: string;
+  /** @description Destination Token Address */
+  destToken: string;
+  /** @description srcToken amount (in case of SELL) or destToken amount (in case of BUY), in wei */
+  amount: string;
+  /** @description Source Token Decimals.  */
+  srcDecimals: number;
+  /** @description Destination Token Decimals */
+  destDecimals: number;
+  /** @description SELL or BUY */
+  side: SwapSideUnion;
+  /** @description User's Wallet Address */
+  userAddress?: string;
+  /** @description Partner string */
+  partner?: string;
+  /** @description Preferred mode for the trade. In case of "all", Delta pricing is returned, with Market as a fallback */
+  mode: M;
+};
+
+type QuoteQueryOptions = QuoteParams & {
+  chainId: number; // will return error from API on unsupported chains
+};
+
+type FallbackReason = {
+  errorType: string;
+  details: string;
+};
+
+export type QuoteWithMarketPrice = {
+  market: OptimalRate;
+};
+
+export type QuoteWithDeltaPrice = {
+  delta: DeltaPrice;
+};
+
+export type QuoteWithMarketPriceAsFallback = QuoteWithMarketPrice & {
+  fallbackReason: FallbackReason;
+};
+
+export type QuoteResponse =
+  | QuoteWithDeltaPrice
+  | QuoteWithMarketPrice
+  | QuoteWithMarketPriceAsFallback;
+
+interface GetQuoteFunc {
+  (
+    options: QuoteParams<'delta'>,
+    requestParams?: RequestParameters
+  ): Promise<QuoteWithDeltaPrice>;
+  (
+    options: QuoteParams<'market'>,
+    requestParams?: RequestParameters
+  ): Promise<QuoteWithMarketPrice>;
+  (options: QuoteParams<'all'>, requestParams?: RequestParameters): Promise<
+    QuoteWithDeltaPrice | QuoteWithMarketPriceAsFallback // "all" mode tries for deltaPrice and falls back to market priceRoute
+  >;
+  (
+    options: QuoteParams,
+    requestParams?: RequestParameters
+  ): Promise<QuoteResponse>;
+}
+
+export type GetQuoteFunctions = {
+  getQuote: GetQuoteFunc;
+};
+
+export const constructGetQuote = ({
+  apiURL = API_URL,
+  chainId,
+  fetcher,
+}: ConstructFetchInput): GetQuoteFunctions => {
+  const pricesUrl = `${apiURL}/quote` as const;
+
+  function getQuote(
+    options: QuoteParams<'delta'>,
+    requestParams?: RequestParameters
+  ): Promise<QuoteWithDeltaPrice>;
+  function getQuote(
+    options: QuoteParams<'market'>,
+    requestParams?: RequestParameters
+  ): Promise<QuoteWithMarketPrice>;
+  function getQuote(
+    options: QuoteParams<'all'>,
+    requestParams?: RequestParameters
+  ): Promise<QuoteWithDeltaPrice | QuoteWithMarketPriceAsFallback>;
+  function getQuote(
+    options: QuoteParams,
+    requestParams?: RequestParameters
+  ): Promise<QuoteResponse>;
+  async function getQuote(
+    options: QuoteParams,
+    requestParams?: RequestParameters
+  ): Promise<QuoteResponse> {
+    const search = constructSearchString<QuoteQueryOptions>({
+      ...options,
+      chainId,
+      // side: SwapSide.SELL, // so far SELL side only for Delta
+    });
+
+    const fetchURL = `${pricesUrl}/${search}` as const;
+
+    const data = await fetcher<QuoteResponse>({
+      url: fetchURL,
+      method: 'GET',
+      requestParams,
+    });
+
+    return data;
+  }
+
+  return {
+    getQuote,
+  };
+};

package/src/methods/swap/adapters.ts

@@ -0,0 +1,49 @@
+import type {
+  ConstructFetchInput,
+  APIVersion,
+  RequestParameters,
+} from '../../types';
+import { constructSearchString } from '../../helpers/misc';
+import { API_URL, DEFAULT_VERSION } from '../../constants';
+
+type AdaptersAsStrings = string[];
+
+export type GetAdaptersFunctions = {
+  getAdapters: (
+    requestParams?: RequestParameters
+  ) => Promise<AdaptersAsStrings>;
+};
+
+type SearchStringParams = {
+  network: number;
+  version?: APIVersion;
+};
+
+export const constructGetAdapters = ({
+  apiURL = API_URL,
+  version = DEFAULT_VERSION,
+  chainId,
+  fetcher,
+}: ConstructFetchInput): GetAdaptersFunctions => {
+  const getAdapters: GetAdaptersFunctions['getAdapters'] = async (
+    requestParams
+  ): Promise<AdaptersAsStrings> => {
+    // always pass explicit type to make sure UrlSearchParams are correct
+    const query = constructSearchString<SearchStringParams>({
+      network: chainId,
+      version,
+    });
+
+    const fetchURL = `${apiURL}/adapters/list${query}` as const;
+
+    const data = await fetcher<AdaptersAsStrings>({
+      url: fetchURL,
+      method: 'GET',
+      requestParams,
+    });
+
+    return data;
+  };
+
+  return { getAdapters };
+};

package/src/methods/swap/approve.ts

@@ -0,0 +1,51 @@
+import { constructGetSpender } from './spender';
+import type {
+  ConstructProviderFetchInput,
+  TxSendOverrides,
+  Address,
+  PriceString,
+  RequestParameters,
+} from '../../types';
+import { ApproveToken, approveTokenMethodFactory } from '../../helpers/approve';
+
+type ApproveTokenBulk<T> = (
+  amount: PriceString,
+  tokenAddresses: Address[],
+  overrides?: TxSendOverrides,
+  requestParams?: RequestParameters
+) => Promise<Awaited<T>[]>;
+
+export type ApproveTokenFunctions<T> = {
+  approveToken: ApproveToken<T>;
+  approveTokenBulk: ApproveTokenBulk<T>;
+};
+
+// returns whatever `contractCaller` returns
+// to allow for better versatility
+export const constructApproveToken = <T>(
+  options: ConstructProviderFetchInput<T, 'transactCall'>
+): ApproveTokenFunctions<T> => {
+  // getSpender is cached internally for the same instance of SDK
+  // so should persist across same apiUrl & network
+  const { getSpender } = constructGetSpender(options);
+
+  const approveToken: ApproveToken<T> = approveTokenMethodFactory<T>(
+    options.contractCaller,
+    getSpender
+  );
+
+  const approveTokenBulk: ApproveTokenBulk<T> = async (
+    amount,
+    tokenAddresses,
+    overrides,
+    requestParams
+  ) => {
+    return Promise.all(
+      tokenAddresses.map((tokenAddress) =>
+        approveToken(amount, tokenAddress, overrides, requestParams)
+      )
+    );
+  };
+
+  return { approveToken, approveTokenBulk };
+};

package/src/methods/swap/balance.ts

@@ -0,0 +1,147 @@
+import { API_URL } from '../../constants';
+import {
+  Token,
+  Address,
+  constructToken,
+  AddressOrSymbol,
+} from '../../helpers/token';
+import type {
+  ConstructFetchInput,
+  TokenApiResponse,
+  TokensApiResponse,
+  RequestParameters,
+} from '../../types';
+
+type GetBalances = (
+  userAddress: Address,
+  requestParams?: RequestParameters
+) => Promise<Token[]>;
+type GetBalance = (
+  userAddress: Address,
+  tokenAddressOrSymbol: AddressOrSymbol,
+  requestParams?: RequestParameters
+) => Promise<Token | typeof NOT_FOUND_RESPONSE>;
+
+export interface Allowance {
+  tokenAddress: Address;
+  allowance: string;
+}
+
+type GetAllowances = (
+  userAddress: Address,
+  tokenAddresses: Address[],
+  requestParams?: RequestParameters
+) => Promise<Allowance[]>;
+type GetAllowance = (
+  userAddress: Address,
+  tokenAddress: Address,
+  requestParams?: RequestParameters
+) => Promise<Allowance | typeof NOT_FOUND_RESPONSE>;
+
+export const isAllowance = (
+  arg: Awaited<ReturnType<GetAllowance>>
+): arg is Allowance => {
+  return 'allowance' in arg;
+};
+
+export type GetBalancesFunctions = {
+  getBalance: GetBalance;
+  getBalances: GetBalances;
+  getAllowance: GetAllowance;
+  getAllowances: GetAllowances;
+};
+
+const NOT_FOUND_RESPONSE = { message: 'Not Found' } as const;
+
+export const constructGetBalances = ({
+  apiURL = API_URL,
+  chainId,
+  fetcher,
+}: ConstructFetchInput): GetBalancesFunctions => {
+  const tokensUrl = `${apiURL}/users/tokens/${chainId}` as const;
+
+  const getBalances: GetBalances = async (userAddress, requestParams) => {
+    const fetchURL = `${tokensUrl}/${userAddress}` as const;
+
+    const data = await fetcher<TokensApiResponse>({
+      url: fetchURL,
+      method: 'GET',
+      requestParams,
+    });
+
+    const tokens = data.tokens.map(constructToken);
+
+    return tokens;
+  };
+
+  const getBalance: GetBalance = async (
+    userAddress,
+    tokenAddressOrSymbol,
+    requestParams
+  ) => {
+    const fetchURL =
+      `${tokensUrl}/${userAddress}/${tokenAddressOrSymbol}` as const;
+
+    const data = await fetcher<TokenApiResponse>({
+      url: fetchURL,
+      method: 'GET',
+      requestParams,
+    });
+
+    if (!data.token) {
+      return NOT_FOUND_RESPONSE;
+    }
+
+    return constructToken(data.token);
+  };
+
+  const getAllowances: GetAllowances = async (
+    userAddress,
+    tokenAddresses,
+    requestParams
+  ) => {
+    const tokenAddressesLowercaseSet = new Set(
+      tokenAddresses.map((address) => address.toLowerCase())
+    );
+
+    const balances = await getBalances(userAddress, requestParams);
+
+    const allowances: Allowance[] = balances
+      .filter((token) =>
+        tokenAddressesLowercaseSet.has(token.address.toLowerCase())
+      )
+      .map(({ address, allowance = '0' }) => ({
+        tokenAddress: address,
+        allowance,
+      }));
+
+    return allowances;
+  };
+
+  const getAllowance: GetAllowance = async (
+    userAddress,
+    tokenAddress,
+    requestParams
+  ) => {
+    const balanceOrNotFound = await getBalance(
+      userAddress,
+      tokenAddress,
+      requestParams
+    );
+
+    if ('message' in balanceOrNotFound) {
+      return balanceOrNotFound;
+    }
+
+    const { address, allowance = '0' } = balanceOrNotFound;
+
+    return { tokenAddress: address, allowance };
+  };
+
+  return {
+    getBalance,
+    getBalances,
+    getAllowance,
+    getAllowances,
+  };
+};

package/src/methods/swap/helpers/normalizeRateOptions.ts

@@ -0,0 +1,55 @@
+import type { PickKeys } from 'ts-essentials';
+import type { RateOptions } from '../rates';
+
+type StringArrKeys = PickKeys<RateOptions, string[] | undefined>;
+
+type MinRateOptionsInput = Pick<RateOptions, StringArrKeys> &
+  Pick<RateOptions, 'partner'>;
+
+type NormalizedRateOptions<
+  O extends MinRateOptionsInput,
+  T extends { options?: Partial<O> }
+> = Partial<Record<StringArrKeys | 'partner', string>> &
+  Partial<Omit<O, StringArrKeys | 'partner'>> &
+  Omit<T, 'options'>;
+
+export function normalizeRateOptions<
+  O extends MinRateOptionsInput,
+  T extends { options?: Partial<O> }
+>({ options = {}, ...restInput }: T): NormalizedRateOptions<O, T> {
+  const {
+    excludeContractMethods,
+    includeContractMethods,
+    partner,
+    includeDEXS,
+    excludeDEXS,
+    excludePools,
+    ...restOptions
+  } = options;
+
+  const [
+    _includeDEXS,
+    _excludeDEXS,
+    _excludePools,
+    _excludeContractMethods,
+    _includeContractMethods,
+  ] = [
+    includeDEXS,
+    excludeDEXS,
+    excludePools,
+    excludeContractMethods,
+    includeContractMethods,
+    //                                                                                              no "" empty string
+  ].map((array) => array?.join(',') || undefined);
+
+  const transformed: Partial<Record<StringArrKeys | 'partner', string>> = {
+    excludeContractMethods: _excludeContractMethods,
+    includeContractMethods: _includeContractMethods,
+    partner,
+    includeDEXS: _includeDEXS,
+    excludeDEXS: _excludeDEXS,
+    excludePools: _excludePools,
+  };
+
+  return { ...transformed, ...restOptions, ...restInput };
+}

package/src/methods/swap/index.ts

@@ -0,0 +1,38 @@
+import { constructPartialSDK, SDKConfig } from '../../sdk/partial';
+import { constructGetAdapters, GetAdaptersFunctions } from './adapters';
+import { ApproveTokenFunctions, constructApproveToken } from './approve';
+import { constructGetBalances, GetBalancesFunctions } from './balance';
+import { constructGetRate, GetRateFunctions } from './rates';
+import { constructGetSpender, GetSpenderFunctions } from './spender';
+import { constructSwapTx, GetSwapTxFunctions } from './swapTx';
+import { constructGetTokens, GetTokensFunctions } from './token';
+import { BuildTxFunctions, constructBuildTx } from './transaction';
+
+export type SwapSDKMethods<TxResponse> = GetBalancesFunctions &
+  GetTokensFunctions &
+  GetSpenderFunctions &
+  ApproveTokenFunctions<TxResponse> &
+  BuildTxFunctions &
+  GetAdaptersFunctions &
+  GetRateFunctions &
+  GetSwapTxFunctions;
+
+/** @description construct SDK with every Swap-related method, fetching from API and token approval */
+export const constructSwapSDK = <TxResponse>(
+  config: SDKConfig<TxResponse>
+): SwapSDKMethods<TxResponse> => {
+  const constructApproveTokenWithTxResponse = constructApproveToken<TxResponse>;
+
+  // include all available Swap methods
+  return constructPartialSDK(
+    config,
+    constructGetBalances,
+    constructGetTokens,
+    constructGetSpender,
+    constructApproveTokenWithTxResponse,
+    constructBuildTx,
+    constructGetAdapters,
+    constructGetRate,
+    constructSwapTx
+  );
+};