Signature Construction

ComposableCoW orders use EIP-1271 (smart contract) signatures rather than EOA signatures. This guide explains how to construct the signature bytes that the settlement contract needs to verify your programmatic order.

This guide assumes you have already set up your Safe with the ExtensibleFallbackHandler and ComposableCoW as domain verifier, and created a programmatic order via create() or createWithContext().

How signature verification works

When the CoW Protocol settlement contract executes a trade for a ComposableCoW order, the following verification chain runs:

GPv2Settlement
  │
  ├─ calls isValidSignature(orderDigest, signature) on the Safe
  │
  ▼
Safe (owner)
  │
  ├─ delegates to ExtensibleFallbackHandler (fallback handler)
  │
  ▼
ExtensibleFallbackHandler
  │
  ├─ extracts the domain separator from the signature
  ├─ routes to the registered domain verifier (ComposableCoW)
  │
  ▼
ComposableCoW
  │
  ├─ decodes ConditionalOrderParams and offchainInput from signature
  ├─ verifies the order was authorized (via create() or merkle proof)
  ├─ calls getTradeableOrderWithSignature() on the handler
  ├─ compares the resulting order's digest to the provided orderDigest
  └─ returns EIP-1271 magic value (0x1626ba7e) if valid

The signature you construct is what gets passed through this entire chain. ComposableCoW decodes it to recover the ConditionalOrderParams and any offchain input, then uses these to regenerate the expected order and verify it matches.

Signature encoding

The signature for a ComposableCoW order is an ABI-encoded byte string containing two values:

Component	Type	Description
`params`	`ConditionalOrderParams`	The handler address, salt, and staticInput used when creating the order
`offchainInput`	`bytes`	Any additional off-chain data the handler needs (empty bytes if none)

The ConditionalOrderParams struct consists of:

Field	Type	Description
`handler`	`address`	The programmatic order handler contract (e.g., TWAP at `0x6cF1e9cA41f7611dEf408122793c358a3d11E5a5`)
`salt`	`bytes32`	Unique identifier for this order
`staticInput`	`bytes`	ABI-encoded parameters specific to the handler

The encoding format is:

abi.encode(ConditionalOrderParams params, bytes offchainInput)

Step-by-step construction

Full example

Putting it all together, here is a complete example of constructing and submitting a ComposableCoW order signature:

import { AbiCoder } from 'ethers';

// The Safe address that owns the programmatic order
const safeAddress = '0xYourSafeAddress';

// Must match exactly what was passed to ComposableCoW.create()
const params = {
  handler: '0x6cF1e9cA41f7611dEf408122793c358a3d11E5a5',
  salt: '0xabc123...', // your unique salt
  staticInput: '0xdef456...' // your encoded handler params
};

const offchainInput = '0x';

// Step 1: Encode the signature
const encoder = new AbiCoder();
const signature = encoder.encode(
  ['tuple(address handler, bytes32 salt, bytes staticInput)', 'bytes'],
  [params, offchainInput]
);

// Step 2: Submit to the CoW Protocol API
const orderPayload = {
  // ... your order fields (sellToken, buyToken, etc.)
  from: safeAddress,
  signingScheme: 'eip1271',
  signature: signature,
};

const response = await fetch(
  'https://api.cow.fi/mainnet/api/v1/orders',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(orderPayload),
  }
);

Common pitfalls

Pitfall	Symptom	Fix
Wrong `signingScheme`	API rejects the order or signature verification fails	Set `signingScheme` to `eip1271`, not `eip712` or `ethsign`
Wrong `from` address	`isValidSignature` is called on the wrong contract	Use the Safe address, not an EOA signer address
Mismatched `ConditionalOrderParams`	ComposableCoW cannot find the order in `singleOrders` mapping	Ensure `handler`, `salt`, and `staticInput` exactly match what was passed to `create()`
Handler returns unexpected order	Order digest mismatch during verification	Verify the handler’s `getTradeableOrder()` output matches the order you are submitting
Missing offchain input	Handler reverts when generating the tradeable order	Provide the offchain data your handler expects, or empty bytes if none
Safe not configured	`isValidSignature` reverts or returns wrong value	Ensure ExtensibleFallbackHandler is set and ComposableCoW is registered as domain verifier (Setup guide)

Verifying locally

Before submitting to the API, you can verify your signature will pass validation by calling the isValidSignature function directly on the Safe:

import { Contract, AbiCoder } from 'ethers';

// Compute the order digest using @cowprotocol/contracts
import { domain, hashOrder } from '@cowprotocol/contracts';

const orderDigest = hashOrder(
  domain(1, '0x9008D19f58AAbD9eD0D60971565AA8510560ab41'),
  order
);

// Call isValidSignature on the Safe
const safe = new Contract(safeAddress, [
  'function isValidSignature(bytes32, bytes) view returns (bytes4)'
], provider);

const MAGIC_VALUE = '0x1626ba7e';

try {
  const result = await safe.isValidSignature(orderDigest, signature);
  if (result === MAGIC_VALUE) {
    console.log('Signature is valid');
  } else {
    console.log('Signature is invalid, returned:', result);
  }
} catch (error) {
  console.error('Verification reverted:', error.message);
}

This call simulates the exact check the settlement contract performs during order execution. If it returns the magic value (0x1626ba7e), your signature will be accepted.

Next steps

Creating orders — learn how to create the programmatic order on-chain
Managing orders — revoke or update existing orders
Signing schemes — understand all CoW Protocol signing methods
Troubleshooting — debug common issues

Contracts

Hooks Trampoline

Composable CoW

Contracts SDK

Flash Loan Router

Signature Construction

Signature Construction

How signature verification works

Signature encoding

Step-by-step construction

Full example

Common pitfalls

Verifying locally

Next steps

​Signature Construction

​How signature verification works

​Signature encoding

​Step-by-step construction

​Full example

​Common pitfalls

​Verifying locally

​Next steps

Signature Construction

How signature verification works

Signature encoding

Step-by-step construction

Full example

Common pitfalls

Verifying locally

Next steps