@cowprotocol/sdk-contracts-ts

Contract interaction utilities and settlement encoding

The @cowprotocol/sdk-contracts-ts package provides TypeScript utilities for interacting with CoW Protocol smart contracts, encoding settlements, and managing orders.

Installation

npm install @cowprotocol/sdk-contracts-ts

Order Types

Order

Gnosis Protocol v2 order data structure.

interface Order {
  sellToken: string
  buyToken: string
  receiver?: string
  sellAmount: BigIntish
  buyAmount: BigIntish
  validTo: Timestamp
  appData: HashLike
  feeAmount: BigIntish
  kind: OrderKind
  partiallyFillable: boolean
  sellTokenBalance?: OrderBalance
  buyTokenBalance?: OrderBalance
}

OrderKind

enum OrderKind {
  SELL = 'sell',
  BUY = 'buy'
}

OrderBalance

Specifies how token balances are managed.

enum OrderBalance {
  ERC20 = 'erc20',
  EXTERNAL = 'external', // Balancer Vault external balances
  INTERNAL = 'internal'  // Balancer Vault internal balances
}

Example:

import { Order, OrderKind, OrderBalance } from '@cowprotocol/sdk-contracts-ts'

const order: Order = {
  sellToken: '0x...', // USDC
  buyToken: '0x...',  // DAI
  sellAmount: 1000000n, // 1 USDC (6 decimals)
  buyAmount: 990000000000000000n, // 0.99 DAI (18 decimals)
  validTo: Math.floor(Date.now() / 1000) + 3600, // 1 hour from now
  appData: '0x0000000000000000000000000000000000000000000000000000000000000000',
  feeAmount: 0n,
  kind: OrderKind.SELL,
  partiallyFillable: false
}

Signing Schemes

SigningScheme

enum SigningScheme {
  EIP712 = 0b00,   // EIP-712 typed data signing (preferred)
  ETHSIGN = 0b01,  // eth_sign RPC call
  EIP1271 = 0b10,  // Smart contract signatures (EIP-1271)
  PRESIGN = 0b11   // Pre-signed orders
}

Signature Types

type EcdsaSigningScheme = SigningScheme.EIP712 | SigningScheme.ETHSIGN

interface EcdsaSignature {
  scheme: EcdsaSigningScheme
  data: SignatureLike
}

type Signature = EcdsaSignature | Eip1271Signature | PreSignSignature

Order Utilities

hashOrder

Computes the 32-byte signing hash for an order.

function hashOrder(domain: TypedDataDomain, order: Order): string

Parameters:

• domain - EIP-712 domain separator
• order - Order to hash

Returns: Hex-encoded 32-byte order digest

computeOrderUid

Computes the unique order identifier.

function computeOrderUid(
  domain: TypedDataDomain,
  order: Order,
  owner: string
): string

Returns: 56-byte order UID

Example:

import { computeOrderUid } from '@cowprotocol/sdk-contracts-ts'

const domain = {
  name: 'Gnosis Protocol',
  version: 'v2',
  chainId: 1,
  verifyingContract: '0x9008D19f58AAbD9eD0D60971565AA8510560ab41'
}

const orderUid = computeOrderUid(domain, order, '0x...')

extractOrderUidParams

Extracts parameters from an order UID.

function extractOrderUidParams(orderUid: string): OrderUidParams

interface OrderUidParams {
  orderDigest: string
  owner: string
  validTo: number
}

normalizeOrder

Normalizes an order for EIP-712 signing.

function normalizeOrder(order: Order): NormalizedOrder

Settlement Encoding

SettlementEncoder

Encoder for CoW Protocol settlement transactions.

class SettlementEncoder {
  constructor(
    public readonly domain: TypedDataDomain,
    adapter?: AbstractProviderAdapter
  )

  get tokens(): string[]
  get trades(): Trade[]
  get interactions(): [Interaction[], Interaction[], Interaction[]]

  encodeTrade(
    order: Order,
    signature: Signature,
    tradeExecution?: Partial<TradeExecution>
  ): void

  async signEncodeTrade(
    order: Order,
    scheme: EcdsaSigningScheme,
    tradeExecution?: Partial<TradeExecution>,
    owner?: SignerLike
  ): Promise<void>

  encodeInteraction(
    interaction: InteractionLike,
    stage?: InteractionStage
  ): void

  clearingPrices(prices: Prices): BigIntish[]

  encodedSettlement(prices: Prices): EncodedSettlement

  static encodedSetup(
    ...interactions: InteractionLike[]
  ): EncodedSettlement
}

Example:

import {
  SettlementEncoder,
  SigningScheme,
  InteractionStage
} from '@cowprotocol/sdk-contracts-ts'

const encoder = new SettlementEncoder(domain)

// Add a trade
await encoder.signEncodeTrade(
  order,
  SigningScheme.EIP712,
  { executedAmount: order.sellAmount }
)

// Add a pre-interaction (e.g., approve)
encoder.encodeInteraction(
  {
    target: '0x...',
    callData: '0x...'
  },
  InteractionStage.PRE
)

// Get encoded settlement
const prices = {
  '0x...': 1000000n, // USDC price
  '0x...': 1000000000000000000n // DAI price
}
const settlement = encoder.encodedSettlement(prices)

InteractionStage

enum InteractionStage {
  PRE = 0,   // Before trading (e.g., approvals, permits)
  INTRA = 1, // During trading (e.g., AMM interactions)
  POST = 2   // After trading
}

TokenRegistry

Tracks tokens for settlement encoding.

class TokenRegistry {
  constructor(adapter?: AbstractProviderAdapter)

  get addresses(): string[]

  index(token: string): number
}

Trade Encoding

Trade

type Trade = TradeExecution & Omit<
  NormalizedOrder,
  'sellToken' | 'buyToken' | 'kind' | 'partiallyFillable' |
  'sellTokenBalance' | 'buyTokenBalance'
> & {
  sellTokenIndex: BigIntish
  buyTokenIndex: BigIntish
  flags: BigIntish
  signature: Bytes
}

interface TradeExecution {
  executedAmount: BigIntish
}

encodeTradeFlags

Encodes trade flags as a bitfield.

function encodeTradeFlags(flags: TradeFlags): number

interface TradeFlags extends OrderFlags {
  signingScheme: SigningScheme
}

decodeTradeFlags

Decodes trade flags from a bitfield.

function decodeTradeFlags(flags: BigIntish): TradeFlags

decodeOrder

Decodes an order from a settlement trade.

function decodeOrder(trade: Trade, tokens: string[]): Order

Order Cancellations

OrderCancellations

interface OrderCancellations {
  orderUids: Bytes[]
}

hashOrderCancellation

Computes the hash for a single order cancellation.

function hashOrderCancellation(
  domain: TypedDataDomain,
  orderUid: Bytes
): string

hashOrderCancellations

Computes the hash for multiple order cancellations.

function hashOrderCancellations(
  domain: TypedDataDomain,
  orderUids: Bytes[]
): string

Settlement Types

EncodedSettlement

type EncodedSettlement = [
  tokens: string[],
  clearingPrices: BigIntish[],
  trades: Trade[],
  interactions: [Interaction[], Interaction[], Interaction[]]
]

Prices

type Prices = Record<string, BigIntish | undefined>

Example:

const prices: Prices = {
  '0x...USDC': 1000000n,
  '0x...DAI': 1000000000000000000n
}

Interaction

interface Interaction {
  target: string
  callData: string
}

Constants

// Special marker address for buying ETH
const BUY_ETH_ADDRESS = '0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE'

// Order UID byte length
const ORDER_UID_LENGTH = 56

// EIP-712 type fields for orders
const ORDER_TYPE_FIELDS = [
  { name: 'sellToken', type: 'address' },
  { name: 'buyToken', type: 'address' },
  { name: 'receiver', type: 'address' },
  { name: 'sellAmount', type: 'uint256' },
  { name: 'buyAmount', type: 'uint256' },
  { name: 'validTo', type: 'uint32' },
  { name: 'appData', type: 'bytes32' },
  { name: 'feeAmount', type: 'uint256' },
  { name: 'kind', type: 'string' },
  { name: 'partiallyFillable', type: 'bool' },
  { name: 'sellTokenBalance', type: 'string' },
  { name: 'buyTokenBalance', type: 'string' }
]

// EIP-712 type hash
const ORDER_TYPE_HASH = '0xd5a25ba2e97094ad7d83dc28a6572da797d6b3e7fc6663bd93efb789fc17e489'

Package Version

import { CONTRACTS_PKG_VERSION } from '@cowprotocol/sdk-contracts-ts'

console.log(CONTRACTS_PKG_VERSION)