chore: add timestamp to transaction event

[williamrusdyputra]

related: https://github.com/trufnetwork/trufscan/issues/125

Summary by CodeRabbit

Release Notes

• New Features

  • Added transaction timestamp (stampMs) field to transaction events, exposing millisecond timestamp from the block header.

• Documentation

  • Updated API reference and examples to include the new stampMs field in transaction event responses.

• Tests

  • Added validation checks to confirm the stampMs field is present in transaction event results.

[coderabbitai]

Walkthrough

This PR extends the TransactionEvent type with a stampMs field representing the millisecond timestamp from the block header. The implementation fetches this value from an external indexer during transaction event retrieval, adds supporting utilities, and updates documentation and tests accordingly.

Changes

Cohort / File(s)	Change Summary
Documentation Updates README.md, docs/api-reference.md	Added stampMs field to transaction event examples and console output; updated type documentation to describe millisecond timestamp sourced from block header via indexer lookup.
Type Definition src/types/transaction.ts	Added stampMs: number property to TransactionEvent interface with documentation noting indexer-based retrieval and fallback to 0.
Implementation src/contracts-api/transactionAction.ts	Introduced indexer integration utilities (INDEXER_BASE, normalizeTransactionId, fetchTransactionStampMs); enhanced getTransactionEvent to fetch and include stampMs in the returned payload; removed unused Types import.
Test Coverage tests/integration/transactionAction.test.ts	Added runtime assertions across four transaction tests to verify txEvent.stampMs exists and is greater than or equal to 0.

Sequence Diagram

sequenceDiagram
    participant Caller
    participant TransactionAction
    participant Indexer
    participant Blockchain
    
    Caller->>TransactionAction: getTransactionEvent(input)
    TransactionAction->>Blockchain: Validate block height
    Blockchain-->>TransactionAction: ✓ Valid
    
    rect rgba(100, 150, 200, 0.2)
    Note over TransactionAction,Indexer: New: Fetch stampMs from Indexer
    TransactionAction->>TransactionAction: normalizeTransactionId(txId)
    TransactionAction->>Indexer: fetchTransactionStampMs(txId)
    Indexer-->>TransactionAction: stampMs (or 0 if unavailable)
    end
    
    TransactionAction->>TransactionAction: Construct TransactionEvent with stampMs
    TransactionAction-->>Caller: TransactionEvent {stampMs, ...}

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20–25 minutes

• Focus areas for review:
  • Indexer integration logic in fetchTransactionStampMs and normalizeTransactionId utilities to ensure correct transaction ID normalization and API contract with external indexer
  • Error handling and fallback behavior when indexer is unavailable (verified to return 0)
  • Integration point in getTransactionEvent to ensure stampMs is fetched only when needed and properly included in response

Possibly related PRs

• PR #135: Extends the same TransactionAction.getTransactionEvent implementation and TransactionEvent type that this PR modifies.
• PR #133: Introduces and surfaces the stampMs timestamp sourced from the indexer in transaction-returning code paths.
• PR #140: Touches getTransactionEvent documentation and examples that are updated here.

Suggested labels

enhancement

Suggested reviewers

• MicBun
• outerlook

Poem

🐰 A timestamp now flows from indexer's deep well,
Milliseconds captured in each block's tale to tell,
Transactions adorned with their moment in time,
Stamped and validated—a journey sublime! ⏰✨

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 (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: adding a timestamp field to the transaction event object across the codebase.

✨ 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/add-transaction-event-timestamp

---

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 (5)

tests/integration/transactionAction.test.ts (1)

69-77: stampMs assertions are aligned with the fallback contract

Checking txEvent.stampMs >= 0 in these tests fits the documented behavior (real ms timestamp when available, 0 as sentinel when the indexer is unavailable) without making the tests brittle on indexer health.

If you ever want to assert indexer correctness separately, you could add a dedicated test that expects stampMs > 0 behind a flag or env check rather than tightening these core integration tests.

Also applies to: 120-130, 157-163

src/types/transaction.ts (1)

43-47: TransactionEvent.stampMs typing and docs look consistent

The stampMs: number field and its doc (“millisecond timestamp… 0 when indexer unavailable”) match the implementation in TransactionAction.getTransactionEvent and the API docs.

You might mirror this “0 when unavailable” clarification on LastTransaction.stampMs as well for consistency.

docs/api-reference.md (1)

509-520: API docs for stampMs are accurate; minor naming consistency nit

The stampMs description (“millisecond timestamp… 0 when unavailable”) and the example usage align with the public type and implementation.

For consistency with the README and to make units explicit, consider changing the example log line to something like:

-console.log(`Timestamp: ${txEvent.stampMs}`);
+console.log(`Timestamp (ms): ${txEvent.stampMs}`);

Also applies to: 537-542

src/contracts-api/transactionAction.ts (2)

1-41: Indexer integration helper is robust; consider configurability and reuse

The indexer helper (fetchTransactionStampMs) is defensive (handles non‑200s, malformed payloads, and network errors, all falling back to 0), which fits the documented stampMs contract.

• Make INDEXER_BASE configurable (e.g., via client config or env) so non‑mainnet/local setups can point at their own indexer instead of always hitting the infra URL.
• normalizeTransactionId here is identical to the one in tests/integration/utils.ts; consider centralising it in a shared utility to avoid drift.

---

168-182: stampMs fetch in getTransactionEvent matches the new API contract

Fetching stampMs after validating blockHeight and returning it alongside the existing fields cleanly extends getTransactionEvent without changing its error semantics; failures in the indexer path degrade to stampMs = 0 as documented.

Be aware this adds an extra HTTP round‑trip per getTransactionEvent call; if clients start calling this in tight loops, you may eventually want caching or a bulk/indexer endpoint to avoid N+1 patterns.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 9e8ab8b and d545854.

📒 Files selected for processing (5)

• README.md (1 hunks)
• docs/api-reference.md (2 hunks)
• src/contracts-api/transactionAction.ts (2 hunks)
• src/types/transaction.ts (1 hunks)
• tests/integration/transactionAction.test.ts (3 hunks)

🧰 Additional context used

🧬 Code graph analysis (1)

src/contracts-api/transactionAction.ts (1)

tests/integration/utils.ts (1)

• normalizeTransactionId (172-174)

⏰ 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: test

🔇 Additional comments (1)

README.md (1)

332-339: Adding stampMs to the README example looks good

The example now clearly surfaces the millisecond timestamp with an explicit (ms) label, which matches the new TransactionEvent.stampMs field.

[holdex]

Time Submission Status

Member	Status	Time	Action	Last Update
williamrusdyputra	✅ Submitted	1h	Update time	Nov 18, 2025, 8:27 AM
MicBun	✅ Submitted	15min	Update time	Nov 18, 2025, 5:51 PM

[williamrusdyputra]

the nitpick comments isn't necessarily important.

[MicBun]

Lgtm