@slvr-labs/sdk 0.1.0

package/examples/combined-strategy.ts

@@ -0,0 +1,227 @@
+/**
+ * Example: Combined strategy that bets when round has less than 100 ETH
+ * and targets squares with least allocation
+ * 
+ * This combines both strategies into a single automated bot
+ */
+
+import { SlvrSDK } from '../src';
+import { PublicClient, WalletClient, parseEther } from 'viem';
+import { LeastAllocatedStrategy } from './least-allocated-strategy';
+
+/**
+ * Combined automated betting bot
+ * - Monitors rounds for low total wager (< 100 ETH)
+ * - Bets on squares with least allocation when conditions are met
+ */
+export class CombinedBettingBot {
+  private sdk: SlvrSDK;
+  private strategy: LeastAllocatedStrategy;
+  private threshold: bigint;
+  private betAmount: bigint;
+  private squareCount: number;
+  private checkInterval: number;
+  private isRunning: boolean = false;
+  private intervalId?: NodeJS.Timeout;
+
+  constructor(
+    sdk: SlvrSDK,
+    options: {
+      threshold?: bigint; // Default: 100 ETH
+      betAmount?: bigint; // Default: 5 ETH total
+      squareCount?: number; // Default: 5 squares
+      checkInterval?: number; // Default: 5000ms
+    } = {}
+  ) {
+    this.sdk = sdk;
+    this.strategy = new LeastAllocatedStrategy(sdk);
+    this.threshold = options.threshold ?? parseEther('100');
+    this.betAmount = options.betAmount ?? parseEther('5');
+    this.squareCount = options.squareCount ?? 5;
+    this.checkInterval = options.checkInterval ?? 5000;
+  }
+
+  /**
+   * Start monitoring and betting
+   */
+  async start(): Promise<void> {
+    if (this.isRunning) {
+      console.log('Bot is already running');
+      return;
+    }
+
+    if (!this.sdk.getWalletClient()) {
+      throw new Error('Wallet client required for automated betting');
+    }
+
+    this.isRunning = true;
+    console.log('🚀 Combined betting bot started');
+    console.log(`📊 Strategy: Bet when round < ${SlvrSDK.formatToken(this.threshold)} ETH`);
+    console.log(`🎯 Target: ${this.squareCount} least allocated squares`);
+    console.log(`💵 Bet amount: ${SlvrSDK.formatToken(this.betAmount)} ETH`);
+    console.log(`⏱️  Checking every ${this.checkInterval / 1000} seconds\n`);
+
+    // Check immediately
+    await this.checkAndBet();
+
+    // Then check at intervals
+    this.intervalId = setInterval(async () => {
+      await this.checkAndBet();
+    }, this.checkInterval);
+  }
+
+  /**
+   * Stop the bot
+   */
+  stop(): void {
+    if (!this.isRunning) {
+      return;
+    }
+
+    this.isRunning = false;
+    if (this.intervalId) {
+      clearInterval(this.intervalId);
+      this.intervalId = undefined;
+    }
+    console.log('\n🛑 Combined betting bot stopped');
+  }
+
+  /**
+   * Check round and place bet if conditions are met
+   */
+  private async checkAndBet(): Promise<void> {
+    try {
+      const roundId = await this.sdk.lottery.currentRoundId();
+      const round = await this.sdk.lottery.getRound(roundId);
+      const isOpen = await this.sdk.lottery.roundOpen(roundId);
+
+      // Check if round is open
+      if (!isOpen) {
+        const timeRemaining = await this.sdk.getTimeRemaining(roundId);
+        if (timeRemaining > 0) {
+          console.log(`⏸️  Round ${roundId} not open yet (${timeRemaining}s remaining)`);
+        } else {
+          console.log(`✅ Round ${roundId} has ended`);
+        }
+        return;
+      }
+
+      // Check if total wager is below threshold
+      if (round.totalWager >= this.threshold) {
+        const remaining = this.threshold - round.totalWager;
+        console.log(
+          `💰 Round ${roundId}: ${SlvrSDK.formatToken(round.totalWager)} ETH ` +
+          `(need ${SlvrSDK.formatToken(remaining < 0n ? 0n : remaining)} more to reach threshold)`
+        );
+        return;
+      }
+
+      console.log(`\n🎯 Round ${roundId} conditions met!`);
+      console.log(`   Total wager: ${SlvrSDK.formatToken(round.totalWager)} ETH`);
+      console.log(`   Threshold: ${SlvrSDK.formatToken(this.threshold)} ETH`);
+
+      // Get analysis of least allocated squares
+      const analysis = await this.strategy.analyzeRound(roundId);
+      console.log(`   Total allocation: ${SlvrSDK.formatToken(analysis.totalAllocation)} ETH`);
+      console.log(`   Least allocated squares: ${analysis.leastAllocated.join(', ')}`);
+
+      // Place bet on least allocated squares
+      const squares = analysis.leastAllocated.slice(0, this.squareCount);
+      const amounts = this.strategy.calculateBetAmounts(this.betAmount, squares.length);
+
+      console.log(`\n📊 Placing bet:`);
+      squares.forEach((square, i) => {
+        const squareData = analysis.squares.find(sq => sq.square === square);
+        console.log(
+          `   Square ${square}: ${SlvrSDK.formatToken(amounts[i])} ETH ` +
+          `(current: ${SlvrSDK.formatToken(squareData?.total || 0n)} ETH, ` +
+          `${squareData?.percentage.toFixed(2)}%)`
+        );
+      });
+      console.log(`   Total bet: ${SlvrSDK.formatToken(this.betAmount)} ETH`);
+
+      const txHash = await this.sdk.lottery.bet({
+        roundId,
+        squares,
+        amounts,
+      });
+
+      console.log(`\n✅ Bet placed successfully!`);
+      console.log(`   Transaction: ${txHash}\n`);
+    } catch (error) {
+      console.error('❌ Error in combined betting bot:', error);
+      if (error instanceof Error) {
+        console.error('   Message:', error.message);
+      }
+    }
+  }
+}
+
+/**
+ * Example usage
+ * 
+ * Set PRIVATE_KEY environment variable to enable betting
+ */
+export async function exampleCombinedStrategy() {
+  const { createPublicClient, createWalletClient, http } = await import('viem');
+  const { defineChain } = await import('viem');
+  const { privateKeyToAccount } = await import('viem/accounts');
+  const { SlvrSDK } = await import('../src');
+  const { CONTRACTS, ROBINHOOD_CHAIN } = await import('./constants');
+
+  // Create clients
+  const robinhood = defineChain(ROBINHOOD_CHAIN);
+  const publicClient = createPublicClient({
+    chain: robinhood,
+    transport: http(),
+  });
+
+  const privateKey = process.env.PRIVATE_KEY;
+  if (!privateKey) {
+    throw new Error('PRIVATE_KEY environment variable is required');
+  }
+
+  const account = privateKeyToAccount(privateKey as `0x${string}`);
+  const walletClient = createWalletClient({
+    chain: robinhood,
+    transport: http(),
+    account,
+  });
+
+  // Initialize SDK
+  const sdk = new SlvrSDK({
+    publicClient,
+    walletClient,
+    addresses: {
+      lottery: CONTRACTS.LOTTERY,
+      staking: CONTRACTS.STAKING,
+      token: CONTRACTS.TOKEN,
+      autoCommit: CONTRACTS.AUTO_COMMIT !== '0x...' ? CONTRACTS.AUTO_COMMIT : undefined,
+    },
+  });
+
+  // Create bot
+  const bot = new CombinedBettingBot(sdk, {
+    threshold: parseEther('100'), // Bet when round has less than 100 ETH
+    betAmount: parseEther('5'), // Bet 5 ETH total
+    squareCount: 5, // Bet on 5 least allocated squares
+    checkInterval: 5000, // Check every 5 seconds
+  });
+
+  // Start the bot
+  await bot.start();
+
+  // Handle graceful shutdown
+  process.on('SIGINT', () => {
+    console.log('\nReceived SIGINT, stopping bot...');
+    bot.stop();
+    process.exit(0);
+  });
+
+  process.on('SIGTERM', () => {
+    console.log('\nReceived SIGTERM, stopping bot...');
+    bot.stop();
+    process.exit(0);
+  });
+}
+

package/examples/constants.ts

@@ -0,0 +1,35 @@
+/**
+ * Contract addresses and chain config used by the examples.
+ *
+ * These default to the canonical Robinhood Chain mainnet deployment that ships
+ * with the SDK (`deployments.robinhood`). Point them at your own deployment by
+ * editing the values below, or import `deployments` / `robinhoodChain` directly
+ * from `@slvr-labs/sdk` in your own code.
+ */
+
+import { Address } from 'viem';
+import { deployments, robinhoodChain } from '../src';
+
+const { addresses } = deployments.robinhood;
+
+/**
+ * Contract addresses on Robinhood Chain.
+ */
+export const CONTRACTS = {
+  /** SlvrGridLottery contract address */
+  LOTTERY: addresses.lottery as Address,
+
+  /** SlvrVoteEscrowStaking (veNFT staker) contract address */
+  STAKING: addresses.staking as Address,
+
+  /** SlvrToken contract address */
+  TOKEN: addresses.token as Address,
+
+  /** SlvrAutoCommitV2 contract address (optional) */
+  AUTO_COMMIT: (addresses.autoCommit ?? '0x...') as Address,
+} as const;
+
+/**
+ * Robinhood Chain configuration (a ready-made viem chain).
+ */
+export const ROBINHOOD_CHAIN = robinhoodChain;

package/examples/custom-strategy-example.ts

@@ -0,0 +1,231 @@
+/**
+ * Example: How to create custom strategies
+ * 
+ * This file shows how easy it is to create custom betting strategies
+ * by extending the BettingStrategy base class.
+ */
+
+import { BettingStrategy } from './strategy-base';
+import { parseEther } from 'viem';
+import { SlvrSDK } from '../src';
+
+/**
+ * Example 1: Bet on squares with least allocation
+ */
+export class LeastAllocatedCustomStrategy extends BettingStrategy {
+  private squareCount: number;
+  private totalBetAmount: bigint;
+
+  constructor(sdk: SlvrSDK, config: { squareCount?: number; totalBetAmount?: bigint; threshold?: bigint }) {
+    super(sdk, { threshold: config.threshold });
+    this.squareCount = config.squareCount ?? 5;
+    this.totalBetAmount = config.totalBetAmount ?? parseEther('5');
+  }
+
+  protected async selectSquares(roundId: bigint): Promise<number[]> {
+    // Get all squares with their allocations
+    const squares = await this.sdk.lottery.getRoundSquares(roundId);
+    
+    // Sort by total (ascending) - least allocated first
+    const sorted = squares
+      .map(({ square, total }) => ({ square, total }))
+      .sort((a, b) => {
+        if (a.total < b.total) return -1;
+        if (a.total > b.total) return 1;
+        return 0;
+      });
+
+    // Return the N least allocated squares
+    return sorted.slice(0, this.squareCount).map(({ square }) => square);
+  }
+
+  protected async calculateAmounts(roundId: bigint, round: any, squares: number[]): Promise<bigint[]> {
+    // Distribute total bet amount evenly
+    const amountPerSquare = this.totalBetAmount / BigInt(squares.length);
+    const remainder = this.totalBetAmount % BigInt(squares.length);
+    
+    const amounts = squares.map(() => amountPerSquare);
+    if (remainder > 0n) {
+      amounts[0] += remainder; // Add remainder to first square
+    }
+    
+    return amounts;
+  }
+}
+
+/**
+ * Example 2: Bet on random squares
+ */
+export class RandomSquaresStrategy extends BettingStrategy {
+  private squareCount: number;
+  private amountPerSquare: bigint;
+
+  constructor(sdk: SlvrSDK, config: { squareCount?: number; amountPerSquare?: bigint; threshold?: bigint }) {
+    super(sdk, { threshold: config.threshold });
+    this.squareCount = config.squareCount ?? 5;
+    this.amountPerSquare = config.amountPerSquare ?? parseEther('1');
+  }
+
+  protected async selectSquares(): Promise<number[]> {
+    // Generate random squares
+    const allSquares = Array.from({ length: 25 }, (_, i) => i);
+    const shuffled = [...allSquares].sort(() => Math.random() - 0.5);
+    return shuffled.slice(0, this.squareCount);
+  }
+
+  protected async calculateAmounts(roundId: bigint, round: any, squares: number[]): Promise<bigint[]> {
+    return squares.map(() => this.amountPerSquare);
+  }
+}
+
+/**
+ * Example 3: Bet on squares with most bettors (social proof strategy)
+ */
+export class MostBettorsStrategy extends BettingStrategy {
+  private squareCount: number;
+  private amountPerSquare: bigint;
+
+  constructor(sdk: SlvrSDK, config: { squareCount?: number; amountPerSquare?: bigint; threshold?: bigint }) {
+    super(sdk, { threshold: config.threshold });
+    this.squareCount = config.squareCount ?? 5;
+    this.amountPerSquare = config.amountPerSquare ?? parseEther('1');
+  }
+
+  protected async selectSquares(roundId: bigint): Promise<number[]> {
+    const squares = await this.sdk.lottery.getRoundSquares(roundId);
+    
+    // Sort by number of bettors (descending)
+    const sorted = squares
+      .map(({ square, bettors }) => ({ square, bettors }))
+      .sort((a, b) => {
+        if (a.bettors > b.bettors) return -1;
+        if (a.bettors < b.bettors) return 1;
+        return 0;
+      });
+
+    return sorted.slice(0, this.squareCount).map(({ square }) => square);
+  }
+
+  protected async calculateAmounts(roundId: bigint, round: any, squares: number[]): Promise<bigint[]> {
+    return squares.map(() => this.amountPerSquare);
+  }
+}
+
+/**
+ * Example 4: Weighted strategy - bet more on squares with less allocation
+ */
+export class WeightedAllocationStrategy extends BettingStrategy {
+  private squareCount: number;
+  private totalBetAmount: bigint;
+
+  constructor(sdk: SlvrSDK, config: { squareCount?: number; totalBetAmount?: bigint; threshold?: bigint }) {
+    super(sdk, { threshold: config.threshold });
+    this.squareCount = config.squareCount ?? 5;
+    this.totalBetAmount = config.totalBetAmount ?? parseEther('10');
+  }
+
+  protected async selectSquares(roundId: bigint): Promise<number[]> {
+    const squares = await this.sdk.lottery.getRoundSquares(roundId);
+    const sorted = squares
+      .map(({ square, total }) => ({ square, total }))
+      .sort((a, b) => {
+        if (a.total < b.total) return -1;
+        if (a.total > b.total) return 1;
+        return 0;
+      });
+
+    return sorted.slice(0, this.squareCount).map(({ square }) => square);
+  }
+
+  protected async calculateAmounts(roundId: bigint, round: any, squares: number[]): Promise<bigint[]> {
+    // Get allocations for selected squares
+    const squaresData = await this.sdk.lottery.getRoundSquares(roundId);
+    const selectedData = squaresData.filter(sq => squares.includes(sq.square));
+    
+    // Calculate total allocation for selected squares
+    const totalAllocation = selectedData.reduce((sum, sq) => sum + sq.total, 0n);
+    
+    if (totalAllocation === 0n) {
+      // If no allocation, distribute evenly
+      const amountPerSquare = this.totalBetAmount / BigInt(squares.length);
+      const remainder = this.totalBetAmount % BigInt(squares.length);
+      const amounts = squares.map(() => amountPerSquare);
+      if (remainder > 0n) amounts[0] += remainder;
+      return amounts;
+    }
+
+    // Weight inversely by allocation (less allocation = more bet)
+    // Calculate weights: weight = 1 / (allocation + 1) to avoid division by zero
+    const weights = selectedData.map(sq => {
+      const allocation = sq.total;
+      // Use inverse weight: lower allocation gets higher weight
+      // Add 1 to avoid division issues
+      return Number(1000000n / (allocation + 1n)); // Scale up for precision
+    });
+
+    const totalWeight = weights.reduce((sum, w) => sum + w, 0);
+    
+    // Distribute bet amount proportionally to weights
+    const amounts = weights.map(weight => {
+      return (this.totalBetAmount * BigInt(Math.round(weight))) / BigInt(totalWeight);
+    });
+
+    // Adjust for rounding
+    const total = amounts.reduce((sum, amt) => sum + amt, 0n);
+    const diff = this.totalBetAmount - total;
+    if (diff !== 0n) {
+      amounts[0] += diff;
+    }
+
+    return amounts;
+  }
+}
+
+/**
+ * Example 5: Conditional strategy - only bet on certain conditions
+ */
+export class ConditionalStrategy extends BettingStrategy {
+  private squares: number[];
+  private amountPerSquare: bigint;
+  private minBettors: number; // Only bet if squares have at least this many bettors
+
+  constructor(
+    sdk: SlvrSDK,
+    config: {
+      squares: number[];
+      amountPerSquare: bigint;
+      minBettors?: number;
+      threshold?: bigint;
+    }
+  ) {
+    super(sdk, { threshold: config.threshold });
+    this.squares = config.squares;
+    this.amountPerSquare = config.amountPerSquare;
+    this.minBettors = config.minBettors ?? 0;
+  }
+
+  protected async shouldBet(roundId: bigint, round: any): Promise<{ shouldBet: boolean; reason?: string }> {
+    // Check if squares have enough bettors
+    const squaresData = await this.sdk.lottery.getRoundSquares(roundId);
+    const selectedData = squaresData.filter(sq => this.squares.includes(sq.square));
+    
+    const minBettors = Math.min(...selectedData.map(sq => Number(sq.bettors)));
+    if (minBettors < this.minBettors) {
+      return {
+        shouldBet: false,
+        reason: `Squares don't have enough bettors (min: ${this.minBettors}, found: ${minBettors})`,
+      };
+    }
+
+    return { shouldBet: true };
+  }
+
+  protected async selectSquares(): Promise<number[]> {
+    return this.squares;
+  }
+
+  protected async calculateAmounts(roundId: bigint, round: any, squares: number[]): Promise<bigint[]> {
+    return squares.map(() => this.amountPerSquare);
+  }
+}
+