#6. Implement SO4 Soroban Event Mappings

[IbrahimIjai]

Primary outcome: The indexer decodes SO4 Soroban contract events and keeps GraphQL entities in sync with protocol state transitions.

Background

The contracts emit short symbol topics and tuple payloads. Important events include mkt_new, dep_crt, dep_exe, dep_can, wth_crt, wth_exe, wth_can, ord_crt, ord_exe, ord_can, ord_upd, ord_frz, pos_inc, pos_dec, liq_req, liq_exe, adl_req, adl_exe, fee_clm, fnd_clm, ui_fee_acc, ui_fee_clm, ui_fee_set, ref_reg, ref_set, ref_xfr, token events, and faucet events.

Implementation checklist

• Replace the starter transfer-only handleEvent mapping with SO4 event dispatch.
• Add decoding helpers for symbol topics.
• Add decoding helpers for Soroban addresses.
• Add decoding helpers for BytesN<32> keys.
• Add decoding helpers for booleans.
• Add decoding helpers for signed and unsigned integer ScVal values.
• Add decoding helpers for tuple payloads emitted by SO4 contracts.
• Restrict handlers to configured SO4 contract IDs and token IDs from Issue 2.
• Implement mkt_new indexing from market_factory.
• Implement deposit lifecycle mappings for dep_crt, dep_exe, and dep_can.
• Implement withdrawal lifecycle mappings for wth_crt, wth_exe, and wth_can.
• Implement order lifecycle mappings for ord_crt, ord_exe, ord_can, ord_upd, and ord_frz.
• Implement position lifecycle mappings for pos_inc and pos_dec.
• Implement liquidation mappings for liq_req and liq_exe.
• Implement ADL mappings for adl_req and adl_exe.
• Implement fee mappings for fee_clm, fnd_clm, ui_fee_acc, ui_fee_clm, and ui_fee_set.
• Implement referral mappings for ref_reg, ref_set, and ref_xfr.
• Implement token/faucet mappings for transfers, mints, burns, approvals, and claims where useful to the app.
• Make entity writes idempotent so reprocessing a ledger does not duplicate rows.
• Store ledger, timestamp, event id, contract id, and transaction hash if SubQuery exposes them.
• Log and skip unknown events without crashing the indexer.

Acceptance checklist

• Mappings build under Bun.
• Unit tests cover at least one market event.
• Unit tests cover at least one deposit event.
• Unit tests cover at least one withdrawal event.
• Unit tests cover at least one order event.
• Unit tests cover at least one position event.
• Unit tests cover at least one liquidation or ADL event.
• Unit tests cover at least one fee or referral event.
• Unit tests cover at least one token or faucet event.
• Unknown or malformed events are handled safely with structured logs.
• Entity IDs are deterministic and documented.

Verification commands

• Run bun run --cwd apps/s03-indexer codegen.
• Run bun run --cwd apps/s03-indexer build.
• Run bun run --cwd apps/s03-indexer test.

[jerrymusaga]

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

Hi! Please I will like to work on this issue

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

[ositaemmanuel653-netizen]

@ositaemmanuel653-netizen has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

Hello maintainer allow me to resolve this issue for a swift and good result.

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

[0xMegie]

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

Gm gm sir, I'd like to take this on. This is the decode layer that ties the schema to real protocol state: replacing the starter's transfer-only handleEvent with an SO4 event dispatcher keyed on the short symbol topics (mkt_new, dep_, wth_, ord_, pos_, liq_, adl_, fee_clm/fnd_clm/ui_fee_, ref_, token/faucet). I'll build the ScVal decode helpers first — symbol topics, Soroban addresses, BytesN<32> keys, bools, signed/unsigned ints (preserving precision, no downcasting), and the tuple payloads — then restrict handlers to the configured contract + token IDs from the manifest sync so stray contracts don't leak in.
From there, the lifecycle mappings across all the events: market creation from market_factory, deposit/withdrawal create-execute-cancel, order create/execute/cancel/update/freeze, position inc/dec, liquidation req/exe, ADL req/exe, the fee + referral set, and token/faucet activity where it's useful to the app. Entity writes will be idempotent with deterministic, documented IDs so reprocessing a ledger never duplicates rows, and I'll persist ledger/timestamp/event id/contract id/tx hash where SubQuery exposes them. Unknown or malformed events get structured-logged and skipped rather than crashing the indexer. Tests will cover at least one event from each family (market, deposit, withdrawal, order, position, liquidation/ADL, fee/referral, token/faucet) plus the malformed-event path, and I'll verify codegen/build/test pass under Bun. Could you assign it to me?

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

[0xsteins]

Gm gm sir, I'd like to take this on. This is the decode layer that ties the schema to real protocol state: replacing the starter's transfer-only handleEvent with an SO4 event dispatcher keyed on the short symbol topics (mkt_new, dep_, wth_, ord_, pos_, liq_, adl_, fee_clm/fnd_clm/ui_fee_, ref_, token/faucet). I'll build the ScVal decode helpers first — symbol topics, Soroban addresses, BytesN<32> keys, bools, signed/unsigned ints (preserving precision, no downcasting), and the tuple payloads — then restrict handlers to the configured contract + token IDs from the manifest sync so stray contracts don't leak in.
From there, the lifecycle mappings across all the events: market creation from market_factory, deposit/withdrawal create-execute-cancel, order create/execute/cancel/update/freeze, position inc/dec, liquidation req/exe, ADL req/exe, the fee + referral set, and token/faucet activity where it's useful to the app. Entity writes will be idempotent with deterministic, documented IDs so reprocessing a ledger never duplicates rows, and I'll persist ledger/timestamp/event id/contract id/tx hash where SubQuery exposes them. Unknown or malformed events get structured-logged and skipped rather than crashing the indexer. Tests will cover at least one event from each family (market, deposit, withdrawal, order, position, liquidation/ADL, fee/referral, token/faucet) plus the malformed-event path, and I'll verify codegen/build/test pass under Bun. Could you assign it to me?

[0xsteins]

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

Good day, I’d love to take this on.

I'll replace the starter handleEvent with an SO4 dispatcher keyed on short symbol topics, starting with the ScVal decode helpers scoped to the manifest. From there, I'll map the full lifecycle (markets, orders, positions, fees) using idempotent writes and deterministic IDs to prevent duplicate rows during reprocessing. Malformed events will be gracefully logged to keep the indexer stable.

I'll wrap up by ensuring all event families and error paths build and pass tests under Bun. Could you assign this to me?

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

[drips-wave]

Congratulations, @0xsteins! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 30, 2026.

🧑‍💻 @0xsteins: 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 🌊

[grantfox-oss]

🦊 GrantFox — @0xsteins has been assigned to this issue as part of the Official Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #183)
2. Your PR will be reviewed by the SO4-Markets 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 campaign!

@0xsteins's PR #190 was approved and merged by @IbrahimIjai.

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

👏 Great work, @0xsteins! Keep contributing to SO4-Markets.