chore: filter attestations by hash and payload

[williamrusdyputra]

resolves: https://github.com/trufnetwork/trufscan/issues/141

Summary by CodeRabbit

• New Features

  • Added new attestation filters for attestation hash and canonical result to support more precise queries.

• Improvements

  • Prioritized multi-branch filtering with explicit ordering and LIMIT/OFFSET to ensure deterministic paging across filter combinations.

• Tests

  • Expanded test coverage to validate filtering by attestation hash and result canonical and adjusted test calls for the new parameters.

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

[coderabbitai]

Walkthrough

The list_attestations action signature was extended with two optional filters (attestation_hash, result_canonical) and the query was reworked into a prioritized branching: match request_tx_id → attestation_hash → result_canonical → requester → all records; tests updated to pass the new parameters.

Changes

Cohort / File(s)	Summary
Database action internal/migrations/024-attestation-actions.sql	Added parameters $attestation_hash BYTEA, $result_canonical BYTEA to list_attestations; implemented prioritized multi-branch filtering (request_tx_id → attestation_hash → result_canonical → requester → all), added explicit ORDER BY and LIMIT/OFFSET per branch, updated comments.
Tests tests/streams/attestation/attestation_retrieval_test.go	Added subtests and helpers to verify filtering by attestation_hash and result_canonical; updated all calls to list_attestations to include two extra nil placeholders and adjusted expectations/row counting accordingly.

Sequence Diagram(s)

sequenceDiagram
  participant Test as Tests
  participant DB as list_attestations action

  Test->>DB: call list_attestations(requester?, request_tx_id?, attestation_hash?, result_canonical?, limit, offset, order_by)
  alt request_tx_id provided
    DB-->>Test: SELECT ... WHERE request_tx_id = $request_tx_id ORDER BY created_height DESC, request_tx_id ASC LIMIT/OFFSET
  else attestation_hash provided
    DB-->>Test: SELECT ... WHERE attestation_hash = $attestation_hash ORDER BY created_height DESC, request_tx_id ASC LIMIT/OFFSET
  else result_canonical provided
    DB-->>Test: SELECT ... WHERE result_canonical = $result_canonical ORDER BY created_height DESC, request_tx_id ASC LIMIT/OFFSET
  else requester IS NULL
    DB-->>Test: SELECT ... (no requester filter) ORDER BY created_height {ASC|DESC} LIMIT/OFFSET
  else
    DB-->>Test: SELECT ... WHERE requester = $requester ORDER BY created_height {ASC|DESC} LIMIT/OFFSET
  end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Review focus: correctness of SQL branching precedence and WHERE conditions
• Verify ORDER BY / LIMIT/OFFSET are deterministic across branches
• Ensure test parameter positions and expectations correctly map to the new signature

Possibly related PRs

• chore: add stream info on attestation table #1259 — modifies the same migration and list_attestations action; overlaps in SQL/action changes.
• chore: compatibilize evm attestation integration #1218 — continues attestation-related schema/handler changes (canonical payload handling) and tests that interact with list_attestations.
• chore: filter attestation list by transaction id #1257 — earlier adjustments to list_attestations and tests around request_tx_id filtering.

Suggested reviewers

• MicBun

Poem

🐰 I nibble through query rows at night,
New hashes and payloads in gentle light,
A cascade of filters, tidy and bright,
Tests hop along, keeping paging right,
Cheers — the attestation meadow's in sight! 🌿

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ 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 accurately describes the main changes: adding filter functionality for attestations by hash and payload, matching the core changes in the migration and tests.
Linked Issues check	✅ Passed	The PR successfully implements filtering for attestations by attestation_hash and result_canonical (payload), directly addressing the requirement from issue #141 to enable searching by these fields.
Out of Scope Changes check	✅ Passed	All changes are directly related to implementing the new filtering functionality: migration updates the list_attestations procedure with new parameters, and tests validate the new filters without introducing unrelated modifications.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch chore/filter-by-hash-payload

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between eae6d4b and f57649c.

📒 Files selected for processing (1)

• tests/streams/attestation/attestation_retrieval_test.go (7 hunks)

🧰 Additional context used

🧠 Learnings (1)

📓 Common learnings

Learnt from: outerlook
Repo: trufnetwork/node PR: 1207
File: internal/migrations/024-attestation-actions.sql:58-76
Timestamp: 2025-10-10T13:00:14.189Z
Learning: In the attestation system for internal/migrations/024-attestation-actions.sql, the attestation_hash is computed from (version|algo|data_provider|stream_id|action_id|args) and intentionally excludes created_height. This design ensures the hash is deterministic based only on user input, not network state like block height.

Learnt from: outerlook
Repo: trufnetwork/node PR: 1207
File: internal/migrations/023-attestation-schema.sql:20-21
Timestamp: 2025-10-10T13:00:13.731Z
Learning: In the attestations table (internal/migrations/023-attestation-schema.sql), the primary key is (requester, created_height, attestation_hash) because attestation_hash is computed deterministically from user input only (version|algo|data_provider|stream_id|action_id|args) and does not include created_height. This allows the same user to request the same attestation at different block heights.

🧬 Code graph analysis (1)

tests/streams/attestation/attestation_retrieval_test.go (2)

tests/streams/attestation/test_helpers.go (3)

• InvalidTxID (35-35)
• AttestationTestHelper (77-82)
• TestAddresses (58-62)

tests/streams/utils/setup/common.go (1)

• NewEngineContext (36-38)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: acceptance-test

🔇 Additional comments (4)

tests/streams/attestation/attestation_retrieval_test.go (4)

136-142: LGTM! Well-structured test additions.

The new test subcases for filtering by attestation hash and result canonical are properly integrated into the test suite and follow the existing organizational pattern.

---

159-161: LGTM! Parameter updates are consistent and correct.

All existing test functions have been properly updated to accommodate the new list_attestations signature with attestation_hash and result_canonical filter parameters. The parameter ordering is consistent across all calls.

Also applies to: 169-183, 187-194, 206-230, 335-341, 344-346

---

232-267: LGTM! Comprehensive test coverage for attestation hash filtering.

The test properly validates:

• Filtering by a specific attestation hash returns the correct single result
• Different attestation hashes return different results
• Non-existent attestation hashes return no results

The test follows the established pattern and provides thorough coverage of the new filtering capability.

---

269-327: LGTM! Well-implemented test for result canonical filtering.

The test correctly validates filtering by result_canonical:

• Directly queries the database to fetch actual canonical values (necessary since they're not returned by helpers)
• Verifies filtering by each canonical value returns the correct attestation
• Tests non-existent canonical values return no results

The direct database access via h.platform.Engine.Execute is appropriate here since result_canonical values must be retrieved to test the filter functionality. Error handling is properly implemented.

---

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

[williamrusdyputra]

log: test passed on streams/

[holdex]

Time Submission Status

Member	Status	Time	Action	Last Update
williamrusdyputra	✅ Submitted	1h	Update time	Nov 20, 2025, 5:18 AM
MicBun	✅ Submitted	10min	Update time	Nov 20, 2025, 6:04 AM