@cypher-zk/sdk 0.3.0 → 0.5.0

package/README.md

@@ -2,268 +2,699 @@
 
 > **TypeScript SDK for the [Cypher](https://cyphers.live) privacy-preserving prediction market on Solana**, powered by [Arcium](https://arcium.com) MPC.
 
-[![Tests](https://img.shields.io/badge/tests-107%20passing-brightgreen)]()
-[![License: Source Available](https://img.shields.io/badge/license-Source%20Available-orange.svg)]()
+[![tests](https://img.shields.io/badge/tests-150%20passing-brightgreen)]()
+[![typecheck](https://img.shields.io/badge/typecheck-clean-brightgreen)]()
+[![bundle](https://img.shields.io/badge/dist-ESM%20%2B%20.d.ts-blue)]()
+[![version](https://img.shields.io/badge/version-0.2.0-blue)]()
+[![license](https://img.shields.io/badge/license-Source%20Available-orange.svg)](./LICENSE)
+
+A framework-agnostic core (Node, Bun, browser) with an optional React
+hooks subpath and end-to-end progress callbacks so frontends can render
+fine-grained loading state across every multi-step on-chain flow.
+
+> **v0.2 — dispute window.** Reveal callbacks now land the market in
+> `PendingResolution`, not `Resolved`. A configurable 24h–48h challenge
+> window lets anyone flag a wrong outcome before claims open. See
+> [§ Dispute window (v0.2)](#dispute-window-v02) for the full flow and
+> three new instructions / actions / hooks.
 
 ---
 
-## Features
+## Why this SDK exists
 
-- **Full instruction coverage** — builders for all 26 Anchor instructions
-- **High-level action helpers** — encrypt → send → await MPC callback → refetch, in one call
-- **Typed event parsing** — 7 on-chain events decoded and narrowed via discriminated unions
-- **Real-time & poll-based subscriptions** — WebSocket `onLogs` + HTTP fallback
-- **Framework-agnostic core** — works in any TS environment (Node, Deno, Bun, browser)
-- **React hooks layer** — optional `@cypher/sdk/react` with React Query integration
-- **Cluster-aware** — reads `GlobalState.accepted_mint` on-chain (devnet=CSDC, mainnet=USDC)
-- **Deterministic test suite** — 107 unit tests, 581 assertions
+Cypher is a Solana program that wraps prediction-market state in
+[Arcium MPC](https://docs.arcium.com) so user bets stay encrypted on
+chain. Talking to it directly involves wiring:
 
-## Installation
+- A typed Anchor `Program` against the program's IDL
+- Per-flow Arcium queue accounts (cluster offset, mempool, comp def, …)
+- `x25519` keypair generation + Rescue cipher encryption for each bet
+- Polling the computation account until the MPC nodes finalize the
+  callback
+- Refetching the position/market after the callback updates state
+
+This SDK gives you a single `client.actions.placeBet({...})` call that
+does all of that, with progress events for the UI and discriminated-
+union typed events for the indexer.
+
+```ts
+const result = await client.actions.placeBet({
+  payer: wallet.publicKey,
+  user: wallet.publicKey,
+  marketId: 7n,
+  side: 1,                 // 1 = YES
+  amountUsdc: 5_000_000n,  // $5 (6 decimals)
+  onProgress: (e) => updateLoaderUI(e.stage, e.message),
+});
+// Persist result.userKeypair.privateKey under the wallet's key — that's
+// the only way to later decrypt this position to claim a payout.
+```
+
+## What's in the box
+
+- **All 29 program instructions** with typed builders that return raw
+  `TransactionInstruction`s (compose, simulate, bundle freely) — 3 admin,
+  8 init comp def, 4 market lifecycle, 2 bet, 2 resolve, 4 claim, plus
+  **3 dispute-window** instructions added in v0.2.
+- **Ten high-level action helpers** (`createMarket`,
+  `createMarketMulti`, `placeBet`, `resolveMarket`, `claimPayout`,
+  `claimRefund`, `cancelMarket`, `withdrawCreatorFunds`, plus
+  **`flagResolution`, `finalizeResolution`, `adminOverrideResolution`**)
+  that hide the "encrypt → send → await MPC callback → refetch"
+  choreography.
+- **Async progress events** on every multi-step action, so frontends can
+  render `Encrypting…` → `Submitting…` → `Awaiting MPC nodes…` instead
+  of one generic spinner.
+- **Typed event surface** — **10 discriminated-union events** (7 core +
+  3 dispute-window in v0.2) with `parseLogs`, `parseLogsFor`,
+  `subscribeAll`, `onXxx` helpers, and a WebSocket-less `pollEvents`
+  fallback. Decoded fields are camelCase `bigint`s, matching the typed
+  interfaces 1:1.
+- **Account fetch + memcmp filters** for every program account, with
+  byte offsets drift-tested against the IDL.
+- **React hooks** (`@cypher-zk/sdk/react`): `CypherProvider`,
+  `useGlobalState`, `useMarket`, `useMarkets`, `useUserPositions`,
+  `usePlaceBet`, `useResolveMarket`, `useClaimPayout`, `useClaimRefund`,
+  `useCreateMarket`, `useCancelMarket`, **`useFlagResolution`,
+  `useFinalizeResolution`, `useAdminOverrideResolution`** (v0.2),
+  `useMarketEvents` — all built on TanStack Query with sensible
+  cache-invalidation defaults.
+- **Phase-aware UI gating** — `marketPhase(market)` returns one of nine
+  literal values including `pendingResolution`, `awaitingFinalize`, and
+  `disputed` so buttons only render when the corresponding ix is
+  actually clickable.
+- **Cluster-agnostic at runtime** — reads `GlobalState.accepted_mint`
+  on-chain, so the same build works against any deployment (devnet CSDC,
+  mainnet USDC, localnet test mint).
+- **150 unit tests** (712 assertions) covering PDA derivations, fee
+  math, deadline phases, IDL drift, Arcium offsets, encryption
+  round-trip, event parser round-trip with all 10 event types, action
+  input validation (including dispute-window phase gating), and React
+  hook wiring. Plus opt-in localnet integration and devnet smoke suites.
+
+## Install
 
 ```bash
-npm install @cypher-zk/sdk
-# or
 bun add @cypher-zk/sdk
+# or
+npm install @cypher-zk/sdk
 ```
 
 ### Peer dependencies
 
-| Package                    | Required for                      |
-| -------------------------- | --------------------------------- |
-| `react` ^18/^19            | `@cypher-zk/sdk/react` hooks only |
-| `@tanstack/react-query` ^5 | `@cypher-zk/sdk/react` hooks only |
-| `typescript` ^5            | Type checking                     |
+| Package | Required for |
+| --- | --- |
+| `react` ^18 \|\| ^19 | `@cypher-zk/sdk/react` subpath only |
+| `@tanstack/react-query` ^5 | `@cypher-zk/sdk/react` subpath only |
 
-## Quick Start
+Core SDK works in any TypeScript environment with no peer requirements.
 
-### Core SDK
+---
+
+## Quickstart
+
+### 1. Construct a client
 
 ```ts
-import { CypherClient, keypairToWallet } from "@cypher-zk/sdk";
-import { Connection, Keypair } from "@solana/web3.js";
+import { Connection } from "@solana/web3.js";
+import { CypherClient } from "@cypher-zk/sdk";
 
-const connection = new Connection("https://api.devnet.solana.com");
-const wallet = keypairToWallet(Keypair.generate());
+const connection = new Connection("https://api.devnet.solana.com", "confirmed");
 
+// Wallet can be:
+//   - any @solana/wallet-adapter wallet (browser)
+//   - `keypairToWallet(Keypair)` (Node / scripts / tests)
 const client = new CypherClient({ connection, wallet, cluster: "devnet" });
+```
 
-// Fetch protocol state
+### 2. Read protocol state
+
+```ts
 const gs = await client.globalState.fetch();
-console.log("Market counter:", gs.marketCounter);
+console.log("Protocol fee:", gs.protocolFeeRate, "bps");
 
-// Fetch a specific market
 const market = await client.markets.fetch(0n);
-console.log("Question:", market?.question);
-
-// Fetch all active markets
-const active = await client.markets.byState(0); // MarketState.Active
+const active = await client.markets.byState(0);              // MarketState.Active
+const mine   = await client.markets.byCreator(wallet.publicKey);
+const myBets = await client.positions.byUser(wallet.publicKey);
 ```
 
-### Place a Private Bet (end-to-end)
+### 3. Place a private bet — with live progress
 
 ```ts
-import { MarketType } from "@cypher-zk/sdk";
+import { computeFees } from "@cypher-zk/sdk";
 
-const result = await client.actions.placeBet({
+// Preview the fee split before showing a confirm modal:
+const preview = computeFees(5_000_000n, {
+  protocolFeeRateBps: gs.protocolFeeRate,
+  lpFeeRateBps: gs.lpFeeRate,
+});
+console.log("Net stake:", preview.netAmount, "after fees:", preview.protocolFee + preview.lpFee);
+
+// Fire the end-to-end flow:
+const { signature, position, userKeypair } = await client.actions.placeBet({
   payer: wallet.publicKey,
   user: wallet.publicKey,
   marketId: 0n,
-  marketType: MarketType.YesNo,
-  side: 0, // 0=YES, 1=NO
-  amountUsdc: 5_000_000n, // $5 USDC (6 decimals)
+  side: 1,                 // 0 = NO, 1 = YES
+  amountUsdc: 5_000_000n,  // $5 (USDC has 6 decimals)
+  onProgress: ({ stage, message, signature }) => {
+    // stage ∈ "validating" | "fetching-state" | "encrypting" | "submitting"
+    //       | "awaiting-callback" | "refetching" | "done"
+    console.log(stage, message ?? "", signature ?? "");
+  },
 });
 
-console.log("Tx:", result.signature);
-console.log("Entry odds:", result.position?.entryOdds);
+// IMPORTANT: persist userKeypair.privateKey somewhere the user controls
+// (e.g. localStorage encrypted under the wallet's signature) — without
+// it, the user cannot decrypt this position later when claiming.
+saveSecretForLater(position!.market, userKeypair.privateKey);
 ```
 
-### Create a Market
+The progress callback lets you drive multi-step UI:
+
+```
+[ Validating … ]                  ◄ instant, client-side
+[ Fetching protocol state … ]
+[ Encrypting your bet … ]
+[ Submitting transaction … ]      ◄ tx signature available here
+[ Awaiting MPC nodes (~10s) … ]
+[ Updating position … ]
+[ Done! ]
+```
+
+### 4. Create a market
 
 ```ts
-const result = await client.actions.createMarket({
+const { marketId, marketPda, signature } = await client.actions.createMarket({
   creator: wallet.publicKey,
   question: "Will ETH hit $10k by end of 2026?",
   closeTime: BigInt(Math.floor(Date.now() / 1000) + 7 * 24 * 3600),
-  category: 0, // Crypto
+  category: 0,                            // MarketCategory.Crypto
+  // v0.2+: optional. Defaults to MIN_CHALLENGE_PERIOD_SECS (24h).
+  // Must be in [MIN_CHALLENGE_PERIOD_SECS, MAX_CHALLENGE_PERIOD_SECS]
+  // (24h–48h). Pin shorter for prediction markets that settle fast.
+  challengePeriod: 24 * 3600,
+  onProgress: (e) => console.log(e.stage),
+});
+```
+
+Multi-outcome variant — `createMarketMulti` with `numOutcomes: 2 | 3 | 4`.
+
+### 5. Resolve, claim payout, claim refund
+
+```ts
+// Resolver (oracle / DAO):
+await client.actions.resolveMarket({
+  payer: wallet.publicKey,
+  resolver: wallet.publicKey,
+  marketId,
+  outcomeValue: 1,
+  onProgress: (e) => console.log(e.stage),
+});
+
+// Winning bettor:
+await client.actions.claimPayout({
+  payer: wallet.publicKey,
+  user: wallet.publicKey,
+  marketId,
 });
 
-console.log("Market ID:", result.marketId);
-console.log("Market PDA:", result.marketPda.toBase58());
+// Bettor on an unresolved market (past resolution_deadline):
+await client.actions.claimRefund({
+  payer: wallet.publicKey,
+  user: wallet.publicKey,
+  marketId,
+});
 ```
 
-### Subscribe to Events
+Each refuses pre-flight if the market isn't in the right phase
+(`marketPhase` returns `"claimable"` for payout, `"refundable"` for
+refund) so the user never burns gas on a guaranteed-to-fail tx.
+
+> **v0.2 note:** `resolveMarket` no longer flips the market to
+> `Resolved`. The reveal callback now sets `state = PendingResolution`
+> and starts the challenge window. `claimPayout` opens only after
+> `finalizeResolution` / `adminOverrideResolution` runs — see
+> [§ Dispute window (v0.2)](#dispute-window-v02) below.
+
+### 6. Subscribe to events
 
 ```ts
-// Real-time (WebSocket)
+// Real-time (WebSocket):
 const sub = client.events.onBetPlaced((data) => {
-  console.log("Bet placed! Odds:", data.entryOdds);
+  // `data` is BetPlacedEvent — fully typed (camelCase fields, bigint amounts):
+  console.log(`Bet placed on market ${data.market.toBase58()} — odds ${data.entryOdds}`);
+});
+
+// Generic, typed by name:
+const sub2 = client.events.subscribe("MarketResolvedEvent", (data) => {
+  console.log("Outcome:", data.outcome, "Payout ratio:", data.payoutRatio);
+});
+
+// v0.2: dispute-window events
+const sub3 = client.events.onResolutionFlagged((data) => {
+  console.log("Market disputed by:", data.flaggedBy.toBase58());
+});
+const sub4 = client.events.onMarketFinalized((data) => {
+  console.log("Market finalized — claims now open. Outcome:", data.outcome);
+});
+const sub5 = client.events.onResolutionOverridden((data) => {
+  console.log(`Admin override: ${data.oldOutcome} → ${data.newOutcome}`);
 });
 
-// Later: sub.unsubscribe();
+// Later
+sub.unsubscribe();
+sub2.unsubscribe();
 
-// Poll-based (no WS needed)
+// Poll-based fallback (no WS required):
 const recent = await client.events.pollEvents({ limit: 20 });
-for (const { event } of recent) {
-  console.log(event.name, event.data);
+for (const { event, signature, slot } of recent) {
+  console.log(event.name, "in tx", signature, "at slot", slot);
+}
+
+// Parse events out of a known transaction:
+import { parseLogs, parseLogsFor } from "@cypher-zk/sdk";
+const tx = await connection.getTransaction(sig, { maxSupportedTransactionVersion: 0 });
+const allEvents   = parseLogs(tx?.meta?.logMessages ?? []);
+const payoutsOnly = parseLogsFor(tx?.meta?.logMessages ?? [], "PayoutClaimedEvent");
+```
+
+### 7. Phase helpers
+
+```ts
+import { marketPhase, projectDeadlines } from "@cypher-zk/sdk";
+
+// Compute what action is currently available on a market:
+switch (marketPhase(market)) {
+  case "betting":            /* show "Bet" button */ break;
+  case "awaitingResolve":    /* show "Pending resolution" */ break;
+  case "pendingResolution":  /* v0.2: in challenge window — show countdown + "Flag" */ break;
+  case "awaitingFinalize":   /* v0.2: window elapsed — show "Finalize" button */ break;
+  case "disputed":           /* v0.2: flagged — admin override required */ break;
+  case "claimable":        /* show "Claim payout" */ break;
+  case "refundable":       /* show "Claim refund" */ break;
+  case "expired":          /* show "Admin sweep eligible" */ break;
+  case "cancelled":        /* show "Cancelled" */ break;
 }
+
+// Preview deadlines for a draft market the user is filling in:
+const projected = projectDeadlines(BigInt(closeTimeSec));
+console.log("Resolution deadline:", new Date(Number(projected.resolutionDeadline) * 1000));
+```
+
+---
+
+## Dispute window (v0.2)
+
+After the reveal callback lands, the market enters a configurable
+**24h–48h** challenge window (`market.state === PendingResolution = 4`)
+during which anyone can flag a wrong outcome. Only after the window
+closes does the market move to `Resolved` and claims open.
+
+```
+Resolver calls resolveMarket
+       │
+       ▼ reveal_market_outcome_* (Arcium MPC)
+  callback writes: outcome, revealedPool*, payoutRatio
+                   state = PendingResolution
+                   challengeDeadline = now + challenge_period
+
+  ┌─────────────────────────────────────┐
+  │  Challenge window (24h–48h)         │
+  │  Anyone may flagResolution          │
+  │    → market.disputed = true         │
+  └─────────────────────────────────────┘
+       │                          │
+   (undisputed)               (disputed)
+       │                          │
+       ▼                          ▼
+  finalizeResolution      adminOverrideResolution
+  (anyone, post-window)   (admin only, recomputes payout_ratio)
+       │                          │
+       └──────────┬───────────────┘
+                  ▼
+         state = Resolved
+       claim_deadline + refund_deadline set
+              claimPayout opens
 ```
 
-### Parse Transaction Logs
+### Three new actions
 
 ```ts
-import { parseLogs } from "@cypher-zk/sdk";
+// 1. ANYONE during the challenge window — flag a wrong resolution
+await client.actions.flagResolution({
+  flagger: wallet.publicKey,
+  marketId,
+  onProgress: (e) => console.log(e.stage),
+});
+
+// 2. ANYONE after the window closes undisputed — finalize → state = Resolved
+await client.actions.finalizeResolution({
+  caller: wallet.publicKey,
+  marketId,
+  onProgress: (e) => console.log(e.stage),
+});
+
+// 3. ADMIN ONLY when market.disputed === true — re-resolve with corrected outcome
+//    Recomputes payout_ratio from the already-revealed plaintext pools.
+await client.actions.adminOverrideResolution({
+  admin: wallet.publicKey,
+  marketId,
+  outcomeValue: 1,
+  onProgress: (e) => console.log(e.stage),
+});
+```
+
+Each emits `validating → submitting → refetching → done` progress
+stages and refuses pre-flight if the market isn't in the right phase
+(SDK throws clean errors pointing at the next valid step — e.g.
+"market is in 'pendingResolution' — call finalizeResolution first").
 
-const tx = await connection.getTransaction(sig, { commitment: "confirmed" });
-const events = parseLogs(tx.meta?.logMessages ?? []);
+### Phase gating
 
-for (const evt of events) {
-  if (evt.name === "MarketResolvedEvent") {
-    console.log("Outcome:", evt.data.outcome);
+`marketPhase(market)` returns the three new values whenever
+`state === PendingResolution`:
+
+| `marketPhase` | Meaning | Clickable |
+| --- | --- | --- |
+| `"pendingResolution"` | inside challenge window, not flagged | `flagResolution` (any user) |
+| `"awaitingFinalize"` | window elapsed, not flagged | `finalizeResolution` (any user) |
+| `"disputed"` | flagged during window | `adminOverrideResolution` (admin only) |
+| `"claimable"` | finalized → window closed (state=Resolved) | `claimPayout` |
+
+`claimPayoutAction` and `useClaimPayout` reject pre-flight in the
+first three phases with a hint to call `finalizeResolution` first.
+
+### React example
+
+```tsx
+import {
+  useMarket,
+  useFlagResolution,
+  useFinalizeResolution,
+} from "@cypher-zk/sdk/react";
+import { marketPhase } from "@cypher-zk/sdk";
+
+function ChallengeWindowControls({ marketId }: { marketId: bigint }) {
+  const { data: market } = useMarket(marketId, { refetchInterval: 5_000 });
+  const flag = useFlagResolution();
+  const finalize = useFinalizeResolution();
+  if (!market) return null;
+
+  const phase = marketPhase(market);
+  if (phase === "pendingResolution") {
+    return (
+      <>
+        <p>Challenge closes at {new Date(Number(market.challengeDeadline) * 1000).toLocaleString()}</p>
+        <button onClick={() => flag.mutate({ flagger: wallet.publicKey!, marketId })}>
+          Flag this resolution
+        </button>
+      </>
+    );
   }
+  if (phase === "awaitingFinalize") {
+    return (
+      <button onClick={() => finalize.mutate({ caller: wallet.publicKey!, marketId })}>
+        Finalize resolution
+      </button>
+    );
+  }
+  if (phase === "disputed") {
+    return <p>Awaiting admin override.</p>;
+  }
+  return null;
 }
 ```
 
-## React Hooks
+### Defaults & bounds
+
+| Constant | Value | Notes |
+| --- | --- | --- |
+| `MIN_CHALLENGE_PERIOD_SECS` | `24 * 3600` (24h) | Action helpers default here |
+| `MAX_CHALLENGE_PERIOD_SECS` | `48 * 3600` (48h) | Hard ceiling enforced by contract |
+
+The high-level `client.actions.createMarket` makes `challengePeriod`
+optional and defaults to `MIN_CHALLENGE_PERIOD_SECS`. The raw
+`createMarketIx` builder requires it — out-of-range values throw
+client-side before the tx is built.
+
+### Six new error codes
+
+| Code | Name | When |
+| --- | --- | --- |
+| `6036` | `InvalidChallengePeriod` | `challengePeriod` outside 24h–48h |
+| `6037` | `NotPendingResolution` | flag/finalize/override on wrong state |
+| `6038` | `ChallengePeriodNotElapsed` | finalize called too early |
+| `6039` | `ChallengePeriodElapsed` | flag called after window closed |
+| `6040` | `MarketDisputed` | finalize on a flagged market |
+| `6041` | `MarketNotDisputed` | admin override on a clean market |
+
+Use `parseCypherError(err)` to extract a typed `CypherErrorCode` for
+branching.
+
+### Three new events
+
+`ResolutionFlaggedEvent`, `MarketFinalizedEvent`,
+`ResolutionOverriddenEvent` are added to the discriminated `CypherEvent`
+union and have matching `client.events.on*` helpers.
+
+---
+
+## React hooks
 
 ```tsx
-import { CypherProvider, useMarket, usePlaceBet } from "@cypher-zk/sdk/react";
+import {
+  CypherProvider,
+  useGlobalState,
+  useMarket,
+  useMarkets,
+  usePlaceBet,
+} from "@cypher-zk/sdk/react";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { useState } from "react";
+import { CypherClient, keypairToWallet, MarketState } from "@cypher-zk/sdk";
+import type { ActionProgressEvent } from "@cypher-zk/sdk";
 
 const queryClient = new QueryClient();
+const client = new CypherClient({ connection, wallet, cluster: "devnet" });
 
 function App() {
   return (
     <QueryClientProvider client={queryClient}>
       <CypherProvider client={client}>
-        <MarketView />
+        <MarketView marketId={0n} />
       </CypherProvider>
     </QueryClientProvider>
   );
 }
 
-function MarketView() {
-  const { data: market, isLoading } = useMarket(0n);
-  const { mutateAsync: placeBet, isPending } = usePlaceBet();
+function MarketView({ marketId }: { marketId: bigint }) {
+  const { data: market, isLoading } = useMarket(marketId);
+  const [stage, setStage] = useState<ActionProgressEvent | null>(null);
 
-  if (isLoading) return <p>Loading…</p>;
+  const placeBet = usePlaceBet({
+    onSuccess: ({ userKeypair }) => persistUserSecret(userKeypair.privateKey),
+  });
+
+  if (isLoading) return <p>Loading market…</p>;
+  if (!market)   return <p>Market not found.</p>;
 
   return (
     <div>
-      <h1>{market?.question}</h1>
+      <h2>{market.question}</h2>
       <button
-        disabled={isPending}
+        disabled={placeBet.isPending}
         onClick={() =>
-          placeBet({
+          placeBet.mutate({
             payer: wallet.publicKey,
             user: wallet.publicKey,
-            marketId: 0n,
-            marketType: 0,
-            side: 0,
-            amountUsdc: 1_000_000n,
+            marketId,
+            side: 1,
+            amountUsdc: 5_000_000n,
+            onProgress: setStage,
           })
         }
       >
-        Bet YES ($1)
+        {placeBet.isPending && stage ? `Bet → ${stage.stage}` : "Bet $5 YES"}
       </button>
+      {placeBet.error && <p style={{ color: "crimson" }}>{placeBet.error.message}</p>}
     </div>
   );
 }
 ```
 
-### Available Hooks
+### Available hooks
+
+| Hook | Kind | Description |
+| --- | --- | --- |
+| `useGlobalState()` | Query | Protocol config (fees, mint, admin, counter) |
+| `useMarket(id)` | Query | Single market by ID |
+| `useMarkets(filter?)` | Query | All/filtered markets (creator, state) |
+| `useUserPositions(user)` | Query | All bet positions for a user |
+| `usePlaceBet()` | Mutation | End-to-end private bet |
+| `useCreateMarket()` | Mutation | Create a new market |
+| `useResolveMarket()` | Mutation | Submit outcome + await reveal |
+| `useClaimPayout()` | Mutation | Claim winning payout |
+| `useClaimRefund()` | Mutation | Claim refund on unresolved market |
+| `useCancelMarket()` | Mutation | Cancel a zero-bet market |
+| `useFlagResolution()` *(v0.2)* | Mutation | Flag a pending resolution during the challenge window |
+| `useFinalizeResolution()` *(v0.2)* | Mutation | Finalize a pending resolution after the window elapses undisputed |
+| `useAdminOverrideResolution()` *(v0.2)* | Mutation | Admin re-resolves a disputed market |
+| `useMarketEvents()` | Subscription | Live event stream (component-scoped) |
+
+Mutation hooks auto-invalidate the relevant query keys on success. Read
+hooks expose their `queryKey` factories (`marketKeys.one(id)`,
+`positionKeys.byUser(user)`, `globalStateKeys.all`) for manual
+invalidation.
+
+Live example under [`examples/react-vite/`](./examples/react-vite/) — a
+small Vite app that renders the protocol state, lists active markets,
+and drives `usePlaceBet` with live progress.
 
-| Hook                     | Type         | Description                         |
-| ------------------------ | ------------ | ----------------------------------- |
-| `useGlobalState()`       | Query        | Protocol config (fees, mint, admin) |
-| `useMarket(id)`          | Query        | Single market by ID                 |
-| `useMarkets(filter?)`    | Query        | All/filtered markets                |
-| `useUserPositions(user)` | Query        | User's bet positions                |
-| `usePlaceBet()`          | Mutation     | End-to-end private bet              |
-| `useResolveMarket()`     | Mutation     | Resolve a market                    |
-| `useClaimPayout()`       | Mutation     | Claim winning payout                |
-| `useClaimRefund()`       | Mutation     | Claim refund on unresolved market   |
-| `useCreateMarket()`      | Mutation     | Create a new market                 |
-| `useCancelMarket()`      | Mutation     | Cancel a zero-bet market            |
-| `useMarketEvents()`      | Subscription | Live event stream                   |
+---
 
-## Architecture
+## Layout
 
 ```
 cypher-sdk/
-├── src/                    # Framework-agnostic core
-│   ├── config.ts           # Program ID, cluster presets, on-chain constants
-│   ├── pda.ts              # PDA derivation helpers
-│   ├── wallet.ts           # Wallet adapter interface
-│   ├── fees.ts             # Fee calculation (mirrors on-chain math)
-│   ├── deadlines.ts        # Market lifecycle phase computation
-│   ├── errors.ts           # Typed error codes + parsing
-│   ├── client.ts           # CypherClient — unified entry point
-│   ├── accounts/           # Account fetchers (GlobalState, Market, Position, LP)
-│   ├── arcium/             # MPC glue (cipher, encoding, queue accounts, offsets)
-│   ├── instructions/       # Raw instruction builders (26 instructions)
-│   ├── actions/            # High-level flows (encrypt → send → callback → refetch)
-│   ├── events/             # Event parser + WebSocket/poll subscriptions
-│   ├── idl/                # Synced Anchor IDL (source of truth)
-│   └── node/               # Node-only admin helpers
-├── react/src/              # Optional React hooks layer
-│   ├── CypherProvider.tsx  # Context + provider
-│   ├── useGlobalState.ts   # Read hook
-│   ├── useMarket.ts        # Read hooks (single + filtered)
-│   ├── useUserPositions.ts # Read hook
-│   ├── mutations.ts        # Write hooks (all actions)
-│   └── useMarketEvents.ts  # Live event subscription hook
+├── src/                    # framework-agnostic core (ESM)
+│   ├── config.ts           # program ID, cluster presets, constants
+│   ├── pda.ts              # PDA derivations
+│   ├── wallet.ts           # Wallet interface + Keypair adapter
+│   ├── fees.ts             # mirrors on-chain fee math
+│   ├── deadlines.ts        # market phase computation
+│   ├── errors.ts           # CypherErrorCode + Anchor error walker
+│   ├── client.ts           # CypherClient — single import surface
+│   ├── accounts/           # fetch + memcmp filter helpers per account
+│   ├── arcium/             # MPC glue (cipher, queue accounts, offsets)
+│   ├── instructions/       # raw TransactionInstruction builders (29 ix, v0.2)
+│   ├── actions/            # high-level flows + progress events
+│   ├── events/             # typed event parser + WS/poll subscriptions
+│   ├── idl/                # synced Anchor IDL (source of truth)
+│   └── node/               # node-only admin helpers
+├── react/src/              # @cypher-zk/sdk/react hooks subpath
+├── examples/react-vite/    # minimal Vite app smoke
+├── docs/
+│   ├── architecture.md     # three-surface model + module map
+│   └── flows.md            # one diagram per user flow
 └── tests/
-    ├── unit/               # 107 tests, 581 assertions
-    ├── integration/        # Localnet lifecycle (INTEGRATION=1)
-    └── devnet/             # Devnet smoke test (DEVNET=1)
+    ├── unit/               # 150 tests, 712 assertions — pure, no chain
+    ├── integration/        # INTEGRATION=1 — Arcium localnet lifecycle
+    └── devnet/             # DEVNET=1 — devnet read-only + opt-in writes
 ```
 
-## Cluster Configuration
+See [`docs/architecture.md`](./docs/architecture.md) for the three-surface
+model (circuit / program / client), the account topology, and the full
+runtime flow of a private bet. See [`docs/flows.md`](./docs/flows.md) for
+per-flow ASCII diagrams.
+
+---
 
-The SDK is **cluster-agnostic** — it reads `GlobalState.accepted_mint` on-chain at runtime:
+## Cluster strategy
 
-| Cluster    | Accepted Mint         | Arcium Cluster Offset |
-| ---------- | --------------------- | --------------------- |
-| `devnet`   | CSDC (`8AF9BABN…`)    | `456`                 |
-| `mainnet`  | USDC (`EPjFWdd5…`)    | TBD                   |
-| `localnet` | CSDC (same as devnet) | `1116522022`          |
+The SDK is **cluster-agnostic at runtime**: it reads the accepted SPL mint
+from `GlobalState.accepted_mint` on every flow rather than hard-coding
+CSDC vs USDC. The same build works against any Cypher deployment.
 
-Override cluster detection:
+| Cluster | RPC default | Accepted mint | Arcium offset |
+| --- | --- | --- | --- |
+| `devnet` | `api.devnet.solana.com` | CSDC (`8AF9BABN…`) | `456` |
+| `mainnet` | `api.mainnet-beta.solana.com` | USDC (`EPjFWdd5…`) | (set at deploy) |
+| `localnet` | `localhost:8899` | CSDC (test build) | `1116522022` |
 
 ```ts
-// Explicit preset
+// Explicit preset:
 const client = new CypherClient({ connection, wallet, cluster: "devnet" });
 
-// Fully custom
+// Custom config — override RPC and/or Arcium cluster offset:
 const client = new CypherClient({
   connection,
   wallet,
   cluster: {
     name: "devnet",
-    rpc: "https://my-helius-rpc.com",
+    rpc: "https://my-helius-endpoint.example",
     arciumClusterOffset: 456,
-    expectedMint: new PublicKey("8AF9BABNWwEhipRxtXPYoWSZW24SKjUn6YqbKd9ZqhwB"),
+    expectedMint: KNOWN_MINTS.devnetCSDC,
   },
 });
 ```
 
+---
+
 ## Scripts
 
-```bash
-bun run build           # Build dist/ with tsup
-bun run typecheck       # Type-check without emitting
-bun run test            # All unit tests
-bun run test:unit       # Unit tests only
-bun run test:integration # Integration (requires localnet)
-bun run test:devnet     # Devnet smoke (requires DEVNET_KEYPAIR)
-bun run sync:idl        # Copy IDL from ../cypher-main
-bun run clean           # Remove dist/
-```
+| Command | Purpose |
+| --- | --- |
+| `bun install` | Install deps |
+| `bun test` | All unit suites (gates skipped) |
+| `bun run test:unit` | Unit-only |
+| `bun run test:integration` | `INTEGRATION=1` — Arcium localnet lifecycle |
+| `bun run test:devnet` | `DEVNET=1` — devnet read-only + opt-in writes |
+| `bun run typecheck` | `tsc --noEmit` (strict) |
+| `bun run build` | ESM + `.d.ts` via tsup → `dist/` |
+| `bun run sync:idl` | Re-copy IDL + types from `../cypher-main` |
+| `bun run prepublishOnly` | sync IDL → typecheck → unit tests → build |
+
+---
 
 ## Security
 
-The Cypher protocol has undergone a comprehensive security audit (June 2026). All 9 findings — including 3 critical, 2 high, and 4 medium/low — have been fully remediated and verified in a second-round audit. See `cypher-main/audit_report.md` for the full report.
+The Cypher protocol underwent a two-round security audit. All 9
+findings — 3 critical, 2 high, 4 medium/low — have been remediated and
+verified. See `cypher-main/audit_report.md` for the full report.
+
+The SDK adds defense-in-depth client-side:
+
+- **`computeFees` mirrors the on-chain math exactly** — `placeBet`
+  pre-asserts the encrypted `net_amount` will match what the contract
+  computes from the gross. The contract's circuit also verifies this
+  on-chain (audit fix H-1) — the SDK guard surfaces the failure as a
+  clean rejection instead of a wasted MPC computation.
+- **`marketPhase` blocks known-bad claims** — `claimPayout` /
+  `claimRefund` refuse to send if the market isn't in the right phase,
+  saving users from on-chain `MarketStillOpen` / `ClaimPeriodExpired`
+  rejections.
+- **Position double-claim guard** — `claimPayout` reads `position.claimed`
+  before submitting (the contract enforces it again as audit fix H-2).
+- **Strict ciphertext-length enforcement** — every builder that takes a
+  `Uint8Array` ciphertext asserts `length === 32` before assembling the
+  ix, catching the "combined ciphertext arrays" mistake from the Arcium
+  skill before it hits the program.
+- **v0.2 dispute-window phase gating** — `claimPayout` rejects pre-flight
+  if `market.state === PendingResolution` with a typed error pointing
+  the caller at `finalizeResolution`, so users don't pay MPC compute
+  fees on a guaranteed-to-fail tx. `flagResolution` /
+  `finalizeResolution` / `adminOverrideResolution` validate against
+  `market.disputed` + `challengeDeadline` client-side.
+
+## Changelog
+
+### 0.2.0 — dispute window
+
+- **NEW**: 3 instructions (`flagResolution`, `finalizeResolution`,
+  `adminOverrideResolution`) + 3 actions + 3 React hooks + 3 events
+  + 6 error codes (6036–6041).
+- **NEW**: `MarketState.PendingResolution = 4` and three new
+  `marketPhase` values: `pendingResolution`, `awaitingFinalize`,
+  `disputed`.
+- **NEW**: `Market` gains `challengePeriod`, `challengeDeadline`,
+  `disputed` fields; layout offsets shifted.
+- **NEW**: `MIN_CHALLENGE_PERIOD_SECS` / `MAX_CHALLENGE_PERIOD_SECS`
+  constants (24h / 48h).
+- **BREAKING**: `createMarketIx` / `createMarketMultiIx` raw builders
+  require a new `challengePeriod` arg. The high-level
+  `client.actions.createMarket` makes it optional (defaults to 24h).
+- **BREAKING**: `resolveMarket` now leaves the market in
+  `PendingResolution`; `claimPayout` opens only after
+  `finalizeResolution` or `adminOverrideResolution` runs.
+- **DX**: `claimPayoutAction` pre-flight error now explicitly names
+  `finalizeResolution` as the next step when state is
+  `PendingResolution`.
+
+---
 
 ## License
 
-Source Available — use is permitted, redistribution is not. See [LICENSE](./LICENSE) for full terms.
+Source Available — use is permitted, redistribution is not. See
+[LICENSE](./LICENSE) for full terms.