xmarket-solana-sdk 1.0.11

package/README.md

@@ -0,0 +1,339 @@
+# @prediction-market-sdk/xmarket-sdk
+
+Solana SDK for XMarket — binary prediction markets with on-chain CLOB, conditional tokens (Token-2022), and Ed25519 order signing.
+
+## Install
+
+```bash
+npm install @prediction-market-sdk/xmarket-sdk
+```
+
+## Quick Start
+
+```typescript
+import { XMarketSDK, signOrder } from "@prediction-market-sdk/xmarket-sdk";
+import * as anchor from "@coral-xyz/anchor";
+
+const sdk = XMarketSDK.devnet(new anchor.Wallet(keypair));
+
+sdk.market   // QuestionMarket program
+sdk.ctf      // Conditional Tokens program
+sdk.clob     // CLOB exchange
+sdk.oracle   // Oracle program
+sdk.hook     // Transfer-hook program
+```
+
+---
+
+## XMarketSDK
+
+```typescript
+XMarketSDK.devnet(wallet: anchor.Wallet, marketOwner?: PublicKey): XMarketSDK
+XMarketSDK.localnet(wallet: anchor.Wallet, marketOwner?: PublicKey): XMarketSDK
+XMarketSDK.mainnet(wallet: anchor.Wallet, marketOwner?: PublicKey): XMarketSDK
+XMarketSDK.custom(config: NetworkConfig, wallet: anchor.Wallet, marketOwner?: PublicKey): XMarketSDK
+```
+
+---
+
+## sdk.market — MarketClient
+
+### Instructions (sign + send)
+
+```typescript
+market.initialize(admin: PublicKey, oracle: PublicKey): Promise<TxResult>
+
+market.createQuestion(params: CreateQuestionParams, oracle: PublicKey): Promise<TxResult & {
+  questionPda: PublicKey; conditionPda: PublicKey; questionId: Uint8Array
+}>
+
+market.approveQuestion(questionPda: PublicKey): Promise<TxResult>
+market.rejectQuestion(questionPda: PublicKey): Promise<TxResult>
+market.resolveQuestion(questionId: Uint8Array, oracle: PublicKey): Promise<TxResult>
+market.updateConfig(params: { newAdmin?: PublicKey; newOracle?: PublicKey; isPaused?: boolean }): Promise<TxResult>
+```
+
+### Transaction builders (build only — no sign, no send)
+
+Each `*Tx` method returns a `Transaction` (or `{ tx, ...pdas }` for `createQuestionTx`).
+The caller is responsible for setting `feePayer`, signing, and submitting.
+Signer pubkey params default to `wallet.publicKey` if omitted.
+
+```typescript
+market.initializeTx(admin: PublicKey, oracle: PublicKey, owner?: PublicKey): Promise<Transaction>
+
+market.createQuestionTx(
+  params: CreateQuestionParams,
+  oracle: PublicKey,
+  creator?: PublicKey
+): Promise<{ tx: Transaction; questionPda: PublicKey; conditionPda: PublicKey; questionId: Uint8Array }>
+
+market.approveQuestionTx(questionPda: PublicKey, admin?: PublicKey): Promise<Transaction>
+market.rejectQuestionTx(questionPda: PublicKey, authority?: PublicKey): Promise<Transaction>
+market.resolveQuestionTx(questionId: Uint8Array, oracle: PublicKey, payer?: PublicKey): Promise<Transaction>
+market.updateConfigTx(
+  params: { newAdmin?: PublicKey; newOracle?: PublicKey; isPaused?: boolean },
+  authority?: PublicKey
+): Promise<Transaction>
+```
+
+**Backend pattern** — build tx, sign externally (e.g. Privy), submit via relay:
+
+```typescript
+const { tx, questionPda } = await sdk.market.createQuestionTx(params, oracle, userPubkey);
+
+tx.feePayer = beWallet.publicKey;
+tx.recentBlockhash = (await connection.getLatestBlockhash()).blockhash;
+
+// sign with Privy (creator) + BE wallet (feePayer)
+const signedTx = await privySigner.signTransaction(tx);
+beWallet.signTransaction(signedTx);
+
+await connection.sendRawTransaction(signedTx.serialize());
+```
+
+### Queries
+
+```typescript
+market.fetchConfig(): Promise<QuestionMarketConfig | null>
+market.fetchQuestion(questionPda: PublicKey): Promise<Question | null>
+market.questionPda(questionId: Uint8Array): PublicKey
+market.configPda: PublicKey
+```
+
+### CreateQuestionParams
+
+```typescript
+{
+  content: string           // question text
+  expirationTime: number    // unix timestamp
+  collateralMint: PublicKey // USDC mint
+  hookProgram: PublicKey    // transfer-hook program ID
+  authorizedClob: PublicKey // use PDA.clobConfig(programIds)[0]
+  questionId?: Uint8Array   // auto-derived from content if omitted
+  contentHash?: Uint8Array  // auto-derived from content if omitted
+}
+```
+
+---
+
+## sdk.ctf — CtfClient
+
+```typescript
+ctf.initializeVault(collateralMint: PublicKey): Promise<TxResult>
+
+ctf.splitPosition(condition: PublicKey, collateralMint: PublicKey, amount: BN, user?: PublicKey): Promise<TxResult>
+ctf.mergePosition(condition: PublicKey, collateralMint: PublicKey, amount: BN, user?: PublicKey): Promise<TxResult>
+ctf.redeemPositions(condition: PublicKey, collateralMint: PublicKey, user?: PublicKey): Promise<TxResult>
+
+ctf.reportPayouts(condition: PublicKey, payoutNumerators: number[]): Promise<TxResult>
+ctf.updateAuthorizedClob(condition: PublicKey, newAuthorizedClob: PublicKey): Promise<TxResult>
+ctf.transferPositionIx(...): Promise<TransactionInstruction>  // CPI only
+
+ctf.fetchCondition(conditionPda: PublicKey): Promise<Condition | null>
+ctf.fetchVault(collateralMint: PublicKey): Promise<CollateralVault | null>
+ctf.fetchPosition(condition: PublicKey, outcomeIndex: number, owner?: PublicKey): Promise<Position | null>
+ctf.fetchBothPositions(condition: PublicKey, owner?: PublicKey): Promise<{ yes: Position | null; no: Position | null }>
+
+ctf.yesMintPda(condition: PublicKey): PublicKey       // outcome index 1
+ctf.noMintPda(condition: PublicKey): PublicKey        // outcome index 0
+ctf.mintAuthorityPda(condition: PublicKey): PublicKey
+ctf.collateralVaultPda(collateralMint: PublicKey): PublicKey
+```
+
+> `splitPosition(amount)` — locks `amount` USDC, mints `amount` YES + `amount` NO (6 decimals, 1:1).
+> `redeemPositions` — requires both YES and NO position accounts. Call `splitPosition(new BN(1))` to init a missing position before redeeming.
+
+---
+
+## sdk.clob — ClobClient
+
+```typescript
+clob.initialize(operators: PublicKey[], feeRecipient: PublicKey, feeRateBps: number): Promise<TxResult>
+clob.addOperator(operator: PublicKey): Promise<TxResult>
+clob.removeOperator(operator: PublicKey): Promise<TxResult>
+clob.setPaused(paused: boolean): Promise<TxResult>
+clob.cancelOrder(nonce: BN): Promise<TxResult>
+
+// Secondary market: buyer pays USDC, seller gives YES/NO
+clob.matchComplementary(
+  buySigned: SignedOrder, sellSigned: SignedOrder, fillAmount: BN,
+  collateralMint: PublicKey, feeRecipient: PublicKey,
+  lookupTable?: AddressLookupTableAccount
+): Promise<TxResult>
+
+// Primary market: two buyers mint YES+NO from collateral
+clob.matchMintOrders(
+  yesSigned: SignedOrder, noSigned: SignedOrder, fillAmount: BN,
+  collateralMint: PublicKey, lookupTable?: AddressLookupTableAccount
+): Promise<TxResult>
+
+// Liquidity exit: two sellers merge YES+NO back to collateral
+clob.matchMergeOrders(
+  yesSigned: SignedOrder, noSigned: SignedOrder, fillAmount: BN,
+  collateralMint: PublicKey, feeRecipient: PublicKey,
+  lookupTable?: AddressLookupTableAccount
+): Promise<TxResult>
+
+clob.fetchConfig(): Promise<ClobConfig | null>
+clob.fetchOrderStatus(maker: PublicKey, nonce: BN): Promise<OrderStatus | null>
+clob.isOrderCancelled(maker: PublicKey, nonce: BN): Promise<boolean>
+clob.configPda(): PublicKey
+```
+
+---
+
+## sdk.oracle — OracleClient
+
+```typescript
+oracle.initialize(admin: PublicKey): Promise<TxResult>
+oracle.addReporter(reporterAddress: PublicKey, ownerPubkey?: PublicKey): Promise<TxResult>
+oracle.removeReporter(reporterAddress: PublicKey, ownerPubkey?: PublicKey): Promise<TxResult>
+
+// payoutNumerators: index 0 = NO, index 1 = YES
+// YES wins → [0, 1]   NO wins → [1, 0]
+oracle.resolveQuestion(questionId: Uint8Array, outcomeCount: number, payoutNumerators: number[], ownerPubkey?: PublicKey): Promise<TxResult>
+
+oracle.updateAdmin(newAdmin: PublicKey, ownerPubkey?: PublicKey): Promise<TxResult>
+oracle.transferOwnership(newOwner: PublicKey, ownerPubkey?: PublicKey): Promise<TxResult>
+oracle.pause(paused: boolean, ownerPubkey?: PublicKey): Promise<TxResult>
+
+oracle.fetchConfig(owner?: PublicKey): Promise<OracleConfig | null>
+oracle.fetchReporter(reporterAddress: PublicKey, ownerPubkey?: PublicKey): Promise<OracleReporter | null>
+oracle.fetchQuestionResult(questionId: Uint8Array, ownerPubkey?: PublicKey): Promise<QuestionResult | null>
+oracle.isReporter(reporterAddress: PublicKey, ownerPubkey?: PublicKey): Promise<boolean>
+oracle.configPda(owner?: PublicKey): PublicKey
+```
+
+---
+
+## sdk.hook — HookClient
+
+```typescript
+hook.initialize(initialWhitelist: PublicKey[]): Promise<TxResult>
+
+// Call once per YES/NO mint after condition creation
+hook.initializeExtraAccountMetaList(mint: PublicKey): Promise<TxResult>
+
+hook.addToWhitelist(program: PublicKey): Promise<TxResult>
+hook.removeFromWhitelist(program: PublicKey): Promise<TxResult>
+hook.freezeWhitelist(): Promise<TxResult>
+
+hook.fetchConfig(): Promise<HookConfig | null>
+hook.isWhitelisted(program: PublicKey): Promise<boolean>
+hook.configPda(): PublicKey
+```
+
+---
+
+## Ed25519 Order Signing
+
+```typescript
+import { signOrder } from "@prediction-market-sdk/xmarket-sdk";
+import nacl from "tweetnacl";
+import BN from "bn.js";
+
+const signed = await signOrder(
+  {
+    maker:    wallet.publicKey,
+    condition: conditionPda,
+    tokenId:  1,              // 1 = YES, 0 = NO
+    side:     1,              // 1 = BUY, 0 = SELL
+    priceBps: new BN(7_800),  // 0.78 USDC per token
+    amount:   new BN(10_000_000_000), // 10,000 tokens (6 decimals)
+    nonce:    new BN(Date.now()),
+    expiry:   new BN(0),      // 0 = no expiry
+  },
+  (msg) => nacl.sign.detached(msg, keypair.secretKey)
+);
+
+// Pass SignedOrder directly — Ed25519 precompile bundled automatically
+await sdk.clob.matchComplementary(buySigned, sellSigned, fillAmount, usdcMint, feeRecipient, alt);
+```
+
+---
+
+## PDA Utilities
+
+```typescript
+import { PDA, generateQuestionId, generateContentHash } from "@prediction-market-sdk/xmarket-sdk";
+
+PDA.questionMarketConfig(owner, programIds): [PublicKey, number]
+PDA.question(config, questionId, programIds): [PublicKey, number]
+PDA.condition(oracle, questionId, programIds): [PublicKey, number]
+PDA.collateralVault(collateralMint, programIds): [PublicKey, number]
+PDA.yesMint(condition, programIds): [PublicKey, number]     // outcome 1
+PDA.noMint(condition, programIds): [PublicKey, number]      // outcome 0
+PDA.mintAuthority(condition, programIds): [PublicKey, number]
+PDA.position(condition, outcomeIndex, owner, programIds): [PublicKey, number]
+PDA.clobConfig(programIds): [PublicKey, number]
+PDA.orderStatus(maker, nonce, programIds): [PublicKey, number]
+PDA.hookConfig(programIds): [PublicKey, number]
+PDA.extraAccountMetaList(mint, programIds): [PublicKey, number]
+PDA.oracleConfig(owner, programIds): [PublicKey, number]
+PDA.reporter(oracleConfig, reporterAddress, programIds): [PublicKey, number]
+PDA.questionResult(oracleConfig, questionId, programIds): [PublicKey, number]
+
+generateQuestionId(content: string, salt?: number): Uint8Array
+generateContentHash(content: string): Uint8Array
+```
+
+---
+
+## Full Flow Example
+
+```typescript
+import { XMarketSDK, PDA, signOrder, DEVNET_CONFIG } from "@prediction-market-sdk/xmarket-sdk";
+import * as anchor from "@coral-xyz/anchor";
+import nacl from "tweetnacl";
+import BN from "bn.js";
+
+const sdk = XMarketSDK.devnet(new anchor.Wallet(operatorKeypair));
+
+// 1. Create question
+const { conditionPda, questionPda, questionId } = await sdk.market.createQuestion({
+  content:        "Will BTC exceed $100k by end of 2025?",
+  expirationTime: Math.floor(Date.now() / 1000) + 30 * 86400,
+  collateralMint: USDC_MINT,
+  hookProgram:    DEVNET_CONFIG.programIds.hook,
+  authorizedClob: PDA.clobConfig(DEVNET_CONFIG.programIds)[0],
+}, oracleConfigPda);
+
+// 2. Approve + init hook metas
+await sdk.market.approveQuestion(questionPda);
+await sdk.hook.initializeExtraAccountMetaList(sdk.ctf.yesMintPda(conditionPda));
+await sdk.hook.initializeExtraAccountMetaList(sdk.ctf.noMintPda(conditionPda));
+
+// 3. Seller splits 10,000 USDC → YES + NO
+const sellerSdk = XMarketSDK.devnet(new anchor.Wallet(sellerKeypair));
+await sellerSdk.ctf.splitPosition(conditionPda, USDC_MINT, new BN(10_000_000_000));
+
+// 4. Match: buyer buys 10,000 YES @ 0.78 USDC
+const buySigned  = await signOrder(
+  { maker: buyerKp.publicKey,  condition: conditionPda, tokenId: 1, side: 1,
+    priceBps: new BN(7_800), amount: new BN(10_000_000_000), nonce: new BN(Date.now()),     expiry: new BN(0) },
+  (msg) => nacl.sign.detached(msg, buyerKp.secretKey)
+);
+const sellSigned = await signOrder(
+  { maker: sellerKp.publicKey, condition: conditionPda, tokenId: 1, side: 0,
+    priceBps: new BN(7_800), amount: new BN(10_000_000_000), nonce: new BN(Date.now() + 1), expiry: new BN(0) },
+  (msg) => nacl.sign.detached(msg, sellerKp.secretKey)
+);
+await sdk.clob.matchComplementary(buySigned, sellSigned, new BN(10_000_000_000),
+  USDC_MINT, feeRecipientPubkey, lookupTable);
+
+// 5. Oracle resolves YES wins → [NO=0, YES=1]
+await sdk.oracle.resolveQuestion(questionId, 2, [0, 1]);
+await sdk.market.resolveQuestion(questionId, oracleConfigPda);
+
+// 6. Redeem
+const buyerSdk = XMarketSDK.devnet(new anchor.Wallet(buyerKeypair));
+await buyerSdk.ctf.redeemPositions(conditionPda, USDC_MINT);  // winner
+await sellerSdk.ctf.redeemPositions(conditionPda, USDC_MINT); // loser → 0
+```
+
+---
+
+## License
+
+MIT