Route EscrowMonitor's swallowed handler/polling errors through SDKLogger with an onError hook

[meshackyaro]

Description

This issue aims to address the implementation of onError Hook for EscrowMonitor.

The core objective is to: Give EscrowMonitor (src/escrow/monitor.ts) a way to surface polling and handler errors — via the SDK's existing SDKLogger (src/utils/logger.ts) and an optional onError callback — instead of silently discarding them. EscrowMonitor.startPolling currently does const events = await fetchFn().catch(() => []) — any error from the caller-supplied fetchFn (e.g. a network failure fetching events) is silently swallowed and polling just continues with an empty event list, with no way for the consumer to know a poll failed. Handler errors are only slightly better surfaced: Promise.resolve(h(event)).catch(console.error) logs to raw console.error with no prefix/timestamp/structure, bypassing the SDK's own SDKLogger (currently unused anywhere per a companion issue) entirely, and gives the consumer no way to react.

By completing this feature, we will ensure that the TrustFlow protocol maintains its high standards for security, usability, and decentralized logic. This issue requires careful attention to the SDK Wrapper architecture and adherence to the existing project conventions.

Component

SDK

Difficulty

🟡 Medium

Tasks

• Review existing Typescript classes (EscrowMonitor)
• Implement SDK method for: an optional onError(error, context) callback on EscrowMonitor, invoked for both fetchFn failures and handler failures
• Replace the raw console.error call with the SDK's logger (or make logging pluggable via the same mechanism)
• Update typedoc comments for the new feature
• Write Jest tests validating both the fetchFn-failure and handler-failure paths invoke onError

Acceptance Criteria

• Feature accurately implements the objective above
• Existing polling/handler behavior is unchanged for consumers that don't opt into onError
• Any PR that introduces TypeScript errors is automatically blocked
• Code is properly reviewed and approved by codeowners

Estimated Time

1-2 days

[mazzam2006]

@mazzam2006 has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

I can handle this, let me take it on.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @mazzam2006 to this issue.

[Priyanshu1-62]

@Priyanshu1-62 has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

Hi maintainers,
Please assign this issue to me.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Priyanshu1-62 to this issue.

[PEPPERITO23]

@PEPPERITO23 has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

I've reviewed the issue thoroughly and can start working on it right away. Looking forward to contributing

ℹ️ Repo Maintainers: To accept this application, review their application or assign @PEPPERITO23 to this issue.

[akansmafengadamu]

@akansmafengadamu has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

Hi Maintainer please I will like to work on this issue

ℹ️ Repo Maintainers: To accept this application, review their application or assign @akansmafengadamu to this issue.

[connelevalsam]

@connelevalsam has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

I like this project and would like to work on this.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @connelevalsam to this issue.

[drips-wave]

Congratulations, @connelevalsam! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on August 31, 2026.

🧑‍💻 @connelevalsam: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊