# 5. Replace the Starter GraphQL Schema With SO4 Protocol Entities

[IbrahimIjai]

Primary outcome: The SubQuery schema models SO4 markets, pools, orders, positions, fees, referrals, and protocol events.

Background

The current starter schema indexes generic accounts, payments, credits, debits, and transfer events. SO4 needs protocol entities based on real contract events and market state: mkt_new, dep_*, wth_*, ord_*, pos_*, liq_*, adl_*, fee/referral events, and token/faucet activity.

Implementation checklist

• Replace or extend apps/s03-indexer/schema.graphql with SO4-specific entities.
• Add market and token metadata entities: ProtocolContract, Token, Market, and MarketConfigSnapshot.
• Add liquidity lifecycle entities: Deposit, Withdrawal, PoolBalanceSnapshot, and MarketTokenTransfer.
• Add trading lifecycle entities: Order, Position, PositionChange, Liquidation, and AdlEvent.
• Add fee/referral entities: FeeClaim, UiFeeAccrual, FundingFeeClaim, ReferralCode, TraderReferral, and ReferralOwnershipTransfer.
• Add useful indexed fields for app filters: account, market, key, status, ledger, timestamp, and transaction hash where available.
• Preserve numeric precision by storing protocol-scale values as BigInt or strings where needed.
• Do not downcast USD 1e30 values to JavaScript numbers in mappings.
• Add schema comments explaining which contract event feeds each entity.
• Remove starter-only entities unless they are intentionally still used for token/payment observability.

Acceptance checklist

• subql codegen succeeds with the new schema.
• Generated types are committed if the project convention requires them.
• The schema can represent market creation.
• The schema can represent deposit create, execute, and cancel.
• The schema can represent withdrawal create, execute, and cancel.
• The schema can represent order create, update, freeze, execute, and cancel.
• The schema can represent position increase, decrease, close, liquidation, and ADL reduction.
• The schema can represent fee claim and referral registration flows.

Verification commands

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

[Kaybee973]

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

Hello maintainer, I am qualified to resolve this issue and would like to work on this issue

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

[DTriple-p]

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

Hi, I'd like to work on this issue.

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

[martinshub-tech]

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

I'd like to take this issue. I've analyzed the root cause and am confident I can deliver a reliable fix with proper testing

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

[stacyelliott492-star]

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

HELLO DEAR I WOULD LOVE TO WORK ON THIS ISSUE PLEASE HELP THE NEEDY

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

[madisonsc52-del]

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

Hi maintainer i can work on this, I'll make sure to work on the issue asap

ℹ️ Repo Maintainers: To accept this application, review their application or assign @madisonsc52-del 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. The goal is to swap the starter's generic accounts/payments/transfers schema for SO4 protocol entities driven by the real contract events (mkt_new, dep_, wth_, ord_, pos_, liq_, adl_, fee/referral, token/faucet). I'll model the three lifecycles in schema.graphql: metadata (ProtocolContract, Token, Market, MarketConfigSnapshot), liquidity (Deposit, Withdrawal, PoolBalanceSnapshot, MarketTokenTransfer), and trading (Order, Position, PositionChange, Liquidation, AdlEvent), plus fees/referrals (FeeClaim, UiFeeAccrual, FundingFeeClaim, ReferralCode, TraderReferral, ReferralOwnershipTransfer).
I'll add indexed fields for the common app filters (account, market, key, status, ledger, timestamp, tx hash where available), store protocol-scale values as BigInt/strings so USD 1e30 magnitudes never get downcast to JS numbers in mappings, and comment each entity with the contract event that feeds it. Starter-only entities get removed unless kept intentionally for token/payment observability. I'll make sure the schema covers the full state transitions called out — market creation, deposit/withdrawal create-execute-cancel, order create/update/freeze/execute/cancel, position increase/decrease/close/liquidation/ADL, and fee-claim + referral registration — and verify codegen and build both pass, committing generated types if the repo convention requires. Could you assign it to me?

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

[0xsteins]

Hi — I'd like to take this on. The goal is to swap the starter's generic accounts/payments/transfers schema for SO4 protocol entities driven by the real contract events (mkt_new, dep_, wth_, ord_, pos_, liq_, adl_, fee/referral, token/faucet). I'll model the three lifecycles in schema.graphql: metadata (ProtocolContract, Token, Market, MarketConfigSnapshot), liquidity (Deposit, Withdrawal, PoolBalanceSnapshot, MarketTokenTransfer), and trading (Order, Position, PositionChange, Liquidation, AdlEvent), plus fees/referrals (FeeClaim, UiFeeAccrual, FundingFeeClaim, ReferralCode, TraderReferral, ReferralOwnershipTransfer).
I'll add indexed fields for the common app filters (account, market, key, status, ledger, timestamp, tx hash where available), store protocol-scale values as BigInt/strings so USD 1e30 magnitudes never get downcast to JS numbers in mappings, and comment each entity with the contract event that feeds it. Starter-only entities get removed unless kept intentionally for token/payment observability. I'll make sure the schema covers the full state transitions called out — market creation, deposit/withdrawal create-execute-cancel, order create/update/freeze/execute/cancel, position increase/decrease/close/liquidation/ADL, and fee-claim + referral registration — and verify codegen and build both pass, committing generated types if the repo convention requires. Could you assign it to me?

[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 #182)
2. Your PR will be reviewed by the SO4-Markets maintainers

Good luck! Track your progress on GrantFox.