DX-086: Document the SyntheticsReader contract

[IbrahimIjai]

Context

SyntheticsReader is the read path integrators will use most: positions, market
state, and derived values without reconstructing them from raw storage. Getting
its units and scaling right is the difference between a working integration and
one that is off by six decimal places.

Scope

• The contract's role and when to use it instead of DataStore.
• Every read function with parameters, return shapes, and errors, following the
  DX-084 template.
• Decimal scaling for every returned value, stated explicitly, with a conversion
  helper example.
• Worked examples: reading a position, reading market state, computing a
  liquidation price from returned values.
• Cross-links to the concept pages that explain what the numbers mean.

Acceptance criteria

• Function coverage asserted against the generated bindings.
• Every returned numeric value has its scale documented.
• The liquidation-price example agrees with what the interface displays for
  the same position.
• Uses <ParamTable> consistently.

Out of scope

• Indexer-based reads (DX-088).

---

Spec: docs/dx_1/003_content_map.md §2 · Depends on: DX-085

[OmniZlatoon]

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

Good day sir, Ready to deliver the task A.S.A.P. Gone through the issue and to be honest, i can work the task with the right tools at hand. please assign me maintainer . My eta is 5 hours

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

[doncross03]

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

Hello Maintainer, after reviewing the issue, I believe I can provide an effective solution that aligns with the project's standards and acceptance criteria. Kindly consider assigning it to me

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

[Olasunkanmi975]

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

I have a solid understanding of the underlying architecture required for this task and am ready to start testing a solution immediately.

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

[badmusdare4]

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

Hello maintainer, I understand the problem scope and can provide the required solution while meeting acceptance criteria. Kindly consider assigning this issue to me.

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

[Oluwatomilola]

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

I can fix this, kindly assign.

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

[drips-wave]

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

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