fix(split routing): topological order for cross-depth hops

[tamaralipows]

Problem, summarized:

The original two paths:

WETH ───▶ USDC ─── pool_a ──▶ DAI                    (shorter path)
WETH ───▶ USDT ────────▶ USDC ── pool_a ──▶ DAI      (longer path)

The merged paths:

WETH ──┬────────────▶ USDC ─── pool_a ──▶ DAI
       │                ▲
       └────▶ USDT ─────┘
                                       

Our merging algo was emitting the USDC ─ pool_a ─▶ DAI before emitting the USDT ─▶ USDC swap. This would cause unintended consequences on our router side, since only the amount for WETH ─▶ USDC would be inputted into the final USDC ─▶ DAI swap, ignoring the USDT ─▶ USDC amount.

Related addition to the Tycho docs: propeller-heads/tycho#1068

Solution

Replace naive BFS in build_split_route with Kahn's topological sort.

Summary of Kahn's topological sort:

1. Count incoming edges for every node (the "in-degree")
2. Enqueue all nodes with in-degree 0 — they have no dependencies
3. Loop: pop a node from the queue, "emit" it, and decrement the in-degree of each of its neighbors. Whenever a neighbor's in-degree reaches 0, enqueue it
4. Done when the queue is empty. If any nodes were never enqueued, the graph has a dependency cycle (A → B → A → C) — distinct from a valid trade cycle (A → B → A) where the trade starts and ends at the same token

Consequence

The USDC ─── pool_a ──▶ DAI will now be one swap meaning we should only count gas once. The swap will be emitted only after the inflow swaps are emitted. Our router is happy.

Important Note: Unsupported edge case

The following case is still not supported, because Pool A and Pool B cause a deadlock from being swapped in opposite orders in different branches:

WETH ─┬─ USDC ─ (Pool A) ─ DAI ─ PEPE ─ (Pool B) ─ UNI ─ WBTC
      └─ PEPE ─ (Pool B) ─ UNI ─ USDC ─ (Pool A) ─ DAI ─ WBTC

This is a pretty rare case and any solutions I found resulted in a massive refactor. For now, I've added a test that ensures this results in an error. Let me know if you agree or if you think this is worth spending time to support.

[tamaralipows]

Docstring getting too long. Considering removing this example.

[tamaralipows]

It's okay that we are already taking the deduplicated (after merged_shared_hops) paths here, because in-degree isn't tracking how many times Pool A appears - it's tracking how many distinct swaps produce a given token. We still have this information with the given data.