@vercora-protocol/sdk 0.0.10 → 0.0.12

package/README.md

@@ -14,97 +14,207 @@ yarn add @vercora-protocol/sdk
 
 ```bash
 npm install @coral-xyz/anchor @solana/web3.js @solana/spl-token bn.js
+# or
+yarn add @coral-xyz/anchor @solana/web3.js @solana/spl-token bn.js
 ```
 
 ## Quick start
 
 ```ts
 import * as anchor from "@coral-xyz/anchor";
-import { Program } from "@coral-xyz/anchor";
 import { Connection, clusterApiUrl } from "@solana/web3.js";
-import {
-  IDL,
-  PROGRAM_ID,
-  PredictionMarketClient,
-} from "@vercora-protocol/sdk";
+import { IDL, PROGRAM_ID, PredictionMarketClient } from "@vercora-protocol/sdk";
 import type { Vercora } from "@vercora-protocol/sdk";
-import { BN } from "bn.js";
 
-// 1. Set up an Anchor provider (browser wallet / NodeWallet)
 const connection = new Connection(clusterApiUrl("devnet"));
 const provider = new anchor.AnchorProvider(connection, wallet, {});
 anchor.setProvider(provider);
 
-// 2. Program from the bundled IDL (`IDL` includes the program address; `PROGRAM_ID` matches it)
+// Bundled IDL — program id is embedded in `IDL.address` (`PROGRAM_ID` matches it)
 const program = new anchor.Program<Vercora>(IDL, provider);
-
-// 3. Create the client
 const client = new PredictionMarketClient(program);
 ```
 
-## Platforms and categories
+Most transaction methods use **`provider.wallet.publicKey`** as the signer (`user`, `authority`, `creator`, etc.). Pass a wallet that can sign; read-only flows can use a read-only provider for fetch helpers only.
 
-Markets store **`platform_id`** as **`u32`** and **`category_id`** as **`u8`** on-chain (not pubkeys). See the IDL `CreateMarketArgs` and account layouts for the exact Borsh layout.
+## Package exports
 
-1. **`register_platform`** (program authority) — assigns the next id from `GlobalConfig.next_platform_id` and creates a **`PlatformRegistry`** PDA: seeds `["platform", platform_id.to_le_bytes()]` (4-byte little-endian `u32`). Holds `next_category_id` and `profile_authority` (who may edit the **`PlatformProfile`** for that id).
-2. **`create_market_category`** — args `(platform_id, category_id, name)`; **`category_id`** must equal **`PlatformRegistry.next_category_id`** (then the registry is bumped after init). PDA seeds: `["market-category", platform_id le u32, category_id le u8]`.
-3. **`create_market`** — args include `platform_id` and `category_id`. Rules: if `platform_id == 0` then `category_id` must be `0` and no registry/category accounts are passed. If `platform_id > 0`, pass the **`platform_registry`** account; if `category_id > 0`, pass the matching **`market_category`** account.
+| Export                   | Description                                                                                  |
+| ------------------------ | -------------------------------------------------------------------------------------------- |
+| `PredictionMarketClient` | High-level program wrapper (see below).                                                      |
+| `IDL`, `PROGRAM_ID`      | Anchor IDL JSON and `PublicKey` for the deployed program.                                    |
+| `pda` helpers            | `deriveMarket`, `deriveVault`, `deriveParimutuelState`, … (see [PDA helpers](#pda-helpers)). |
+| `types`                  | Params and account shapes (`CreateMarketParams`, `ListedMarket`, …).                         |
+| `marketUi`               | Pure UI helpers (`getMarketLifecycleStatus`, `formatTimeLeft`, …).                           |
+| `Vercora` (type)         | Anchor `Program` generic for `Program<Vercora>`.                                             |
 
-Use the SDK helpers **`derivePlatformRegistry`**, **`derivePlatformProfile`**, and **`deriveMarketCategory(programId, platformId, categoryId)`** when building transactions manually.
+---
 
-## Market types
+## `PredictionMarketClient` API
 
-Use `marketType: 'parimutuel'` or `marketType: 'completeSet'` when creating a market (the Anchor default is `completeSet` if you omit the field — set `parimutuel` explicitly for pool mode). The choice is permanent.
+Public properties: **`program`**, **`connection`**, **`globalConfig`** (PDA).
 
-### `parimutuel` — pool markets (**easiest to get started**)
+### Global config (authority)
 
-Stakes go into shared outcome pools on-chain. No outcome SPL tokens are minted. Odds follow pool sizes; the winning side splits the pot at settlement.
+| Method                              | Purpose                                        |
+| ----------------------------------- | ---------------------------------------------- |
+| `initializeConfig(params)`          | One-time init; `authority` = connected wallet. |
+| `updateConfig(params)`              | Update fees, treasury, authorities.            |
+| `addAllowedCollateralMint(mint)`    | Allowlist a collateral mint.                   |
+| `removeAllowedCollateralMint(mint)` | Remove from allowlist.                         |
 
-- **No liquidity layer required** — the pool is the market. Ship without wiring a DEX or running an AMM.
-- **Minimal integration** — stake, withdraw, claim; no outcome-token listings to maintain.
-- Positions are ledger entries, not transferable tokens. Early withdrawal may use a configurable penalty.
-- **Best for:** most prediction-style apps and teams that want live odds and settlement without operating liquidity infrastructure.
+### Platforms & categories
 
-### `completeSet` — token markets (**needs a liquidity layer**)
+| Method                         | Purpose                                                                  |
+| ------------------------------ | ------------------------------------------------------------------------ |
+| `registerPlatform(params)`     | Next `platform_id` from `GlobalConfig`; returns `{ platformId, sig }`.   |
+| `createMarketCategory(params)` | Next category id per `PlatformRegistry` (must match `next_category_id`). |
+| `updateMarketCategory(params)` | Rename / toggle active.                                                  |
 
-The protocol mints one SPL outcome token per outcome when users deposit collateral. The **program does not include an order book or AMM** — you must provide or integrate liquidity so users can trade between outcomes.
+### Market creation
+
+| Method                                                                                  | Purpose                                                                                             |
+| --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `createMarket(creator, collateralMint, creatorFeeAccount, params)`                      | Step 1: market + vault.                                                                             |
+| `initializeMarketResolverSlots(marketPda, params, opts?, parimutuelStateParams?)`       | Resolver PDAs; optional `parimutuelStateParams` appends `initializeParimutuelState` in the same tx. |
+| `initializeMarketOutcomeSlots(marketPda, params)`                                       | `MarketOutcome` labels (complete-set & pari).                                                       |
+| `initializeMarketMints(marketPda, marketId)`                                            | Mint 8 outcome SPLs (complete-set only).                                                            |
+| `initializeParimutuelState(marketPda, params)`                                          | Standalone pari pool + penalty params (if not bundled with resolvers).                              |
+| `createMarketFull(creator, collateralMint, creatorFeeAccount, resolverPubkeys, params)` | Runs create → outcomes → resolvers (+ mints **or** pari state in one flow).                         |
+| `updateParimutuelState(marketPda, params)`                                              | Creator updates early-exit penalty (open pari pool).                                                |
+
+**`CreateMarketParams` (pari-mutuel):** optional **`isEarlyWithdrawAllowed`** (default **`true`**). When **`false`**, the program rejects **`parimutuelWithdraw`** with **`EarlyWithdrawNotAllowed`** until close or resolution. Ignored for complete-set markets. Read back on **`fetchMarket(marketPda).isEarlyWithdrawAllowed`**.
+
+### Complete-set trading
+
+| Method                                                                                                                                   | Purpose                                          |
+| ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
+| `mintCompleteSet(user, marketPda, collateralMint, userCollateralAta, platformTreasury, creatorFeeAccount, params, opts?, tokenProgram?)` | Mint full set; creates missing outcome ATAs.     |
+| `redeemCompleteSet(user, marketPda, collateralMint, userCollateralAta, params)`                                                          | Burn full set for collateral.                    |
+| `redeemWinning(user, marketPda, collateralMint, userCollateralAta, params)`                                                              | After resolution, redeem winning outcome tokens. |
+
+### Parimutuel trading
 
-- Outcome tokens are composable SPL assets (wallets, DEXes, DeFi).
-- Mint/redeem full complete sets before close without a counterparty for that step.
-- **Single-outcome trading requires external liquidity** (AMM, RFQ, market-maker, etc.) or users cannot reliably move between legs.
-- **Best for:** teams that control or integrate a DEX, run their own pools, or pair the program with an explicit liquidity strategy.
+| Method                                  | Purpose                                                 |
+| --------------------------------------- | ------------------------------------------------------- |
+| `parimutuelStake(marketPda, params)`    | Stake; signer is **provider wallet** (`user` on-chain). |
+| `parimutuelWithdraw(marketPda, params)` | Early exit (penalty may apply). Errors if `Market.isEarlyWithdrawAllowed` is false. |
+| `parimutuelClaim(marketPda, params)`    | Claim after resolution.                                 |
+
+### Resolution & lifecycle
+
+| Method                                    | Purpose                                       |
+| ----------------------------------------- | --------------------------------------------- |
+| `voteResolution(marketPda, params)`       | Resolver vote.                                |
+| `revokeResolutionVote(marketPda, params)` | Clear vote before changing.                   |
+| `finalizeResolution(marketPda, params)`   | Anyone, once threshold met.                   |
+| `closeMarketEarly(marketPda, params)`     | Creator / config authority before `close_at`. |
+| `voidMarket(marketPda, params)`           | Void market.                                  |
+| `abandonMarket(marketPda, params)`        | Creator abandons empty market (reclaim rent). |
+
+### Discovery & reads
+
+| Method                                                            | Purpose                                                                                       |
+| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `fetchGlobalConfig()`                                             | Global config account.                                                                        |
+| `fetchMarket(marketPda)`                                          | `Market` account.                                                                             |
+| `fetchAllMarkets(platformId?)`                                    | All markets (optional `memcmp` on `platform_id`); includes outcome labels.                    |
+| `fetchMarketsByPlatform(platformId)`                              | Same as `fetchAllMarkets(platformId)`.                                                        |
+| `fetchMarketsByCreator(creator)`                                  | Raw rows `{ pubkey, account }[]`, memcmp on creator.                                          |
+| `getUsersMarkets(creator, filters?)`                              | **`ListedMarket[]`** for creator; optional `platformId` (RPC) + `categoryId` (client filter). |
+| `fetchMarketOutcomeLabels(marketPda, outcomeCount)`               | Outcome labels.                                                                               |
+| `fetchVaultBalance(marketPda)`                                    | Vault balance (bigint base units).                                                            |
+| `fetchOutcomeBalance(marketPda, user, outcomeIndex)`              | Single outcome token balance (complete-set).                                                  |
+| `fetchAllOutcomeBalances(marketPda, user, outcomeCount)`          | All outcome balances for user.                                                                |
+| `fetchMarketCategory(categoryPda)`                                | One category.                                                                                 |
+| `fetchAllMarketCategories()`                                      | All categories (sorted).                                                                      |
+| `fetchResolutionVote(marketPda, resolverIndex)`                   | Vote PDA or null.                                                                             |
+| `fetchMarketOutcomesSnapshot(marketPda, outcomeCount)`            | Decoded outcomes + tallies.                                                                   |
+| `fetchOutcomeTallyCounts(marketPda)`                              | Quick tally array.                                                                            |
+| `fetchAllowedCollateralMints()`                                   | Allowlist mints.                                                                              |
+| `fetchUserProfile(wallet)`                                        | User profile or null.                                                                         |
+| `fetchPlatformProfile(platformId)`                                | Platform profile or null.                                                                     |
+| `fetchParimutuelState(marketPda)`                                 | Pari pool state.                                                                              |
+| `fetchParimutuelPosition(marketPda, user, outcomeIndex)`          | Position or null.                                                                             |
+| `fetchParimutuelActiveStakesBatch(marketPda, user, outcomeCount)` | Active stakes per outcome.                                                                    |
+| `computeParimutuelOdds(state, outcomeCount)`                      | Implied probs + payout multipliers.                                                           |
+| `fetchResolver(marketPda, index)`                                 | One resolver account.                                                                         |
+| `fetchAllResolvers(marketPda, numResolvers)`                      | Initialized resolver slots.                                                                   |
+
+### Profiles
+
+| Method                             | Purpose                                     |
+| ---------------------------------- | ------------------------------------------- |
+| `upsertUserProfile(params)`        | Display name / URL.                         |
+| `closeUserProfile()`               | Close caller’s profile.                     |
+| `verifyUserProfile(params)`        | Verifier marks verified.                    |
+| `upsertPlatformProfile(params)`    | Platform profile (scoped by `platform_id`). |
+| `closePlatformProfile(platformId)` | Close profile.                              |
+| `verifyPlatformProfile(params)`    | Verify platform profile.                    |
 
 ---
 
-## Usage examples
+## Examples
 
-### Create a market
+### Global config (first deploy)
 
 ```ts
-import { BN } from "bn.js";
+import { PublicKey } from "@solana/web3.js";
+import BN from "bn.js";
+
+await client.initializeConfig({
+  // System program / “none” placeholder — use a real secondary authority pubkey in production
+  secondaryAuthority: new PublicKey("11111111111111111111111111111111"),
+  depositPlatformFeeBps: 100,
+  platformTreasuryWallet: treasuryPubkey,
+  platformFeeLamports: new BN(357_000),
+  parimutuelWithdrawPlatformFeeBps: 50,
+});
+```
+
+### Register platform & category
+
+```ts
+const { platformId } = await client.registerPlatform({
+  profileAuthority: profileSignerPubkey,
+});
 
-const marketId = new BN(Date.now()); // unique u64 per creator
+await client.createMarketCategory({
+  platformId,
+  name: "Politics",
+});
+```
+
+### Create a market (manual steps, complete-set)
+
+```ts
+import BN from "bn.js";
+
+const marketId = new BN(Date.now());
 const { marketPda } = await client.createMarket(
-  provider.wallet.publicKey, // creator
-  collateralMintPubkey,
-  creatorFeeAccountPubkey,
+  creatorPubkey,
+  collateralMint,
+  creatorFeeAta,
   {
     marketId,
     outcomeCount: 2,
     resolutionThreshold: 1,
-    closeAt: new BN(Math.floor(Date.now() / 1000) + 86400), // 24 h from now
+    closeAt: new BN(Math.floor(Date.now() / 1000) + 86400),
     creatorFeeBps: 50,
-    depositPlatformFeeBps: 0, // 0 = inherit global config
+    depositPlatformFeeBps: 0,
     numResolvers: 1,
+    maxOutcomeInvestment: new BN(0),
     title: "Will it rain tomorrow?",
-    marketType: "completeSet", // or 'parimutuel'
-    // Optional: scoped market (omit or use new BN(0) for unscoped / uncategorized)
+    marketType: "completeSet",
     platformId: new BN(0),
     categoryId: new BN(0),
   },
 );
 
-// Resolver slots and outcome mints must be initialised before trading
+await client.initializeMarketOutcomeSlots(marketPda, {
+  marketId,
+  labels: ["Yes", "No"],
+});
 await client.initializeMarketResolverSlots(marketPda, {
   marketId,
   resolverPubkeys: [resolverPubkey],
@@ -112,98 +222,192 @@ await client.initializeMarketResolverSlots(marketPda, {
 await client.initializeMarketMints(marketPda, marketId);
 ```
 
-### Complete-set trading
+### Create market in one call (`createMarketFull`)
+
+Complete-set (mints outcome tokens):
 
 ```ts
-// Mint one complete set (all outcomes)
-await client.mintCompleteSet(
-  user,
-  marketPda,
+const marketPda = await client.createMarketFull(
+  creatorPubkey,
   collateralMint,
-  userCollateralAta,
-  platformTreasury,
-  creatorFeeAccount,
-  { marketId, amount: new BN(1_000_000) },
+  creatorFeeAta,
+  [resolverPubkey],
+  {
+    marketId,
+    outcomeCount: 2,
+    resolutionThreshold: 1,
+    closeAt: new BN(Math.floor(Date.now() / 1000) + 86400),
+    creatorFeeBps: 50,
+    depositPlatformFeeBps: 0,
+    numResolvers: 1,
+    maxOutcomeInvestment: new BN(0),
+    title: "Two-outcome market",
+    marketType: "completeSet",
+    outcomeLabels: ["Yes", "No"],
+  },
 );
+```
 
-// Redeem a complete set back to collateral
-await client.redeemCompleteSet(
-  user,
-  marketPda,
+Parimutuel (resolver tx also initializes pari state; optional `parimutuelInit` overrides defaults):
+
+```ts
+const marketPda = await client.createMarketFull(
+  creatorPubkey,
   collateralMint,
-  userCollateralAta,
-  { marketId },
+  creatorFeeAta,
+  [resolverPubkey],
+  {
+    marketId,
+    outcomeCount: 2,
+    resolutionThreshold: 1,
+    closeAt: new BN(Math.floor(Date.now() / 1000) + 86400),
+    creatorFeeBps: 50,
+    depositPlatformFeeBps: 0,
+    numResolvers: 1,
+    maxOutcomeInvestment: new BN(0),
+    title: "Pari pool",
+    marketType: "parimutuel",
+    outcomeLabels: ["A", "B"],
+    // Optional — default true. Set false to lock stakes until close/resolution (no early parimutuelWithdraw).
+    isEarlyWithdrawAllowed: true,
+    parimutuelInit: {
+      earlyWithdrawPenaltyBps: 500,
+      penaltyKeptInPoolBps: 8000,
+    },
+  },
 );
-
-// After resolution — redeem the winning outcome tokens
-await client.redeemWinning(user, marketPda, collateralMint, userCollateralAta, {
-  marketId,
-  amount: winningBalance,
-});
 ```
 
-### Parimutuel trading
+### Complete-set trading
 
 ```ts
-// Stake on an outcome
-await client.parimutuelStake(
-  user,
+const treasury = (await client.fetchGlobalConfig()).platformTreasury;
+
+await client.mintCompleteSet(
+  userPubkey,
   marketPda,
   collateralMint,
   userCollateralAta,
-  platformTreasury,
-  creatorFeeAccount,
-  { marketId, outcomeIndex: 0, amount: new BN(500_000) },
+  treasury,
+  creatorFeeAta,
+  { marketId, amount: new BN(1_000_000) },
 );
 
-// Withdraw before market closes (penalty may apply)
-await client.parimutuelWithdraw(
-  user,
+await client.redeemCompleteSet(
+  userPubkey,
   marketPda,
   collateralMint,
   userCollateralAta,
-  { marketId, outcomeIndex: 0, amount: new BN(500_000) },
+  { marketId },
 );
 
-// Claim winnings after resolution
-await client.parimutuelClaim(
-  user,
+await client.redeemWinning(
+  userPubkey,
   marketPda,
   collateralMint,
   userCollateralAta,
-  { marketId, outcomeIndex: 0 },
+  {
+    marketId,
+    amount: winningAmountBn,
+  },
 );
 ```
 
+### Parimutuel trading
+
+Signer is always the **connected wallet** (no `user` first argument):
+
+```ts
+await client.parimutuelStake(marketPda, {
+  marketId,
+  outcomeIndex: 0,
+  amount: new BN(500_000),
+});
+
+await client.parimutuelWithdraw(marketPda, {
+  marketId,
+  outcomeIndex: 0,
+  amount: new BN(500_000),
+});
+// If create used isEarlyWithdrawAllowed: false, parimutuelWithdraw throws (Anchor: EarlyWithdrawNotAllowed).
+
+await client.parimutuelClaim(marketPda, {
+  marketId,
+  outcomeIndex: 0,
+});
+
+const state = await client.fetchParimutuelState(marketPda);
+const odds = client.computeParimutuelOdds(state, 2);
+```
+
 ### Resolution
 
 ```ts
-// Resolver votes on the winning outcome
 await client.voteResolution(marketPda, {
   marketId,
   resolverIndex: 0,
-  outcomeIndex: 1, // 0-based
+  outcomeIndex: 1,
 });
 
-// Once the threshold is met, anyone can finalize
 await client.finalizeResolution(marketPda, { marketId });
 ```
 
-### Read on-chain state
+### Discovery
+
+```ts
+// Every market (heavy on RPC)
+const all = await client.fetchAllMarkets();
+
+// By platform (memcmp)
+const byPlatform = await client.fetchAllMarkets(new BN(1));
+
+// Markets created by a wallet — full rows with labels + filters
+const mine = await client.getUsersMarkets(creatorPubkey, {
+  platformId: new BN(1), // optional RPC filter
+  categoryId: 2, // optional; applied after decode
+});
+
+// Raw accounts only (no labels)
+const raw = await client.fetchMarketsByCreator(creatorPubkey);
+```
+
+### User profile
 
 ```ts
-const market = await client.fetchMarket(marketPda);
-console.log(market.title, market.marketType, market.platformId.toString(), market.categoryId.toString());
+await client.upsertUserProfile({
+  displayName: "Alice",
+  url: "https://example.com",
+});
 
-const config = await client.fetchGlobalConfig();
+const profile = await client.fetchUserProfile(wallet.publicKey);
 ```
 
+---
+
+## Platforms and categories
+
+On-chain, **`platform_id`** is **`u32`** and **`category_id`** is **`u8`** in `CreateMarketArgs` (not pubkeys).
+
+1. **`register_platform`** — assigns the next id from `GlobalConfig.next_platform_id`; PDA `["platform", platform_id le u32]`.
+2. **`create_market_category`** — `category_id` must equal `PlatformRegistry.next_category_id` before bump; PDA `["market-category", platform_id, category_id]`.
+3. **`create_market`** — if `platform_id == 0` then `category_id` must be `0`. If `platform_id > 0`, pass `platform_registry`; if `category_id > 0`, pass `market_category`.
+
+Use **`derivePlatformRegistry`**, **`derivePlatformProfile`**, **`deriveMarketCategory`** when building instructions manually.
+
+## Market types
+
+Use `marketType: 'parimutuel'` or `'completeSet'` at creation; the choice is permanent.
+
+- **Parimutuel** — pooled stakes, no outcome SPLs; good default for prediction apps. Optional **`isEarlyWithdrawAllowed`** on create (default **allowed**); when disabled, users cannot call **`parimutuelWithdraw`** early.
+- **Complete-set** — outcome SPL tokens; you still need external liquidity for single-leg trading.
+
 ## PDA helpers
 
-All PDAs are derived in `pda.ts` and re-exported from the package:
+From `@vercora-protocol/sdk`:
 
 ```ts
 import {
+  PROGRAM_ID,
   deriveGlobalConfig,
   deriveAllowedMint,
   deriveMarket,
@@ -213,24 +417,49 @@ import {
   deriveResolver,
   deriveAllResolvers,
   deriveResolutionVote,
+  deriveMarketOutcome,
+  deriveAllMarketOutcomes,
+  deriveParimutuelState,
+  deriveParimutuelPosition,
   deriveUserProfile,
   derivePlatformRegistry,
   derivePlatformProfile,
   deriveMarketCategory,
+  bnLike,
+  bnToU32,
+  bnToU8,
 } from "@vercora-protocol/sdk";
 
-const marketPda = deriveMarket(program.programId, creatorPubkey, marketId);
-const vaultPda = deriveVault(program.programId, marketPda);
-const [mint0] = deriveAllOutcomeMints(program.programId, marketPda, 2);
+const marketPda = deriveMarket(PROGRAM_ID, creatorPubkey, marketId);
+const vaultPda = deriveVault(PROGRAM_ID, marketPda);
 ```
 
-## TypeScript types
+Offsets **`MARKET_ACCOUNT_CREATOR_MEMCMP_OFFSET`** and **`MARKET_ACCOUNT_PLATFORM_ID_MEMCMP_OFFSET`** are exported for custom `getProgramAccounts` filters.
+
+## `marketUi` helpers
+
+```ts
+import {
+  getMarketLifecycleStatus,
+  formatTimeLeft,
+  listedMarketFeedTag,
+} from "@vercora-protocol/sdk";
 
-All parameter and account types are exported directly:
+const status = getMarketLifecycleStatus({
+  isVoided: false,
+  isClosedEarly: false,
+  winningOutcomeIndex: null,
+  closeAt: ts,
+});
+```
+
+## TypeScript types
 
 ```ts
 import type {
   CreateMarketParams,
+  ListedMarket,
+  GetUsersMarketsFilters,
   MarketAccount,
   ParimutuelStateAccount,
   ParimutuelOdds,
@@ -241,20 +470,18 @@ import type {
 
 ## AI agent integration
 
-If you are building agents or automation on top of this protocol:
-
-1. **Bootstrap**: create a `Connection`, wallet, `Program<Vercora>`, then `PredictionMarketClient`.
-2. **Read + route**: call `fetchMarket(marketPda)` and branch by `market.marketType`.
-3. **Flow**:
-   - Optional: `registerPlatform` → `createMarketCategory` for a scoped listing; then `createMarket` with matching `platformId` / `categoryId`.
-   - Create: `createMarket` → `initializeMarketResolverSlots` → `initializeMarketMints` (or `initializeParimutuelState`)
-   - Complete-set: `mintCompleteSet` → `redeemCompleteSet` → `redeemWinning`
-   - Parimutuel: `parimutuelStake` → `parimutuelWithdraw` → `parimutuelClaim`
-   - Resolution: `voteResolution` → `finalizeResolution`
-4. **Safety**: verify signer role, derive PDAs with helpers, handle missing ATAs, return tx signatures.
+1. **Bootstrap**: `Connection` → `AnchorProvider` → `Program<Vercora>` from `IDL` → `PredictionMarketClient`.
+2. **Branch**: `fetchMarket` → `market.marketType` (`completeSet` vs `parimutuel`).
+3. **Flows**:
+   - Optional: `registerPlatform` → `createMarketCategory` → `createMarket` with ids.
+   - Create: `createMarketFull` **or** `createMarket` + resolver / outcome / mint **or** pari init.
+   - Complete-set: `mintCompleteSet` → `redeemCompleteSet` → `redeemWinning`.
+   - Parimutuel: `parimutuelStake` → optional `parimutuelWithdraw` (if `isEarlyWithdrawAllowed`) → `parimutuelClaim`.
+   - Resolution: `voteResolution` → `finalizeResolution`.
+4. **Discovery**: `fetchAllMarkets`, `getUsersMarkets`, `fetchMarketsByCreator`.
+5. **Safety**: verify signers, PDAs, ATAs, and RPC limits on `getProgramAccounts`.
 
 ## Links
 
-- [GitHub source](https://github.com/vercora/vercora-anchor)
 - [Vercora app](https://vercora.xyz)
 - [npm package](https://www.npmjs.com/package/@vercora-protocol/sdk)

package/dist/client.d.ts

@@ -2,7 +2,7 @@ import * as anchor from '@coral-xyz/anchor';
 import { Program, BN } from '@coral-xyz/anchor';
 import { Connection, PublicKey } from '@solana/web3.js';
 import type { Vercora } from './generated/vercora';
-import type { CreateMarketParams, InitializeParimutuelStateParams, ParimutuelStakeParams, ParimutuelWithdrawParams, ParimutuelClaimParams, InitializeConfigParams, UpdateConfigParams, InitializeMarketResolverSlotsParams, InitializeMarketOutcomeSlotsParams, MintCompleteSetParams, RedeemCompleteSetParams, VoteResolutionParams, FinalizeResolutionParams, RevokeResolutionVoteParams, RedeemWinningParams, CloseMarketEarlyParams, VoidMarketParams, AbandonMarketParams, GlobalConfigAccount, MarketAccount, ResolverAccount, UpsertUserProfileParams, VerifyUserProfileParams, UserProfileAccount, UpsertPlatformProfileParams, VerifyPlatformProfileParams, PlatformProfileAccount, ParimutuelStateAccount, ParimutuelPositionAccount, ParimutuelOdds, MarketCategoryAccount, CreateMarketCategoryParams, UpdateMarketCategoryParams, RegisterPlatformParams, UpdateParimutuelStateParams, ResolutionVoteAccount, ListedMarket } from './types';
+import type { CreateMarketParams, InitializeParimutuelStateParams, ParimutuelStakeParams, ParimutuelWithdrawParams, ParimutuelClaimParams, InitializeConfigParams, UpdateConfigParams, InitializeMarketResolverSlotsParams, InitializeMarketOutcomeSlotsParams, MintCompleteSetParams, RedeemCompleteSetParams, VoteResolutionParams, FinalizeResolutionParams, RevokeResolutionVoteParams, RedeemWinningParams, CloseMarketEarlyParams, VoidMarketParams, AbandonMarketParams, GlobalConfigAccount, MarketAccount, ResolverAccount, UpsertUserProfileParams, VerifyUserProfileParams, UserProfileAccount, UpsertPlatformProfileParams, VerifyPlatformProfileParams, PlatformProfileAccount, ParimutuelStateAccount, ParimutuelPositionAccount, ParimutuelOdds, MarketCategoryAccount, CreateMarketCategoryParams, UpdateMarketCategoryParams, RegisterPlatformParams, UpdateParimutuelStateParams, ResolutionVoteAccount, ListedMarket, GetUsersMarketsFilters } from './types';
 export declare class PredictionMarketClient {
     readonly program: Program<Vercora>;
     readonly connection: Connection;
@@ -56,6 +56,9 @@ export declare class PredictionMarketClient {
     /**
      * Step 1 — Create Market + Vault.
      * Returns the market PDA and the transaction signature.
+     *
+     * For pari-mutuel markets, `params.isEarlyWithdrawAllowed` (default `true`) is stored on-chain.
+     * When `false`, `parimutuelWithdraw` fails until close/resolution (see `PredictionMarketError::EarlyWithdrawNotAllowed`).
      */
     createMarket(creator: PublicKey, collateralMint: PublicKey, creatorFeeAccount: PublicKey, params: CreateMarketParams, opts?: anchor.web3.ConfirmOptions): Promise<{
         marketPda: PublicKey;
@@ -79,6 +82,8 @@ export declare class PredictionMarketClient {
     /**
      * Convenience: run all 3 market creation steps in sequence.
      * Returns the market PDA.
+     *
+     * Pari-mutuel: passes `params.isEarlyWithdrawAllowed` through `createMarket` (default allows early withdraw).
      */
     createMarketFull(creator: PublicKey, collateralMint: PublicKey, creatorFeeAccount: PublicKey, 
     /** Length must equal `params.numResolvers` (typically the first N of an 8-slot UI). */
@@ -91,6 +96,11 @@ export declare class PredictionMarketClient {
      */
     updateParimutuelState(marketPda: PublicKey, params: UpdateParimutuelStateParams, opts?: anchor.web3.ConfirmOptions): Promise<string>;
     parimutuelStake(marketPda: PublicKey, params: ParimutuelStakeParams, opts?: anchor.web3.ConfirmOptions): Promise<string>;
+    /**
+     * Reduce stake before `close_at` / resolution (early exit). Penalties and platform fees may apply.
+     * Fails with Anchor error **`EarlyWithdrawNotAllowed`** when `fetchMarket(marketPda).isEarlyWithdrawAllowed === false`
+     * (set at `createMarket` / `createMarketFull` via `CreateMarketParams.isEarlyWithdrawAllowed`).
+     */
     parimutuelWithdraw(marketPda: PublicKey, params: ParimutuelWithdrawParams, opts?: anchor.web3.ConfirmOptions): Promise<string>;
     parimutuelClaim(marketPda: PublicKey, params: ParimutuelClaimParams, opts?: anchor.web3.ConfirmOptions): Promise<string>;
     /**
@@ -143,6 +153,10 @@ export declare class PredictionMarketClient {
     fetchGlobalConfig(): Promise<GlobalConfigAccount>;
     fetchMarket(market: PublicKey): Promise<MarketAccount>;
     private bnFieldToListedString;
+    /**
+     * Map raw `Market` account rows to {@link ListedMarket} (including outcome labels).
+     */
+    private buildListedMarketsFromRawRows;
     /**
      * List on-chain `Market` accounts, with outcome labels fetched per market.
      * Uses Anchor `program.account.market.all()`; when `platformId` is set, uses RPC `memcmp` on
@@ -163,6 +177,14 @@ export declare class PredictionMarketClient {
         pubkey: PublicKey;
         account: MarketAccount;
     }[]>;
+    /**
+     * Markets created by `creator`, as {@link ListedMarket} rows (with outcome labels).
+     *
+     * Uses RPC `memcmp` on `creator` and optionally on `platform_id` (when `filters.platformId` is set).
+     * When `filters.categoryId` is set, results are narrowed after decode (see {@link GetUsersMarketsFilters}).
+     * Sorted by `market_id` ascending.
+     */
+    getUsersMarkets(creator: PublicKey, filters?: GetUsersMarketsFilters): Promise<ListedMarket[]>;
     /**
      * Read `MarketOutcome.label` for each active outcome index (parallel fetches).
      * Missing accounts yield `Outcome {i+1}` placeholders.