> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whisky.casino/llms.txt
> Use this file to discover all available pages before exploring further.

# Whisky Core SDK

> TypeScript SDK for direct protocol interaction and smart contract calls

# Whisky Core SDK

The Whisky Core SDK is a comprehensive TypeScript library that provides direct interaction with the Whisky Gaming Protocol smart contracts on Solana. It abstracts complex blockchain operations and provides type-safe interfaces for building gaming applications.

## Overview

The Core SDK serves as the protocol layer, handling:

* **Smart Contract Calls**: Direct blockchain interactions
* **Transaction Building**: Creating and signing transactions
* **Account Management**: PDA derivation and management
* **Protocol Logic**: Mathematical calculations and validations

## Installation

### Prerequisites

* Node.js 16.0.0 or higher
* Solana CLI tools
* Anchor framework
* TypeScript 4.5.0 or higher

### Install Dependencies

```bash theme={null}
npm install @whisky-gaming/core
```

### Anchor Program

```bash theme={null}
anchor build
anchor deploy
```

## Quick Start

### Initialize SDK

```typescript theme={null}
import { WhiskySDK } from '@whisky-gaming/core';
import { Connection, Keypair } from '@solana/web3.js';

const sdk = new WhiskySDK({
  connection: new Connection('https://api.mainnet-beta.solana.com'),
  wallet: yourWallet,
  programId: WHISKY_PROGRAM_ID
});
```

### Initialize Protocol

```typescript theme={null}
// Initialize protocol (one-time setup)
await sdk.initializeProtocol({
  authority: authorityPublicKey,
  rngProvider: rngProviderPublicKey,
  protocolFee: 200 // 2%
});
```

### Create Gaming Pool

```typescript theme={null}
// Create USDC gaming pool
const poolAddress = await sdk.createPool({
  tokenMint: USDC_MINT_ADDRESS,
  minimumWager: 1_000_000, // 1 USDC
  poolAuthority: poolAuthorityKeypair
});
```

### Add Liquidity

```typescript theme={null}
// Deposit 1000 USDC to earn fees from games
await sdk.depositLiquidity(poolAddress, 1000_000_000);
```

### Play Game

```typescript theme={null}
// Simple coinflip game
const gameResult = await sdk.playGame({
  poolAddress,
  wager: 10_000_000, // 10 USDC
  bet: [50, 50], // Equal probability outcomes
  clientSeed: 'player_randomness_123',
  creatorFee: 100, // 1%
  jackpotFee: 50,  // 0.5%
  metadata: 'Coinflip Game #1'
});

// Wait for RNG settlement
await sdk.waitForSettlement(gameResult.gameAddress);

// Claim winnings if won
if (gameResult.won) {
  await sdk.claimWinnings(gameResult.gameAddress);
}
```

## Core API Reference

### WhiskySDK Class

#### Constructor

```typescript theme={null}
new WhiskySDK(config: WhiskySDKConfig)
```

**Configuration:**

```typescript theme={null}
interface WhiskySDKConfig {
  connection: Connection;
  wallet: Wallet;
  programId: PublicKey;
  commitment?: Commitment;
  confirmTransactionInitialTimeout?: number;
}
```

### Gaming Methods

#### `playGame(params: PlayGameParams): Promise<GameResult>`

Initiates a new gaming session.

**Parameters:**

```typescript theme={null}
interface PlayGameParams {
  poolAddress: PublicKey;
  wager: number;
  bet: number[];
  clientSeed: string;
  creatorFee: number;
  jackpotFee: number;
  metadata: string;
}
```

**Returns:**

```typescript theme={null}
interface GameResult {
  gameAddress: PublicKey;
  signature: string;
  won: boolean;
  payout?: number;
  multiplier?: number;
}
```

**Example:**

```typescript theme={null}
const result = await sdk.playGame({
  poolAddress: new PublicKey('POOL_ADDRESS'),
  wager: 1000000, // 1 USDC
  bet: [25, 25, 25, 25], // Four equal outcomes
  clientSeed: 'my_random_seed_123',
  creatorFee: 100, // 1%
  jackpotFee: 50,  // 0.5%
  metadata: 'Dice Roll Game'
});
```

#### `waitForSettlement(gameAddress: PublicKey): Promise<GameSettlement>`

Waits for game settlement and returns the result.

**Returns:**

```typescript theme={null}
interface GameSettlement {
  gameAddress: PublicKey;
  result: number;
  payout: number;
  multiplier: number;
  won: boolean;
  signature: string;
}
```

#### `claimWinnings(gameAddress: PublicKey): Promise<string>`

Claims winnings from a settled game.

**Returns:** Transaction signature

### Pool Management

#### `createPool(params: CreatePoolParams): Promise<PublicKey>`

Creates a new liquidity pool for specified token.

**Parameters:**

```typescript theme={null}
interface CreatePoolParams {
  tokenMint: PublicKey;
  minimumWager: number;
  maximumWager?: number;
  poolAuthority: Keypair;
  feeBps?: number;
}
```

**Returns:** Pool address

**Example:**

```typescript theme={null}
const poolAddress = await sdk.createPool({
  tokenMint: new PublicKey('USDC_MINT_ADDRESS'),
  minimumWager: 1000000, // 1 USDC
  maximumWager: 1000000000, // 1000 USDC
  poolAuthority: poolAuthorityKeypair,
  feeBps: 100 // 1%
});
```

#### `depositLiquidity(poolAddress: PublicKey, amount: number): Promise<string>`

Deposits tokens into liquidity pool.

**Parameters:**

* `poolAddress`: Target pool address
* `amount`: Token amount to deposit (in base units)

**Returns:** Transaction signature

**Example:**

```typescript theme={null}
const signature = await sdk.depositLiquidity(
  new PublicKey('POOL_ADDRESS'),
  1000000000 // 1000 USDC
);
```

#### `withdrawLiquidity(poolAddress: PublicKey, lpTokenAmount: number): Promise<string>`

Withdraws liquidity from pool.

**Parameters:**

* `poolAddress`: Target pool address
* `lpTokenAmount`: LP token amount to burn

**Returns:** Transaction signature

#### `getPoolInfo(poolAddress: PublicKey): Promise<PoolInfo>`

Gets pool information.

**Returns:**

```typescript theme={null}
interface PoolInfo {
  poolAuthority: PublicKey;
  underlyingTokenMint: PublicKey;
  minWager: number;
  maxWager: number;
  totalLiquidity: number;
  totalPlays: number;
  totalVolume: number;
  lpTokenMint: PublicKey;
  feeBps: number;
}
```

### Account Management

#### `getWhiskyState(): Promise<WhiskyState>`

Gets global protocol state.

**Returns:**

```typescript theme={null}
interface WhiskyState {
  authority: PublicKey;
  rngAddress: PublicKey;
  whiskyFeeBps: number;
  playingAllowed: boolean;
  totalVolume: number;
  totalGames: number;
  totalFees: number;
}
```

#### `getGameInfo(gameAddress: PublicKey): Promise<GameInfo>`

Gets game information.

**Returns:**

```typescript theme={null}
interface GameInfo {
  pool: PublicKey;
  player: PublicKey;
  wager: number;
  bet: number[];
  clientSeed: string;
  rngSeed: string;
  status: GameStatus;
  result?: number;
  payout?: number;
  multiplier?: number;
  timestamp: number;
}
```

### Utility Functions

#### `validateBet(bet: number[]): boolean`

Validates betting structure for mathematical correctness.

```typescript theme={null}
// Valid examples
validateBet([50, 50]);           // Equal probability
validateBet([25, 25, 25, 25]);   // Four equal outcomes
validateBet([90, 10]);           // Asymmetric probability

// Invalid examples
validateBet([0, 0]);             // No winning outcomes
validateBet([]);                 // Empty bet array
```

#### `calculatePayout(wager: number, bet: number[], outcome: number): number`

Calculates payout for specific outcome.

```typescript theme={null}
const payout = calculatePayout(1000000, [50, 50], 0); // 2x multiplier
```

#### `calculateJackpotOdds(wager: number, poolSize: number): number`

Determines jackpot probability based on wager size.

```typescript theme={null}
const odds = calculateJackpotOdds(10000000, 1000000000); // 0.001% base odds
```

#### `deriveGameAddress(poolAddress: PublicKey, player: PublicKey, nonce: number): PublicKey`

Derives game account address.

```typescript theme={null}
const gameAddress = deriveGameAddress(poolAddress, player, nonce);
```

## Advanced Usage Examples

### Binary Prediction Market

```typescript theme={null}
// Create yes/no prediction market
const predictionGame = await sdk.playGame({
  poolAddress: usdcPool,
  wager: 50_000_000, // 50 USDC
  bet: [60, 40], // 60% probability for "Yes"
  clientSeed: 'prediction_12345',
  creatorFee: 200, // 2% to market creator
  jackpotFee: 0,   // No jackpot for predictions
  metadata: 'Election Outcome Prediction'
});
```

### Multi-Outcome Casino Game

```typescript theme={null}
// Six-sided dice roll
const diceGame = await sdk.playGame({
  poolAddress: solPool,
  wager: 5_000_000_000, // 5 SOL
  bet: [16, 16, 16, 16, 16, 20], // Slightly favor outcome 6
  clientSeed: 'dice_roll_789',
  creatorFee: 300, // 3% house edge
  jackpotFee: 100, // 1% progressive jackpot
  metadata: 'Lucky Dice Roll'
});
```

### Slot Machine Simulation

```typescript theme={null}
// Complex probability distribution
const slotGame = await sdk.playGame({
  poolAddress: bonkPool,
  wager: 1_000_000_000, // 1B BONK tokens
  bet: [
    500, // 50% - No win
    300, // 30% - Small win (2x)
    150, // 15% - Medium win (5x)
    40,  // 4% - Large win (20x)
    9,   // 0.9% - Huge win (100x)
    1    // 0.1% - Jackpot (1000x)
  ],
  clientSeed: 'slot_machine_456',
  creatorFee: 500, // 5% house edge
  jackpotFee: 200, // 2% progressive jackpot
  metadata: 'Triple 7s Slot Machine'
});
```

### Batch Operations

```typescript theme={null}
// Create multiple pools
const poolAddresses = await Promise.all([
  sdk.createPool({
    tokenMint: USDC_MINT_ADDRESS,
    minimumWager: 1_000_000,
    poolAuthority: poolAuthority1
  }),
  sdk.createPool({
    tokenMint: SOL_MINT_ADDRESS,
    minimumWager: 1_000_000_000,
    poolAuthority: poolAuthority2
  })
]);

// Deposit liquidity to multiple pools
const depositSignatures = await Promise.all([
  sdk.depositLiquidity(poolAddresses[0], 1000_000_000), // 1000 USDC
  sdk.depositLiquidity(poolAddresses[1], 100_000_000_000) // 100 SOL
]);
```

### Error Handling

```typescript theme={null}
try {
  const result = await sdk.playGame({
    poolAddress: new PublicKey('INVALID_POOL'),
    wager: 1000000,
    bet: [50, 50],
    clientSeed: 'test',
    creatorFee: 100,
    jackpotFee: 50,
    metadata: 'Test Game'
  });
} catch (error) {
  if (error instanceof WhiskyError) {
    switch (error.code) {
      case 'INSUFFICIENT_LIQUIDITY':
        console.error('Pool has insufficient liquidity');
        break;
      case 'INVALID_BET':
        console.error('Invalid betting structure');
        break;
      case 'WAGER_TOO_SMALL':
        console.error('Wager below minimum');
        break;
      default:
        console.error('Unknown error:', error.message);
    }
  } else {
    console.error('Unexpected error:', error);
  }
}
```

## Mathematical Utilities

### Probability Calculations

```typescript theme={null}
import { calculateMultiplier, validateProbabilityDistribution } from '@whisky-gaming/core';

// Calculate multiplier for outcome
const multiplier = calculateMultiplier([25, 25, 25, 25], 0); // 4.0

// Validate probability distribution
const isValid = validateProbabilityDistribution([50, 30, 20]); // true
```

### House Edge Calculations

```typescript theme={null}
import { calculateHouseEdge, calculateExpectedValue } from '@whisky-gaming/core';

// Calculate house edge
const houseEdge = calculateHouseEdge([50, 50], 100); // 0% (fair game)
const unfairEdge = calculateHouseEdge([45, 55], 100); // 10% house edge

// Calculate expected value
const ev = calculateExpectedValue([50, 50], 1000000); // 1000000 (fair)
```

## Transaction Management

### Custom Transaction Options

```typescript theme={null}
const result = await sdk.playGame({
  poolAddress,
  wager: 1000000,
  bet: [50, 50],
  clientSeed: 'test',
  creatorFee: 100,
  jackpotFee: 50,
  metadata: 'Test Game'
}, {
  commitment: 'confirmed',
  preflightCommitment: 'processed',
  maxRetries: 3
});
```

### Transaction Monitoring

```typescript theme={null}
const signature = await sdk.playGame(gameParams);

// Monitor transaction
const confirmation = await sdk.connection.confirmTransaction(signature, 'confirmed');

if (confirmation.value.err) {
  console.error('Transaction failed:', confirmation.value.err);
} else {
  console.log('Transaction confirmed');
}
```

## Security Considerations

### Input Validation

```typescript theme={null}
// Always validate inputs before sending transactions
if (!validateBet(bet)) {
  throw new Error('Invalid betting structure');
}

if (wager < minWager || wager > maxWager) {
  throw new Error('Wager out of range');
}
```

### Error Handling

```typescript theme={null}
// Handle specific error types
try {
  await sdk.playGame(gameParams);
} catch (error) {
  if (error instanceof WhiskyError) {
    // Handle protocol-specific errors
    handleWhiskyError(error);
  } else if (error instanceof SolanaError) {
    // Handle Solana-specific errors
    handleSolanaError(error);
  } else {
    // Handle unexpected errors
    console.error('Unexpected error:', error);
  }
}
```

### Transaction Safety

```typescript theme={null}
// Always verify transaction before sending
const transaction = await sdk.buildPlayGameTransaction(gameParams);
const simulation = await sdk.connection.simulateTransaction(transaction);

if (simulation.value.err) {
  console.error('Transaction simulation failed:', simulation.value.err);
  return;
}

// Send transaction only after successful simulation
const signature = await sdk.sendTransaction(transaction);
```

## Performance Optimization

### Connection Management

```typescript theme={null}
// Use connection pooling for high-frequency operations
const connection = new Connection('https://api.mainnet-beta.solana.com', {
  commitment: 'confirmed',
  wsEndpoint: 'wss://api.mainnet-beta.solana.com',
  confirmTransactionInitialTimeout: 60000
});

const sdk = new WhiskySDK({
  connection,
  wallet: yourWallet,
  programId: WHISKY_PROGRAM_ID
});
```

### Batch Transactions

```typescript theme={null}
// Batch multiple operations in a single transaction
const instructions = [
  await sdk.buildPlayGameInstruction(gameParams1),
  await sdk.buildPlayGameInstruction(gameParams2),
  await sdk.buildClaimWinningsInstruction(gameAddress)
];

const transaction = new Transaction().add(...instructions);
const signature = await sdk.sendTransaction(transaction);
```

## Testing

### Unit Testing

```typescript theme={null}
import { WhiskySDK } from '@whisky-gaming/core';

describe('WhiskySDK', () => {
  let sdk: WhiskySDK;

  beforeEach(() => {
    sdk = new WhiskySDK({
      connection: new Connection('http://localhost:8899'),
      wallet: testWallet,
      programId: testProgramId
    });
  });

  test('should create pool successfully', async () => {
    const poolAddress = await sdk.createPool({
      tokenMint: testTokenMint,
      minimumWager: 1000000,
      poolAuthority: testAuthority
    });

    expect(poolAddress).toBeDefined();
  });
});
```

### Integration Testing

```typescript theme={null}
describe('Game Flow', () => {
  test('should complete full game cycle', async () => {
    // Create pool
    const poolAddress = await sdk.createPool(poolParams);
    
    // Add liquidity
    await sdk.depositLiquidity(poolAddress, 1000000000);
    
    // Play game
    const gameResult = await sdk.playGame(gameParams);
    
    // Wait for settlement
    const settlement = await sdk.waitForSettlement(gameResult.gameAddress);
    
    // Claim winnings if won
    if (settlement.won) {
      await sdk.claimWinnings(gameResult.gameAddress);
    }
    
    expect(settlement).toBeDefined();
  });
});
```

## Deployment

### Mainnet Configuration

```typescript theme={null}
const MAINNET_CONFIG = {
  programId: new PublicKey('WHISKY_PROGRAM_ID'),
  rpcEndpoint: 'https://api.mainnet-beta.solana.com',
  wsEndpoint: 'wss://api.mainnet-beta.solana.com',
  commitment: 'confirmed' as Commitment
};

const sdk = new WhiskySDK({
  connection: new Connection(MAINNET_CONFIG.rpcEndpoint, {
    commitment: MAINNET_CONFIG.commitment,
    wsEndpoint: MAINNET_CONFIG.wsEndpoint
  }),
  wallet: yourWallet,
  programId: MAINNET_CONFIG.programId
});
```

### Devnet Configuration

```typescript theme={null}
const DEVNET_CONFIG = {
  programId: new PublicKey('DEVNET_PROGRAM_ID'),
  rpcEndpoint: 'https://api.devnet.solana.com',
  wsEndpoint: 'wss://api.devnet.solana.com',
  commitment: 'confirmed' as Commitment
};
```

## Support

For SDK support and questions:

* **Documentation**: This documentation
* **Examples**: [GitHub Examples](https://github.com/weknowyourgame/whisky-gaming/examples)
* **Community**: [Discord Server](https://discord.gg/whisky-gaming)
* **Issues**: [GitHub Issues](https://github.com/weknowyourgame/whisky-gaming/issues)
* **Email**: [support@whisky.casino](mailto:support@whisky.casino)