[MicBun]

Description

A caller can now ask the node how much traded on one order book over a time window. get_market_activity($query_id, $from_ts, $to_ts) returns the filled volume with its direct and mint/burn parts, the unique traders, the fill and share counts, the first and last fill inside the window, and how far back the node's order events reach. Every SDK will call this action instead of carrying its own copy of the SQL, so the definition of volume lives in one place.

• 058-order-book-market-activity.sql creates the action. It is a new object, so it gets a new file, and it references no bridge, so there is no .prod.sql twin.
• The definition is the Goal's, unchanged. A direct_buy_fill counts price * amount, and a mint or burn counts 100 * amount on its YES row. The sell row and the NO row add traders but no volume. Splits, placements, cancels, amends and settlement add nothing. The fill types are an allowlist, and the window includes both of its ends.
• 044-order-book-events.sql gains an index on ob_order_events (query_id, block_timestamp), so a read costs what its window holds rather than a scan of the whole retained table.
• The action refuses a NULL argument and a window that ends before it starts. A market that does not exist returns no row, as get_market_depth does.

One change from the Goal's statement

On a node that holds no order events, the statement returned NULL for coverage_from_block and coverage_complete. The action returns 0 and false, so every SDK can type both as non-null, and false still says a zero from that market cannot be trusted.

Worth knowing before the release

Coverage errs on the safe side. coverage_complete compares the market's creation height with the oldest event the node holds. For a market older than every held event it reads false even when nothing was trimmed, but it never reads true when fills were trimmed. The test covers both cases.

The index is built when the migration runs. CREATE INDEX IF NOT EXISTS locks ob_order_events against writes while it builds. The table held about 174k rows on mainnet on 6 Oct, and on 175k synthetic rows the build took 178 ms on my workstation.

The SDK calls need this on the network first. The sdk-go pull request below moves to this action once it ships, and the JS and Python calls will use it from the start:

• feat: read a market's volume and traders over a time window sdk-go#206

Related Problem

resolves: #1443

Part of:

• Goal: SDK call for market volume over a time period #1429

How Has This Been Tested?

go test -tags kwiltest ./tests/streams/order_book/ -run TestMarketActivity trades on a real order book, setting each call's block height and time. All five function tests pass.

• Every column. One market gets a split and resting orders, then a direct fill of 30 shares at 55, a mint of 10 and a burn of 10. Over the whole window the action returns 3650 cents: 1650 direct and 2000 from the mint and burn, with 4 traders, 3 fills, 50 shares, and the times of the first and last fill. The test first checks that the split rows, the direct sell row and the NO rows of the mint and burn exist, so every exclusion is exercised.
• Both ends of the window. A one-second window on each fill returns that fill alone. The seconds before the first fill and after the last return zeros with no fill times.
• Coverage follows the trim. trim_order_events runs as the block leader. When the market's oldest events go, coverage_complete turns false and the volume holds. When the direct fill goes, the volume drops to 2000.
• Nothing traded. A market on a node with no order events returns one row of zeros with coverage 0 and false. A market that does not exist returns no row.
• Bad input. A NULL argument and an inverted window are refused.
• Index use. On a throwaway Postgres 16.8 with 175k synthetic events across 1,000 markets, a one-week read of one market went from a parallel sequential scan (21 ms) to a bitmap index scan on the new index (0.3 ms). The coverage minimum already reads the block_height index.
• Mutation check. I changed the SQL ten ways and a test caught each one: counting the sell row, the NO row of a mint or burn, or a split as volume; making either end of the window exclusive; leaving sellers out of the traders; taking the first fill time from any event; leaving empty coverage NULL; allowing an inverted window; and comparing coverage with the window instead of the market's creation.

kwil-cli utils parse accepts both migration files, and go vet -tags kwiltest ./tests/streams/order_book/ is clean.

Summary by CodeRabbit

• New Features
  • Added market activity reporting for a selected time window, including trading volume, direct and mint/burn activity, trader and fill counts, shares traded, and first and last event times.
  • Reports indicate whether event history is complete and the block where retained history begins. Existing markets with no matching trades return zero-valued totals; unknown markets return no result.
  • Reversed time windows and missing required inputs are rejected.

[holdex]

Time Submission Status

Member	#	Time	Running Total	Status	Last Update
MicBun			4h	✅ Submitted	Oct 8, 2026, 2:49 PM

---

Submit or update total time with:

@holdex pr submit-time 2h

Add time on top of previous submission with:

@holdex pr add-time 1h30m

See available commands to help comply with our Guidelines.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 769c6663-14bc-4046-9920-a217a63564c5

📥 Commits

Reviewing files that changed from the base of the PR and between b64fe03 and ca7bd3b.

📒 Files selected for processing (3)

• internal/migrations/044-order-book-events.sql
• internal/migrations/058-order-book-market-activity.sql
• tests/streams/order_book/market_activity_test.go

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

Adds an index for order-event time-window queries and a public get_market_activity action. The action returns market activity aggregates and retained-event coverage. Integration tests exercise its results, time filtering, coverage, and input handling.

Changes

Market activity query

Layer / File(s)	Summary
Indexed activity query internal/migrations/044-order-book-events.sql, internal/migrations/058-order-book-market-activity.sql	Adds an index on (query_id, block_timestamp) and the public get_market_activity action. The action validates inputs, aggregates matching events, and reports retained-event coverage.
Activity action integration tests tests/streams/order_book/market_activity_test.go	Tests activity totals, time-window filtering, coverage before and after event trimming, empty and unknown markets, and invalid inputs.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature · Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant get_market_activity
  participant ob_order_events
  Client->>get_market_activity: query_id and time window
  get_market_activity->>get_market_activity: validate required inputs and time window
  get_market_activity->>ob_order_events: aggregate matching market events
  ob_order_events-->>get_market_activity: event aggregates and retained-event coverage
  get_market_activity-->>Client: activity row or no row for an unknown market

Loading

Merge Risk: ⚪ Minimal · up to ca7bd

This adds a read-only market activity action and a supporting index. No concrete merge-blocking risk was found.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: adding a node action to read a market's volume and trader activity. It is concise and specific enough for pull request history.
Linked Issues check	✅ Passed	The PR satisfies the coding requirements in directly linked issue #1443, with the Goal context from #1429. Migration 058 adds the public get_market_activity($query_id, $from_ts, $to_ts) action and r…
Out of Scope Changes check	✅ Passed	The changed files stay within issue #1443. The index supports the new action, and the integration test verifies its required behavior. No unrelated product behavior or unrelated files appear in the re…
Docstring Coverage	✅ Passed	Docstring coverage is 91.67% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 12 functions across 1 files. (2 skipped: 2 …

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Commit to this branch
• Create a new PR

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

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

[MicBun]

@holdex pr submit-time 4h