fix(frontend): wire dispute and claim flows to the contract, drop nonexistent endpoints (#1755, #1756)

docs/data-flow.md

@@ -139,6 +139,17 @@ Admin / Contract event
 | **Deletion** | Not possible for on-chain data. PostgreSQL mirror rows are not deleted |
 | **Who has access** | Public on-chain (permissionless read of Stellar ledger); API via Stellar RPC (`GET /api/v1/blockchain/user-bets/:address`); DB admin |
 
+**Client-side contract writes (dispute, claim).** Not every on-chain write has
+an API route. `file_dispute`, `cast_vote`, and `claim_winnings` are invoked
+directly from the browser: the page builds the invocation with
+`frontend/src/lib/wallet/soroban.ts`, the connected wallet signs the XDR, and
+the signed transaction is submitted to Soroban RPC. Contract id and RPC
+endpoint come from `NEXT_PUBLIC_CONTRACT_ID` / `NEXT_PUBLIC_SOROBAN_RPC_URL`;
+when either is unset the pages render a "not configured" message instead of
+failing. Reads for those pages still go through the API
+(`GET /api/v1/blockchain/market/:id`, `GET /api/v1/blockchain/users/:user/bets`)
+— there is deliberately no `/disputes` or per-bet HTTP route.
+
 ---
 
 ### 6. Email Tracking & Delivery Events

frontend/.env.example

@@ -18,3 +18,17 @@ NEXT_PUBLIC_TTS_API_URL=http://localhost:3002
 # When unset or empty, the built-in PUBLIC/TESTNET/FUTURENET endpoints are used.
 # Example: https://horizon.my-org.internal
 NEXT_PUBLIC_HORIZON_URL_OVERRIDE=
+
+# Soroban contract configuration (optional)
+# Required for on-chain write flows (filing a dispute, claiming winnings).
+# When either is unset, those pages render a "not configured" message instead
+# of submitting to a nonexistent backend route.
+# Example: CAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABSC4
+NEXT_PUBLIC_CONTRACT_ID=
+# Soroban RPC endpoint for the network the contract is deployed to.
+# Example: https://soroban-testnet.stellar.org
+NEXT_PUBLIC_SOROBAN_RPC_URL=
+# Network passphrase the wallet should sign for. Defaults to the Stellar
+# testnet passphrase when unset.
+# Example: "Public Global Stellar Network ; September 2015"
+NEXT_PUBLIC_STELLAR_NETWORK_PASSPHRASE=

frontend/README.md

@@ -9,6 +9,24 @@ This package contains the Handsoff web frontend.
 - [Design system](./docs/design-system.md) — design system guidelines and conventions for the frontend.
 - [`docs/`](./docs/) — additional frontend documentation.
 
+## On-chain contract writes
+
+`file_dispute`, `cast_vote`, and `claim_winnings` have no API route, so the
+pages that need them call the contract directly via
+[`src/lib/wallet/soroban.ts`](./src/lib/wallet/soroban.ts): build → wallet-sign
+→ submit to Soroban RPC. Configure it with:
+
+| Variable | Purpose |
+|---|---|
+| `NEXT_PUBLIC_CONTRACT_ID` | The PredictIQ contract id to invoke |
+| `NEXT_PUBLIC_SOROBAN_RPC_URL` | Soroban RPC endpoint for the contract's network |
+| `NEXT_PUBLIC_STELLAR_NETWORK_PASSPHRASE` | Network passphrase the wallet signs for (defaults to testnet) |
+
+When `NEXT_PUBLIC_CONTRACT_ID` or `NEXT_PUBLIC_SOROBAN_RPC_URL` is unset, those
+pages render a "not configured" message and disable the submit button rather
+than calling a nonexistent endpoint. See `.env.example` for examples.
+
+
 ## Styling conventions (CSP-safe, no inline styles)
 
 ### Why: the CSP constraint