Recent Escrow Events Viewer (Last 7 Days)

[techrebelgit]

Product: Escrow Viewer (Astro-based dApp)
Type: Feature · On-chain Observability
Difficulty: Medium → Hard
Track: Soroban · Stellar RPC · Transparency
Repo: Escrow Viewer repository

---

Overview

Add a “Recent Events” section to the Escrow Viewer that shows Soroban contract events emitted by the escrow in the last 7 days, if any.

This feature uses Stellar RPC (getEvents) directly and is intentionally limited to recent history due to RPC retention constraints.

---

Context

Soroban smart contracts can emit events, which are queryable via Stellar RPC using the getEvents method.

However:

• RPC nodes only retain event data for ~7 days
• Full historical event data requires ingestion or an indexer
• Trustless Work is building an indexer, but it is out of scope here

This task implements a best-effort, real-time event view for escrow contracts.

---

Goal

Allow users to:

“See what happened recently on this escrow contract.”

Examples:

• Milestone updates
• Releases
• Disputes
• Other escrow-related events (if emitted)

---

Data Source (Required)

Use Stellar RPC:

• Method: getEvents

• Network-aware (testnet / mainnet)

• Filter by:

  • contractIds: [escrowContractId]
  • type: "contract"

⚠️ Do not ingest or persist events.

---

Important Constraints (Non-Negotiable)

🚨 This feature must be read-only and ephemeral.

• ❌ No database
• ❌ No cron jobs
• ❌ No Prisma / SQLite
• ❌ No ingestion logic
• ❌ No guarantees beyond ~7 days

This is not an indexer.

---

UI Requirements

Section Placement

WE have a View transaction history button on the viewer that open a Modal where this was supposed to be. You can modify it or add

• Add a new section in the Escrow Viewer:

  • Title: Recent Contract Events
  • Subtitle: Last 7 days (RPC-limited)

---

Event Display

For each event, show (best-effort):

• Event type
• Ledger number
• Event ID
• Topics (decoded if possible, raw base64 otherwise)
• Value (decoded if possible, raw base64 otherwise)

Order:

• Most recent first

---

Empty & Error States

• If no events found:

  “No contract events found in the last 7 days.”

• If RPC fails:

  “Unable to fetch recent events from Stellar RPC.”

---

Disclosure (Important UX)

Include a clear note:

“This view shows only events available via Stellar RPC (last ~7 days).
Historical events will be available in future versions.”

---

Technical Expectations

• Use @stellar/stellar-sdk RPC client
• Use existing network configuration (testnet / mainnet)
• Contract ID must come from the currently loaded escrow
• Keep logic isolated and readable

Decoding:

• Decode topics / values only if safe and simple
• It’s acceptable to show base64 for unknown structures

---

Functional Requirements

• Queries Stellar RPC using getEvents
• Filters by escrow contract ID
• Handles testnet and mainnet correctly
• Displays recent events (if any)
• Handles empty and error states gracefully
• No persistence or ingestion

---

Developer Workflow (required)

• Create a new branch:

feature/recent-escrow-events

• Open a PR into main

• Include:

  • Screenshot of the events section
  • Screenshot of empty state (if applicable)
  • Short explanation of RPC approach

---

Acceptance Criteria

• Events load correctly when available
• UI clearly communicates limitations
• Viewer remains performant
• No backend or storage added
• No regressions elsewhere in Viewer

---

Learning Outcomes (why this task exists)

By completing this task, contributors will learn:

• How Soroban contract events work

• How to use Stellar RPC getEvents

• Why event retention matters

• The difference between:

  • RPC queries
  • Indexers
  • Ingestion pipelines

• How to design honest, limitation-aware UX in Web3

---

Notes for Contributors

This task values:

• correctness
• clarity
• restraint

It is OK to:

• show raw data when decoding is unclear
• document limitations

It is NOT OK to:

• build an indexer
• over-engineer persistence
• hide the 7-day limitation

---

✅ Ideal for contributors who want to:

• Learn Soroban deeply
• Work with Stellar RPC
• Understand on-chain observability
• Build transparent Web3 UX

[drips-wave]

This issue has been added to the Stellar Wave Program and is worth 200 Points.

🧑‍💻 Interested in contributing? Apply to work on this issue on Drips Wave, earn points, and receive rewards.

🤠 Repo maintainers: You can manage this issue's Points and Complexity on your Maintainer Dashboard here. Please keep an eye on applications and respond quickly 💙

ℹ️ Learn more about Drips Wave

[yhoungdev]

Hey @techrebelgit its me again, glad i saw this issue, and i have been contributing to escrow-viewer in the past.

I’d like to take on the “Recent Contract Events” feature: use @stellar/stellar-sdk RPC getEvents (network-aware), filter by the active escrow contract ID, show event type/ledger/event ID/topics/value (decoded when safe), newest-first, with clear empty/error states and the 7‑day RPC disclosure.

I’ll open a feature/recent-escrow-events branch and PR with a prove of screenshots, thank you.

[bitstarkbridge]

@bitstarkbridge has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

I’d like to work on this issue because it aligns closely with the kind of problems I enjoy solvingsystems that require careful logic, reliability, and attention to edge cases. I’m particularly motivated by issues where correctness and security matter, not just making something “work,” but making it production-ready

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

[Villarley]

@Villarley has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

Hey Alberto i'm Santiago Villarreal Full stack and smart contract dev in stellar ecosystem. would love to tackle on this one!

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

[Jayrodri088]

@Jayrodri088 has applied to work on this issue as part of the Stellar Wave Program's 1st wave.

Hello @techrebelgit Can I take this issue?

I'm a developer with a solid background in Web3, working across both front-end and back-end. You can check out my profile to see my contributions to the most important projects within the Stellar ecosystem.

Additionally, I have experience working in other ecosystems such as StarkNet, Optimism, and Worldcoin, and I have already contributed multiple times to Akkuea, Offer-Hub and kindifi.

My ETA on this issue will be 17 hours

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

[drips-wave]

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

🧑‍💻 @bitstarkbridge: 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.

⚠️ Important: When opening a PR, please link it to this issue to ensure it gets tracked accurately.

🤠 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 🌊

[bitstarkbridge]

please can you merged my pr it has be 4 days now