@cypher-zk/sdk 0.4.0 → 0.6.0

package/README.md

@@ -2,15 +2,22 @@
 
 > **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-130%20passing-brightgreen)]()
+[![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.5.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.
+
 ---
 
 ## Why this SDK exists
@@ -35,8 +42,8 @@ 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)
+  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
@@ -45,34 +52,45 @@ const result = await client.actions.placeBet({
 
 ## What's in the box
 
-- **All 26 program instructions** with typed builders that return raw
-  `TransactionInstruction`s (compose, simulate, bundle freely).
-- **Seven high-level action helpers** (`createMarket`,
+- **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`) that hide the
-  "encrypt → send → await MPC callback → refetch" choreography.
+  `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** — 7 discriminated-union events with
-  `parseLogs`, `parseLogsFor`, `subscribeAll`, 7 `onXxx` helpers, and a
-  WebSocket-less `pollEvents` fallback. Decoded fields are camelCase
-  `bigint`s, matching the typed interfaces 1:1.
+- **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`, `useMarketEvents` — all built on
-  TanStack Query with sensible cache-invalidation defaults.
+  `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).
-- **130 unit tests** covering PDA derivations, fee math, deadline
-  phases, IDL drift, Arcium offsets, encryption round-trip, event
-  parser round-trip with all 7 event types, action input validation,
-  and React hook wiring. Plus opt-in localnet integration and devnet
-  smoke suites.
+- **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
 
@@ -84,9 +102,9 @@ npm install @cypher-zk/sdk
 
 ### Peer dependencies
 
-| Package | Required for |
-| --- | --- |
-| `react` ^18 \|\| ^19 | `@cypher-zk/sdk/react` subpath only |
+| Package                    | Required for                        |
+| -------------------------- | ----------------------------------- |
+| `react` ^18 \|\| ^19       | `@cypher-zk/sdk/react` subpath only |
 | `@tanstack/react-query` ^5 | `@cypher-zk/sdk/react` subpath only |
 
 Core SDK works in any TypeScript environment with no peer requirements.
@@ -116,8 +134,8 @@ const gs = await client.globalState.fetch();
 console.log("Protocol fee:", gs.protocolFeeRate, "bps");
 
 const market = await client.markets.fetch(0n);
-const active = await client.markets.byState(0);              // MarketState.Active
-const mine   = await client.markets.byCreator(wallet.publicKey);
+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);
 ```
 
@@ -131,15 +149,20 @@ const preview = computeFees(5_000_000n, {
   protocolFeeRateBps: gs.protocolFeeRate,
   lpFeeRateBps: gs.lpFeeRate,
 });
-console.log("Net stake:", preview.netAmount, "after fees:", preview.protocolFee + preview.lpFee);
+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,
-  side: 1,                 // 0 = NO, 1 = YES
-  amountUsdc: 5_000_000n,  // $5 (USDC has 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"
@@ -172,7 +195,11 @@ 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,                            // MarketCategory.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),
 });
 ```
@@ -210,13 +237,21 @@ 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):
 const sub = client.events.onBetPlaced((data) => {
   // `data` is BetPlacedEvent — fully typed (camelCase fields, bigint amounts):
-  console.log(`Bet placed on market ${data.market.toBase58()} — odds ${data.entryOdds}`);
+  console.log(
+    `Bet placed on market ${data.market.toBase58()} — odds ${data.entryOdds}`,
+  );
 });
 
 // Generic, typed by name:
@@ -224,6 +259,17 @@ 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();
 sub2.unsubscribe();
@@ -236,9 +282,14 @@ for (const { event, signature, slot } of recent) {
 
 // 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");
+const tx = await connection.getTransaction(sig, {
+  maxSupportedTransactionVersion: 0,
+});
+const allEvents = parseLogs(tx?.meta?.logMessages ?? []);
+const payoutsOnly = parseLogsFor(
+  tx?.meta?.logMessages ?? [],
+  "PayoutClaimedEvent",
+);
 ```
 
 ### 7. Phase helpers
@@ -248,18 +299,196 @@ 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 "claimable":        /* show "Claim payout" */ break;
-  case "refundable":       /* show "Claim refund" */ break;
-  case "expired":          /* show "Admin sweep eligible" */ break;
-  case "cancelled":        /* show "Cancelled" */ break;
+  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));
+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
+```
+
+### Three new actions
+
+```ts
+// 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").
+
+### Phase gating
+
+`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;
+}
+```
+
+### 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.
 
 ---
 
@@ -300,7 +529,7 @@ function MarketView({ marketId }: { marketId: bigint }) {
   });
 
   if (isLoading) return <p>Loading market…</p>;
-  if (!market)   return <p>Market not found.</p>;
+  if (!market) return <p>Market not found.</p>;
 
   return (
     <div>
@@ -320,7 +549,9 @@ function MarketView({ marketId }: { marketId: bigint }) {
       >
         {placeBet.isPending && stage ? `Bet → ${stage.stage}` : "Bet $5 YES"}
       </button>
-      {placeBet.error && <p style={{ color: "crimson" }}>{placeBet.error.message}</p>}
+      {placeBet.error && (
+        <p style={{ color: "crimson" }}>{placeBet.error.message}</p>
+      )}
     </div>
   );
 }
@@ -328,19 +559,22 @@ function MarketView({ marketId }: { marketId: bigint }) {
 
 ### 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 |
-| `useMarketEvents()` | Subscription | Live event stream (component-scoped) |
+| 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)`,
@@ -367,7 +601,7 @@ cypher-sdk/
 │   ├── client.ts           # CypherClient — single import surface
 │   ├── accounts/           # fetch + memcmp filter helpers per account
 │   ├── arcium/             # MPC glue (cipher, queue accounts, offsets)
-│   ├── instructions/       # raw TransactionInstruction builders (26 ix)
+│   ├── 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)
@@ -378,7 +612,7 @@ cypher-sdk/
 │   ├── architecture.md     # three-surface model + module map
 │   └── flows.md            # one diagram per user flow
 └── tests/
-    ├── unit/               # 130 tests, 660+ assertions — pure, no chain
+    ├── unit/               # 150 tests, 712 assertions — pure, no chain
     ├── integration/        # INTEGRATION=1 — Arcium localnet lifecycle
     └── devnet/             # DEVNET=1 — devnet read-only + opt-in writes
 ```
@@ -396,11 +630,11 @@ 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.
 
-| 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` |
+| 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:
@@ -423,17 +657,17 @@ const client = new CypherClient({
 
 ## Scripts
 
-| 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 |
+| 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     |
 
 ---
 
@@ -460,6 +694,36 @@ The SDK adds defense-in-depth client-side:
   `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`.
 
 ---