Take Orders SDK Functionality

[findolor]

Summary

Add a high‑level “take orders” builder to the SDK that:

• Discovers candidate orders for a given (inputToken, outputToken, networkKey).
• Quotes them via quote2 (outputMax, IORatio) and builds take‑order candidates.
• Runs an off‑chain exact‑in simulation to derive:
  • Expected output, minimum output, effective price.
  • A slippage‑safe TakeOrdersConfigV4 suitable for IOrderBookV5.takeOrders3.
• Exposes this as a wasm/JS API (no UI work in this epic).

This work is implemented via smaller issues for:

• Phase 1: Directional token filters for order discovery (subgraph + local DB) and API plumbing.
• Phase 2: Take‑order candidates and quoting (turn orders + quotes into TakeOrderCandidate[]).
• Phase 3+: Exact‑in simulation + slippage mapping + js_api builder (future issues, out of scope for this PR batch).

---

Motivation

Today, Raindex exposes:

• Subgraph/local‑DB backed order discovery (GetOrdersFilters / SgOrdersListFilterArgs).
• On‑chain pricing via quote2 (get_order_quotes, RaindexOrder::get_quotes).
• Low‑level ABI helpers (getTakeOrders3Calldata).

But there is no single SDK call for:

“Given network + tokens + amount + slippage, tell me the expected output and give me calldata/config for takeOrders3 using the best available orders.”

This epic adds that orchestration while keeping:

• Directional token filters and order discovery cleanly abstracted.
• Economic logic (quotes, simulation, slippage) as pure functions.
• js_api as a thin orchestration/interop layer.

---

Assumptions (to validate, see design questions)

• Amount semantics (tentative): v1 will be exact‑in – amount is the taker’s inputToken amount (tokens they give).
• Multi‑orderbook behavior (tentative):
  • For a given network, we fetch orders from all configured orderbooks.
  • We pool take‑order candidates across those books for a pair.
  • We sort candidates globally by ratio ascending (cheapest first), even if that mixes orderbooks.
• Simulation & slippage:
  • We will simulate off‑chain using quote2 outputs (outputMax, IORatio) to compute a blended expected price and output.
  • We will map those into maximumIORatio, minimumInput (minOut), and maximumInput, and back this with local‑EVM integration tests that compare outcomes to takeOrders3.

If any of these assumptions change, the architecture (filters → candidates → simulation → config) should remain valid; only the simulation/mapping strategy and builder API surface need to be adjusted.

---

Scope of this issue

In scope:

• Rust + wasm/JS code changes in:
  • crates/subgraph
  • crates/common
  • crates/quote
  • crates/js_api
• New pure types/functions:
  • Directional order filters (input_tokens / output_tokens) wired through subgraph + local‑DB.
  • TakeOrderCandidate and builders derived from RaindexOrder + get_quotes.
  • A pure exact‑in simulator and a pure TakeOrdersConfigV4 mapper.
• js_api builder:
  • buildTakeOrdersExactIn(params) → { expectedOutput, minimumOutput, effectivePrice, takeOrdersConfig }.

Out of scope:

• Webapp / Svelte UI changes.
• Tauri / desktop app wiring.
• UX flows, routing, or state management outside the wasm/JS API surface.

---

Sub‑issues

• Phase 1 – Directional token filters for order discovery
  • Implemented in TAKE_ORDERS_SDK_PHASE1_FILTERS_ISSUE.md.
• Phase 2 – Take‑order candidates and quoting
  • Implemented in TAKE_ORDERS_SDK_PHASE2_CANDIDATES_ISSUE.md.
• Phase 3 – Exact‑in simulation + slippage + js_api builder
  • To be split into separate issues once Phase 1 and 2 are stable.

[hardyjosh]

@findolor a known issue is that if one order in the list reverts on handle-io, the entire transaction reverts.

Three ways to deal with this that I see:

• simulate the batch with a debug call and if it reverts, inspect the trace and isolate the order that caused the issue, remove it and retry
• try a process of elimination (could be very complex if it's multiple causing the revert)
• simulate a full take of each order on its own, remove any that revert from the list

[hardyjosh]

Also - not sure how you intend for multi-orderbook to work

[alastairong1]

@hardyjosh This is all great.

My biggest general concern with market orders is scalability when fetching all the orders and up-to-date quotes. I'm guessing this is supposed to be handled by the localDB?

The other thing I need (and it might be outside of this call itself) is to be able to set a max slippage tolerance. I.e. when you re-order the candidate orders from best to worst quote, what % from the best quote before we stop.