Event Schema Hardening

[Robotron2]

Issue #20 — refactor: Event Schema Hardening

Description

Off-chain indexers and data lakes rely entirely on emitted contract events to track state. If events lack consistency (e.g., differing topic structures or payload types), indexers break. Hardening the event schema ensures predictable, reliable data feeds for the PadiPay backend.

---

Requirements & Context

Architectural Goal: Guarantee a deterministic, strict schema for all emitted events.

Implementation Expectations: Audit events.rs. Ensure that every event consistently places the primary identifier (EscrowId) as the first topic. Standardize the data payload shapes (e.g., passing explicit structs rather than loose tuple fragments) if appropriate.

---

Acceptance Criteria

• events.rs exposes a highly uniform structure.
• All emitted events conform to the standardized schema.
• Emitted events remain deterministic and parseable.

---

Out of Scope

• Changing the underlying event emission mechanisms of Soroban.

---

Suggested Execution

git checkout -b refactor/event-schema

---

Suggested Commit Message

refactor: standardize event emission payloads for indexer reliability

---

Testing Notes

• Verify test suites are updated to match the new event signatures.
• Perform manual event verification using soroban-cli if necessary to verify payload decoding.

---

References

Soroban env.events().publish() mechanics.
src/events.rs

---

Definition of Done

• Ready for review.

[Okorie2000-code]

Hi Maintainer,
I’d like to work on this issue. I understand the event schema requirements and will standardize event structures, ensure deterministic payloads, and update tests for reliable indexing. Kindly assign.

[Achievers-sketch]

Experienced designing deterministic Soroban event schemas, standardizing contract events for reliable indexing, improving type safety, and validating compatibility through comprehensive testing.

[connelevalsam]

Hello Maintainer, I have the exaact expereince to resolve this issue.
Please do assign this to me

[dumbdev]

Hi Maintainer, I'd like to work on this issue.
This is my approach:

Audit events.rs to catalog every emitted event, its current topic structure, and payload shape — flagging inconsistencies (e.g., events where EscrowId isn't the first topic, or loose tuple payloads instead of explicit structs)
Standardize the topic ordering so EscrowId is consistently the first topic across every event, ensuring indexers can reliably key off it
Where payloads use loose tuple fragments, refactor them into explicit, named structs so the schema is self-documenting and less error-prone to decode
Update env.events().publish() call sites accordingly, keeping the underlying Soroban emission mechanism unchanged (per the out-of-scope note)
Update existing tests to match the new event signatures, and add/adjust assertions to verify topic ordering and payload shape explicitly rather than loosely
Manually verify decoding with soroban-cli against a few emitted events to confirm the schema is deterministic and parseable end-to-end for the PadiPay backend indexers

I'm a blockchain developer with Soroban/Rust experience, including working directly with env.events().publish() and structuring on-chain events for downstream indexer consumption, so I understand both the contract-side mechanics and why schema consistency matters for off-chain reliability.
I can start immediately and expect to complete this within 1-2 days, covering the full audit, schema standardization across all events, test updates, and manual soroban-cli verification before marking it ready for review on branch refactor/event-schema.

[grantfox-oss]

🦊 GrantFox — @dumbdev has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #70)
2. Your PR will be reviewed by the Padi-Pay maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign | FWC26 campaign!

@dumbdev's PR #87 was approved and merged by @Robotron2.

🏆 @dumbdev: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (309 total points). Track your full progress on GrantFox.

👏 Great work, @dumbdev! Keep contributing to Padi-Pay.