Add derived trades table schema

[findolor]

Chained PRs

Stack order: #2587 -> #2588 -> #2589 -> #2590

Motivation

Trade-list reads need a persistent local DB read model so the API and SDK do not reconstruct trades from raw event tables on every request. This first PR establishes the schema surface for that read model.

Solution

• Add the derived_trades table with a stable primary key and token, owner, taker, order-hash, and transaction indexes.
• Add the table to local DB required-table validation.
• Include derived_trades in clear/reset paths.
• Bump the local DB manifest/schema version to reject old bootstrap dumps that do not contain the derived table.

Checks

• COMMIT_SHA=local nix develop -c cargo test -p raindex_common local_db::query --lib
• COMMIT_SHA=local nix develop -c cargo test -p raindex_common local_db::pipeline::adapters::apply --lib
• COMMIT_SHA=local nix develop -c cargo test -p raindex_common local_db::export --lib
• COMMIT_SHA=local nix develop -c cargo test -p raindex_common raindex_client::trades --lib

Summary by CodeRabbit

• Chores
  • Updated local database schema from version 3 to 4
  • Expanded local database with new trade data structures to store trade metadata, order details, transaction information, and token exchange records
  • Added supporting database indexes for efficient data retrieval and organization

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR introduces the derived_trades table to the local database schema (version 4), storing trade metadata indexed by chain, raindex address, and trade ID. The table is registered in required tables, validated in tests, and lifecycle operations (clear and drop) are updated to manage it.

Changes

Derived Trades Table Introduction

Layer / File(s)	Summary
Derived trades table definition and indexes crates/common/src/local_db/query/create_tables/query.sql	Adds derived_trades table with composite primary key (chain_id, raindex_address, trade_id) storing trade kind, side, order/transaction references, sender, and input/output vault metadata. Creates six supporting indexes for queries by input/output token, owner, sender, order hash, and transaction hash.
Table registration and schema validation crates/common/src/local_db/query/create_tables/mod.rs	Registers derived_trades in the REQUIRED_TABLES constant and updates the schema-parsing test to assert the trade_id column is present, ensuring SQL schema matches registered table requirements.
Schema versioning and table lifecycle operations crates/settings/src/local_db_manifest.rs, crates/common/src/local_db/query/clear_raindex_data/query.sql, crates/common/src/local_db/query/clear_tables/query.sql	Increments DB_SCHEMA_VERSION to 4. Updates the clear-raindex-data query to delete derived_trades rows for a given chain and address. Updates clear-tables to drop the derived_trades table.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• rainlanguage/raindex#2583: Main PR that bumps the schema version and extends REQUIRED_TABLES, which triggers bootstrap logic to check for DB mismatches and reset the database before watermark inspection.

Suggested reviewers

• 0xgleb
• JuaniRios
• hardyjosh

Poem

🐰 A table for trades now takes its place,
With indexes swift to win the race,
Schema versioned four, so clean and neat,
Life cycle managed, the tale complete! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Add derived trades table schema' directly and accurately summarizes the main change: the introduction of a new derived_trades table with its schema definition.
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 arda/derived-trades-schema

---

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]

• Superseded: Materialize vault deltas for balance sync #2591
• Test derived trades integration #2590
• Read trades from derived table #2589
• Maintain derived trades during sync #2588
• Add derived trades table schema #2587 👈 (View in Graphite)
• main

---

How to use the Graphite Merge Queue

Add the label Raindex-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.

[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 `@crates/settings/src/local_db_manifest.rs`:
- Line 12: Tests in this file still assert and use the old db-schema-version (3)
after updating the constant DB_SCHEMA_VERSION to 4, causing
parse_manifest_header/parse_manifest_doc to fail; update all fixtures and
assertions to use the new schema version or, better, make fixtures driven by the
DB_SCHEMA_VERSION constant (e.g., use the constant when constructing test
manifest headers and replace hard-coded `db-schema-version: 3` and `sv == 3`
checks with DB_SCHEMA_VERSION or a helper that emits the current
DB_SCHEMA_VERSION) so parse_manifest_header/parse_manifest_doc and sv assertions
stay in sync.

🪄 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: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: fe951c46-c297-4b06-911f-ef16e953f9f4

📥 Commits

Reviewing files that changed from the base of the PR and between 29b7822 and 46756c6.

📒 Files selected for processing (5)

• crates/common/src/local_db/query/clear_raindex_data/query.sql
• crates/common/src/local_db/query/clear_tables/query.sql
• crates/common/src/local_db/query/create_tables/mod.rs
• crates/common/src/local_db/query/create_tables/query.sql
• crates/settings/src/local_db_manifest.rs

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Update manifest test fixtures to schema version 4.

After Line 12 bumped DB_SCHEMA_VERSION to 4, tests in this file still use db-schema-version: 3 (and some assert sv == 3), which will now fail through parse_manifest_header/parse_manifest_doc.

Suggested fix pattern

- db-schema-version: 3
+ db-schema-version: 4

Or better, avoid future churn by templating fixtures with DB_SCHEMA_VERSION in helper builders.

🤖 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 `@crates/settings/src/local_db_manifest.rs` at line 12, Tests in this file
still assert and use the old db-schema-version (3) after updating the constant
DB_SCHEMA_VERSION to 4, causing parse_manifest_header/parse_manifest_doc to
fail; update all fixtures and assertions to use the new schema version or,
better, make fixtures driven by the DB_SCHEMA_VERSION constant (e.g., use the
constant when constructing test manifest headers and replace hard-coded
`db-schema-version: 3` and `sv == 3` checks with DB_SCHEMA_VERSION or a helper
that emits the current DB_SCHEMA_VERSION) so
parse_manifest_header/parse_manifest_doc and sv assertions stay in sync.