Use derived trades table for trade queries

[findolor]

Dependent PRs

This REST API PR depends on the raindex stack landing first:

• rainlanguage/raindex#2590: Test derived trades integration
• Graphite: https://app.graphite.com/github/pr/rainlanguage/raindex/2590

The submodule pointer in this PR is expected to reference the derived-trades implementation from that raindex stack.

Summary

• bump the orderbook submodule to the derived-trades implementation
• alias the renamed raindex crates under the existing REST dependency names
• update REST call sites and health mapping for the orderbook-to-raindex API rename

Linear

Part of RAI-580.

Benchmark context

Local server was run against the copied producer DB and localhost-served manifest/dump for the Base raindex. Health showed local DB sync active and the trade endpoints returned data from the SDK derived_trades path.

HTTP timings from the local server:

Endpoint	Fixture	Rows returned / total	Time	Payload
GET /v1/trades/token/{USDC}?pageSize=20	USDC	20 / 9,813	0.315s	10 KB
GET /v1/trades/token/{USDC}?pageSize=50	USDC	50 / 9,813	0.412s	25 KB
GET /v1/trades/token/{USDC}?pageSize=500	USDC	500 / 9,813	1.703s	253 KB
GET /v1/trades/{owner}?pageSize=20	top owner	20 / 3,439	0.305s	11 KB
GET /v1/trades/{owner}?pageSize=50	top owner	50 / 3,439	0.397s	27 KB
GET /v1/trades/{owner}?pageSize=500	top owner	500 / 3,439	1.700s	264 KB
GET /v1/trades/taker/{address}?pageSize=20	top taker	20 / 1,921	0.311s	10 KB
GET /v1/trades/taker/{address}?pageSize=50	top taker	50 / 1,921	0.391s	26 KB
GET /v1/trades/taker/{address}?pageSize=500	top taker	500 / 1,921	1.652s	264 KB
GET /v1/trades/tx/{txHash}	3-trade tx	3	0.250s	2 KB
POST /v1/trades/query	1 high-volume order hash	587	1.848s	291 KB
POST /v1/trades/query	5 high-volume order hashes	2,600	7.133s	1.36 MB

The direct SDK benchmark on the same copied DB returned USDC page size 20 in roughly 20 ms warm, with 9,813 matching trades.

Validation

• nix develop -c cargo check
• nix develop -c cargo fmt
• nix develop -c rainix-rs-static
• local Rocket server health: /health/detailed returned active local DB sync
• local authenticated trade endpoint benchmarks above returned data from derived_trades

Summary by CodeRabbit

• Refactor
  • Switched runtime identifiers and API responses from "orderbook"-based to "raindex"-based, updating health, order, orders, swap, cancel, and token behaviors to return raindex-aligned identifiers.
• Chores
  • Updated project dependency metadata to preserve previous feature behavior while changing how local packages are referenced.
• Tests
  • Updated test fixtures and mocks to use the raindex schema/version.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR replaces "orderbook" references with "raindex": dependency package names and submodule pointer updated; health snapshot mapping now iterates raindexes and uses a helper to produce orderbook-facing sync info; API responses and swap/cancel flows source identifiers/addresses from raindex(); tests and fixtures updated to registry schema v6 with raindexes.

Changes

Raindex Terminology Migration

Layer / File(s)	Summary
Dependency and submodule updates Cargo.toml, lib/rain.orderbook	Cargo.toml switches rain_orderbook_* dependencies to explicit package = raindex_* mappings while keeping local path and default-features = false; lib/rain.orderbook subproject commit advanced.
Health reporting refactor src/routes/health.rs	Imports use RaindexSyncStatusSnapshot; map_raindex_snapshot iterates snapshot.raindexes and maps via map_raindex_status_snapshot; network orderbook_count comes from raindex count; error logging iterates raindexes; unit test fixtures rebuilt with raindex_id/raindex_key/raindex_count.
Order and swap API response updates src/routes/order/cancel.rs, src/routes/order/get_order.rs, src/routes/orders/mod.rs, src/routes/swap/mod.rs	Cancel transaction to, order detail orderbook_id, order summary orderbook_id, and swap calldata to now use raindex()/take_orders_info.raindex() instead of orderbook().
Client and provider integration src/routes/tests.rs	Provider client call changed to get_raindex_subgraph_client(orderbook_address) in the test helper route.
Test fixtures and mock data src/routes/order/mod.rs, src/routes/tokens.rs, src/test_helpers.rs	Registry YAML fixtures updated from version 5 to 6 with raindexes: sections; mock JSON/YAML for orders, trades, vaults, tokens, and TakeOrderCandidate replaced orderbook fields with raindex; stub client payloads switched to raindex_yaml.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• ST0x-Technology/st0x.rest.api#35: Related change to cancel-order destination address sourcing using raindex().
• ST0x-Technology/st0x.rest.api#52: Related changes to order summary identifier sourcing from raindex.
• ST0x-Technology/st0x.rest.api#95: Related health endpoint and raindex snapshot mapping changes.

Suggested reviewers

• hardyjosh
• JuaniRios
• 0xgleb

Poem

🐰 I hopped through code to change the name,
From orderbook to raindex—what a game.
Snapshots dance and tests now sing,
Addresses point to the new bright thing.
A tiny rabbit's refactor, neat and tame.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 24.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Title check	❓ Inconclusive	The PR title 'Use derived trades table for trade queries' is only partially related to the changeset. While the PR does update to use a derived trades implementation from raindex, the actual changes visible in the diff focus on renaming orderbook references to raindex references throughout the codebase (dependency aliases, health routes, order endpoints, etc.). The title emphasizes the trades table aspect but doesn't capture the broader scope of the orderbook-to-raindex API rename that dominates the actual file changes.	Consider a more comprehensive title that reflects the primary code changes, such as 'Refactor orderbook references to raindex API' or 'Update to raindex-based architecture for derived trades', to better represent the scope of identifier/naming changes throughout the codebase.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/use-derived-trades-table

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[findolor]

• Filter swap quote orders by funded output vault #118
• Use derived trades table for trade queries #113 👈 (View in Graphite)
• Use generic trades query for owner endpoint #110
• Improve order endpoint trade lookup #109
• Use api.staging.st0x.io for preview #111
• main

---

How to use the Graphite Merge Queue

Add the label add-to-gt-merge-queue to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

[linear-code]

RAI-580

RAI-644

[findolor]

Preview validation passed for derived trades local DB sync.

Context:

• REST branch: feature/use-derived-trades-table
• Registry PR head used for private artifact: ST0x-Technology/st0x.registry@b9958e17c8659da99b22644848f0489beffa1de1
• Preview deploy run: https://github.com/ST0x-Technology/st0x.rest.api/actions/runs/26390357483

Validation:

• Preview service deployed successfully from feature/use-derived-trades-table.
• Preview loaded the private registry artifact and raindex registry successfully.
• /health/detailed reports status=ok, raindex.status=active, and Base orderbook ready.
• Preview local DB was pulled from the versioned manifest, db_schema_version = 4.
• derived_trades exists and contains 10,065 rows.

Public-network benchmark from local machine:

Endpoint	Preview	Production
GET /v1/trades/token/USDC?pageSize=20	0.600s	11.358s
GET /v1/trades/token/USDC?pageSize=50	0.767s	8.015s
GET /v1/trades/token/USDC?pageSize=500	1.563s	10.950s
GET /v1/trades/{owner}?pageSize=20	0.584s	16.372s
GET /v1/trades/{owner}?pageSize=50	0.699s	19.004s
GET /v1/trades/{owner}?pageSize=500	1.548s	17.707s
GET /v1/trades/taker/{taker}?pageSize=20	0.579s	2.334s
GET /v1/trades/taker/{taker}?pageSize=50	0.694s	2.610s
GET /v1/trades/taker/{taker}?pageSize=500	1.801s	4.641s
GET /v1/trades/tx/{txHash}	0.471s	0.551s
POST /v1/trades/query (1 high-volume order hash)	1.688s	1.915s

The main improvement is on token/owner trade reads, where preview is roughly 10-25x faster than current production for the tested fixtures.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@lib/rain.orderbook`:
- Line 1: The submodule pointer for lib/rain.orderbook references an unreachable
commit (da24ba21571c...) instead of the actual current submodule HEAD
(80e940d7ad22...), so update the gitlink to a reachable commit that contains the
raindex#2590 "derived-trades" changes: fetch the submodule remote for
lib/rain.orderbook, identify the commit that implements raindex#2590, update the
submodule to that reachable commit (replace the bad hash with the real commit),
stage the submodule change in the superproject and commit the updated pointer so
the submodule update will succeed.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 95c13372-0559-4e2f-8c65-508df8833c94

📥 Commits

Reviewing files that changed from the base of the PR and between 1c151e2 and 80e940d.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (12)

• Cargo.toml
• infra/terraform.tfstate.age
• lib/rain.orderbook
• src/routes/health.rs
• src/routes/order/cancel.rs
• src/routes/order/get_order.rs
• src/routes/order/mod.rs
• src/routes/orders/mod.rs
• src/routes/swap/mod.rs
• src/routes/tests.rs
• src/routes/tokens.rs
• src/test_helpers.rs

[coderabbitai]

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Description: Verify the rain.orderbook submodule commit is accessible and contains expected changes

cd lib/rain.orderbook || exit 1

# Check if the commit exists and is reachable
if git cat-file -e da24ba21571c71015b69f41cf10782dba356c997^{commit} 2>/dev/null; then
    echo "✓ Commit da24ba21571c71015b69f41cf10782dba356c997 exists"
    
    # Show commit message to verify it's the derived-trades implementation
    echo -e "\n=== Commit message ==="
    git log -1 --oneline da24ba21571c71015b69f41cf10782dba356c997
    
    # Check for derived_trades or raindex related changes in recent history
    echo -e "\n=== Recent commits referencing derived-trades or raindex ==="
    git log --oneline --all --grep="derived.*trade\|raindex" -10
    
    # List modified files in this commit to verify scope
    echo -e "\n=== Files changed in target commit ==="
    git show --stat --oneline da24ba21571c71015b69f41cf10782dba356c997
else
    echo "✗ Commit da24ba21571c71015b69f41cf10782dba356c997 not found or not accessible"
    echo "Fetch latest changes with: git fetch --all"
    exit 1
fi

Repository: ST0x-Technology/st0x.rest.api

Length of output: 194

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

cd lib/rain.orderbook

echo "== Submodule gitdir =="
git rev-parse --git-dir

echo "== Current HEAD =="
git rev-parse HEAD
git log -1 --oneline

echo "== Remotes =="
git remote -v || true

echo "== Commit presence checks =="
git cat-file -e da24ba21571c71015b69f41cf10782dba356c997^{commit} && echo "present" || echo "NOT present"

echo "== Any refs containing the hash (local only) =="
git branch --contains da24ba21571c71015b69f41cf10782dba356c997 2>/dev/null || true

echo "== Grep local objects (may be large; just check loose refs first) =="
git show-ref | rg -n 'da24ba21571c71015b69f41cf10782dba356c997' || echo "no local refs match"

Repository: ST0x-Technology/st0x.rest.api

Length of output: 757

---

Fix submodule pointer to a reachable derived-trades commit

• The target submodule commit da24ba21571c71015b69f41cf10782dba356c997 is not present/reachable in lib/rain.orderbook; git reports upload-pack: not our ref ..., so the commit can’t be inspected and the submodule update may fail.
• Current submodule HEAD is 80e940d7ad22d9e9f8891f10f2f1ddfea0d896a9 (“Use derived trades table from orderbook”), which doesn’t match the proposed hash. Update the pointer to an existing commit that matches the intended raindex#2590 derived-trades changes.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@lib/rain.orderbook` at line 1, The submodule pointer for lib/rain.orderbook
references an unreachable commit (da24ba21571c...) instead of the actual current
submodule HEAD (80e940d7ad22...), so update the gitlink to a reachable commit
that contains the raindex#2590 "derived-trades" changes: fetch the submodule
remote for lib/rain.orderbook, identify the commit that implements raindex#2590,
update the submodule to that reachable commit (replace the bad hash with the
real commit), stage the submodule change in the superproject and commit the
updated pointer so the submodule update will succeed.

[graphite-app]

Merge activity

• May 26, 5:59 PM UTC: findolor added this pull request to the Graphite merge queue.
• May 26, 6:14 PM UTC: Merged by the Graphite merge queue.

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/routes/tests.rs (1)

9-20: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Add tracing/span propagation to shared_client_contract

src/routes/tests.rs’s #[get("/shared-client")] async fn shared_client_contract(...) has no TracingSpan, no .instrument(span.0), and no tracing::... logs. Update it to accept a span: TracingSpan request guard (like other route handlers) and instrument the async client call with .instrument(span.0), with tracing for “request received” and error paths.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/routes/tests.rs` around lines 9 - 20, shared_client_contract currently
lacks tracing/span propagation and logs; update the handler signature to accept
a TracingSpan request guard (like other handlers), log a "request received"
message with tracing::info! at the start of shared_client_contract, call
provider.client().get_raindex_subgraph_client(orderbook_address) inside the
async flow instrumented with .instrument(span.0), and on failure emit a
tracing::error! with the error before mapping to ApiError::Internal (keep the
existing return mapping but add the trace logging and span instrumentation
around the client call).

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@src/routes/tests.rs`:
- Around line 9-20: shared_client_contract currently lacks tracing/span
propagation and logs; update the handler signature to accept a TracingSpan
request guard (like other handlers), log a "request received" message with
tracing::info! at the start of shared_client_contract, call
provider.client().get_raindex_subgraph_client(orderbook_address) inside the
async flow instrumented with .instrument(span.0), and on failure emit a
tracing::error! with the error before mapping to ApiError::Internal (keep the
existing return mapping but add the trace logging and span instrumentation
around the client call).

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 1cc07759-c684-44c7-bdd9-4182a2b511d2

📥 Commits

Reviewing files that changed from the base of the PR and between 80e940d and 4063edd.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (12)

• Cargo.toml
• infra/terraform.tfstate.age
• lib/rain.orderbook
• src/routes/health.rs
• src/routes/order/cancel.rs
• src/routes/order/get_order.rs
• src/routes/order/mod.rs
• src/routes/orders/mod.rs
• src/routes/swap/mod.rs
• src/routes/tests.rs
• src/routes/tokens.rs
• src/test_helpers.rs

✅ Files skipped from review due to trivial changes (1)

• src/routes/tokens.rs