Michealshodipo56 · Oct 9, 2026 · Oct 9, 2026
diff --git a/.gitbook.yaml b/.gitbook.yaml
@@ -0,0 +1,5 @@
+root: ./docs
+
+structure:
+  readme: README.md
+  summary: SUMMARY.md
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,21 @@
+# Resolve Documentation
+
+Resolve is a binary YES/NO prediction-market protocol running on Stellar Testnet. Users create markets, stake a SEP-41 token, and claim proportional payouts after resolution.
+
+## Live project
+
+- [Open the application](https://resolveit-app.vercel.app)
+- [View the contract on Stellar Expert](https://stellar.expert/explorer/testnet/contract/CD3YJNAYKVKT72DYPVS644OPNVNW6673TUIQWGXXA4VQD7536ARWB6MZ)
+- [Check indexer health](https://resolve-indexer.onrender.com/health)
+- [Check indexer readiness](https://resolve-indexer.onrender.com/ready)
+
+Resolve is a testnet preview. The contracts are unaudited and must not be presented as suitable for production funds.
+
+## Repositories
+
+- [resolve-app](https://github.com/resolve-web/resolve-app)
+- [resolve-contract](https://github.com/resolve-web/resolve-contract)
+- [resolve-sdk](https://github.com/resolve-web/resolve-sdk)
+- [resolve-indexer](https://github.com/resolve-web/resolve-indexer)
+
+Continue with the [architecture](architecture.md), [user guide](user-guide.md), or [verified deployment](deployment.md).
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -0,0 +1,13 @@
+# Table of contents
+
+- [Introduction](README.md)
+- [Architecture](architecture.md)
+- [User guide](user-guide.md)
+- [Smart contract](contract.md)
+- [SDK](sdk.md)
+- [Indexer](indexer.md)
+- [Verified deployment](deployment.md)
+- [Security](security.md)
+- [Submission evidence](submission.md)
+- [Demo runbook](DEMO.md)
+- [Deployment checklist](DEPLOYMENT.md)
diff --git a/docs/architecture.md b/docs/architecture.md
@@ -0,0 +1,23 @@
+# Architecture
+
+```text
+Freighter wallet
+      |
+      v
+Resolve web app ---> Resolve TypeScript SDK ---> Stellar Soroban RPC
+      |                                             |
+      v                                             v
+Resolve indexer <--- contract events <--- Resolve contract + SEP-41 token
+```
+
+The contract and Stellar ledger are authoritative for financial state. The indexer is a discovery cache: it lists markets, positions, and activity, but it never authorizes settlement or determines claim amounts.
+
+The browser signs transactions through Freighter. The SDK builds and simulates contract calls. The application never stores secret keys.
+
+## Market lifecycle
+
+1. A creator opens a market with a question, resolver, token, close time, and resolution timeout.
+2. Participants stake on YES or NO before closing.
+3. The designated resolver records YES, NO, or Invalid after closing.
+4. If the resolver does not act before the timeout, anyone can invalidate the market.
+5. Winners claim proportional payouts. Invalid markets refund both sides.
diff --git a/docs/contract.md b/docs/contract.md
@@ -0,0 +1,22 @@
+# Smart contract
+
+The Resolve Soroban contract supports:
+
+- `create_market`
+- `stake`
+- `resolve`
+- `invalidate`
+- `claim`
+- `get_market`, `get_position`, `get_claimable`, and `next_market_id`
+
+The resolver is trusted to report an honest outcome. Permissionless invalidation protects funds only when no resolution arrives before the configured timeout; it does not arbitrate a disputed outcome.
+
+Payouts use integer arithmetic:
+
+```text
+floor(user winning stake × total pool / winning pool)
+```
+
+Rounding dust remains in the contract. The v0.1.0 contract is not upgradeable and has not received an independent audit.
+
+See the [contract repository](https://github.com/resolve-web/resolve-contract) for source, tests, and the full security model.
diff --git a/docs/deployment.md b/docs/deployment.md
@@ -0,0 +1,14 @@
+# Verified testnet deployment
+
+| Component | Value |
+| --- | --- |
+| Network | Stellar Testnet |
+| Resolve contract | `CD3YJNAYKVKT72DYPVS644OPNVNW6673TUIQWGXXA4VQD7536ARWB6MZ` |
+| Settlement token | `CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC` |
+| Application | <https://resolveit-app.vercel.app> |
+| Indexer | <https://resolve-indexer.onrender.com> |
+| Contract release | [v0.1.0](https://github.com/resolve-web/resolve-contract/releases/tag/v0.1.0) |
+
+The deployment manifest records WASM SHA-256 `33218e4af670d895873420bf4edb248ea3b8654ec8a65460cdcf61ebc5b9ebb9`.
+
+A verified market lifecycle used market `1` and recorded public transaction hashes for creation, staking, resolution, and claiming in the contract repository's `deployments/testnet-e2e.json` file.
diff --git a/docs/indexer.md b/docs/indexer.md
@@ -0,0 +1,17 @@
+# Indexer and API
+
+The Render service ingests Resolve contract events into a persistent SQLite database and exposes a read-only API.
+
+| Endpoint | Purpose |
+| --- | --- |
+| `/health` | Process health and latest cursor |
+| `/ready` | Confirms ingestion is configured and checkpointed |
+| `/markets` | Paginated market discovery |
+| `/markets/:id` | Indexed market |
+| `/markets/:id/positions` | Indexed positions |
+| `/users/:address/positions` | User discovery |
+| `/users/:address/activity` | User event history |
+
+The deployment replays from ledger `5095009`, the beginning of the verified testnet lifecycle, when it detects an empty database with a newer checkpoint. Event identities make reprocessing idempotent.
+
+The indexer is not authoritative for balances, payouts, or settlement. Those values must be confirmed through the contract.
diff --git a/docs/sdk.md b/docs/sdk.md
@@ -0,0 +1,11 @@
+# TypeScript SDK
+
+The SDK provides typed builders for contract reads and writes. It supports ESM and CommonJS on Node.js 22.12 or newer.
+
+```bash
+npm install github:resolve-web/resolve-sdk
+```
+
+The public npm package has not been published yet, so production consumers should pin a Git commit.
+
+Write methods return an `AssembledTransaction`; the caller signs and sends it. Read methods simulate against Soroban RPC. See the [SDK repository](https://github.com/resolve-web/resolve-sdk) for examples and API details.
diff --git a/docs/security.md b/docs/security.md
@@ -0,0 +1,10 @@
+# Security
+
+- Resolve is an unaudited testnet preview.
+- Never enter a secret key in the application. Freighter performs wallet signing.
+- The designated resolver is trusted to report the correct outcome.
+- The indexer is a cache and cannot authorize claims or settlement.
+- The settlement token is assumed to implement SEP-41 correctly.
+- v0.1.0 has no upgrade or administrator path; changes require a new deployment.
+
+Report vulnerabilities privately through the relevant repository's GitHub Security Advisory page. Do not publish exploitable details in a public issue.
diff --git a/docs/submission.md b/docs/submission.md
@@ -0,0 +1,20 @@
+# Submission evidence
+
+## Verified
+
+- Four public repositories with Apache-2.0 licensing and contribution/security guidance.
+- Required CI checks on protected `main` branches.
+- Vercel application responds publicly over HTTPS.
+- Render indexer exposes healthy and ready endpoints with persistent storage.
+- Deployed Stellar Testnet contract and settlement token are recorded in version control.
+- Public create → stake → resolve → claim transaction hashes are recorded.
+- Contract unit tests cover creation, staking, resolution, invalidation, refunds, rounding, double claims, and pool invariants.
+- App, SDK, and indexer have automated TypeScript checks and tests.
+
+## Scope and limitations
+
+- Testnet only.
+- Contracts are unaudited.
+- Resolver correctness is a trust assumption.
+- The SDK is installed from GitHub until an npm release is published.
+- The indexer is not a settlement authority.
diff --git a/docs/user-guide.md b/docs/user-guide.md
@@ -0,0 +1,17 @@
+# User guide
+
+## Connect a wallet
+
+Install Freighter, select Stellar Testnet, and connect from the application header. Keep enough testnet XLM for transaction fees and use only test assets.
+
+## Create a market
+
+Open **Create**, enter an objective question and resolution description, choose a resolver address, select the settlement token, and set the close and timeout values. Review the transaction before approving it in Freighter.
+
+## Stake
+
+Open a market, select YES or NO, enter an amount, review the summary, and approve the wallet transaction. One wallet may stake on both sides.
+
+## Claim or refund
+
+After resolution, open the market and claim. YES/NO winners receive their proportional share of the total pool. Invalid markets refund deposits. On-chain reads remain authoritative if the indexer is temporarily delayed.
diff --git a/next.config.ts b/next.config.ts
@@ -16,6 +16,20 @@ const nextConfig: NextConfig = {
       {
         source: "/(.*)",
         headers: [
+          {
+            key: "Content-Security-Policy",
+            value: [
+              "default-src 'self'",
+              "script-src 'self' 'unsafe-inline' 'unsafe-eval'",
+              "style-src 'self' 'unsafe-inline'",
+              "img-src 'self' data: blob:",
+              "font-src 'self' data:",
+              "connect-src 'self' https://soroban-testnet.stellar.org https://horizon-testnet.stellar.org https://resolve-indexer.onrender.com",
+              "frame-ancestors 'none'",
+              "base-uri 'self'",
+              "form-action 'self'",
+            ].join("; "),
+          },
           { key: "X-Content-Type-Options", value: "nosniff" },
           { key: "Referrer-Policy", value: "strict-origin-when-cross-origin" },
           { key: "X-Frame-Options", value: "DENY" },