feat: rank a token's wallets by balance

[MicBun]

What

Adds a read-only get_ordered_balances action (migration 053, dev + prod twin) that returns a token's wallets ordered by balance — a richlist.

Why

Backs trufscan #185. There was no way to ask the node for a token's largest (or smallest) holders — only per-wallet balance lookups existed. This reads the per-token balance ledger kwil_erc20_meta.balances directly and returns it ordered.

Interface

get_ordered_balances($token TEXT, $ascending BOOL=false, $limit INT=20, $min_balance NUMERIC(78,0)=NULL)
  -> TABLE(address TEXT, balance NUMERIC(78,0))

• $token: 'TRUF' | 'USDC' (case-insensitive) → resolved to a reward_id via the bridge alias's id() (dev hoodi_tt/hoodi_tt2, mainnet eth_truf/eth_usdc — hence the dev/prod twin).
• $limit is hard-capped at 50; balance/$min_balance are token base units; addresses are 0x-lowercase hex.

Notes

• New PUBLIC VIEW read only (no ALTER, no writes) — safe to apply against a live, settling node.
• First migration to SELECT across the kwil_erc20_meta namespace; the engine allows it (privilege checks are bypassed inside action bodies) and it's validated end-to-end below.

Test

tests/streams/order_book/richlist_test.go — 7 cases: descending, ascending, limit (top-N + a >50 request clamps, doesn't error), threshold, TRUF/USDC instance isolation, unknown-token error, and empty. All pass.

Related

• resolves: trufnetwork/trufscan#185

Summary by CodeRabbit

• New Features
  • Added a read-only get_ordered_balances rich list for TRUF and USDC token balances.
  • Supports ascending/descending ordering, $limit clamped to 1–50, and optional minimum-balance filtering.
  • Returns wallet addresses (hex 0x…) with balances and rejects unsupported tokens.
• Tests
  • Added end-to-end coverage for ordering, limit clamping, filtering, TRUF/USDC isolation, empty results, and invalid token requests.

[holdex]

Time Submission Status

Member	#	Time	Running Total	Status	Last Update
MicBun			4h	✅ Submitted	Jul 17, 2026, 5:04 AM

---

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: Pro

Run ID: 039c630a-8170-4736-b9b2-ffe89fcf7d1b

📥 Commits

Reviewing files that changed from the base of the PR and between ff1483f and 908fd80.

📒 Files selected for processing (2)

• internal/migrations/053-order-book-richlist.prod.sql
• internal/migrations/053-order-book-richlist.sql

🚧 Files skipped from review as they are similar to previous changes (2)

• internal/migrations/053-order-book-richlist.sql
• internal/migrations/053-order-book-richlist.prod.sql

---

📝 Walkthrough

Walkthrough

Adds the public get_ordered_balances action for TRUF and USDC, supporting sorting, limits, minimum balances, encoded addresses, and validation through bridge-backed schema tests.

Changes

Ordered balances richlist

Layer / File(s)	Summary
Richlist action contract and token resolution internal/migrations/053-order-book-richlist.sql	Defines the public action, return table, supported token aliases, and unsupported-token error behavior.
Balance filtering and ordered output internal/migrations/053-order-book-richlist.sql, internal/migrations/053-order-book-richlist.prod.sql	Clamps limits to 1–50, applies optional minimum balances, orders matching ERC20 balances, and returns hex-encoded addresses.
Schema setup and behavior validation tests/streams/order_book/richlist_test.go	Tests ordering, limits, thresholds, token isolation, address encoding, invalid tokens, and empty results using seeded bridge balances.

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

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant get_ordered_balances
  participant kwil_erc20_meta_balances
  Caller->>get_ordered_balances: Submit token and query options
  get_ordered_balances->>kwil_erc20_meta_balances: Filter and order matching balances
  kwil_erc20_meta_balances-->>get_ordered_balances: Return balance rows
  get_ordered_balances-->>Caller: Return addresses and balances

Loading

Suggested labels: type: feat

Suggested reviewers: pr-time-tracker

🚥 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 is concise and accurately summarizes the main change: ranking token wallets by balance.
Linked Issues check	✅ Passed	The new public action meets the requested TRUF/USDC ordering, limit, threshold, and richlist query behavior.
Out of Scope Changes check	✅ Passed	The changes stay focused on the richlist action and its tests, with no unrelated feature or schema work.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/ordered-token-balances

---

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

[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 `@internal/migrations/053-order-book-richlist.sql`:
- Around line 63-83: Update both rich-list migration files,
internal/migrations/053-order-book-richlist.sql lines 63-83 and
internal/migrations/053-order-book-richlist.prod.sql lines 58-78, by adding
address ASC as a secondary sort key to both ascending and descending balance
ORDER BY clauses. Keep the existing balance direction and LIMIT behavior
unchanged.

🪄 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: a7b03347-0e7c-49fd-a83e-3424e6907a30

📥 Commits

Reviewing files that changed from the base of the PR and between b548cf0 and ff1483f.

📒 Files selected for processing (3)

• internal/migrations/053-order-book-richlist.prod.sql
• internal/migrations/053-order-book-richlist.sql
• tests/streams/order_book/richlist_test.go