@cypher-zk/sdk 0.3.0 → 0.4.0

package/README.md

@@ -2,268 +2,468 @@
 
 > **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-130%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)]()
+[![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.
 
 ---
 
-## Features
+## Why this SDK exists
+
+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:
+
+- 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
 
-- **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
+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.
 
-## Installation
+```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 26 program instructions** with typed builders that return raw
+  `TransactionInstruction`s (compose, simulate, bundle freely).
+- **Seven high-level action helpers** (`createMarket`,
+  `createMarketMulti`, `placeBet`, `resolveMarket`, `claimPayout`,
+  `claimRefund`, `cancelMarket`, `withdrawCreatorFunds`) 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.
+- **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.
+- **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.
+
+## 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 |
+
+Core SDK works in any TypeScript environment with no peer requirements.
+
+---
 
-## Quick Start
+## Quickstart
 
-### Core SDK
+### 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" });
+```
+
+### 2. Read protocol state
 
-// Fetch 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
+  onProgress: (e) => console.log(e.stage),
 });
+```
+
+Multi-outcome variant — `createMarketMulti` with `numOutcomes: 2 | 3 | 4`.
 
-console.log("Market ID:", result.marketId);
-console.log("Market PDA:", result.marketPda.toBase58());
+### 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,
+});
+
+// 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.
+
+### 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);
 });
 
-// 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");
 ```
 
-### Parse Transaction Logs
+### 7. Phase helpers
 
 ```ts
-import { parseLogs } from "@cypher-zk/sdk";
-
-const tx = await connection.getTransaction(sig, { commitment: "confirmed" });
-const events = parseLogs(tx.meta?.logMessages ?? []);
-
-for (const evt of events) {
-  if (evt.name === "MarketResolvedEvent") {
-    console.log("Outcome:", evt.data.outcome);
-  }
+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;
 }
+
+// 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));
 ```
 
-## React Hooks
+---
+
+## 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 |
+| `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 (26 ix)
+│   ├── 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/               # 130 tests, 660+ 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.
+
+---
 
 ## 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cypher-zk/sdk",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "TypeScript SDK for the Cypher prediction market (Arcium + Anchor on Solana)",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",