@luxexchange/lx 1.0.0

package/src/features/transactions/types/transactionRequests.ts

@@ -0,0 +1,14 @@
+import { TransactionRequest } from '@ethersproject/providers'
+import { NonEmptyArray } from '@luxfi/utilities/src/primitives/array'
+
+export type PopulatedTransactionRequestArray = NonEmptyArray<ValidatedTransactionRequest>
+export type ValidatedTransactionRequest = TransactionRequest & { to: string; chainId: number }
+
+export function isValidTransactionRequest(request: TransactionRequest): request is ValidatedTransactionRequest {
+  return (
+    typeof request.to === 'string' &&
+    request.to.length > 0 &&
+    typeof request.chainId === 'number' &&
+    request.chainId > 0
+  )
+}

package/src/features/transactions/types/transactionState.ts

@@ -0,0 +1,70 @@
+import { AssetType, TradeableAsset } from '@luxexchange/lx/src/entities/assets'
+import { UniverseChainId } from '@luxexchange/lx/src/features/chains/types'
+import { FiatOffRampMetaData } from '@luxexchange/lx/src/features/fiatOnRamp/types'
+import { FrontendSupportedProtocol } from '@luxexchange/lx/src/features/transactions/swap/utils/protocols'
+import { CurrencyField, CurrencyId } from '@luxexchange/lx/src/types/currency'
+import { currencyIdToAddress, currencyIdToChain } from '@luxexchange/lx/src/utils/currencyId'
+
+export interface TransactionState {
+  txId?: string
+  [CurrencyField.INPUT]: TradeableAsset | null
+  [CurrencyField.OUTPUT]: TradeableAsset | null
+  exactCurrencyField: CurrencyField
+  exactAmountToken: string
+  isMax?: boolean
+  exactAmountFiat?: string
+  focusOnCurrencyField?: CurrencyField | null
+  skipFocusOnCurrencyField?: boolean
+  recipient?: string
+  isFiatInput?: boolean
+  selectingCurrencyField?: CurrencyField
+  selectingCurrencyChainId?: UniverseChainId
+  showRecipientSelector?: boolean
+  customSlippageTolerance?: number
+  customDeadline?: number
+  selectedProtocols?: FrontendSupportedProtocol[]
+  fiatOffRampMetaData?: FiatOffRampMetaData
+  filteredChainIdsOverride?: {
+    [CurrencyField.INPUT]?: UniverseChainId
+    [CurrencyField.OUTPUT]?: UniverseChainId
+  }
+}
+
+export const prepareSwapFormState = ({
+  inputCurrencyId,
+  outputCurrencyId,
+  defaultChainId,
+  filteredChainIdsOverride,
+  exactCurrencyField,
+  exactAmountToken,
+}: {
+  inputCurrencyId?: CurrencyId
+  outputCurrencyId?: CurrencyId
+  defaultChainId: UniverseChainId
+  filteredChainIdsOverride?: {
+    [CurrencyField.INPUT]?: UniverseChainId
+    [CurrencyField.OUTPUT]?: UniverseChainId
+  }
+  exactCurrencyField?: CurrencyField
+  exactAmountToken?: string
+}): TransactionState => {
+  return {
+    exactCurrencyField: exactCurrencyField ?? CurrencyField.INPUT,
+    exactAmountToken: exactAmountToken ?? '',
+    [CurrencyField.INPUT]: inputCurrencyId
+      ? {
+          address: currencyIdToAddress(inputCurrencyId),
+          chainId: currencyIdToChain(inputCurrencyId) ?? defaultChainId,
+          type: AssetType.Currency,
+        }
+      : null,
+    [CurrencyField.OUTPUT]: outputCurrencyId
+      ? {
+          address: currencyIdToAddress(outputCurrencyId),
+          chainId: currencyIdToChain(outputCurrencyId) ?? defaultChainId,
+          type: AssetType.Currency,
+        }
+      : null,
+    filteredChainIdsOverride,
+  }
+}

package/src/features/transactions/types/utils.ts

@@ -0,0 +1,131 @@
+import {
+  BridgeTransactionInfo,
+  ConfirmedSwapTransactionInfo,
+  FINAL_STATUSES,
+  FinalizedPlanTXDetails,
+  FinalizedTransactionDetails,
+  FinalizedTransactionStatus,
+  InterfaceTransactionDetails,
+  PlanTransactionDetails,
+  PlanTransactionInfo,
+  TransactionDetails,
+  TransactionStatus,
+  TransactionType,
+  TransactionTypeInfo,
+} from '@luxexchange/lx/src/features/transactions/types/transactionDetails'
+
+export function isConfirmedSwapTypeInfo(typeInfo: TransactionTypeInfo): typeInfo is ConfirmedSwapTransactionInfo {
+  return Boolean(
+    (typeInfo as ConfirmedSwapTransactionInfo).inputCurrencyAmountRaw &&
+      (typeInfo as ConfirmedSwapTransactionInfo).outputCurrencyAmountRaw,
+  )
+}
+
+export function isSwapTypeInfo(typeInfo: TransactionTypeInfo): boolean {
+  return typeInfo.type === TransactionType.Swap
+}
+
+export function isBridgeTypeInfo(typeInfo: TransactionTypeInfo): typeInfo is BridgeTransactionInfo {
+  return typeInfo.type === TransactionType.Bridge
+}
+
+export function isPlanTransactionDetails(tx: TransactionDetails): tx is PlanTransactionDetails {
+  return isPlanTransactionInfo(tx.typeInfo)
+}
+
+export function isPlanTransactionInfo(tx: TransactionTypeInfo): tx is PlanTransactionInfo {
+  return tx.type === TransactionType.Plan
+}
+
+export function isFinalizedTxStatus(status: TransactionStatus): status is FinalizedTransactionStatus {
+  return FINAL_STATUSES.some((finalStatus) => finalStatus === status)
+}
+
+export function isFinalizedPlanTXDetails(tx: FinalizedTransactionDetails): tx is FinalizedPlanTXDetails {
+  return isPlanTransactionDetails(tx)
+}
+
+export function isFinalizedTx(
+  tx: TransactionDetails | InterfaceTransactionDetails | FinalizedTransactionDetails,
+): tx is FinalizedTransactionDetails {
+  const validateFinalizedTx = (): FinalizedTransactionDetails | undefined => {
+    const { status, hash } = tx
+    if (isPlanTransactionDetails(tx)) {
+      if (isFinalizedTxStatus(status)) {
+        return { ...tx, status }
+      }
+      return undefined
+    }
+    if (status === TransactionStatus.Success) {
+      if (!hash) {
+        return undefined
+      }
+      return { ...tx, status, hash }
+    } else if (isFinalizedTxStatus(status)) {
+      return { ...tx, status }
+    }
+    return undefined
+  }
+
+  // Validation fn prevents & future-proofs the typeguard from illicit casting
+  return Boolean(validateFinalizedTx())
+}
+
+// Type guard that combines multiple checks for interface-specific fields
+export function isWalletTransaction(
+  transaction: TransactionDetails | InterfaceTransactionDetails,
+): transaction is TransactionDetails {
+  // Wallet transactions have these optional fields that interface transactions don't have.  We can't rely on this alone because it's possible none of these fields are present.
+  const hasWalletOptionalFields = 'cancelRequest' in transaction || 'networkFee' in transaction
+
+  if (hasWalletOptionalFields) {
+    return true
+  }
+
+  // Interface transactions have these optional fields that wallet transactions don't have:
+  const hasInterfaceOptionalFields =
+    'batchInfo' in transaction ||
+    'lastCheckedBlockNumber' in transaction ||
+    'deadline' in transaction ||
+    'cancelled' in transaction
+
+  return !hasInterfaceOptionalFields
+}
+
+// Function that returns the transaction typed as TransactionDetails when it's a wallet transaction
+export function getWalletTransaction(
+  transaction: TransactionDetails | InterfaceTransactionDetails,
+): TransactionDetails | undefined {
+  return isWalletTransaction(transaction) ? transaction : undefined
+}
+
+// Type guard that checks for interface-specific fields and ensures no wallet-specific fields are present
+export function isInterfaceTransaction(
+  transaction: TransactionDetails | InterfaceTransactionDetails,
+): transaction is InterfaceTransactionDetails {
+  // Interface transactions have these optional fields that wallet transactions don't have.  We can't rely on this alone because it's possible none of these fields are present.
+  const hasInterfaceOptionalFields =
+    'batchInfo' in transaction ||
+    'lastCheckedBlockNumber' in transaction ||
+    'deadline' in transaction ||
+    'cancelled' in transaction
+
+  if (hasInterfaceOptionalFields) {
+    return true
+  }
+
+  // Wallet transactions have these optional fields that interface transactions don't have:
+  // - receipt
+  // - cancelRequest
+  // - networkFee
+  const hasWalletOptionalFields = 'cancelRequest' in transaction || 'networkFee' in transaction
+
+  return !hasWalletOptionalFields
+}
+
+// Function that returns the transaction typed as InterfaceTransactionDetails when it's an interface transaction
+export function getInterfaceTransaction(
+  transaction: TransactionDetails | InterfaceTransactionDetails,
+): InterfaceTransactionDetails | undefined {
+  return isInterfaceTransaction(transaction) ? transaction : undefined
+}

package/src/features/transactions/types/wrap.ts

@@ -0,0 +1,5 @@
+export enum WrapType {
+  NotApplicable = 0,
+  Wrap = 1,
+  Unwrap = 2,
+}

package/src/features/transactions/utils/dex.utils.test.ts

@@ -0,0 +1,95 @@
+import { TradingApi } from '@luxfi/api'
+import { UniverseChainId } from '@luxexchange/lx/src/features/chains/types'
+import {
+  TransactionOriginType,
+  TransactionStatus,
+  TransactionType,
+  DEXOrderDetails,
+} from '@luxexchange/lx/src/features/transactions/types/transactionDetails'
+import {
+  convertOrderStatusToTransactionStatus,
+  convertOrderTypeToRouting,
+  isLimitOrder,
+} from '@luxexchange/lx/src/features/transactions/utils/dex.utils'
+
+describe('DEX Utils', () => {
+  describe('convertOrderTypeToRouting', () => {
+    it.each([
+      [TradingApi.OrderType.PRIORITY, TradingApi.Routing.PRIORITY],
+      [TradingApi.OrderType.DUTCH_V2, TradingApi.Routing.DUTCH_V2],
+      [TradingApi.OrderType.DUTCH_V3, TradingApi.Routing.DUTCH_V3],
+      [TradingApi.OrderType.DUTCH, TradingApi.Routing.DUTCH_LIMIT],
+      [TradingApi.OrderType.DUTCH_LIMIT, TradingApi.Routing.DUTCH_LIMIT],
+    ])('should convert %s to %s', (input, expected) => {
+      expect(convertOrderTypeToRouting(input)).toBe(expected)
+    })
+  })
+
+  describe('convertOrderTypeToRouting invalid input', () => {
+    it.each([['UNKNOWN' as TradingApi.OrderType, TradingApi.Routing.DUTCH_LIMIT]])(
+      'should convert %s to %s',
+      (input, expected) => {
+        expect(convertOrderTypeToRouting(input)).toBe(expected)
+      },
+    )
+  })
+
+  describe('convertOrderStatusToTransactionStatus', () => {
+    it.each([
+      [TradingApi.OrderStatus.FILLED, TransactionStatus.Success],
+      [TradingApi.OrderStatus.OPEN, TransactionStatus.Pending],
+      [TradingApi.OrderStatus.EXPIRED, TransactionStatus.Expired],
+      [TradingApi.OrderStatus.ERROR, TransactionStatus.Failed],
+      [TradingApi.OrderStatus.CANCELLED, TransactionStatus.Canceled],
+      [TradingApi.OrderStatus.INSUFFICIENT_FUNDS, TransactionStatus.InsufficientFunds],
+      [TradingApi.OrderStatus.UNVERIFIED, TransactionStatus.Unknown],
+    ])('should convert %s to %s', (input, expected) => {
+      expect(convertOrderStatusToTransactionStatus(input)).toBe(expected)
+    })
+  })
+
+  describe('convertOrderStatusToTransactionStatus invalid input', () => {
+    it.each([['UNKNOWN_STATUS' as TradingApi.OrderStatus, TransactionStatus.Unknown]])(
+      'should convert %s to %s',
+      (input, expected) => {
+        expect(convertOrderStatusToTransactionStatus(input)).toBe(expected)
+      },
+    )
+  })
+
+  describe('isLimitOrder', () => {
+    const mockLimitOrder: DEXOrderDetails = {
+      id: 'test-limit-order',
+      chainId: UniverseChainId.Mainnet,
+      routing: TradingApi.Routing.DUTCH_LIMIT,
+      orderHash: '0x123',
+      from: '0xabc',
+      status: TransactionStatus.Pending,
+      addedTime: Date.now(),
+      transactionOriginType: TransactionOriginType.External,
+      typeInfo: {
+        type: TransactionType.Swap,
+        inputCurrencyId: 'ETH',
+        outputCurrencyId: 'USDC',
+        inputCurrencyAmountRaw: '1000000000000000000',
+        expectedOutputCurrencyAmountRaw: '1000000',
+        minimumOutputCurrencyAmountRaw: '990000',
+        tradeType: 0,
+        isDEXOrder: true,
+      },
+    }
+
+    const mockRegularDEXOrder: DEXOrderDetails = {
+      ...mockLimitOrder,
+      routing: TradingApi.Routing.DUTCH_V2,
+    }
+
+    it('should return true for limit orders', () => {
+      expect(isLimitOrder(mockLimitOrder)).toBe(true)
+    })
+
+    it('should return false for regular DEX orders', () => {
+      expect(isLimitOrder(mockRegularDEXOrder)).toBe(false)
+    })
+  })
+})

package/src/features/transactions/utils/dex.utils.ts

@@ -0,0 +1,135 @@
+import { GraphQLApi, TradingApi } from '@luxfi/api'
+import { isDEX } from '@luxexchange/lx/src/features/transactions/swap/utils/routing'
+import {
+  TransactionDetails,
+  TransactionStatus,
+  DEXOrderDetails,
+} from '@luxexchange/lx/src/features/transactions/types/transactionDetails'
+
+/**
+ * Converts a trading API OrderType to internal Routing type.
+ * Used when creating transactions from external DEX orders.
+ */
+export function convertOrderTypeToRouting(
+  orderType: TradingApi.OrderType,
+):
+  | TradingApi.Routing.DUTCH_LIMIT
+  | TradingApi.Routing.DUTCH_V2
+  | TradingApi.Routing.DUTCH_V3
+  | TradingApi.Routing.PRIORITY {
+  switch (orderType) {
+    case TradingApi.OrderType.PRIORITY:
+      return TradingApi.Routing.PRIORITY
+    case TradingApi.OrderType.DUTCH_V2:
+      return TradingApi.Routing.DUTCH_V2
+    case TradingApi.OrderType.DUTCH_V3:
+      return TradingApi.Routing.DUTCH_V3
+    case TradingApi.OrderType.DUTCH:
+    case TradingApi.OrderType.DUTCH_LIMIT:
+    default:
+      return TradingApi.Routing.DUTCH_LIMIT
+  }
+}
+
+/**
+ * Converts a GraphQL GraphQLApi.SwapOrderType to internal Routing type.
+ * Used when creating transactions from external DEX orders.
+ */
+export function convertSwapOrderTypeToRouting(
+  orderType: GraphQLApi.SwapOrderType,
+): TradingApi.Routing.DUTCH_LIMIT | TradingApi.Routing.DUTCH_V2 | TradingApi.Routing.PRIORITY {
+  switch (orderType) {
+    case GraphQLApi.SwapOrderType.Priority:
+      return TradingApi.Routing.PRIORITY
+    case GraphQLApi.SwapOrderType.Dutch:
+    case GraphQLApi.SwapOrderType.DutchV2:
+      return TradingApi.Routing.DUTCH_V2
+    case GraphQLApi.SwapOrderType.Limit:
+      return TradingApi.Routing.DUTCH_LIMIT
+    default:
+      return TradingApi.Routing.DUTCH_V2
+  }
+}
+
+/**
+ * Converts a trading API OrderStatus to internal TransactionStatus.
+ * Used for syncing order status from backend to local transaction state.
+ */
+export function convertOrderStatusToTransactionStatus(status: TradingApi.OrderStatus): TransactionStatus {
+  switch (status) {
+    case TradingApi.OrderStatus.FILLED:
+      return TransactionStatus.Success
+    case TradingApi.OrderStatus.OPEN:
+      return TransactionStatus.Pending
+    case TradingApi.OrderStatus.EXPIRED:
+      return TransactionStatus.Expired
+    case TradingApi.OrderStatus.ERROR:
+      return TransactionStatus.Failed
+    case TradingApi.OrderStatus.CANCELLED:
+      return TransactionStatus.Canceled
+    case TradingApi.OrderStatus.INSUFFICIENT_FUNDS:
+      return TransactionStatus.InsufficientFunds
+    case TradingApi.OrderStatus.UNVERIFIED:
+    default:
+      return TransactionStatus.Unknown
+  }
+}
+
+/**
+ * Converts a GraphQL OrderStatus to internal TransactionStatus.
+ * Used for syncing order status from backend to local transaction state.
+ */
+export function remoteOrderStatusToLocalTxStatus(orderStatus: GraphQLApi.SwapOrderStatus): TransactionStatus {
+  switch (orderStatus) {
+    case GraphQLApi.SwapOrderStatus.Open:
+      return TransactionStatus.Pending
+    case GraphQLApi.SwapOrderStatus.Expired:
+      return TransactionStatus.Expired
+    case GraphQLApi.SwapOrderStatus.Error:
+      return TransactionStatus.Failed
+    case GraphQLApi.SwapOrderStatus.InsufficientFunds:
+      return TransactionStatus.InsufficientFunds
+    case GraphQLApi.SwapOrderStatus.Filled:
+      return TransactionStatus.Success
+    case GraphQLApi.SwapOrderStatus.Cancelled:
+      return TransactionStatus.Canceled
+    default:
+      return TransactionStatus.Unknown
+  }
+}
+
+/**
+ * Checks if a transaction is a limit order.
+ * Limit orders are DEX orders with DUTCH_LIMIT routing.
+ */
+export function isLimitOrder(tx: TransactionDetails): tx is DEXOrderDetails {
+  return isDEX(tx) && tx.routing === TradingApi.Routing.DUTCH_LIMIT
+}
+
+/**
+ * Type guard to check if a DEX order has the encoded order data needed for cancellation.
+ * Orders that have been filled won't have encodedOrder, and it's only present for orders
+ * that haven't been submitted yet or are still pending.
+ */
+export function hasEncodedOrder(order: DEXOrderDetails): order is DEXOrderDetails & { encodedOrder: string } {
+  return 'encodedOrder' in order && typeof order.encodedOrder === 'string'
+}
+
+/**
+ * Check if a limit order can be cancelled
+ */
+export function isLimitCancellable(order: DEXOrderDetails): boolean {
+  return order.status === TransactionStatus.Pending || order.status === TransactionStatus.InsufficientFunds
+}
+
+/**
+ * Checks if a DEX order is in a pending-like state.
+ * This includes orders that are actively pending, being cancelled, or have insufficient funds.
+ */
+export function isDEXOrderPending(order: DEXOrderDetails): boolean {
+  return (
+    order.status === TransactionStatus.Pending ||
+    order.status === TransactionStatus.Cancelling ||
+    order.status === TransactionStatus.InsufficientFunds
+  )
+}

package/src/features/transactions/utils/permit2.ts

@@ -0,0 +1,43 @@
+import { PERMIT2_ADDRESS, permit2Address } from '@luxdex/permit2-sdk'
+import { Contract, providers } from 'ethers/lib/ethers'
+import PERMIT2_ABI from '@luxexchange/lx/src/abis/permit2.json'
+import { Permit2 } from '@luxexchange/lx/src/abis/types'
+import { UniverseChainId } from '@luxexchange/lx/src/features/chains/types'
+
+/**
+ * Factory function to create a Permit2 contract instance
+ * Use this when you need a contract for read operations or transaction building
+ *
+ * @returns Permit2 contract instance without signer
+ */
+export function createPermit2Contract(): Permit2 {
+  // Permit2 has the same address on all chains
+  return new Contract(PERMIT2_ADDRESS, PERMIT2_ABI) as Permit2
+}
+
+interface CreatePermit2ContractOptions {
+  chainId: UniverseChainId
+  provider: providers.Web3Provider | providers.JsonRpcProvider
+  signerAddress: string
+}
+
+/**
+ * Creates a Permit2 contract instance for a specific chain with a signer
+ * Some legacy code uses chain-specific addresses
+ *
+ * @param options - Configuration object
+ * @param options.chainId - Chain ID
+ * @param options.provider - Provider with signer
+ * @param options.signerAddress - Specific signer address to use (prevents using wrong account)
+ * @returns Permit2 contract instance with signer
+ */
+export function createPermit2ContractForChain({
+  chainId,
+  provider,
+  signerAddress,
+}: CreatePermit2ContractOptions): Permit2 {
+  const address = permit2Address(chainId)
+  // Use the specific signer for the provided address
+  const signer = provider.getSigner(signerAddress)
+  return new Contract(address, PERMIT2_ABI, signer) as Permit2
+}

package/src/features/transactions/utils/receipt.test.ts

@@ -0,0 +1,64 @@
+import { BigNumber } from '@ethersproject/bignumber'
+import { providers } from 'ethers/lib/ethers'
+import { receiptFromEthersReceipt, receiptFromViemReceipt } from '@luxexchange/lx/src/features/transactions/utils/receipt'
+import { TransactionReceipt as ViemTransactionReceipt } from 'viem'
+
+describe('receipt conversion helpers', () => {
+  test('receiptFromEthersReceipt converts ethers receipt correctly', () => {
+    const ethersReceipt: providers.TransactionReceipt = {
+      to: '0x0',
+      from: '0x0',
+      contractAddress: '',
+      transactionIndex: 1,
+      gasUsed: BigNumber.from(21_000),
+      logsBloom: '',
+      blockHash: '0xabc',
+      transactionHash: '0x123',
+      logs: [],
+      blockNumber: 100,
+      cumulativeGasUsed: BigNumber.from(21_000),
+      effectiveGasPrice: BigNumber.from(1_000_000_000),
+      byzantium: true,
+      type: 2,
+      status: 1,
+      confirmations: 5,
+    }
+
+    const adapted = receiptFromEthersReceipt(ethersReceipt)!
+
+    expect(adapted.blockHash).toBe('0xabc')
+    expect(adapted.blockNumber).toBe(100)
+    expect(adapted.transactionIndex).toBe(1)
+    expect(adapted.gasUsed).toBe(21_000)
+    expect(adapted.effectiveGasPrice).toBe(1_000_000_000)
+    expect(typeof adapted.confirmedTime).toBe('number')
+  })
+
+  test('receiptFromViemReceipt converts viem receipt correctly', () => {
+    const viemReceipt: ViemTransactionReceipt = {
+      blockHash: '0xdef',
+      blockNumber: BigInt(200),
+      contractAddress: null,
+      cumulativeGasUsed: BigInt(30_000),
+      effectiveGasPrice: BigInt(2_000_000_000),
+      from: '0x0',
+      gasUsed: BigInt(30_000),
+      logs: [],
+      logsBloom: '0x0',
+      status: 'success',
+      to: '0x0',
+      transactionHash: '0x456',
+      transactionIndex: 2,
+      type: 'eip1559',
+    }
+
+    const adapted = receiptFromViemReceipt(viemReceipt)!
+
+    expect(adapted.blockHash).toBe('0xdef')
+    expect(adapted.blockNumber).toBe(200)
+    expect(adapted.transactionIndex).toBe(2)
+    expect(adapted.gasUsed).toBe(30_000)
+    expect(adapted.effectiveGasPrice).toBe(2_000_000_000)
+    expect(typeof adapted.confirmedTime).toBe('number')
+  })
+})

package/src/features/transactions/utils/receipt.ts

@@ -0,0 +1,73 @@
+// New helper for adapting ethers or viem receipts to the shared TransactionReceipt type
+import { providers } from 'ethers/lib/ethers'
+import { TransactionReceipt as SharedTransactionReceipt } from '@luxexchange/lx/src/features/transactions/types/transactionDetails'
+import { TransactionReceipt as ViemTransactionReceipt } from 'viem'
+import { ZksyncTransactionReceipt } from 'viem/chains'
+
+type ViemTransactionReceiptOrZksyncReceipt = ViemTransactionReceipt | ZksyncTransactionReceipt
+
+// Helper to normalize bigint / BigNumber / number to a JS number
+const toNumber = (value: unknown): number => {
+  if (value == null) {
+    return 0
+  }
+  if (typeof value === 'bigint') {
+    return Number(value)
+  }
+  if (typeof value === 'number') {
+    return value
+  }
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  if (typeof value === 'object' && value !== null && 'toNumber' in (value as Record<string, unknown>)) {
+    try {
+      return (value as { toNumber: () => number }).toNumber()
+    } catch {
+      /* fall through */
+    }
+  }
+  return Number(value)
+}
+
+/**
+ * Adapt an ethers.js TransactionReceipt to the shared receipt shape.
+ */
+export function receiptFromEthersReceipt(
+  ethersReceipt: providers.TransactionReceipt | undefined,
+  confirmedTime?: number,
+): SharedTransactionReceipt | undefined {
+  if (!ethersReceipt) {
+    return undefined
+  }
+
+  return {
+    blockHash: ethersReceipt.blockHash,
+    blockNumber: toNumber(ethersReceipt.blockNumber),
+    transactionIndex: toNumber(ethersReceipt.transactionIndex),
+    confirmedTime: confirmedTime ?? Date.now(),
+    gasUsed: toNumber(ethersReceipt.gasUsed),
+    effectiveGasPrice: toNumber(ethersReceipt.effectiveGasPrice),
+  }
+}
+
+/**
+ * Adapt a viem‐style TransactionReceipt (returned by wagmi/publicClient) to the
+ * shared receipt shape.
+ * The viem receipt already uses plain numbers & bigint, so we just normalize.
+ */
+export function receiptFromViemReceipt(
+  viemReceipt: ViemTransactionReceiptOrZksyncReceipt | undefined,
+  confirmedTime?: number,
+): SharedTransactionReceipt | undefined {
+  if (!viemReceipt) {
+    return undefined
+  }
+
+  return {
+    blockHash: viemReceipt.blockHash,
+    blockNumber: toNumber(viemReceipt.blockNumber),
+    transactionIndex: toNumber(viemReceipt.transactionIndex),
+    confirmedTime: confirmedTime ?? Date.now(),
+    gasUsed: toNumber(viemReceipt.gasUsed),
+    effectiveGasPrice: toNumber(viemReceipt.effectiveGasPrice),
+  }
+}

package/src/features/trm/hooks.ts

@@ -0,0 +1,22 @@
+import { useTrmScreenQuery } from '@luxexchange/lx/src/data/apiClients/luxApi/useTrmScreenQuery'
+import { ONE_MINUTE_MS } from '@luxfi/utilities/src/time/time'
+
+export interface IsBlockedResult {
+  isBlockedLoading: boolean
+  isBlocked: boolean
+}
+
+/** Returns TRM status for an address that has been passed in. */
+export function useIsBlocked(address?: string, isViewOnly = false): IsBlockedResult {
+  const shouldSkip = !address || isViewOnly
+
+  const { data, isLoading } = useTrmScreenQuery({
+    params: shouldSkip ? undefined : { address },
+    staleTime: 5 * ONE_MINUTE_MS,
+  })
+
+  return {
+    isBlocked: data?.block || false,
+    isBlockedLoading: isLoading,
+  }
+}