feat: settle order book functionality and validation

[MicBun]

resolves: https://github.com/truflation/website/issues/3205

Summary by CodeRabbit

• Bug Fixes

  • Route collateral unlocks to the correct bridge, validate bridge selection, and return errors on invalid/missing bridges.
  • Improve market validation messaging for missing bridge associations.

• Improvements

  • Switch fee accounting and runtime payouts to USDC.

• Tests

  • Update and extend tests to track dual-token balances, use ABI-encoded market identifiers, and align assertions with USDC flows.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[holdex]

Time Submission Status

Member	Status	Time	Action	Last Update
MicBun	✅ Submitted	8h	Update time	Jan 27, 2026, 12:09 PM

---

You can submit time with the command. Example:

@holdex pr submit-time 15m

See available commands to help comply with our Guidelines.

[coderabbitai]

📝 Walkthrough

Walkthrough

Added multi-bridge routing to order-book settlement and validation: batch-unlock helper now accepts a bridge selector; settlement/fee-distribution look up and pass market bridge; tests refactored to track USDC balances separately from TRUF and to inject TRUF where needed.

Changes

Cohort / File(s)	Summary
SQL Migrations for Bridge Routing internal/migrations/033-order-book-settlement.sql, internal/migrations/037-order-book-validation.sql	ob_batch_unlock_collateral signature changed to accept $bridge TEXT; unlock calls route to specific bridge precompiles (hoodi_tt2, sepolia_bridge, ethereum_bridge). distribute_fees and process_settlement now look up/validate market bridge and pass it into batch-unlock; vault balance retrieval routed by bridge in validation.
Order-Book Tests — Balance Tracking & Helpers tests/streams/order_book/*.go (e.g. cancel_order_test.go, fee_distribution_test.go, fee_distribution_audit_test.go, matching_engine_test.go, queries_test.go, rewards_test.go, settlement_payout_test.go, split_limit_order_test.go, validate_market_collateral_test.go)	Tests switched monetary assertions from TRUF to USDC (getUSDCBalance), introduced separate TRUF balance chaining/state (lastTrufBalancePoint), added/updated chained-injection helpers (giveUSDCBalanceChained, TRUF injection helpers) and reset TRUF state in setups.
Order-Book Test Utilities / Minor Fixes tests/streams/order_book/market_creation_test.go, tests/streams/order_book/settlement_test.go	Fixed stream ID length generation and adjusted an error-message assertion for invalid query_id to match new wording.
Integration Tests / ABI & TRUF Injection extensions/tn_settlement/settlement_integration_test.go	Added ABI-encoding helpers for query_components, replaced attestation-hash usage with encoded components, added TRUF injection helpers and TRUF-state resets, and updated helpers to return encoded components for market creation tests.

Sequence Diagram(s)

sequenceDiagram
  participant Engine as Engine/Scheduler
  participant SQL as process_settlement (migration)
  participant DB as ob_queries / DB
  participant Unlock as ob_batch_unlock_collateral
  participant Bridge as Bridge Precompile

  Engine->>SQL: trigger process_settlement
  SQL->>DB: lookup market info for query_id -> bridge
  DB-->>SQL: bridge name (hoodi_tt2 / sepolia_bridge / ethereum_bridge)
  SQL->>Unlock: call ob_batch_unlock_collateral($bridge, wallets, amounts)
  Unlock->>Bridge: call selected bridge precompile
  Bridge-->>Unlock: ack / result
  Unlock-->>SQL: success / error
  SQL-->>Engine: settlement complete / error

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• feat: distribute settlement fees to liquidity providers #1280 — Modifies distribute_fees and ob_batch_unlock_collateral calls; directly overlaps with bridge-parameter propagation.
• feat: pay out winners on settled markets #1273 — Introduced earlier process_settlement / ob_batch_unlock_collateral logic; this PR extends that implementation with bridge routing.
• feat: validate market collateral and token parity #1282 — Adjusts vault-balance lookup to be bridge-aware in validation SQL; overlaps with the bridge routing changes here.

Suggested reviewers

• outerlook
• williamrusdyputra

Poem

🐰 I hopped through tests and SQL streams,
Pushing bridges into routing dreams,
USDC pennies, TRUFs in tow,
Unlocks find paths where they should go —
A tiny hop, a clean deploy — let's go! 🚀

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

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

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat: settle order book functionality and validation' accurately summarizes the main changes across the pull request, which involve adding settlement functionality with bridge routing, validating market bridges, and adjusting tests for USDC-based settlements.

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

✨ Finishing touches

• 📝 Generate docstrings

---

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.}