@lightconexyz/lightcone-sdk 0.1.0

package/README.md

@@ -0,0 +1,232 @@
+# Lightcone TypeScript SDK
+
+TypeScript SDK for the Lightcone protocol on Solana.
+
+## Installation
+
+```bash
+npm install @lightcone/sdk
+```
+
+## Modules
+
+| Module | Description |
+|--------|-------------|
+| [`program`](src/program/README.md) | On-chain Solana program interaction (accounts, transactions, orders, Ed25519 verification) |
+| [`api`](src/api/README.md) | REST API client for market data and order management |
+| [`websocket`](src/websocket/README.md) | Real-time data streaming via WebSocket |
+| [`shared`](src/shared/README.md) | Shared utilities (Resolution, constants, decimal helpers) |
+
+## Quick Start
+
+```typescript
+import { LightconePinocchioClient, PROGRAM_ID, api, websocket } from "@lightcone/sdk";
+```
+
+### REST API
+
+Query markets, submit orders, and manage positions via the REST API.
+
+```typescript
+import { api } from "@lightcone/sdk";
+
+const client = new api.LightconeApiClient();
+
+// Get markets
+const markets = await client.getMarkets();
+console.log(`Found ${markets.total} markets`);
+
+// Get orderbook depth
+const orderbook = await client.getOrderbook("orderbook_id", 10);
+console.log(`Best bid: ${orderbook.best_bid}`);
+console.log(`Best ask: ${orderbook.best_ask}`);
+
+// Get user positions
+const positions = await client.getUserPositions("user_pubkey");
+```
+
+### On-Chain Program
+
+Build transactions for on-chain operations: minting positions, matching orders, redeeming winnings.
+
+```typescript
+import { Connection, Keypair } from "@solana/web3.js";
+import { LightconePinocchioClient, BidOrderParams } from "@lightcone/sdk";
+
+const connection = new Connection("https://api.devnet.solana.com");
+const client = new LightconePinocchioClient(connection);
+
+// Fetch account state
+const exchange = await client.getExchange();
+const market = await client.getMarket(0n);
+console.log(`Market status: ${market.status}`);
+
+// Create a signed order
+const keypair = Keypair.generate();
+const nonce = await client.getNextNonce(keypair.publicKey);
+
+const order = client.signFullOrder(
+  client.createBidOrder({
+    nonce,
+    maker: keypair.publicKey,
+    market: client.pda.getMarketPda(0n, client.programId)[0],
+    baseMint: conditionalTokenMint,
+    quoteMint: usdcMint,
+    makerAmount: 1_000_000n, // 1 USDC
+    takerAmount: 500_000n,   // 0.5 outcome tokens
+    expiration: 0n,
+  }),
+  keypair
+);
+```
+
+### WebSocket
+
+Stream real-time orderbook updates, trades, and user events.
+
+```typescript
+import { websocket } from "@lightcone/sdk";
+
+const client = await websocket.LightconeWebSocketClient.connectDefault();
+
+// Subscribe to orderbook updates
+client.subscribeBookUpdates(["market:orderbook"]);
+
+// Register event handler
+client.on((event) => {
+  if (event.type === "BookUpdate") {
+    const book = client.getOrderbook(event.orderbookId);
+    if (book) {
+      console.log(`Best bid: ${book.bestBid()}`);
+      console.log(`Best ask: ${book.bestAsk()}`);
+    }
+  } else if (event.type === "Trade") {
+    console.log(`Trade: ${event.trade.size} @ ${event.trade.price}`);
+  } else if (event.type === "Disconnected") {
+    console.log(`Disconnected: ${event.reason}`);
+  }
+});
+```
+
+## Module Overview
+
+### Program Module
+
+Direct interaction with the Lightcone Solana program:
+
+- **Account Types**: Exchange, Market, Position, OrderStatus, UserNonce
+- **Transaction Builders**: All 14 instructions (mint, merge, match, settle, etc.)
+- **PDA Derivation**: 8 PDA functions with seeds
+- **Order Types**: FullOrder (225 bytes), CompactOrder (65 bytes)
+- **Ed25519 Verification**: Three strategies (individual, batch, cross-reference)
+
+```typescript
+import {
+  LightconePinocchioClient,
+  createBidOrder,
+  signOrderFull,
+  hashOrder,
+} from "@lightcone/sdk";
+
+// Create and sign an order
+const order = signOrderFull(
+  createBidOrder({
+    nonce: 1n,
+    maker: pubkey,
+    market: marketPda,
+    baseMint: yesToken,
+    quoteMint: noToken,
+    makerAmount: 100_000n,
+    takerAmount: 50_000n,
+    expiration: 0n,
+  }),
+  keypair
+);
+const orderHash = hashOrder(order);
+```
+
+### API Module
+
+REST API client with typed requests and responses:
+
+- **Markets**: getMarkets, getMarket, getMarketBySlug
+- **Orderbooks**: getOrderbook with depth parameter
+- **Orders**: submitOrder, cancelOrder, cancelAllOrders
+- **Positions**: getUserPositions, getUserMarketPositions
+- **Trades**: getTrades with filters
+- **Price History**: getPriceHistory with OHLCV
+
+```typescript
+import { api } from "@lightcone/sdk";
+
+const client = new api.LightconeApiClient();
+const response = await client.submitOrder({
+  maker: "pubkey",
+  nonce: 1,
+  market_pubkey: "market",
+  base_token: "base",
+  quote_token: "quote",
+  side: 0, // BID
+  maker_amount: 1000000,
+  taker_amount: 500000,
+  expiration: 0,
+  signature: "hex_signature",
+  orderbook_id: "orderbook",
+});
+```
+
+### WebSocket Module
+
+Real-time streaming with automatic state management:
+
+- **Subscriptions**: book_updates, trades, user, price_history, market
+- **State Management**: LocalOrderbook, UserState, PriceHistory
+- **Authentication**: Ed25519 sign-in for user streams
+- **Auto-Reconnect**: Configurable reconnection with exponential backoff and jitter
+
+```typescript
+import { websocket } from "@lightcone/sdk";
+import { Keypair } from "@solana/web3.js";
+
+// Authenticated connection for user streams
+const keypair = Keypair.generate();
+const client = await websocket.LightconeWebSocketClient.connectAuthenticated(keypair);
+client.subscribeUser(keypair.publicKey.toBase58());
+
+// Access maintained state
+const state = client.getUserState(keypair.publicKey.toBase58());
+if (state) {
+  console.log(`Open orders: ${state.orderCount()}`);
+}
+```
+
+### Shared Module
+
+Common utilities used across modules:
+
+- **Resolution**: Candle intervals (1m, 5m, 15m, 1h, 4h, 1d)
+- **Constants**: Program IDs, seeds, discriminators, sizes
+- **Types**: MarketStatus, OrderSide, account data interfaces
+
+```typescript
+import { Resolution, PROGRAM_ID } from "@lightcone/sdk";
+
+const res = Resolution.OneHour; // "1h"
+console.log(res); // "1h"
+```
+
+## Features
+
+- **Full TypeScript support**: Comprehensive types for all APIs
+- **Zero-copy serialization**: Efficient binary order formats
+- **Cross-instruction Ed25519**: Optimized transaction sizes
+- **Automatic reconnection**: Jittered exponential backoff
+- **State management**: Local orderbook and user state tracking
+
+## Program ID
+
+**Mainnet/Devnet**: `EfRvELrn4b5aJRwddD1VUrqzsfm1pewBLPebq3iMPDp2`
+
+## License
+
+MIT

package/dist/api/client.d.ts

@@ -0,0 +1,225 @@
+/**
+ * REST API client for Lightcone.
+ */
+import { Keypair } from "@solana/web3.js";
+import { type AuthCredentials } from "../auth";
+import type { MarketsResponse, MarketInfoResponse, DepositAssetsResponse, OrderbookResponse, SubmitOrderRequest, OrderResponse, CancelResponse, CancelAllResponse, PositionsResponse, MarketPositionsResponse, UserOrdersResponse, PriceHistoryParams, PriceHistoryResponse, TradesParams, TradesResponse, AdminResponse, CreateOrderbookRequest, CreateOrderbookResponse } from "./types";
+export { DEFAULT_API_URL } from "../network";
+/**
+ * Configuration for retry behavior.
+ */
+export interface RetryConfig {
+    /** Maximum number of retry attempts (default: 0 = disabled) */
+    maxRetries: number;
+    /** Initial delay in milliseconds (default: 100) */
+    baseDelayMs: number;
+    /** Maximum delay cap in milliseconds (default: 10000) */
+    maxDelayMs: number;
+}
+/** Default retry configuration (disabled) */
+export declare const DEFAULT_RETRY_CONFIG: RetryConfig;
+/**
+ * Configuration for the Lightcone API client.
+ */
+export interface LightconeApiClientConfig {
+    /** Base URL for the API (default: https://tapi.lightcone.xyz/api) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Additional headers to include in requests */
+    headers?: Record<string, string>;
+    /** Retry configuration for transient failures */
+    retry?: Partial<RetryConfig>;
+    /** Authentication token for authenticated endpoints */
+    authToken?: string;
+}
+/**
+ * REST API client for the Lightcone platform.
+ *
+ * @example
+ * ```typescript
+ * import { LightconeApiClient } from "@lightcone/sdk/api";
+ *
+ * const client = new LightconeApiClient();
+ *
+ * // Get all markets
+ * const markets = await client.getMarkets();
+ *
+ * // Get orderbook
+ * const orderbook = await client.getOrderbook("market1:ob1");
+ * ```
+ */
+export declare class LightconeApiClient {
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly headers;
+    private readonly retryConfig;
+    private authToken?;
+    constructor(config?: LightconeApiClientConfig);
+    /**
+     * Log in with a Solana keypair. Stores the auth token for subsequent requests.
+     *
+     * @param keypair - The Solana Keypair for authentication
+     * @returns AuthCredentials containing the auth token and user info
+     */
+    login(keypair: Keypair): Promise<AuthCredentials>;
+    /**
+     * Set the authentication token manually.
+     */
+    setAuthToken(token: string): void;
+    /**
+     * Clear the authentication token.
+     */
+    clearAuthToken(): void;
+    /**
+     * Check if the client has an authentication token.
+     */
+    hasAuthToken(): boolean;
+    /**
+     * Make an HTTP request with retry support.
+     */
+    private request;
+    /**
+     * Check if the API is healthy.
+     *
+     * @throws {ApiError} If the health check fails
+     */
+    healthCheck(): Promise<void>;
+    /**
+     * Get all available markets.
+     *
+     * @returns List of markets
+     */
+    getMarkets(): Promise<MarketsResponse>;
+    /**
+     * Get market information by pubkey.
+     *
+     * @param marketPubkey - Market PDA address (Base58)
+     * @returns Market details
+     * @throws {ApiError} If marketPubkey is invalid
+     */
+    getMarket(marketPubkey: string): Promise<MarketInfoResponse>;
+    /**
+     * Get market information by slug.
+     *
+     * @param slug - URL-friendly market slug
+     * @returns Market details
+     */
+    getMarketBySlug(slug: string): Promise<MarketInfoResponse>;
+    /**
+     * Get deposit assets for a market.
+     *
+     * @param marketPubkey - Market PDA address (Base58)
+     * @returns Deposit assets
+     * @throws {ApiError} If marketPubkey is invalid
+     */
+    getDepositAssets(marketPubkey: string): Promise<DepositAssetsResponse>;
+    /**
+     * Get orderbook snapshot.
+     *
+     * @param orderbookId - Orderbook identifier
+     * @param depth - Number of levels (default: 20)
+     * @returns Orderbook snapshot
+     */
+    getOrderbook(orderbookId: string, depth?: number): Promise<OrderbookResponse>;
+    /**
+     * Submit a new order.
+     *
+     * @param request - Order details
+     * @returns Order response with hash and fill info
+     * @throws {ApiError} If any pubkey or signature is invalid
+     */
+    submitOrder(request: SubmitOrderRequest): Promise<OrderResponse>;
+    /**
+     * Cancel an order with a pre-computed signature.
+     *
+     * @param orderHash - Hash of the order to cancel (hex)
+     * @param maker - Order creator's pubkey (Base58)
+     * @param signature - Ed25519 signature over the order hash (hex, 128 chars)
+     * @returns Cancel response
+     * @throws {ApiError} If maker pubkey or signature is invalid
+     */
+    cancelOrderWithSignature(orderHash: string, maker: string, signature: string): Promise<CancelResponse>;
+    /**
+     * Cancel an order, auto-signing with the given keypair.
+     *
+     * @param orderHash - Hash of the order to cancel (hex)
+     * @param signer - Keypair to sign the cancellation
+     * @returns Cancel response
+     */
+    cancelOrder(orderHash: string, signer: Keypair): Promise<CancelResponse>;
+    /**
+     * Cancel all orders for a user with a pre-computed signature.
+     *
+     * @param userPubkey - User's public key (Base58)
+     * @param signature - Ed25519 signature over "cancel_all:{pubkey}:{timestamp}" (hex, 128 chars)
+     * @param timestamp - Unix timestamp used in the signed message
+     * @param orderbookId - Optional orderbook filter
+     * @returns Cancel all response
+     * @throws {ApiError} If any pubkey or signature is invalid
+     */
+    cancelAllOrdersWithSignature(userPubkey: string, signature: string, timestamp: number, orderbookId?: string): Promise<CancelAllResponse>;
+    /**
+     * Cancel all orders for a user, auto-signing with the given keypair.
+     *
+     * @param signer - Keypair to sign the cancellation
+     * @param orderbookId - Optional orderbook filter
+     * @returns Cancel all response
+     */
+    cancelAllOrders(signer: Keypair, orderbookId?: string): Promise<CancelAllResponse>;
+    /**
+     * Get user positions across all markets.
+     *
+     * @param userPubkey - User's public key (Base58)
+     * @returns User positions
+     * @throws {ApiError} If userPubkey is invalid
+     */
+    getUserPositions(userPubkey: string): Promise<PositionsResponse>;
+    /**
+     * Get user positions in a specific market.
+     *
+     * @param userPubkey - User's public key (Base58)
+     * @param marketPubkey - Market PDA address (Base58)
+     * @returns Market positions
+     * @throws {ApiError} If any pubkey is invalid
+     */
+    getUserMarketPositions(userPubkey: string, marketPubkey: string): Promise<MarketPositionsResponse>;
+    /**
+     * Get user's open orders.
+     *
+     * @param userPubkey - User's public key (Base58)
+     * @returns User orders and balances
+     * @throws {ApiError} If userPubkey is invalid
+     */
+    getUserOrders(userPubkey: string): Promise<UserOrdersResponse>;
+    /**
+     * Get historical price data.
+     *
+     * @param params - Query parameters
+     * @returns Price history data
+     * @throws {ApiError} If limit is out of bounds (1-500)
+     */
+    getPriceHistory(params: PriceHistoryParams): Promise<PriceHistoryResponse>;
+    /**
+     * Get recent trades.
+     *
+     * @param params - Query parameters
+     * @returns Trade history
+     * @throws {ApiError} If limit is out of bounds (1-500)
+     */
+    getTrades(params: TradesParams): Promise<TradesResponse>;
+    /**
+     * Admin health check.
+     *
+     * @returns Admin status
+     */
+    adminHealthCheck(): Promise<AdminResponse>;
+    /**
+     * Create a new orderbook (admin only).
+     *
+     * @param request - Orderbook creation request
+     * @returns Created orderbook info
+     */
+    createOrderbook(request: CreateOrderbookRequest): Promise<CreateOrderbookResponse>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/api/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"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"}