@cypher-zk/sdk 0.4.0 → 0.5.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.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.
+
 ---
 
 ## Why this SDK exists
@@ -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
 
@@ -173,6 +191,10 @@ const { marketId, marketPda, signature } = await client.actions.createMarket({
   question: "Will ETH hit $10k by end of 2026?",
   closeTime: BigInt(Math.floor(Date.now() / 1000) + 7 * 24 * 3600),
   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,6 +232,12 @@ 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
@@ -224,6 +252,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();
@@ -248,8 +287,11 @@ 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 "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;
@@ -263,6 +305,162 @@ console.log("Resolution deadline:", new Date(Number(projected.resolutionDeadline
 
 ---
 
+## 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.
+
+---
+
 ## React hooks
 
 ```tsx
@@ -340,6 +538,9 @@ function MarketView({ marketId }: { marketId: bigint }) {
 | `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
@@ -367,7 +568,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 +579,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
 ```
@@ -460,6 +661,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`.
 
 ---