Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
8 changes: 0 additions & 8 deletions .cargo/audit.toml
Original file line number Diff line number Diff line change
Expand Up @@ -5,14 +5,6 @@
[advisories]
# Known vulnerabilities that are tracked in https://github.com/cowprotocol/services/issues/3338
ignore = [
# idna - Punycode label vulnerability (RUSTSEC-2024-0421)
# Needs upgrade to 1.0.0+ (transitive dependency)
"RUSTSEC-2024-0421",

# protobuf - Uncontrolled recursion (RUSTSEC-2024-0437)
# Needs upgrade to 3.7.2+ (transitive dependency)
"RUSTSEC-2024-0437",

# rsa - Marvin Attack timing sidechannel (RUSTSEC-2023-0071)
# No patch available yet (cryptography vulnerability)
"RUSTSEC-2023-0071",
Expand Down
20 changes: 15 additions & 5 deletions .claude/commands/debug-order.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,21 @@ Read and follow the instructions in ./docs/COW_ORDER_DEBUG_SKILL.md to investiga

Key steps:
1. Parse the order UID and network from arguments (default: mainnet)
2. Fetch order data from API to get status and details
3. Check order_events in DB for lifecycle events
4. Search Victoria Logs for the order UID
2. **Start with the debug endpoint** — fetch the comprehensive debug report first:
```bash
source .env.claude && curl -s -H "X-API-Key: $COW_DEBUG_API_KEY" "https://partners.cow.fi/$NETWORK/restricted/api/v1/debug/order/$ORDER_UID" | jq .
```
This returns order details, lifecycle events, auction participation, proposed solutions, executions, trades, and settlement attempts — all in one call.
3. Analyze the debug report — key event meanings:
- `ready` = order made it into an auction (was sent to solvers)
- `considered` = a solver included this order in a solution but that solution didn't win
- `executing` = order is in the winning solution, being submitted on-chain
- `traded` = order was settled on-chain
- `filtered` / `invalid` = order was excluded (check the `reason` field)
4. Search Victoria Logs for additional context (filter reasons, error details, solver logs)
- For finding discarded solutions where the order UID appears in calldata, use regex: `.*ORDER_UID_WITHOUT_0X.*` plus `discarded`
5. Identify root cause and report findings with evidence
6. If you haven't found anything go wild and try all SQL / log searches / codebase searches you can think of
5. Use DB queries or API calls only if the debug report is missing info or you need deeper investigation
6. Identify root cause and report findings with evidence
7. If you haven't found anything go wild and try all SQL / log searches / codebase searches you can think of

Always show your evidence (log lines, DB results, API responses) when presenting findings.
56 changes: 43 additions & 13 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,6 +105,7 @@ User signs order → Orderbook validates → Autopilot includes in auction
- Spot format: `cargo +nightly fmt -- <path>` (never call stable `cargo fmt`)
- Lint: `cargo clippy --locked --workspace --all-features --all-targets -- -D warnings`
- Check format: `cargo +nightly fmt --all -- --check`
- Only format **after** as a final step! — i.e. after checking compilation, running tests, etc.

### Local Development Environment
- Start local PostgreSQL: `docker compose up -d`
Expand Down Expand Up @@ -181,26 +182,55 @@ Databases: `mainnet`, `arbitrum-one`, `base`, `linea`, `polygon`, `xdai`, `sepol

Use `$ETH_MAINNET_RPC` from `.env.claude` for mainnet. Use `cast` or whatever tools you want freely.

## Grafana Logs Access
## Victoria Logs Access

Use the `scripts/vlogs` wrapper to query Victoria Logs.
Use the `CoW-Prod` MCP tools to query Victoria Logs directly.

**IMPORTANT**: When running `scripts/vlogs`, do NOT use bash comments before the command (e.g., `# comment\nscripts/vlogs ...`) as this causes unnecessary permission prompts. Just run the command directly.
**Timestamps**: MCP requires RFC3339 format (e.g., `2026-04-09T00:00:00Z`). Compute absolute timestamps from the current date rather than using relative time.

**IMPORTANT**: Order UIDs and other structured fields (like `quote_id`, `auction_id`) live inside the `all` field in Victoria Logs. You MUST prefix them with `all:` to match. Plain text terms (like `order created`, `filtered`) match the log message directly and don't need the prefix.
**IMPORTANT**: Order UIDs and other structured fields (like `quote_id`, `auction_id`) live inside the `all` field in Victoria Logs. You MUST prefix them with `all:` to match. Plain text terms (like `order created`, `filtered`) match the log message directly and don't need the prefix. You can also use parsed fields directly (e.g., `parsed.fields.order_uid:0x...`) for more precise matching.

```bash
scripts/vlogs "<expr>" [--from <time>] [--to <time>] [--max <lines>] [--env <prod|staging>] [--raw]
**IMPORTANT — Protect context window**: Raw log entries contain ~4KB of kubernetes/ec2 metadata each. **Always** append `| fields _time, _msg, all` (or specific `parsed.fields.*`) to strip noise. Use small `limit` values (10-20) and only increase if needed. Examples:
- General order search: `... | fields _time, _msg, all`
- When you only need specific parsed fields: `... | fields _time, _msg, parsed.fields.err, parsed.fields.driver, parsed.spans.auction.auction_id`

scripts/vlogs "NOT container:controller order created all:0xabc..." --from now-24h
scripts/vlogs "NOT container:controller network:mainnet settlement failed" --from now-6h --max 50
scripts/vlogs "error" --env staging --from now-1h
scripts/vlogs "NOT container:controller all:0xabc..." --raw
```
**Available MCP tools:**
- `victorialogs_query` — Main log search (LogsQL expression + time range + limit)
- `victorialogs_hits` — Count matching logs grouped by time buckets
- `victorialogs_field_names` / `victorialogs_field_values` — Explore available fields
- `victorialogs_facets` — Most frequent values per field
- `victorialogs_stats_query` / `victorialogs_stats_query_range` — Aggregation queries
- `victorialogs_stream_field_names` / `victorialogs_stream_field_values` — Stream metadata

Defaults: `--from now-12h`, `--to now`, `--max 100`, `--env prod`
**Key fields:**
- Stream fields (efficient filters): `container`, `namespace`, `pod`
- `network` — chain name (mainnet, arbitrum-one, base, etc.)
- `all` — full structured JSON log (search with `all:` prefix for UIDs)
- `parsed.fields.*` — individual parsed fields (e.g., `parsed.fields.order_uid`, `parsed.fields.quote_id`)
- `_msg` — the log message text

Datasource UIDs (hardcoded in script): `vm-auth-prod` (production), `vm-auth-staging` (staging)
**Example queries:**
```
# Search for order logs (exclude nginx controller, strip metadata)
query: "container:!controller AND network:mainnet AND all:0xabc... | fields _time, _msg, all"
start: "<COMPUTED_RFC3339>"
limit: 20

# Search for order creation on mainnet
query: "container:!controller AND network:mainnet AND \"order created\" AND all:0xabc... | fields _time, _msg, all"
start: "<COMPUTED_RFC3339>"
limit: 10

# Settlement failures with just error details
query: "container:!controller AND network:mainnet AND \"settlement failed\" | fields _time, _msg, parsed.fields.err, parsed.fields.driver, parsed.spans.auction.auction_id"
start: "<COMPUTED_RFC3339>"
limit: 10

# Sort results by time
query: "container:!controller AND network:mainnet AND all:0xabc... | fields _time, _msg, all | sort by (_time) asc"
start: "<COMPUTED_RFC3339>"
limit: 20
```

## Etherscan API (V2)

Expand Down
Loading
Loading