chore: set up transaction input data tracking

[MicBun]

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

Summary by CodeRabbit

• New Features

  • Transaction ID tracking: records now include and propagate a transaction identifier across streams, events, taxonomies, and metadata.

• Tests

  • Added end-to-end test validating transaction ID propagation.
  • Updated attestation tests and helpers to exercise non-exempt user contexts and fee handling; adjusted related assertions.

• Chores

  • Schema updates and new indexes to store and optimize transaction ID tracking.

[coderabbitai]

Walkthrough

Adds transaction identifier tracking: a new tx_id TEXT column plus indexes on streams, primitive_events, taxonomies, and metadata; INSERT paths now populate tx_id from @txid. Tests and test helpers added/updated to validate propagation and non-exempt contexts.

Changes

Cohort / File(s)	Summary
Schema Initialization internal/migrations/000-initial-data.sql	Added tx_id TEXT columns to streams, primitive_events, taxonomies, and metadata. Created indexes: streams_tx_id_idx, pe_tx_id_idx, tax_tx_id_idx, meta_tx_id_idx. Added header comment describing purpose.
Insert Operation Updates internal/migrations/001-common-actions.sql, internal/migrations/003-primitive-insertion.sql, internal/migrations/004-composed-taxonomy.sql	Updated INSERTs across stream creation, metadata insert/disable flows, primitive event insertion, and taxonomy composition to include tx_id populated from @txid. Public action signatures unchanged.
Tests and Test Helpers tests/streams/transaction_events_ledger_test.go, tests/streams/attestation/test_helpers.go, tests/streams/attestation/attestation_max_fee_test.go, tests/streams/attestation/attestation_request_test.go, tests/streams/attestation/request_attestation_fee_test.go	Added TestTransactionIDTracking and runTransactionIDTrackingScenario to assert tx_id propagation. Added NewNonExemptContext helper. Adjusted attestation tests to use non-exempt contexts and updated fee/expectation handling for exempt vs non-exempt users.

Sequence Diagram(s)

sequenceDiagram
    participant Client
    participant Action
    participant TxCtx as TransactionContext
    participant DB as Database

    Client->>Action: invoke write action
    Note right of TxCtx: assign `@txid` for transaction
    Action->>DB: INSERT ... INTO `streams` (..., tx_id = `@txid`)
    Action->>DB: INSERT ... INTO `primitive_events` (..., tx_id = `@txid`)
    Action->>DB: INSERT ... INTO `taxonomies` (..., tx_id = `@txid`)
    Action->>DB: INSERT ... INTO `metadata` (..., tx_id = `@txid`)
    rect rgb(235,245,255)
      Note right of DB: indexes on tx_id allow cross-table lookup
    end
    DB-->>Action: commit
    Client->>DB: SELECT ... WHERE tx_id = <id>
    DB-->>Client: rows from streams, primitive_events, taxonomies, metadata

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

• Verify tx_id column types/nullability and index definitions in 000-initial-data.sql.
• Confirm every INSERT in 001-common-actions.sql, 003-primitive-insertion.sql, and 004-composed-taxonomy.sql includes tx_id sourced from @txid.
• Inspect new test TestTransactionIDTracking for assertions and any timing/race assumptions.
• Review NewNonExemptContext for correct context/authenticator and balance setup.

Possibly related PRs

• chore: implement usage-based pricing for data insertion #1246 — Modifies same SQL write paths; related due to overlapping insert flows and fee-related changes.
• chore: add taxonomies creation fees #1248 — Touches composed-taxonomy insert path; related to taxonomy insert changes and fee/exemption logic.
• chore: add transaction ledger schema and helper actions #1254 — Implements transaction-level recording/hooks; closely related to adding tx_id propagation.

Suggested reviewers

• outerlook
• williamrusdyputra

Poem

🐰
I hop through rows and indices bright,
Leaving tx_id trails by starlit night,
From streams to taxonomies' door,
Metadata lined along the floor,
A little rabbit counts each store.

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 57.14% 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 change: adding transaction ID (tx_id) column and indexes to track transaction input data across multiple database tables.
Linked Issues check	✅ Passed	The PR adds tx_id tracking infrastructure to database tables (streams, primitive_events, taxonomies, metadata) and corresponding tests, which provides the foundation for viewing transaction input data as required by issue #134.
Out of Scope Changes check	✅ Passed	All changes are directly related to transaction tracking: database schema updates add tx_id columns, migration scripts propagate tx_id values, tests validate tracking functionality, and test helper updates support non-exempt user testing—all in scope.

✨ 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 trackTransaction

---

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

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

tests/streams/attestation/attestation_request_test.go (1)

136-174: Consider renaming function to reflect the actual test scenario.

The function name runAttestationUnauthorizedBlocked suggests authorization/role-based failure, but the test now validates insufficient balance failure for non-exempt users. This mismatch could confuse future maintainers.

Consider renaming to something like runAttestationInsufficientBalanceBlocked or runAttestationNonExemptUserWithoutBalance:

-func runAttestationUnauthorizedBlocked(t *testing.T, ctx context.Context, platform *kwilTesting.Platform, helper *AttestationTestHelper, actionName string) {
-	// Create a non-exempt user that does NOT have network_writer role (must pay 40 TRUF fee)
+func runAttestationInsufficientBalanceBlocked(t *testing.T, ctx context.Context, platform *kwilTesting.Platform, helper *AttestationTestHelper, actionName string) {
+	// Create a non-exempt user without balance (cannot pay 40 TRUF fee)

And update the call site on line 43:

 t.Run("UnauthorizedUserBlocked", func(t *testing.T) {
-	runAttestationUnauthorizedBlocked(t, ctx, platform, helper, testActionName)
+	runAttestationInsufficientBalanceBlocked(t, ctx, platform, helper, testActionName)
 })

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between ad0577f and af1a4cc.

📒 Files selected for processing (2)

• tests/streams/attestation/attestation_request_test.go (3 hunks)
• tests/streams/attestation/request_attestation_fee_test.go (5 hunks)

🧰 Additional context used

🧬 Code graph analysis (1)

tests/streams/attestation/attestation_request_test.go (1)

extensions/tn_utils/serialization.go (1)

• EncodeActionArgs (45-76)

⏰ 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). (2)

• GitHub Check: lint
• GitHub Check: acceptance-test

🔇 Additional comments (6)

tests/streams/attestation/attestation_request_test.go (1)

137-174: Clarify the relationship between fee changes and transaction tracking.

The PR title indicates "set up transaction input data tracking" and the AI summary mentions tx_id column additions, but this test file only contains updates related to non-exempt user fee enforcement. The connection between fee changes and transaction data tracking is not evident from the code or comments.

Please clarify:

1. Are the fee enforcement changes a prerequisite for transaction tracking functionality?
2. Should this test file include validation of tx_id propagation in attestation requests?
3. Are these separate features that should be in different PRs?

tests/streams/attestation/request_attestation_fee_test.go (5)

104-104: LGTM!

The comment update accurately reflects the shift from network_writer role-based exemption to non-exempt user fee enforcement.

---

105-135: LGTM!

The test correctly validates non-exempt user fee behavior: grants 100 TRUF, requests attestation, and verifies 40 TRUF deduction. Comments accurately explain the non-exempt context.

---

138-157: LGTM!

The test properly validates insufficient balance scenario: grants only 10 TRUF and confirms attestation fails with appropriate error message.

---

160-195: LGTM!

The test effectively validates cumulative fee charging: 3 attestations with different time ranges correctly deduct 120 TRUF total (3 × 40). The use of varied time ranges to generate unique attestation hashes is a good testing practice.

---

198-277: LGTM!

Both test functions are well-designed:

• testAttestationLeaderReceivesFees correctly validates fee transfer to the block leader
• testAttestationBalanceCorrectlyDeducted provides excellent edge case coverage by testing exact balance consumption (80 TRUF for 2 attestations, then failure on 3rd)

The test logic and balance arithmetic are accurate throughout.

[holdex]

Time Submission Status

Member	Status	Time	Action	Last Update
MicBun	✅ Submitted	8h	Update time	Nov 18, 2025, 6:37 PM
williamrusdyputra	✅ Submitted	10min	Update time	Nov 18, 2025, 6:37 PM