Spec: auto-routing orders (+ tighten ckBTC lot)

[gregorydemay]

Adds the spec for auto-routing orders: placing an order on a non-listed spoke↔spoke pair (e.g. ICP/ckBTC) that the canister executes transparently as two real orders meeting at the ckUSDT hub, in a single hop.

Key decisions captured in the spec, in the order they were worked out this session:

• Topology is a star quoted in ckUSDT, so the transit token is always the hub — "discovery" is a hub lookup, not a graph search; scope is a single hop.
• Execution is a synchronous atomic taker (multi-leg fill-or-kill): plan both legs read-only, then kill-or-apply in one message; settlement is deferred and chunked via the existing settling drain.
• The two book grids cannot generally chain to exactly zero leftover transit; the bounded residual is returned to the user as change in the hub token (ckUSDT), which is the fairest and simplest disposition. Strict-kill, sweep-to-fee-pool and a tolerance band were all considered and rejected.
• Transparent entry point: same endpoint and request type as a direct order; one id back; the canister auto-detects direct vs routable.
• Identity: a filled route is recorded as its two leg orders (where prices/fees are unambiguous); a route_id resolves the returned id to the legs; a killed route is a single Expired record.

Also folds in a small independent listing fix: the ckBTC/ckUSDT lot was retightened to 0.00001 BTC (tick 0.1 USDT), which also shrinks the worst-case routing residual ~10×.

One sub-decision is intentionally left open in the spec (Implementation → Limit semantics): whether the limit is expressed as an input budget or a synthetic limit price. Recommendation noted inline.

Draft — spec only, no implementation yet.

[Copilot]

Pull request overview

Adds a new design/spec document describing auto-routing orders (synthetic spoke↔spoke orders executed atomically as two ckUSDT-hub legs), and updates docs navigation plus an admin-facing listing parameter tweak for ckBTC/ckUSDT.

Changes:

• Introduces spec DEFI-2861 — Auto-Routing Orders covering topology assumptions, FOK two-leg execution, residual disposition, and identity model (route_id).
• Adds the new spec to the docs sidebar (SUMMARY).
• Updates the documented ckBTC/ckUSDT tick/lot values in the admin usage table.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.

File	Description
docs/src/usage/for-admins.md	Updates the documented ckBTC/ckUSDT tick/lot parameters.
docs/src/SUMMARY.md	Adds the DEFI-2861 spec page to the documentation index.
docs/src/development/specs/DEFI-2861-auto-routing-orders.md	New spec defining requirements and design decisions for auto-routing spoke↔spoke orders via the ckUSDT hub.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[github-actions]

canbench 🏋 (dir: canister) 4857ee7 2026-06-29 09:07:43 UTC

✅ canister/canbench_results.yml is up to date
📦 canbench_results_benchmark.csv available in artifacts

---------------------------------------------------

Summary:
  instructions:
    status:   No significant changes 👍
    counts:   [total 14 | regressed 0 | improved 0 | new 0 | unchanged 14]
    change:   [max +365.22K | p75 +2.11K | median 0 | p25 0 | min -32]
    change %: [max +1.58% | p75 +0.21% | median 0.00% | p25 0.00% | min -0.00%]

  heap_increase:
    status:   No significant changes 👍
    counts:   [total 14 | regressed 0 | improved 0 | new 0 | unchanged 14]
    change:   [max 0 | p75 0 | median 0 | p25 0 | min 0]
    change %: [max 0.00% | p75 0.00% | median 0.00% | p25 0.00% | min 0.00%]

  stable_memory_increase:
    status:   No significant changes 👍
    counts:   [total 14 | regressed 0 | improved 0 | new 0 | unchanged 14]
    change:   [max 0 | p75 0 | median 0 | p25 0 | min 0]
    change %: [max 0.00% | p75 0.00% | median 0.00% | p25 0.00% | min 0.00%]

---------------------------------------------------
CSV results saved to canbench_results.csv