@velora-dex/sdk 9.5.4-dev.1 → 9.5.4-dev.2

package/src/methods/deltaV2/getBridgeRoutes.ts

@@ -23,19 +23,19 @@ type GetBridgeRoutes = (
   requestParams?: RequestParameters
 ) => Promise<BridgeRoute[]>;
 
-type GetBridgeProtocolsV2 = (
+type GetBridgeProtocols = (
   requestParams?: RequestParameters
 ) => Promise<BridgeProtocolResponse[]>;
 
-type BridgeProtocolsV2Response = {
+type BridgeProtocolsResponse = {
   bridgeProtocols: BridgeProtocolResponse[];
 };
 
 export type GetBridgeRoutesFunctions = {
   /** @description Fetch supported bridge routes as a flat array (v2 replacement for bridge-info). */
   getBridgeRoutes: GetBridgeRoutes;
-  /** @description Fetch supported bridge protocols (falls through to v1 controller on the v2 path). */
-  getBridgeProtocolsV2: GetBridgeProtocolsV2;
+  /** @description Fetch supported bridge protocols (unchanged from v1). */
+  getBridgeProtocols: GetBridgeProtocols;
 };
 
 export const constructGetBridgeRoutes = ({
@@ -66,10 +66,10 @@ export const constructGetBridgeRoutes = ({
     return data.routes;
   };
 
-  const getBridgeProtocolsV2: GetBridgeProtocolsV2 = async (requestParams) => {
+  const getBridgeProtocols: GetBridgeProtocols = async (requestParams) => {
     const fetchURL = `${deltaPricesUrl}/bridge-protocols` as const;
 
-    const data = await fetcher<BridgeProtocolsV2Response>({
+    const data = await fetcher<BridgeProtocolsResponse>({
       url: fetchURL,
       method: 'GET',
       requestParams,
@@ -78,5 +78,5 @@ export const constructGetBridgeRoutes = ({
     return data.bridgeProtocols;
   };
 
-  return { getBridgeRoutes, getBridgeProtocolsV2 };
+  return { getBridgeRoutes, getBridgeProtocols };
 };

package/src/methods/deltaV2/getDeltaOrders.ts

@@ -0,0 +1,149 @@
+import { API_URL } from '../../constants';
+import { constructSearchString } from '../../helpers/misc';
+import type {
+  Address,
+  ConstructFetchInput,
+  PaginatedResponse,
+  RequestParameters,
+} from '../../types';
+import type { DeltaOrderType, OnChainOrderType } from '../delta/helpers/types';
+import type { DeltaOrderStatus, DeltaAuction } from './types';
+
+type GetDeltaOrderById = (
+  orderId: string,
+  requestParams?: RequestParameters
+) => Promise<DeltaAuction>;
+
+type GetDeltaOrderByHash = (
+  orderHash: string,
+  requestParams?: RequestParameters
+) => Promise<DeltaAuction>;
+
+type OrdersFilter = {
+  /** @description `order.owner` to fetch Delta Orders for. */
+  userAddress: Address;
+  /** @description Pagination option. Default 1. */
+  page?: number;
+  /** @description Pagination option. Default 100, max 1000. */
+  limit?: number;
+  /** @description Filter by chainId. Omitted = orders across all chains. */
+  chainId?: number[];
+  /** @description Filter by integrator-facing status. */
+  status?: DeltaOrderStatus[];
+  /** @description Filter by order type. MARKET or LIMIT. */
+  type?: DeltaOrderType;
+  /** @description Filter by on-chain order type. */
+  onChainOrderType?: OnChainOrderType;
+};
+
+type OrderFiltersQuery = Omit<OrdersFilter, 'chainId' | 'status'> & {
+  chainId?: string;
+  status?: string;
+};
+
+type GetDeltaOrders = (
+  options: OrdersFilter,
+  requestParams?: RequestParameters
+) => Promise<PaginatedResponse<DeltaAuction>>;
+
+type GetRequiredBalanceParams = {
+  userAddress: Address;
+  tokenAddress?: Address;
+};
+
+type GetRequiredBalance = (
+  userParams: GetRequiredBalanceParams,
+  requestParams?: RequestParameters
+) => Promise<Record<string, string>>; // token -> required balance across open Delta orders
+
+export type GetDeltaOrdersFunctions = {
+  /** @description Fetch a single order by its UUID. */
+  getDeltaOrderById: GetDeltaOrderById;
+  /** @description Fetch a single order by its EIP-712 order hash. */
+  getDeltaOrderByHash: GetDeltaOrderByHash;
+  /** @description List Delta orders with the v2 pagination envelope. */
+  getDeltaOrders: GetDeltaOrders;
+  /** @description Required balance per token across the user's open Delta v2 orders. Pass `tokenAddress` to narrow the result to a single token. */
+  getRequiredBalanceForDeltaOrders: GetRequiredBalance;
+};
+
+export const constructGetDeltaOrders = ({
+  apiURL = API_URL,
+  fetcher,
+  chainId,
+}: ConstructFetchInput): GetDeltaOrdersFunctions => {
+  const baseUrl = `${apiURL}/delta/v2/orders` as const;
+
+  const getDeltaOrderById: GetDeltaOrderById = async (
+    orderId,
+    requestParams
+  ) => {
+    const fetchURL = `${baseUrl}/${orderId}` as const;
+    return fetcher<DeltaAuction>({
+      url: fetchURL,
+      method: 'GET',
+      requestParams,
+    });
+  };
+
+  const getDeltaOrderByHash: GetDeltaOrderByHash = async (
+    orderHash,
+    requestParams
+  ) => {
+    const fetchURL = `${baseUrl}/hash/${orderHash}` as const;
+    return fetcher<DeltaAuction>({
+      url: fetchURL,
+      method: 'GET',
+      requestParams,
+    });
+  };
+
+  const getDeltaOrders: GetDeltaOrders = async (options, requestParams) => {
+    const chainIdString = options.chainId?.join(',');
+    const statusString = options.status?.join(',');
+
+    const search = constructSearchString<OrderFiltersQuery>({
+      userAddress: options.userAddress,
+      page: options.page,
+      limit: options.limit,
+      type: options.type,
+      onChainOrderType: options.onChainOrderType,
+      chainId: chainIdString,
+      status: statusString,
+    });
+
+    const fetchURL = `${baseUrl}${search}` as const;
+
+    return fetcher<PaginatedResponse<DeltaAuction>>({
+      url: fetchURL,
+      method: 'GET',
+      requestParams,
+    });
+  };
+
+  const getRequiredBalanceForDeltaOrders: GetRequiredBalance = async (
+    userParams,
+    requestParams
+  ) => {
+    const userURL =
+      `${baseUrl}/fillablebalance/${chainId}/${userParams.userAddress}` as const;
+    const fetchURL = userParams.tokenAddress
+      ? (`${userURL}/${userParams.tokenAddress}` as const)
+      : userURL;
+
+    const response = await fetcher<Record<string, string>>({
+      url: fetchURL,
+      method: 'GET',
+      requestParams,
+    });
+
+    return response;
+  };
+
+  return {
+    getDeltaOrderById,
+    getDeltaOrderByHash,
+    getDeltaOrders,
+    getRequiredBalanceForDeltaOrders,
+  };
+};

package/src/methods/deltaV2/{getDeltaPriceV2.ts → getDeltaPrice.ts}

@@ -5,11 +5,11 @@ import type {
   EnumerateLiteral,
   RequestParameters,
 } from '../../types';
-import type { DeltaPriceV2 } from './types';
+import type { DeltaPrice } from './types';
 
 type SwapSideUnion = EnumerateLiteral<typeof SwapSide>;
 
-export type DeltaPriceV2Params = {
+export type DeltaPriceParams = {
   /** @description Source Token Address */
   srcToken: string;
   /** @description Destination Token Address. For Crosschain Orders, the destination token on the destination chain */
@@ -46,8 +46,8 @@ export type DeltaPriceV2Params = {
   degenMode?: boolean;
 };
 
-type DeltaPriceV2QueryOptions = Omit<
-  DeltaPriceV2Params,
+type DeltaPriceQueryOptions = Omit<
+  DeltaPriceParams,
   'includeAgents' | 'excludeAgents' | 'includeBridges' | 'excludeBridges'
 > & {
   chainId: number;
@@ -57,24 +57,24 @@ type DeltaPriceV2QueryOptions = Omit<
   excludeBridges?: string;
 };
 
-type GetDeltaPriceV2 = (
-  options: DeltaPriceV2Params,
+type GetDeltaPrice = (
+  options: DeltaPriceParams,
   requestParams?: RequestParameters
-) => Promise<DeltaPriceV2>;
+) => Promise<DeltaPrice>;
 
-export type GetDeltaPriceV2Functions = {
+export type GetDeltaPriceFunctions = {
   /** @description Fetch a v2 price quote (route-based response). */
-  getDeltaPriceV2: GetDeltaPriceV2;
+  getDeltaPrice: GetDeltaPrice;
 };
 
-export const constructGetDeltaPriceV2 = ({
+export const constructGetDeltaPrice = ({
   apiURL = API_URL,
   chainId,
   fetcher,
-}: ConstructFetchInput): GetDeltaPriceV2Functions => {
+}: ConstructFetchInput): GetDeltaPriceFunctions => {
   const pricesUrl = `${apiURL}/delta/v2/prices` as const;
 
-  const getDeltaPriceV2: GetDeltaPriceV2 = async (options, requestParams) => {
+  const getDeltaPrice: GetDeltaPrice = async (options, requestParams) => {
     const {
       includeAgents,
       excludeAgents,
@@ -83,7 +83,7 @@ export const constructGetDeltaPriceV2 = ({
       ...rest
     } = options;
 
-    const search = constructSearchString<DeltaPriceV2QueryOptions>({
+    const search = constructSearchString<DeltaPriceQueryOptions>({
       ...rest,
       chainId,
       side: options.side ?? SwapSide.SELL,
@@ -95,7 +95,7 @@ export const constructGetDeltaPriceV2 = ({
 
     const fetchURL = `${pricesUrl}${search}` as const;
 
-    const data = await fetcher<DeltaPriceV2>({
+    const data = await fetcher<DeltaPrice>({
       url: fetchURL,
       method: 'GET',
       requestParams,
@@ -104,5 +104,5 @@ export const constructGetDeltaPriceV2 = ({
     return data;
   };
 
-  return { getDeltaPriceV2 };
+  return { getDeltaPrice };
 };

package/src/methods/deltaV2/helpers/orders.ts

@@ -0,0 +1,363 @@
+import type { NonEmptyArray } from 'ts-essentials';
+import { OrderHelpers as DeltaV1OrderHelpers } from '../../delta/helpers/orders';
+import type {
+  SwapSideUnion,
+  UnifiedDeltaOrderData,
+} from '../../delta/helpers/types';
+import type {
+  DeltaAuction,
+  DeltaOrderStatus,
+  DeltaTokenSide,
+  DeltaTransaction,
+} from '../types';
+
+/**
+ * v2 order helpers.
+ *
+ * The on-chain order structs (`auction.order`) are identical between v1 and v2
+ * — they come from the same `OnChainOrderMap` — so every order-struct guard and
+ * order-level getter is reused directly from v1's `OrderHelpers`. Likewise the
+ * auction discriminant guards only look at `onChainOrderType` (same union in
+ * both versions), so those are reused too.
+ *
+ * What differs in v2 is the *auction* envelope:
+ *  - `status` is the integrator-facing `DeltaOrderStatus`
+ *    (PENDING/ACTIVE/COMPLETED/… — not v1's `DeltaAuctionStatus`),
+ *  - amounts live on `input`/`output` (`DeltaTokenSide`) and `transactions`
+ *    (`DeltaTransaction`) instead of v1's order/transaction shapes,
+ *  - `side` is carried explicitly on the auction.
+ *
+ * Those pieces are reimplemented here against the v2 shapes.
+ */
+
+const v1Checks = DeltaV1OrderHelpers.checks;
+const v1Getters = DeltaV1OrderHelpers.getters;
+
+///// CHECKS //////
+
+/**
+ * @description Checks whether an auction is fully executed (settled on every chain).
+ */
+function isCompletedAuction<T extends Pick<DeltaAuction, 'status'>>(
+  auction: T
+): auction is T & { status: 'COMPLETED' } {
+  return auction.status === 'COMPLETED';
+}
+
+const failedAuctionStatuses = [
+  'FAILED',
+  'EXPIRED',
+  'CANCELLED',
+  'REFUNDED',
+] as const;
+
+const failedAuctionStatusesSet = new Set<DeltaOrderStatus>(
+  failedAuctionStatuses
+);
+
+/**
+ * @description Checks whether an auction is in a terminal failure state
+ * (failed, expired, cancelled, or refunded).
+ */
+function isFailedAuction<T extends Pick<DeltaAuction, 'status'>>(
+  auction: T
+): auction is T & { status: (typeof failedAuctionStatuses)[number] } {
+  return failedAuctionStatusesSet.has(auction.status);
+}
+
+/**
+ * @description Checks whether an auction status is cancelled.
+ */
+function isCanceledAuction<T extends Pick<DeltaAuction, 'status'>>(
+  auction: T
+): auction is T & { status: 'CANCELLED' } {
+  return auction.status === 'CANCELLED';
+}
+
+/**
+ * @description Checks whether an auction status is expired.
+ */
+function isExpiredAuction<T extends Pick<DeltaAuction, 'status'>>(
+  auction: T
+): auction is T & { status: 'EXPIRED' } {
+  return auction.status === 'EXPIRED';
+}
+
+const pendingAuctionStatuses = [
+  'PENDING',
+  'AWAITING_SIGNATURE',
+  'ACTIVE',
+  'BRIDGING',
+] as const;
+
+const pendingAuctionStatusesSet = new Set<DeltaOrderStatus>(
+  pendingAuctionStatuses
+);
+
+/**
+ * @description Checks whether an auction is still in flight (not yet settled
+ * and not failed): awaiting signature, pending, actively executing, or bridging.
+ */
+function isPendingAuction<T extends Pick<DeltaAuction, 'status'>>(
+  auction: T
+): auction is T & { status: (typeof pendingAuctionStatuses)[number] } {
+  return pendingAuctionStatusesSet.has(auction.status);
+}
+
+/**
+ * @description Checks whether an auction is a Fillable auction.
+ * `FillableOrder` is the `onChainOrderType` the server reports for a
+ * `partiallyFillable` Standard order; it carries the same order struct as
+ * `Order`. Consumers that don't distinguish the two should treat
+ * `isDeltaAuction(a) || isFillableAuction(a)` as "is a standard order".
+ */
+function isFillableAuction<T extends Pick<DeltaAuction, 'onChainOrderType'>>(
+  auction: T
+): auction is T & { onChainOrderType: 'FillableOrder' } {
+  return auction.onChainOrderType === 'FillableOrder';
+}
+
+/**
+ * @description Checks whether an auction has been partially executed:
+ * it has at least one transaction and an overall filled percent strictly
+ * between 0 and 100.
+ */
+function isPartiallyExecutedAuction<
+  T extends Pick<DeltaAuction, 'order' | 'transactions'>,
+>(
+  auction: T
+): auction is T & { transactions: NonEmptyArray<DeltaTransaction> } {
+  if (auction.transactions.length === 0) return false;
+
+  const filledPercent = getFilledPercent(auction);
+
+  return filledPercent > 0 && filledPercent < 100;
+}
+
+const checks = {
+  // order-struct guards — order structs are shared with v1, reused as-is.
+  isTWAPOrder: v1Checks.isTWAPOrder,
+  isTWAPSellOrder: v1Checks.isTWAPSellOrder,
+  isTWAPBuyOrder: v1Checks.isTWAPBuyOrder,
+  isExternalOrder: v1Checks.isExternalOrder,
+  isDeltaOrder: v1Checks.isDeltaOrder,
+  isProductiveOrder: v1Checks.isProductiveOrder,
+
+  // auction discriminant guards — `onChainOrderType` union is shared, reused as-is.
+  isTWAPAuction: v1Checks.isTWAPAuction,
+  isTWAPSellAuction: v1Checks.isTWAPSellAuction,
+  isTWAPBuyAuction: v1Checks.isTWAPBuyAuction,
+  isDeltaAuction: v1Checks.isDeltaAuction,
+  isExternalAuction: v1Checks.isExternalAuction,
+  isProductiveAuction: v1Checks.isProductiveAuction,
+  isFillableAuction,
+
+  // status / execution guards — v2 status enum & transaction shape.
+  isCompletedAuction,
+  isFailedAuction,
+  isCanceledAuction,
+  isExpiredAuction,
+  isPendingAuction,
+  isPartiallyExecutedAuction,
+};
+
+///// GETTERS //////
+
+/**
+ * @description Reads an amount off a v2 token side. A SELL input / BUY output
+ * carries an explicit `amount`; the opposite side carries
+ * `expectedAmount`/`executedAmount`. `prefer` chooses which to read on the
+ * expected/executed variant.
+ */
+function getTokenSideAmount(
+  side: DeltaTokenSide,
+  prefer: 'expected' | 'executed'
+): string {
+  if ('amount' in side) return side.amount;
+
+  const value =
+    prefer === 'executed' ? side.executedAmount : side.expectedAmount;
+
+  return value ?? '0';
+}
+
+/**
+ * @description Returns the source chain id for the auction (the input side's chain).
+ */
+function getAuctionSrcChainId(auction: Pick<DeltaAuction, 'input'>): number {
+  return auction.input.chainId;
+}
+
+/**
+ * @description Returns the destination chain id for the auction (the output side's chain).
+ * Equals the source chain id for same-chain orders.
+ */
+function getAuctionDestChainId(auction: Pick<DeltaAuction, 'output'>): number {
+  return auction.output.chainId;
+}
+
+/**
+ * @description Returns the swap side for any auction. v2 carries `side` on the
+ * auction directly, so no order introspection is needed.
+ */
+function getAuctionSwapSide(
+  auction: Pick<DeltaAuction, 'side'>
+): SwapSideUnion {
+  return auction.side;
+}
+
+/**
+ * @description Returns source and destination token addresses for the auction,
+ * read from the input/output sides (already resolved to the dest-chain token
+ * for cross-chain orders).
+ */
+function getAuctionTokenAddresses(
+  auction: Pick<DeltaAuction, 'input' | 'output'>
+) {
+  return {
+    srcToken: auction.input.token,
+    destToken: auction.output.token,
+  };
+}
+
+/**
+ * @description Aggregates transaction amounts into total spent (src) and
+ * received (dest) values.
+ */
+function getTransactionAmounts(transactions: DeltaTransaction[]) {
+  const { srcAmount, destAmount } = transactions.reduce(
+    (acc, { spentAmount, receivedAmount }) => ({
+      srcAmount: acc.srcAmount + BigInt(spentAmount ?? 0),
+      destAmount: acc.destAmount + BigInt(receivedAmount ?? 0),
+    }),
+    { srcAmount: 0n, destAmount: 0n }
+  );
+
+  return {
+    srcAmount: srcAmount.toString(),
+    destAmount: destAmount.toString(),
+  };
+}
+
+/**
+ * @description Calculates the overall filled percent (0–100) from the
+ * per-transaction `filledPercent` values. For TWAP orders each transaction is
+ * a slice (0–100 of that slice), so the slice values are averaged across
+ * `numSlices`; for single-fill orders the values sum directly.
+ */
+function getFilledPercent(
+  auction: Pick<DeltaAuction, 'order' | 'transactions'>
+): number {
+  if (auction.transactions.length === 0) return 0;
+
+  const total = auction.transactions.reduce(
+    (acc, { filledPercent }) => acc + filledPercent,
+    0
+  );
+
+  if (checks.isTWAPOrder(auction.order) && auction.order.numSlices > 0) {
+    return total / auction.order.numSlices;
+  }
+
+  return total;
+}
+
+/**
+ * @description Returns expected amounts and, once the auction is completed,
+ * executed amounts. Executed amounts prefer the `executedAmount` baked onto the
+ * token sides and fall back to summing transactions.
+ */
+function getAuctionAmounts(
+  auction: Pick<
+    DeltaAuction,
+    'status' | 'order' | 'input' | 'output' | 'transactions'
+  >
+) {
+  const expected = {
+    srcAmount: getTokenSideAmount(auction.input, 'expected'),
+    destAmount: getTokenSideAmount(auction.output, 'expected'),
+  };
+
+  if (!isCompletedAuction(auction)) {
+    return { expected };
+  }
+
+  const txAmounts = getTransactionAmounts(auction.transactions);
+
+  const executed = {
+    srcAmount: getExecutedAmount(auction.input, txAmounts.srcAmount),
+    destAmount: getExecutedAmount(auction.output, txAmounts.destAmount),
+  };
+
+  return { expected, executed };
+}
+
+/**
+ * @description Returns the executed amount of a token side when present,
+ * otherwise the provided fallback (typically summed from transactions).
+ */
+function getExecutedAmount(side: DeltaTokenSide, fallback: string): string {
+  if ('executedAmount' in side && side.executedAmount != null) {
+    return side.executedAmount;
+  }
+
+  return fallback;
+}
+
+/**
+ * @description Returns unified order data with normalized amounts, tokens,
+ * chain ids, and side — the v2 counterpart of v1's `getUnifiedDeltaOrderData`,
+ * built from the v2 auction envelope.
+ */
+function getUnifiedDeltaOrderData(
+  auction: DeltaAuction
+): UnifiedDeltaOrderData {
+  const { srcToken, destToken } = getAuctionTokenAddresses(auction);
+  const { expected, executed } = getAuctionAmounts(auction);
+
+  const srcChainId = getAuctionSrcChainId(auction);
+  const destChainId = getAuctionDestChainId(auction);
+  const swapSide = getAuctionSwapSide(auction);
+  const filledPercent = getFilledPercent(auction);
+
+  return {
+    srcChainId,
+    destChainId,
+    srcAmount: executed?.srcAmount || expected.srcAmount,
+    destAmount: executed?.destAmount || expected.destAmount,
+    amounts: {
+      expected,
+      final: executed,
+    },
+    srcToken,
+    destToken,
+    swapSide,
+    filledPercent,
+  };
+}
+
+const getters = {
+  getUnifiedDeltaOrderData,
+
+  // auction-level getters — v2 envelope shape.
+  getAuctionTokenAddresses,
+  getAuctionSrcChainId,
+  getAuctionDestChainId,
+  getAuctionSwapSide,
+  getTransactionAmounts,
+  getAuctionAmounts,
+  getFilledPercent,
+
+  // order-level getters — order structs are shared with v1, reused as-is.
+  getOrderTokenAddresses: v1Getters.getOrderTokenAddresses,
+  getSwapSideFromDeltaOrder: v1Getters.getSwapSideFromDeltaOrder,
+  getSwapSideFromTwapOrderType: v1Getters.getSwapSideFromTwapOrderType,
+  getExpectedTwapSrcAmount: v1Getters.getExpectedTwapSrcAmount,
+  getExpectedTwapDestAmount: v1Getters.getExpectedTwapDestAmount,
+  getExpectedTwapOrderAmounts: v1Getters.getExpectedTwapOrderAmounts,
+};
+
+export const OrderHelpers = {
+  checks,
+  getters,
+};