chore: add more description to trading types

src/trading/getEthFlowTransaction.ts

@@ -50,13 +50,13 @@ export async function getEthFlowTransaction(
       return GAS_LIMIT_DEFAULT
     })
 
-  const callData = contract.interface.encodeFunctionData('createOrder', [ethOrderParams])
+  const data = contract.interface.encodeFunctionData('createOrder', [ethOrderParams])
 
   return {
     orderId,
     transaction: {
-      callData,
-      gasLimit: '0x' + calculateGasMargin(estimatedGas).toString(16),
+      data,
+      gas: '0x' + calculateGasMargin(estimatedGas).toString(16),
       to: contract.address,
       value: '0x' + BigInt(orderToSign.sellAmount).toString(16),
     },

src/trading/getPreSignTransaction.ts

@@ -27,8 +27,8 @@ export async function getPreSignTransaction(
     })
 
   return {
-    callData: preSignatureCall,
-    gasLimit: '0x' + calculateGasMargin(gas).toString(16),
+    data: preSignatureCall,
+    gas: '0x' + calculateGasMargin(gas).toString(16),
     to: settlementContractAddress,
     value: '0',
   }

src/trading/types.ts

@@ -1,5 +1,14 @@
 import type { AppDataParams, latest, LatestAppDataDocVersion } from '@cowprotocol/app-data'
-import type { Address, OrderKind, OrderQuoteRequest, OrderQuoteResponse, QuoteAmountsAndCosts } from '../order-book'
+import {
+  AppData,
+  AppDataHash,
+  OrderKind,
+  OrderParameters,
+  OrderQuoteRequest,
+  OrderQuoteResponse,
+  QuoteAmountsAndCosts,
+  TokenAmount,
+} from '../order-book'
 import type { Signer } from '@ethersproject/abstract-signer'
 import type { CowEnv, SupportedChainId } from '../common'
 import type { ExternalProvider } from '@ethersproject/providers'
@@ -10,60 +19,84 @@ export type AccountAddress = `0x${string}` // 42 characters
 
 export const ORDER_PRIMARY_TYPE = 'Order' as const
 
+/**
+ * EIP-712 typed data domain.
+ */
 interface TypedDataDomain {
   name: string
   version: string
   chainId: number
   verifyingContract: string
 }
 
+/**
+ * EIP-712 typed data field.
+ */
 interface TypedDataField {
   name: string
   type: string
 }
 
+/**
+ * EIP-712 typed data for an order.
+ */
 export interface OrderTypedData {
   domain: TypedDataDomain
   primaryType: typeof ORDER_PRIMARY_TYPE
   types: Record<string, TypedDataField[]>
   message: UnsignedOrder
 }
 
+/**
+ * Minimal set of parameters to create a trade.
+ */
 export interface TradeBaseParameters {
   kind: OrderKind
-  sellToken: Address
+  sellToken: OrderParameters['sellToken']
   sellTokenDecimals: number
-  buyToken: Address
+  buyToken: OrderParameters['buyToken']
   buyTokenDecimals: number
-  amount: string
+  amount: TokenAmount
 }
 
+/**
+ * Optional parameters to create a trade.
+ */
 export interface TradeOptionalParameters {
   env?: CowEnv
-  partiallyFillable?: boolean
-  slippageBps?: number
-  receiver?: string
-  validFor?: number
+  partiallyFillable?: OrderParameters['partiallyFillable']
+  slippageBps?: latest.SlippageBips
+  receiver?: OrderParameters['receiver']
+  validFor?: OrderParameters['validTo']
   partnerFee?: latest.PartnerFee
 }
 
+/**
+ * Information about the trader.
+ */
 export interface TraderParameters {
   chainId: SupportedChainId
-  appCode: string
+  appCode: latest.AppCode
   signer: Signer | ExternalProvider | PrivateKey
 }
 
 export type QuoterParameters = Omit<TraderParameters, 'signer'> & { account: AccountAddress }
 
+/**
+ * Trade type, assets, amounts, and optional parameters.
+ */
 export interface TradeParameters extends TradeBaseParameters, TradeOptionalParameters {}
 
 export interface SwapParameters extends TradeParameters, TraderParameters {}
 
 export interface LimitTradeParameters extends Omit<TradeParameters, 'amount'> {
-  sellAmount: string
-  buyAmount: string
+  sellAmount: OrderParameters['sellAmount']
+  buyAmount: OrderParameters['buyAmount']
+  /**
+   * Id of the quote to be used for the limit order.
+   */
   quoteId: number
-  validTo?: number
+  validTo?: OrderParameters['validTo']
 }
 
 export interface LimitOrderParameters extends TraderParameters, LimitTradeParameters {}
@@ -77,6 +110,10 @@ export interface LimitOrderAdvancedSettings {
   appData?: AppDataParams
 }
 
+/**
+ * Exhaustive set of data which includes information about trade, quote, order, "app-data", and more.
+ * This data is used to create a trade, sign an order, and post it to the order book.
+ */
 export interface QuoteResults {
   tradeParameters: TradeParameters
   amountsAndCosts: QuoteAmountsAndCosts
@@ -92,29 +129,33 @@ export interface QuoteResultsSerialized extends Omit<QuoteResults, 'amountsAndCo
 
 export interface QuoteAndPost {
   quoteResults: QuoteResults
+
   postSwapOrderFromQuote(): Promise<string>
 }
 
-export type AppDataOrderClass = latest.OrderClass['orderClass']
-
 export type AppDataRootSchema = latest.AppDataRootSchema
 
 export interface BuildAppDataParams {
-  appCode: string
-  slippageBps: number
-  orderClass: AppDataOrderClass
+  appCode: latest.AppCode
+  slippageBps: latest.SlippageBips
+  orderClass: latest.OrderClass['orderClass']
 }
 
+/**
+ * https://github.com/cowprotocol/app-data
+ */
 export interface AppDataInfo {
   doc: LatestAppDataDocVersion
-  fullAppData: string
-  appDataKeccak256: string
-  env?: CowEnv
+  fullAppData: AppData
+  appDataKeccak256: AppDataHash
 }
 
+/**
+ * A standard Ethereum transaction object
+ */
 export interface TransactionParams {
-  callData: string
-  gasLimit: string
+  data: string
+  gas: string
   to: string
   value: string
 }