@slvr-labs/sdk 0.1.0

package/examples/README.md

@@ -0,0 +1,417 @@
+# Slvr SDK Examples
+
+This directory contains reference implementations demonstrating how to use the Slvr SDK for various betting strategies and automation.
+
+> **How to use these:** they are reference code, not part of the importable API.
+> Copy the file(s) you want into your own project and change the relative
+> `../src` import at the top of each file to `@slvr-labs/sdk`. The import paths in the
+> snippets below (e.g. `from './fixed-squares-strategy'`) assume you've copied
+> the example files alongside your own code.
+
+## Getting Started
+
+Brand new to the SDK? Run these two first — they use the addresses and chain that
+ship with the SDK (`deployments.robinhood` + `robinhoodChain`), so there's nothing
+to configure.
+
+### `quickstart-read.ts` — read-only tour (no wallet)
+
+The fastest way to confirm everything works. Needs only an RPC — no private key.
+Prints the current round, pot, and the SLVR price in **both ETH and USD**.
+
+```bash
+npx ts-node quickstart-read.ts
+npx ts-node quickstart-read.ts 0xYourAddress   # also show that address's balance + bets
+```
+
+### `quickstart-bet.ts` — place a bet (wallet)
+
+The minimal write path: builds a wallet-backed SDK, checks the round's expected
+value, places one small bet, and shows how to claim after the round resolves. Bets
+are paid in native ETH — no token approval needed.
+
+```bash
+PRIVATE_KEY=0xabc... npx ts-node quickstart-bet.ts
+```
+
+> Start with a small stake (the example defaults to 0.002 ETH). You can only claim
+> a round you won and haven't already claimed.
+
+## Strategy System
+
+The SDK includes a flexible strategy system that makes it easy to create custom betting strategies. All strategies extend the `BettingStrategy` base class, which handles:
+- Round monitoring
+- Threshold checking
+- Error handling
+- Bet execution
+
+### Creating Custom Strategies
+
+Extend `BettingStrategy` and override these methods:
+- `selectSquares()` - Choose which squares to bet on
+- `calculateAmounts()` - Calculate bet amounts for each square
+- `shouldBet()` - Optional: Add custom conditions for betting
+- `onBetPlaced()` - Optional: Handle successful bets
+- `onError()` - Optional: Custom error handling
+
+### Example: Fixed Squares Strategy
+
+The simplest strategy - bet on the same squares every round:
+
+```typescript
+import { FixedSquaresStrategy } from './fixed-squares-strategy';
+import { parseEther } from 'viem';
+
+const strategy = new FixedSquaresStrategy(sdk, {
+  squares: [0, 5, 10, 15, 20], // Bet on these squares
+  amountPerSquare: parseEther('1'), // 1 ETH per square
+  threshold: parseEther('100'), // Only bet when round < 100 ETH
+  checkInterval: 5000, // Check every 5 seconds
+});
+
+await strategy.start();
+```
+
+### Example: Custom Strategy
+
+```typescript
+import { BettingStrategy } from './strategy-base';
+
+class MyCustomStrategy extends BettingStrategy {
+  protected async selectSquares(roundId: bigint): Promise<number[]> {
+    // Your logic to select squares
+    return [0, 1, 2, 3, 4];
+  }
+
+  protected async calculateAmounts(
+    roundId: bigint,
+    round: any,
+    squares: number[]
+  ): Promise<bigint[]> {
+    // Your logic to calculate amounts
+    return squares.map(() => parseEther('1'));
+  }
+}
+
+const strategy = new MyCustomStrategy(sdk, {
+  threshold: parseEther('100'),
+  checkInterval: 5000,
+});
+
+await strategy.start();
+```
+
+## Examples
+
+### 1. Fixed Squares Strategy (`fixed-squares-strategy.ts`)
+
+Bet on a fixed set of squares every round when threshold is met.
+
+**Usage:**
+```typescript
+import { FixedSquaresStrategy } from './fixed-squares-strategy';
+import { parseEther } from 'viem';
+
+const strategy = new FixedSquaresStrategy(sdk, {
+  squares: [0, 5, 10, 15, 20],
+  amountPerSquare: parseEther('1'),
+  threshold: parseEther('100'),
+  checkInterval: 5000,
+});
+
+await strategy.start();
+```
+
+### 3. Automated Betting Bot (`automated-betting.ts`)
+
+A bot that automatically monitors rounds and places bets when the total wager is below a threshold (e.g., 100 ETH). It distributes bets across squares with the least allocation.
+
+**Features:**
+- Monitors rounds at configurable intervals
+- Automatically bets when total wager < threshold
+- Targets squares with least allocation
+- Configurable bet amounts and square counts
+
+**Usage:**
+```typescript
+import { AutomatedBettingBot } from './automated-betting';
+import { parseEther } from 'viem';
+
+const bot = new AutomatedBettingBot(sdk, {
+  threshold: parseEther('100'), // Bet when round has < 100 ETH
+  betAmount: parseEther('1'), // 1 ETH per square
+  minSquares: 3,
+  maxSquares: 5,
+  checkInterval: 5000, // Check every 5 seconds
+});
+
+await bot.start();
+// ... later
+bot.stop();
+```
+
+### 2. Least Allocated Strategy (`least-allocated-strategy.ts`)
+
+A strategy class that helps identify and bet on squares with the least funds allocated.
+
+**Features:**
+- Get squares sorted by allocation
+- Calculate optimal bet distribution
+- Analyze round allocation patterns
+- Place bets on least allocated squares
+
+**Usage:**
+```typescript
+import { LeastAllocatedStrategy } from './least-allocated-strategy';
+import { parseEther } from 'viem';
+
+const strategy = new LeastAllocatedStrategy(sdk);
+const roundId = await sdk.lottery.currentRoundId();
+
+// Analyze the round
+const analysis = await strategy.analyzeRound(roundId);
+console.log('Least allocated:', analysis.leastAllocated);
+
+// Place a bet
+const txHash = await strategy.betOnLeastAllocated(
+  roundId,
+  parseEther('5'), // 5 ETH total
+  5 // Bet on 5 squares
+);
+```
+
+### 4. Combined Strategy (`combined-strategy.ts`)
+
+Combines both strategies: monitors for low total wager AND bets on least allocated squares.
+
+**Features:**
+- Monitors rounds for total wager < threshold
+- Automatically identifies least allocated squares
+- Provides detailed logging and analysis
+- Configurable parameters
+
+**Usage:**
+```typescript
+import { CombinedBettingBot } from './combined-strategy';
+import { parseEther } from 'viem';
+
+const bot = new CombinedBettingBot(sdk, {
+  threshold: parseEther('100'), // Bet when < 100 ETH
+  betAmount: parseEther('5'), // 5 ETH total bet
+  squareCount: 5, // Bet on 5 least allocated squares
+  checkInterval: 5000, // Check every 5 seconds
+});
+
+await bot.start();
+// ... later
+bot.stop();
+```
+
+### 6. Expected-Value Bot (`expected-value-strategy.ts`)
+
+The most "quant" example: it **only bets when the round is positive expected
+value**. It uses the SDK's built-in grid-mining calculator (`sdk.estimateRoundEv`
+/ `computeGridMiningEv`) and SLVR price reader (`sdk.price`), so its math matches
+the protocol's own edge calculator.
+
+**How it decides:** the winning square is drawn uniformly, so mining SLVR only
+pays while the pot is small enough that your SLVR reward beats the ETH you bleed
+to the protocol fee. The bot computes net EV per round and bets when it clears a
+threshold — otherwise it waits for the pot to shrink or SLVR to rise.
+
+**Features:**
+- Live pot / emission / SLVR price pulled on-chain each round
+- Logs the full EV breakdown (share, SLVR mined, ETH bleed, jackpot, net, break-even pot)
+- Bets only on +EV rounds, covering the grid proportionally so it holds the winner
+- Hold vs cash-out mode (accounts for the 10% refining fee when cashing SLVR to ETH)
+
+**Usage:**
+```typescript
+import { ExpectedValueBot } from './expected-value-strategy';
+
+const bot = new ExpectedValueBot(sdk, {
+  stakeEth: 0.1,     // commit 0.1 ETH per +EV round
+  minNetEth: 0,      // bet on any positive-EV round (raise to demand more edge)
+  cashOut: false,    // value mined SLVR at full price (holding/staking it)
+  // ethUsd: 1815,   // optional override; otherwise the Chainlink feed is used
+  checkInterval: 5000,
+});
+
+await bot.start();
+// ... later
+bot.stop();
+```
+
+The bot logs the SLVR price in **both ETH and USD**. USD comes from the SDK's
+Chainlink ETH/USD feed (`sdk.ethUsd`), which is wired for Robinhood Chain, so USD
+shows automatically. Pass `ethUsd` (or run with `ETH_USD=1815 …`) to override it,
+or on a chain without a feed.
+
+> Requires a `slvrEthPair` address so `sdk.price` works — it's included in
+> `deployments.robinhood.addresses`, which this example uses.
+
+## Running Examples
+
+### 1. Install dependencies
+
+From the `sdk/ts` directory:
+
+```bash
+npm install
+```
+
+### 2. Run an example
+
+The examples are TypeScript. The simplest way to run one is with `ts-node` via
+`npx` (it's fetched on demand — no global install needed):
+
+```bash
+# Read-only — needs nothing but an internet connection:
+npx ts-node examples/quickstart-read.ts
+
+# Pass an address to also see its balance/bets:
+npx ts-node examples/quickstart-read.ts 0xYourAddress
+```
+
+> Prefer to compile? `npx tsc` then `node dist-examples/...` also works. `ts-node`
+> just skips the build step.
+
+### 3. Add a private key (only for examples that bet)
+
+Read-only examples (like `quickstart-read.ts`) need **no key**. Examples that send
+transactions read your key from the `PRIVATE_KEY` environment variable. The
+simplest, most reliable way is to set it inline for the one command:
+
+```bash
+PRIVATE_KEY=0xabc123... npx ts-node examples/quickstart-bet.ts
+```
+
+Or keep it in a file: copy `.env.example` to `.env`, put your key in it, then load
+it into your shell before running (the examples don't auto-load `.env`):
+
+```bash
+cp .env.example .env          # then edit .env and paste your key
+set -a; source .env; set +a   # load it into the environment
+npx ts-node examples/quickstart-bet.ts
+```
+
+**Key safety — please read:**
+- Use a **fresh / burner** key, not one holding real value.
+- The account needs a **small amount of ETH on Robinhood Chain** — for gas, plus
+  whatever you bet.
+- **Never commit your key.** `.env` is git-ignored here; only `.env.example`
+  (which has a dummy key) is tracked. Setting the key inline avoids a file entirely.
+
+### 4. (Optional) Point at a custom deployment
+
+`examples/constants.ts` defaults to the canonical Robinhood Chain mainnet addresses
+that ship with the SDK (`deployments.robinhood`). Edit it only to target a local or
+custom deployment.
+
+### Environment Variables
+
+- `PRIVATE_KEY` — your wallet key, hex with `0x` prefix. Required only for examples
+  that send transactions; read-only examples ignore it.
+- `ETH_USD` — optional ETH/USD override for USD display (otherwise the on-chain
+  Chainlink feed is used).
+
+### Basic Setup
+
+All examples use the constants file and environment variables:
+
+```typescript
+import { createPublicClient, createWalletClient, http } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { SlvrSDK } from '@slvr-labs/sdk';
+import { CONTRACTS, ROBINHOOD_CHAIN } from './constants';
+
+// ROBINHOOD_CHAIN is already a viem `Chain` — no need to wrap it.
+const publicClient = createPublicClient({
+  chain: ROBINHOOD_CHAIN,
+  transport: http(),
+});
+
+// Get private key from environment
+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_CHAIN,
+  transport: http(),
+  account,
+});
+
+// Initialize SDK with contract addresses from constants
+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,
+  },
+});
+```
+
+### 5. Custom Strategy Examples (`custom-strategy-example.ts`)
+
+Several example custom strategies showing different approaches:
+- `LeastAllocatedCustomStrategy` - Bet on squares with least allocation
+- `RandomSquaresStrategy` - Bet on random squares
+- `MostBettorsStrategy` - Bet on squares with most bettors (social proof)
+- `WeightedAllocationStrategy` - Weight bets inversely by allocation
+- `ConditionalStrategy` - Only bet when certain conditions are met
+
+## Strategy Ideas
+
+You can easily create your own strategies by extending `BettingStrategy`:
+
+### 1. Equal Distribution Strategy
+Bet equal amounts on all 25 squares to maximize coverage.
+
+### 2. Historical Analysis
+Analyze past rounds to identify patterns and bet accordingly.
+
+### 3. Multi-Round Strategy
+Spread bets across multiple rounds to diversify risk.
+
+### 4. Time-Based Strategy
+Adjust betting based on time remaining in the round.
+
+### 5. Portfolio Strategy
+Diversify across multiple strategies simultaneously.
+
+## Safety Considerations
+
+⚠️ **Important:** These examples are for educational purposes. When running automated bots:
+
+1. **Test on testnet first** - Never run untested code on mainnet
+2. **Set reasonable limits** - Don't bet more than you can afford to lose
+3. **Monitor gas costs** - Frequent transactions can be expensive
+4. **Handle errors gracefully** - Network issues can cause failures
+5. **Respect rate limits** - Don't spam the network
+6. **Secure your keys** - Never expose private keys in code
+
+## Customization
+
+All examples are designed to be easily customizable. You can:
+
+- Adjust thresholds and amounts
+- Modify square selection logic
+- Add additional conditions
+- Integrate with other services (notifications, analytics, etc.)
+- Combine multiple strategies
+
+## Contributing
+
+Feel free to create your own examples and share them! Common patterns include:
+- Integration with notification services
+- Database logging
+- Analytics and reporting
+- Multi-account management
+- Advanced risk management
+

package/examples/automated-betting.ts

@@ -0,0 +1,232 @@
+/**
+ * Example: Automated betting strategy
+ * 
+ * This example demonstrates how to:
+ * 1. Monitor rounds and automatically bet when total wager is less than 100 ETH
+ * 2. Bet on squares with the least funds allocated
+ */
+
+import { SlvrSDK } from '../src';
+import { PublicClient, WalletClient, parseEther } from 'viem';
+
+/**
+ * Automated betting bot that bets when round has less than threshold ETH
+ * and distributes bets across squares with least allocation
+ */
+export class AutomatedBettingBot {
+  private sdk: SlvrSDK;
+  private threshold: bigint; // Minimum total wager threshold (e.g., 100 ETH)
+  private betAmount: bigint; // Amount to bet per square
+  private minSquares: number; // Minimum number of squares to bet on
+  private maxSquares: number; // Maximum number of squares to bet on
+  private checkInterval: number; // How often to check (in milliseconds)
+  private isRunning: boolean = false;
+  private intervalId?: NodeJS.Timeout;
+
+  constructor(
+    sdk: SlvrSDK,
+    options: {
+      threshold?: bigint; // Default: 100 ETH
+      betAmount?: bigint; // Default: 1 ETH per square
+      minSquares?: number; // Default: 3
+      maxSquares?: number; // Default: 5
+      checkInterval?: number; // Default: 5000ms (5 seconds)
+    } = {}
+  ) {
+    this.sdk = sdk;
+    this.threshold = options.threshold ?? parseEther('100');
+    this.betAmount = options.betAmount ?? parseEther('1');
+    this.minSquares = options.minSquares ?? 3;
+    this.maxSquares = options.maxSquares ?? 5;
+    this.checkInterval = options.checkInterval ?? 5000;
+  }
+
+  /**
+   * Start the automated betting bot
+   */
+  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('🤖 Automated betting bot started');
+    console.log(`Threshold: ${SlvrSDK.formatToken(this.threshold)} ETH`);
+    console.log(`Bet amount per square: ${SlvrSDK.formatToken(this.betAmount)} ETH`);
+    console.log(`Checking every ${this.checkInterval / 1000} seconds`);
+
+    // Check immediately
+    await this.checkAndBet();
+
+    // Then check at intervals
+    this.intervalId = setInterval(async () => {
+      await this.checkAndBet();
+    }, this.checkInterval);
+  }
+
+  /**
+   * Stop the automated betting bot
+   */
+  stop(): void {
+    if (!this.isRunning) {
+      return;
+    }
+
+    this.isRunning = false;
+    if (this.intervalId) {
+      clearInterval(this.intervalId);
+      this.intervalId = undefined;
+    }
+    console.log('🛑 Automated betting bot stopped');
+  }
+
+  /**
+   * Check current 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);
+
+      if (!isOpen) {
+        console.log(`⏸️  Round ${roundId} is not open for betting`);
+        return;
+      }
+
+      // Check if total wager is below threshold
+      if (round.totalWager >= this.threshold) {
+        console.log(
+          `💰 Round ${roundId} has ${SlvrSDK.formatToken(round.totalWager)} ETH ` +
+          `(above threshold of ${SlvrSDK.formatToken(this.threshold)} ETH)`
+        );
+        return;
+      }
+
+      console.log(
+        `🎯 Round ${roundId} has ${SlvrSDK.formatToken(round.totalWager)} ETH ` +
+        `(below threshold of ${SlvrSDK.formatToken(this.threshold)} ETH)`
+      );
+
+      // Get squares with least allocation
+      const squares = await this.getLeastAllocatedSquares();
+      
+      if (squares.length < this.minSquares) {
+        console.log(`⚠️  Not enough squares with low allocation (found ${squares.length}, need ${this.minSquares})`);
+        return;
+      }
+
+      // Limit to maxSquares
+      const squaresToBet = squares.slice(0, this.maxSquares);
+      const amounts = squaresToBet.map(() => this.betAmount);
+
+      console.log(`📊 Betting on squares: ${squaresToBet.join(', ')}`);
+      console.log(`💵 Total bet: ${SlvrSDK.formatToken(amounts.reduce((sum, amt) => sum + amt, 0n))} ETH`);
+
+      // Place the bet
+      const txHash = await this.sdk.lottery.bet({
+        roundId,
+        squares: squaresToBet,
+        amounts,
+      });
+
+      console.log(`✅ Bet placed! Transaction: ${txHash}`);
+    } catch (error) {
+      console.error('❌ Error in automated betting:', error);
+    }
+  }
+
+  /**
+   * Get squares with the least funds allocated, sorted by total amount
+   */
+  private async getLeastAllocatedSquares(): Promise<number[]> {
+    const roundId = await this.sdk.lottery.currentRoundId();
+    const squares = await this.sdk.lottery.getRoundSquares(roundId);
+
+    // Sort by total amount (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 sorted.map(({ square }) => square);
+  }
+}
+
+/**
+ * Example usage
+ * 
+ * Set PRIVATE_KEY environment variable to enable betting
+ */
+export async function exampleAutomatedBetting() {
+  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 with custom options
+  const bot = new AutomatedBettingBot(sdk, {
+    threshold: parseEther('100'), // Bet when round has less than 100 ETH
+    betAmount: parseEther('1'), // Bet 1 ETH per square
+    minSquares: 3, // Bet on at least 3 squares
+    maxSquares: 5, // Bet on at most 5 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);
+  });
+}
+