@cypher-zk/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,32 @@
+Cypher SDK — Source Available License
+
+Copyright (c) 2026 Cypher Labs. All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to use the Software solely for the purpose of integrating with and building
+applications on the Cypher, subject to the following conditions:
+
+1. USE: You may use, copy, and modify the Software for internal development,
+   testing, and production use in applications that interact with the Cypher.
+
+2. NO REDISTRIBUTION: You may NOT redistribute, sublicense, publish, sell,
+   or otherwise make available the Software or any derivative works thereof
+   to any third party, whether in source code or compiled form, without the
+   prior written consent of Cypher.
+
+3. NO COMPETING PRODUCTS: You may NOT use the Software or any portion thereof
+   to build or operate a prediction market protocol, SDK, or competing
+   product that is not built on the Cypher.
+
+4. ATTRIBUTION: All copies or substantial portions of the Software used in
+   your applications must retain the above copyright notice and this
+   permission notice.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,266 @@
+# Cypher SDK
+
+> **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)]()
+
+---
+
+## Features
+
+- **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
+
+## Installation
+
+```bash
+npm install @cypher-zk/sdk
+# or
+bun add @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 |
+
+## Quick Start
+
+### Core SDK
+
+```ts
+import { CypherClient, keypairToWallet } from "@cypher-zk/sdk";
+import { Connection, Keypair } from "@solana/web3.js";
+
+const connection = new Connection("https://api.devnet.solana.com");
+const wallet = keypairToWallet(Keypair.generate());
+
+const client = new CypherClient({ connection, wallet, cluster: "devnet" });
+
+// Fetch protocol state
+const gs = await client.globalState.fetch();
+console.log("Market counter:", gs.marketCounter);
+
+// 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
+```
+
+### Place a Private Bet (end-to-end)
+
+```ts
+import { MarketType } from "@cypher-zk/sdk";
+
+const result = 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)
+});
+
+console.log("Tx:", result.signature);
+console.log("Entry odds:", result.position?.entryOdds);
+```
+
+### Create a Market
+
+```ts
+const result = 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
+});
+
+console.log("Market ID:", result.marketId);
+console.log("Market PDA:", result.marketPda.toBase58());
+```
+
+### Subscribe to Events
+
+```ts
+// Real-time (WebSocket)
+const sub = client.events.onBetPlaced((data) => {
+  console.log("Bet placed! Odds:", data.entryOdds);
+});
+
+// Later: sub.unsubscribe();
+
+// Poll-based (no WS needed)
+const recent = await client.events.pollEvents({ limit: 20 });
+for (const { event } of recent) {
+  console.log(event.name, event.data);
+}
+```
+
+### Parse Transaction Logs
+
+```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);
+  }
+}
+```
+
+## React Hooks
+
+```tsx
+import { CypherProvider, useMarket, usePlaceBet } from "@cypher-zk/sdk/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+const queryClient = new QueryClient();
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <CypherProvider client={client}>
+        <MarketView />
+      </CypherProvider>
+    </QueryClientProvider>
+  );
+}
+
+function MarketView() {
+  const { data: market, isLoading } = useMarket(0n);
+  const { mutateAsync: placeBet, isPending } = usePlaceBet();
+
+  if (isLoading) return <p>Loading…</p>;
+
+  return (
+    <div>
+      <h1>{market?.question}</h1>
+      <button
+        disabled={isPending}
+        onClick={() => placeBet({
+          payer: wallet.publicKey,
+          user: wallet.publicKey,
+          marketId: 0n,
+          marketType: 0,
+          side: 0,
+          amountUsdc: 1_000_000n,
+        })}
+      >
+        Bet YES ($1)
+      </button>
+    </div>
+  );
+}
+```
+
+### Available Hooks
+
+| 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
+
+```
+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
+└── tests/
+    ├── unit/               # 107 tests, 581 assertions
+    ├── integration/        # Localnet lifecycle (INTEGRATION=1)
+    └── devnet/             # Devnet smoke test (DEVNET=1)
+```
+
+## Cluster Configuration
+
+The SDK is **cluster-agnostic** — it reads `GlobalState.accepted_mint` on-chain at runtime:
+
+| Cluster | Accepted Mint | Arcium Cluster Offset |
+| --- | --- | --- |
+| `devnet` | CSDC (`8AF9BABN…`) | `456` |
+| `mainnet` | USDC (`EPjFWdd5…`) | TBD |
+| `localnet` | CSDC (same as devnet) | `1116522022` |
+
+Override cluster detection:
+
+```ts
+// Explicit preset
+const client = new CypherClient({ connection, wallet, cluster: "devnet" });
+
+// Fully custom
+const client = new CypherClient({
+  connection, wallet,
+  cluster: {
+    name: "devnet",
+    rpc: "https://my-helius-rpc.com",
+    arciumClusterOffset: 456,
+    expectedMint: new PublicKey("8AF9BABNWwEhipRxtXPYoWSZW24SKjUn6YqbKd9ZqhwB"),
+  },
+});
+```
+
+## 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/
+```
+
+## 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.
+
+## License
+
+Source Available — use is permitted, redistribution is not. See [LICENSE](./LICENSE) for full terms.

package/dist/chunk-5WRI5ZAA.js

@@ -0,0 +1,29 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __commonJS = (cb, mod) => function __require() {
+  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+export { __commonJS, __toESM };
+//# sourceMappingURL=chunk-5WRI5ZAA.js.map
+//# sourceMappingURL=chunk-5WRI5ZAA.js.map

package/dist/chunk-5WRI5ZAA.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"chunk-5WRI5ZAA.js"}