#9 Add Full Local Integration Docs, Checks, and Handoff

[IbrahimIjai]

Primary outcome: A new contributor can run contracts, indexer, and web locally using one documented path with automated checks.

Background

The final integration should not live in someone's terminal history. A contributor should be able to clone the repos, follow the docs, run the commands, and see web UI data sourced from local indexed contract activity.

Implementation checklist

• Add a top-level integration guide under docs/, for example docs/local-full-stack.md.
• Document prerequisites: Bun, Docker, Stellar CLI, Rust/Soroban target, and local/testnet key setup.
• Document how to build contracts.
• Document how to deploy and bootstrap contracts.
• Document how to sync manifests into the indexer.
• Document how to start indexer services.
• Document how to run the local smoke scenario.
• Document how to start the web app.
• Document how to verify GraphQL data.
• Document how to verify the UI is reading indexed data.
• Add troubleshooting for missing .deployed/<network>.env.
• Add troubleshooting for wrong network passphrase.
• Add troubleshooting for stale market token IDs.
• Add troubleshooting for SubQuery database readiness.
• Add troubleshooting for the indexer being behind latest ledger.
• Add troubleshooting for missing local token balances or approvals.
• Add CI or local check scripts for indexer codegen/build.
• Add CI or local check scripts for web typecheck/build.
• Add CI or local check scripts for manifest sync validation with fixture deployment files.
• Add CI or local check scripts for mapping unit tests.
• Add fixture deployment files for tests that do not require live Stellar access.
• Include a final definition-of-done checklist for the complete local integration.

Acceptance checklist

• A new contributor can follow the guide and get contracts, indexer, and web app running locally.
• CI or local scripts catch schema, mapping, and config regressions before review.
• The final guide includes expected URLs for web, SubQuery GraphQL, Postgres, Horizon/RPC, and Docker services.
• The final local smoke report can be compared against what appears in the UI.
• The docs clearly separate local, testnet, and future mainnet behavior.

Verification commands

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

[matieuu1]

right now a new contributor has to piece together contracts, indexer, and web from scattered instructions and trial-and-error, when a single documented path with automated checks would save them days. I'll write docs/local-full-stack.md covering prerequisites through verification, add CI scripts for regressions, and ensure someone following it sees indexed data in the UI working end-to-end.

[0xsteins]

Gm gm sir, I'd like to take this on. The goal is a single documented path so a new contributor can clone, follow the guide, and see the web UI rendering data sourced from locally indexed contract activity — not reconstruct it from someone's terminal history. I'll add docs/local-full-stack.md covering prerequisites (Bun, Docker, Stellar CLI, Rust/Soroban target, key setup) and the full sequence: build → deploy/bootstrap contracts → sync manifests → start indexer services → run the local smoke scenario → start web → verify GraphQL → confirm the UI is reading indexed data, with expected URLs for web, SubQuery GraphQL, Postgres, Horizon/RPC, and Docker services.
I'll write the troubleshooting section against the real failure modes (missing .deployed/.env, wrong network passphrase, stale market token IDs, SubQuery DB readiness, indexer behind latest ledger, missing local balances/approvals) and keep local/testnet/future-mainnet behavior clearly separated. For the automated checks: scripts (CI or local) for indexer codegen/build, web typecheck/build, manifest-sync validation against committed fixture deployment files, and mapping unit tests — the fixtures letting those run without live Stellar access. I'll close with a definition-of-done checklist and verify all six commands (bun install, indexer codegen/build/test, web typecheck/build) pass from a clean checkout. Could you assign it to me?

[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 a single documented path so a new contributor can clone, follow the guide, and see the web UI rendering data sourced from locally indexed contract activity — not reconstruct it from someone's terminal history. I'll add docs/local-full-stack.md covering prerequisites (Bun, Docker, Stellar CLI, Rust/Soroban target, key setup) and the full sequence: build → deploy/bootstrap contracts → sync manifests → start indexer services → run the local smoke scenario → start web → verify GraphQL → confirm the UI is reading indexed data, with expected URLs for web, SubQuery GraphQL, Postgres, Horizon/RPC, and Docker services.
I'll write the troubleshooting section against the real failure modes (missing .deployed/.env, wrong network passphrase, stale market token IDs, SubQuery DB readiness, indexer behind latest ledger, missing local balances/approvals) and keep local/testnet/future-mainnet behavior clearly separated. For the automated checks: scripts (CI or local) for indexer codegen/build, web typecheck/build, manifest-sync validation against committed fixture deployment files, and mapping unit tests — the fixtures letting those run without live Stellar access. I'll close with a definition-of-done checklist and verify all six commands (bun install, indexer codegen/build/test, web typecheck/build) pass from a clean checkout. Could you assign it to me?

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

[0xsteins]

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

Gm gm sir, I'd love to take this on. I'll wire SubQuery in as the app's historical/aggregate source while keeping live reader/oracle calls where freshness matters — adding VITE_INDEXER_GRAPHQL_URL, an indexer-disable fallback flag, local/testnet defaults, and startup env validation, plus a lightweight GraphQL wrapper that fits the existing TanStack Query setup. Then typed query helpers (markets/pools, positions, orders, deposits/withdrawals, trade history, referral stats, fee/funding history) and updates to usePositions, useOrders, pools, and referral hooks to read indexed state while preserving fresh PnL/mark-price reads. I'll add loading/empty/stale/disabled states without breaking pages, and scope query keys by network + account so testnet and mainnet never mix. I'll verify indexer build and web typecheck/build pass. Could you assign it to me? 💛

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

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

Good luck! Track your progress on GrantFox.

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