> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/cowprotocol/cow-sdk/llms.txt
> Use this file to discover all available pages before exploring further.

# OrderSigningUtils

> EIP-712 order signing and cancellation utilities for CoW Protocol

## Overview

The `OrderSigningUtils` class provides cryptographic utilities for signing CoW Protocol orders and cancellations according to EIP-712 specifications. It supports multiple signing schemes including standard wallets and smart contract wallets.

## Installation

```bash theme={null}
npm install @cowprotocol/sdk-order-signing
# or
pnpm add @cowprotocol/sdk-order-signing
# or
yarn add @cowprotocol/sdk-order-signing
```

## Usage

All methods are static and can be called directly on the class.

```typescript theme={null}
import { OrderSigningUtils, SupportedChainId } from '@cowprotocol/sdk-order-signing'
import { EthersV6Adapter } from '@cowprotocol/sdk-ethers-v6-adapter'
import { JsonRpcProvider, Wallet } from 'ethers'
import { setGlobalAdapter } from '@cowprotocol/sdk-common'

const provider = new JsonRpcProvider('YOUR_RPC_URL')
const wallet = new Wallet('YOUR_PRIVATE_KEY', provider)
const adapter = new EthersV6Adapter({ provider, signer: wallet })

// Set global adapter for utilities to use
setGlobalAdapter(adapter)
```

## Methods

### signOrder

Sign an order intent using EIP-712.

```typescript theme={null}
static async signOrder(
  order: UnsignedOrder,
  chainId: SupportedChainId,
  signer: Signer
): Promise<SigningResult>
```

<ParamField path="order" type="UnsignedOrder" required>
  Unsigned order to sign

  <Expandable title="UnsignedOrder properties">
    <ParamField path="sellToken" type="string" required>
      Sell token address
    </ParamField>

    <ParamField path="buyToken" type="string" required>
      Buy token address
    </ParamField>

    <ParamField path="sellAmount" type="string" required>
      Sell amount in atoms
    </ParamField>

    <ParamField path="buyAmount" type="string" required>
      Buy amount in atoms
    </ParamField>

    <ParamField path="validTo" type="number" required>
      Order expiration timestamp (Unix seconds)
    </ParamField>

    <ParamField path="appData" type="string" required>
      App data hash (bytes32)
    </ParamField>

    <ParamField path="feeAmount" type="string" required>
      Fee amount
    </ParamField>

    <ParamField path="kind" type="'sell' | 'buy'" required>
      Order kind
    </ParamField>

    <ParamField path="partiallyFillable" type="boolean" required>
      Whether order can be partially filled
    </ParamField>

    <ParamField path="sellTokenBalance" type="string" default="erc20">
      Sell token balance source (erc20, external, internal)
    </ParamField>

    <ParamField path="buyTokenBalance" type="string" default="erc20">
      Buy token balance destination (erc20, internal)
    </ParamField>

    <ParamField path="receiver" type="string" required>
      Receiver address
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="chainId" type="SupportedChainId" required>
  Chain ID (e.g., 1 for Mainnet, 100 for Gnosis Chain)
</ParamField>

<ParamField path="signer" type="Signer" required>
  Wallet signer instance
</ParamField>

<ResponseField name="result" type="SigningResult">
  Signature and signing scheme

  <Expandable title="SigningResult properties">
    <ResponseField name="signature" type="string">
      Hex-encoded signature
    </ResponseField>

    <ResponseField name="signingScheme" type="'eip712' | 'ethsign'">
      Signing scheme used
    </ResponseField>
  </Expandable>
</ResponseField>

<Warning>
  Ensure the chainId is correct for your network. An incorrect chainId will result in an invalid signature.
</Warning>

#### Example

```typescript theme={null}
import { OrderSigningUtils } from '@cowprotocol/sdk-order-signing'

const orderToSign = {
  sellToken: '0xA0b86a33E6417b528874E10EB3a95beb4F25A0E3',
  buyToken: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2',
  sellAmount: '1000000000000000000',
  buyAmount: '1000000000000000000',
  validTo: Math.floor(Date.now() / 1000) + 3600, // 1 hour
  appData: '0x0000000000000000000000000000000000000000000000000000000000000000',
  feeAmount: '0',
  kind: 'sell',
  partiallyFillable: false,
  sellTokenBalance: 'erc20',
  buyTokenBalance: 'erc20',
  receiver: '0x0000000000000000000000000000000000000000',
}

const signingResult = await OrderSigningUtils.signOrder(
  orderToSign,
  1, // Mainnet
  adapter.signer
)

console.log('Signature:', signingResult.signature)
console.log('Scheme:', signingResult.signingScheme)
```

***

### signOrderCancellation

Sign a cancellation for a single order.

```typescript theme={null}
static async signOrderCancellation(
  orderUid: string,
  chainId: SupportedChainId,
  signer: Signer
): Promise<SigningResult>
```

<ParamField path="orderUid" type="string" required>
  Unique order identifier to cancel
</ParamField>

<ParamField path="chainId" type="SupportedChainId" required>
  Chain ID
</ParamField>

<ParamField path="signer" type="Signer" required>
  Signer who created the order
</ParamField>

<ResponseField name="result" type="SigningResult">
  Signature and signing scheme
</ResponseField>

#### Example

```typescript theme={null}
const orderId = '0xd64389693b6cf89ad6c140a113b10df08073e5ef...'

const cancellationResult = await OrderSigningUtils.signOrderCancellation(
  orderId,
  1,
  adapter.signer
)

console.log('Cancellation signature:', cancellationResult.signature)
```

***

### signOrderCancellations

Sign a cancellation for multiple orders in a single signature.

```typescript theme={null}
static async signOrderCancellations(
  orderUids: string[],
  chainId: SupportedChainId,
  signer: Signer
): Promise<SigningResult>
```

<ParamField path="orderUids" type="string[]" required>
  Array of order UIDs to cancel
</ParamField>

<ParamField path="chainId" type="SupportedChainId" required>
  Chain ID
</ParamField>

<ParamField path="signer" type="Signer" required>
  Signer who created the orders
</ParamField>

<ResponseField name="result" type="SigningResult">
  Signature and signing scheme
</ResponseField>

<Note>
  More gas-efficient than signing cancellations individually when cancelling multiple orders.
</Note>

#### Example

```typescript theme={null}
const orderIds = [
  '0xd64389693b6cf89ad6c140a113b10df08073e5ef...',
  '0xa12345678b6cf89ad6c140a113b10df08073e5ef...',
]

const cancellationResult = await OrderSigningUtils.signOrderCancellations(
  orderIds,
  1,
  adapter.signer
)

// Use with OrderBookApi
await orderBookApi.sendSignedOrderCancellations({
  ...cancellationResult,
  orderUids: orderIds,
})
```

***

### getDomain

Get EIP-712 typed domain data for a chain.

```typescript theme={null}
static async getDomain(
  chainId: SupportedChainId
): Promise<TypedDataDomain>
```

<ParamField path="chainId" type="SupportedChainId" required>
  Chain ID
</ParamField>

<ResponseField name="domain" type="TypedDataDomain">
  EIP-712 domain data

  <Expandable title="TypedDataDomain properties">
    <ResponseField name="name" type="string">
      Domain name ("Gnosis Protocol")
    </ResponseField>

    <ResponseField name="version" type="string">
      Protocol version
    </ResponseField>

    <ResponseField name="chainId" type="number">
      Chain ID
    </ResponseField>

    <ResponseField name="verifyingContract" type="string">
      Settlement contract address
    </ResponseField>
  </Expandable>
</ResponseField>

#### Example

```typescript theme={null}
const domain = await OrderSigningUtils.getDomain(1)

console.log('Domain:', domain)
// {
//   name: 'Gnosis Protocol',
//   version: 'v2',
//   chainId: 1,
//   verifyingContract: '0x9008D19f58AAbD9eD0D60971565AA8510560ab41'
// }
```

***

### getDomainSeparator

Get the domain separator hash.

```typescript theme={null}
static async getDomainSeparator(
  chainId: SupportedChainId
): Promise<string>
```

<ParamField path="chainId" type="SupportedChainId" required>
  Chain ID
</ParamField>

<ResponseField name="domainSeparator" type="string">
  Hex-encoded domain separator hash
</ResponseField>

#### Example

```typescript theme={null}
const separator = await OrderSigningUtils.getDomainSeparator(1)
console.log('Domain separator:', separator)
```

***

### generateOrderId

Generate deterministic order ID from order data.

```typescript theme={null}
static async generateOrderId(
  chainId: SupportedChainId,
  order: Order,
  params: { owner: string }
): Promise<{ orderId: string; orderDigest: string }>
```

<ParamField path="chainId" type="SupportedChainId" required>
  Chain ID
</ParamField>

<ParamField path="order" type="Order" required>
  Order data
</ParamField>

<ParamField path="params" type="{ owner: string }" required>
  Order parameters with owner address
</ParamField>

<ResponseField name="result" type="object">
  Order ID and digest

  <Expandable title="Result properties">
    <ResponseField name="orderId" type="string">
      Unique order identifier (UID)
    </ResponseField>

    <ResponseField name="orderDigest" type="string">
      Order digest hash
    </ResponseField>
  </Expandable>
</ResponseField>

#### Example

```typescript theme={null}
const { orderId, orderDigest } = await OrderSigningUtils.generateOrderId(
  1,
  orderData,
  { owner: '0x123...' }
)

console.log('Order ID:', orderId)
console.log('Order digest:', orderDigest)
```

***

### getEIP712Types

Get the EIP-712 type definitions for CoW Protocol orders.

```typescript theme={null}
static getEIP712Types(): typeof COW_EIP712_TYPES
```

<ResponseField name="types" type="object">
  EIP-712 type definitions
</ResponseField>

#### Example

```typescript theme={null}
const types = OrderSigningUtils.getEIP712Types()
console.log('Order types:', types)
// {
//   Order: [
//     { name: 'sellToken', type: 'address' },
//     { name: 'buyToken', type: 'address' },
//     ...
//   ]
// }
```

***

### getEip1271Signature

Encode order and ECDSA signature for EIP-1271 verification.

```typescript theme={null}
static getEip1271Signature(
  orderToSign: UnsignedOrder,
  ecdsaSignature: string
): string
```

<ParamField path="orderToSign" type="UnsignedOrder" required>
  Order to encode
</ParamField>

<ParamField path="ecdsaSignature" type="string" required>
  ECDSA signature (65 bytes)
</ParamField>

<ResponseField name="signature" type="string">
  ABI-encoded signature for EIP-1271
</ResponseField>

<Info>
  Useful for smart contract wallets that implement EIP-1271 signature verification.
</Info>

#### Example

```typescript theme={null}
const ecdsaSignature = '0x...' // 65 bytes from signing

const eip1271Signature = OrderSigningUtils.getEip1271Signature(
  orderToSign,
  ecdsaSignature
)

// Use with smart contract wallet
```

***

### encodeUnsignedOrder

Encode unsigned order for hashing.

```typescript theme={null}
static encodeUnsignedOrder(
  orderToSign: UnsignedOrder
): Record<string, string>
```

<ParamField path="orderToSign" type="UnsignedOrder" required>
  Order to encode
</ParamField>

<ResponseField name="encoded" type="Record<string, string>">
  Encoded order fields
</ResponseField>

#### Example

```typescript theme={null}
const encoded = OrderSigningUtils.encodeUnsignedOrder(orderToSign)
console.log('Encoded order:', encoded)
```

## Signing Schemes

CoW Protocol supports multiple signing schemes:

### EIP-712 (Default)

Standard wallet signature using typed structured data.

```typescript theme={null}
const result = await OrderSigningUtils.signOrder(order, chainId, signer)
// result.signingScheme === 'eip712'
```

### EthSign (EIP-191)

Legacy signing method using `eth_sign`.

```typescript theme={null}
// Automatically used as fallback if EIP-712 is not supported
```

### Pre-sign

For smart contract wallets that cannot sign directly.

```typescript theme={null}
import { SigningScheme } from '@cowprotocol/sdk-order-book'

// Order is created with PRESIGN scheme
// Then execute pre-sign transaction on-chain
// See TradingSdk.getPreSignTransaction()
```

### EIP-1271

For contracts implementing EIP-1271 signature verification.

```typescript theme={null}
const ecdsaSignature = await signer.signMessage(orderHash)
const eip1271Signature = OrderSigningUtils.getEip1271Signature(
  order,
  ecdsaSignature
)
```

## Integration Examples

### With OrderBookApi

```typescript theme={null}
import { OrderBookApi } from '@cowprotocol/sdk-order-book'
import { OrderSigningUtils } from '@cowprotocol/sdk-order-signing'

const orderBookApi = new OrderBookApi({ chainId: 1 })

// 1. Get quote
const { quote } = await orderBookApi.getQuote(quoteRequest)

// 2. Sign order
const signingResult = await OrderSigningUtils.signOrder(
  quote,
  1,
  signer
)

// 3. Submit order
const orderId = await orderBookApi.sendOrder({
  ...quote,
  ...signingResult,
})

console.log('Order submitted:', orderId)
```

### With TradingSdk

```typescript theme={null}
import { TradingSdk } from '@cowprotocol/sdk-trading'

// TradingSdk handles signing internally
const sdk = new TradingSdk(
  { chainId: 1, appCode: 'My App' },
  {},
  adapter
)

const { orderId } = await sdk.postSwapOrder(params)
// Signing happens automatically
```

### Cancelling Orders

```typescript theme={null}
// Sign cancellation
const cancellation = await OrderSigningUtils.signOrderCancellations(
  [orderId1, orderId2],
  1,
  signer
)

// Submit to API
await orderBookApi.sendSignedOrderCancellations({
  ...cancellation,
  orderUids: [orderId1, orderId2],
})
```

## Error Handling

```typescript theme={null}
try {
  const result = await OrderSigningUtils.signOrder(order, chainId, signer)
  console.log('Signature:', result.signature)
} catch (error) {
  if (error.message.includes('User denied')) {
    console.error('User rejected signature request')
  } else if (error.message.includes('chainId')) {
    console.error('Chain ID mismatch')
  } else {
    console.error('Signing failed:', error)
  }
}
```

## Best Practices

1. **Always verify chain ID** - Incorrect chain ID results in invalid signatures
2. **Set global adapter** - Required for utilities to function properly
3. **Use typed data (EIP-712)** - More secure than eth\_sign
4. **Batch cancellations** - Use `signOrderCancellations` for multiple orders
5. **Handle rejections** - Users can deny signature requests

## See Also

* [TradingSdk](/api/trading-sdk) - High-level trading interface
* [OrderBookApi](/api/order-book-api) - Order book API client
* [MetadataApi](/api/metadata-api) - Order metadata management
* [EIP-712 Specification](https://eips.ethereum.org/EIPS/eip-712)
* [EIP-1271 Specification](https://eips.ethereum.org/EIPS/eip-1271)