docs: add full local integration guide, checks, and handoff (#186)

.github/workflows/integration-checks.yml

@@ -0,0 +1,83 @@
+name: Integration Checks
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: integration-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  indexer:
+    name: Indexer · codegen · build · tests · manifest sync
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Cache Bun dependencies
+        uses: actions/cache@v4
+        with:
+          path: ~/.bun/install/cache
+          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-bun-
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Indexer codegen
+        run: bun run --cwd apps/s03-indexer codegen
+
+      - name: Indexer build
+        run: bun run --cwd apps/s03-indexer build
+
+      - name: Indexer mapping unit tests
+        run: bun run --cwd apps/s03-indexer test
+
+      - name: Manifest sync (offline fixtures)
+        env:
+          SO4_CONTRACTS_REPO: ${{ github.workspace }}/apps/s03-indexer/tests/fixtures/contracts-repo
+        run: bun run --cwd apps/s03-indexer sync:contracts:local
+
+      - name: Validate generated manifest
+        run: bash scripts/validate-manifest.sh apps/s03-indexer/config/contracts.local.json
+
+  web:
+    name: Web · typecheck · build
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Cache Bun dependencies
+        uses: actions/cache@v4
+        with:
+          path: ~/.bun/install/cache
+          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-bun-
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Web typecheck
+        run: bun run --cwd apps/web typecheck
+
+      - name: Web build
+        run: bun run --cwd apps/web build

README.md

@@ -139,6 +139,14 @@ cd so4-monorepo
 bun install
 ```
 
+### Full local stack (contracts + indexer + web)
+
+If you need the indexer and contracts running against the web app, follow the
+[Local Full-Stack Integration Guide](./docs/local-full-stack.md). It documents
+prerequisites, deploy/bootstrap, manifest sync, indexer start, smoke flow,
+GraphQL verification, UI verification, troubleshooting, and the definition of
+done. Run `bun run check:integration` before pushing to mirror the CI matrix.
+
 ### Running the development server
 
 ```bash

apps/s03-indexer/README.md

@@ -4,6 +4,12 @@ This Bun workspace package contains the SubQuery Stellar indexer scaffold for
 the S03 app. It indexes Stellar testnet payments, account credit/debit effects,
 and Soroban `transfer` events.
 
+> **New contributor?** Start with the top-level
+> [Local Full-Stack Integration Guide](../../docs/local-full-stack.md). It
+> covers prerequisites, the deploy → sync → index → query → UI path end-to-end,
+> troubleshooting, and the definition of done. Use the rest of this README as
+> the indexer-specific reference.
+
 ## Workspace Commands
 
 Run these commands from the repository root:

apps/s03-indexer/tests/fixtures/contracts-repo/.deployed/frontend-local.env

@@ -0,0 +1,7 @@
+VITE_NETWORK=local
+VITE_NETWORK_PASSPHRASE=Standalone Network ; February 2017
+VITE_HORIZON_URL=http://host.docker.internal:8000
+VITE_RPC_URL=http://host.docker.internal:8000/soroban/rpc
+VITE_EXCHANGE_ROUTER=CBD6BQSQFROWIIT5QCYN7KL5LJJWUIH7CEWUSZIFMUJO6NPXE6CVGYNW
+VITE_READER=CC6OZUHF3LVO6PNP3V2EB36ORB3YSVYSH3LWD3RFLO4NUO3BYCXSWSYC
+VITE_DATA_STORE=CCZ3VKBEDLNBO2JM3EXL3SNBDJOV5BTN52FVQPER7F6D5GCE53PITQ3J

apps/s03-indexer/tests/fixtures/contracts-repo/.deployed/frontend-local.ts

@@ -0,0 +1,3 @@
+export const networkPassphrase = "Standalone Network ; February 2017";
+export const rpcUrl = "http://host.docker.internal:8000/soroban/rpc";
+export const horizonUrl = "http://host.docker.internal:8000";

apps/s03-indexer/tests/fixtures/contracts-repo/.deployed/local.env

@@ -0,0 +1,17 @@
+NETWORK=local
+ROLE_STORE=CBSUAIAMIFFS4AXQYZ7KR7FNO7IMKAPS5WF4DXANVXDTPKH2F7YUIN6Q
+DATA_STORE=CCZ3VKBEDLNBO2JM3EXL3SNBDJOV5BTN52FVQPER7F6D5GCE53PITQ3J
+ORACLE=CBEMTV23SIJJBIST3V5HTMWHR4MHYGHNBIG4M26U4LGUJTWZXTFSVQEY
+MARKET_FACTORY=CBGX3EJFI3JRHSN5B533O2L5P57JFPTCRS55IPWFS5BNDXLJLXDWA5Z2
+DEPOSIT_HANDLER=CDWOFIP4YQJGMCYAOWLSRBAWN2OTJUG2I5WOFC32O2TX2SRU56RWBE5C
+WITHDRAWAL_HANDLER=CBRWM6PNRRFL5RSTJH6HWEXBTMWCGLQRO45NTRDB6BBABWXZ4ZE7DGTO
+ORDER_HANDLER=CC35OFZVWUTAZPV3B6UKSDVAVORZEWUUMOMTHO33H4YR4C5FKPEFODKY
+LIQUIDATION_HANDLER=CBXUAR5GCHIRFQL75WTZS3FLA6SMWDPIKG4EKNPWVQVNGVFXBHGTJHTM
+ADL_HANDLER=CACFPG3QAKG6DCAJSOP7YGDTM44NV6NPI3SKAG7GUGIV6DMGXPCAMMME
+FEE_HANDLER=CC4P3FJ7EAH6F3RYJPQ2T7VIB4I7UJ4EEYGVWTZVXTAUN647QRVSDHS4
+REFERRAL_STORAGE=CDHTPQO4RRJ6OUBIW3GDXTIVLVOMIKPJC65PGDJH2G5OLDJRE5KTROWK
+READER=CC6OZUHF3LVO6PNP3V2EB36ORB3YSVYSH3LWD3RFLO4NUO3BYCXSWSYC
+EXCHANGE_ROUTER=CBD6BQSQFROWIIT5QCYN7KL5LJJWUIH7CEWUSZIFMUJO6NPXE6CVGYNW
+MARKET_TOKEN_TETH_TUSDC=CCBUUSYZJTGVA6PYUNQDFPZFHTBZ2QSHOUO7YAGRQVA46T3ZLSIYULS4
+MARKET_TOKEN_TWBTC_TUSDC=CDDVSLBGGDV2UOFN5W72R4LW7ABYL7H7ZWVSFHGMXXB3D52ZYANC5G3L
+MARKET_TOKEN_TXLM_TUSDC=CDIBR7BDCDWGAG3CC6PBKRSLMISPYKNDGE57DCZO5TMTLZK34TMGKFQQ

apps/s03-indexer/tests/fixtures/contracts-repo/.deployed/tokens-local.env

@@ -0,0 +1,5 @@
+TUSDC=CBAN5YU3KRDKPTQ2H76D6S7HQFPRBGUD524F65BUM2RQCITPTRLKWKES
+TWBTC=CCFTOPHUPSUDO2MB4X5D3XYJ2HRJ7NJPAW4UVPAVN7ZLE63EZLSMXDUO
+TETH=CAJ6BZKGFT47ALGMVFZZGAOXBV2RWIVYVCU4WJCQIURKRNXU346RWVAU
+TXLM=CAHNXBBSXVMGI6G3FUBY3OTNWKQ7434FDDEEE7ZT733WIW6NUZL4ONU6
+FAUCET=CCWXXBKXHHP5DXC6TYVIL22XUNHD5A75O6WM5D2KM5PY45IOV5VDMARJ

apps/s03-indexer/tests/fixtures/contracts-repo/.stellar/contract-ids/local.json

@@ -0,0 +1,19 @@
+{
+  "network": "local",
+  "network_passphrase": "Standalone Network ; February 2017",
+  "contracts": {
+    "role_store": "CBSUAIAMIFFS4AXQYZ7KR7FNO7IMKAPS5WF4DXANVXDTPKH2F7YUIN6Q",
+    "data_store": "CCZ3VKBEDLNBO2JM3EXL3SNBDJOV5BTN52FVQPER7F6D5GCE53PITQ3J",
+    "oracle": "CBEMTV23SIJJBIST3V5HTMWHR4MHYGHNBIG4M26U4LGUJTWZXTFSVQEY",
+    "market_factory": "CBGX3EJFI3JRHSN5B533O2L5P57JFPTCRS55IPWFS5BNDXLJLXDWA5Z2",
+    "deposit_handler": "CDWOFIP4YQJGMCYAOWLSRBAWN2OTJUG2I5WOFC32O2TX2SRU56RWBE5C",
+    "withdrawal_handler": "CBRWM6PNRRFL5RSTJH6HWEXBTMWCGLQRO45NTRDB6BBABWXZ4ZE7DGTO",
+    "order_handler": "CC35OFZVWUTAZPV3B6UKSDVAVORZEWUUMOMTHO33H4YR4C5FKPEFODKY",
+    "liquidation_handler": "CBXUAR5GCHIRFQL75WTZS3FLA6SMWDPIKG4EKNPWVQVNGVFXBHGTJHTM",
+    "adl_handler": "CACFPG3QAKG6DCAJSOP7YGDTM44NV6NPI3SKAG7GUGIV6DMGXPCAMMME",
+    "fee_handler": "CC4P3FJ7EAH6F3RYJPQ2T7VIB4I7UJ4EEYGVWTZVXTAUN647QRVSDHS4",
+    "referral_storage": "CDHTPQO4RRJ6OUBIW3GDXTIVLVOMIKPJC65PGDJH2G5OLDJRE5KTROWK",
+    "reader": "CC6OZUHF3LVO6PNP3V2EB36ORB3YSVYSH3LWD3RFLO4NUO3BYCXSWSYC",
+    "exchange_router": "CBD6BQSQFROWIIT5QCYN7KL5LJJWUIH7CEWUSZIFMUJO6NPXE6CVGYNW"
+  }
+}

apps/s03-indexer/tests/fixtures/contracts-repo/README.md

@@ -0,0 +1,37 @@
+# Fixture contracts repo
+
+This directory mirrors the on-disk layout of the real contracts repo
+(`../contracts` relative to this interface repo) so the indexer sync script and
+manifest validation checks can run **without a live Stellar deploy**.
+
+It is used by:
+
+- `scripts/check-integration.sh` — local pre-PR integration check.
+- `.github/workflows/integration-checks.yml` — CI integration check.
+- Manual reproduction:
+
+  ```bash
+  SO4_CONTRACTS_REPO=apps/s03-indexer/tests/fixtures/contracts-repo \
+    bun run --cwd apps/s03-indexer sync:contracts:local
+  ```
+
+The IDs here are real testnet contract IDs reused as deterministic fixtures —
+they are **not** intended to be deployed against or signed for. Treat them as
+shape-valid sample data.
+
+## Layout
+
+```
+contracts-repo/
+├── .deployed/
+│   ├── local.env             # core contracts + market token triplets
+│   ├── tokens-local.env      # TUSDC / TWBTC / TETH / TXLM / FAUCET
+│   ├── frontend-local.env    # frontend export env
+│   └── frontend-local.ts     # frontend export TypeScript (passphrase, RPC)
+└── .stellar/
+    └── contract-ids/
+        └── local.json        # combined network passphrase + contract IDs
+```
+
+Update these fixtures whenever the contracts repo adds a new core contract or
+deployment file shape — they are the canonical sample input for offline checks.