docs

# CoW Protocol Order Debug Skill

Debug why CoW Protocol orders fail to match. Requires DB access + Victoria Logs access (via CoW-Prod MCP).

## Quick Checklist

Run through these in order:

1. [ ] **Order status** — Check API status first (cancelled/expired/fulfilled/open)
2. [ ] **User cancellation** — If cancelled, search logs for `"order cancelled" AND all:ORDER_UID` FIRST
3. [ ] **Order in auction** — Was order in autopilot auction? When?
4. [ ] **Solver bids** — Did any solver bid? What happened to their solution?
5. [ ] **Settlement outcome** — Did settlement succeed/fail/timeout?
6. [ ] **Limit price sanity** — Was quote reasonable? Check slippage, fees, gas
7. [ ] **Price movement** — Did price move between quote and expiry?

---

## 1. Fetch Order Data

```bash
# Replace $NETWORK (mainnet/gnosis/arbitrum) and $ORDER_UID
curl -s "https://api.cow.fi/$NETWORK/api/v1/orders/$ORDER_UID" | jq .

# For staging orders:
curl -s "https://barn.api.cow.fi/$NETWORK/api/v1/orders/$ORDER_UID" | jq .
```

### GPV2Order Struct (Smart Contract Source of Truth)

| Field | Meaning | Debug Notes |
|-------|---------|-------------|
| `sellToken` | Token being sold | |
| `buyToken` | Token being bought | |
| `sellAmount` | Amount to sell (wei) | For sell orders, this is exact |
| `buyAmount` | Min amount to receive | For buy orders, this is exact |
| `validTo` | Unix timestamp expiry | Check if expired |
| `appData` | Hash of metadata JSON | Contains hooks, partner fees, flash loan hints |
| `feeAmount` | **Legacy, always 0** | Fee now in limit price |
| `kind` | "sell" or "buy" | |
| `partiallyFillable` | bool | Swaps = false (fill-or-kill), limits can be true |
| `sellTokenBalance` | **Legacy, always "erc20"** | Balancer vault balances never took off |
| `buyTokenBalance` | **Legacy, always "erc20"** | |
| `signingScheme` | eip712/ethsign/presign/eip1271 | See signing section |
| `signature` | The actual signature bytes | |
| `receiver` | Who gets buy tokens | null = order owner |

**Additional API fields:**
- `class`: "market" vs "limit" — see note below
- `status`: fulfilled/open/cancelled/expired
- `surplusFee`: Protocol's fee estimate for limit orders
- `surplusFeeTimestamp`: Must be <10 min old or order won't enter auction

**Note on order class:** In the DB, almost every order is stored as `class = 'limit'`. The "market" vs "limit" distinction is about **fee policy**, not order type:
- **Market order**: Had a quote attached, and the order's limit price is within that quote (in-market). Gets market fee policy.
- **Limit order**: Either no quote, or limit price is outside the quote (out-of-market). Gets limit fee policy with surplus fee.

The `appData.metadata.orderClass` field shows what the UI intended, but the actual classification is determined by comparing the order's price to the quote at placement time.

---

## 2. Signing Schemes

Orders can fail if signature validation fails. Different schemes have different failure modes:

| Scheme | Type | Validation | Common Failures |
|--------|------|------------|-----------------|
| `eip712` | EOA | Static, checked once | Sig doesn't match order fields, or signed by unexpected user |
| `ethsign` | EOA (legacy) | Static, checked once | Same as above |

**Note on unexpected signers:** The majority of signature issues are valid signatures but signed by an unexpected user. This causes the settlement contract to attempt transferring tokens from an account that doesn't have the necessary balance.
| `presign` | Smart contract | On-chain state (`setPreSignature`) | User called `setPreSignature(uid, false)` to cancel |
| `eip1271` | Smart contract | Calls `isValidSignature()` at settlement time | Contract state changed, Safe signer removed, custom logic rejects |

**EIP-1271 is dynamic** — signature can be valid at order placement but invalid later. Autopilot re-checks these every auction.

```bash
# Check if presign is set (returns signed boolean)
cast call $SETTLEMENT_CONTRACT "preSignature(bytes)" $ORDER_UID --rpc-url $RPC
```

---

## 3. Check Logs (Victoria Logs via MCP)

Logs are stored in Victoria Logs and accessible via the `CoW-Prod` MCP tools. Use `mcp__CoW-Prod__victorialogs_query` for log searches. Timestamps must be RFC3339 format (compute from current date).

**IMPORTANT — Protect context window**: Always append `| fields _time, _msg, all` to queries to strip kubernetes/ec2 metadata (~4KB per entry). Use small `limit` values (10-20). When you only need specific fields, use `| fields _time, _msg, parsed.fields.err, parsed.fields.driver` etc.

**Example queries (use `victorialogs_query` tool):**
```
# All order logs (exclude nginx controller, filter by network, strip metadata)
query: "container:!controller AND network:$NETWORK AND all:ORDER_UID | fields _time, _msg, all"
start: "<24h-ago-RFC3339>"
limit: 20

# Search by quote ID
query: "container:!controller AND network:$NETWORK AND all:22788649 | fields _time, _msg, all"

# Search specific solver
query: "container:!controller AND network:$NETWORK AND baseline AND all:22788649 | fields _time, _msg, all"
```

**Useful filters (part of the LogsQL expression):**
- `container:!controller` — excludes nginx access logs (REQUIRED for order UID searches)
- `network:$NETWORK` — **always include when debugging an order** to filter by chain (mainnet, bnb, arbitrum-one, base, etc). Reduces noise and speeds up queries.
- `all:` — prefix for searching structured fields (order UIDs, auction IDs, quote IDs). Without a field prefix, Victoria Logs only searches the log message text, not structured fields. You can also use `parsed.fields.order_uid:0x...` for precise matching, but `all:` works universally.
- `| fields _time, _msg, all` — **always append** to strip k8s metadata and protect context window

**Note:** Always use the **full order UID with 0x prefix** and the `all:` field prefix for reliable matching.

**IMPORTANT - Run targeted lifecycle queries in parallel** (use FULL order UID with 0x). Call multipl