@slvr-labs/sdk 0.1.0

package/examples/local-test.ts

@@ -0,0 +1,172 @@
+/**
+ * Example SDK usage against local Anvil instance
+ * 
+ * Usage:
+ *   1. Start local environment: ./scripts/start-local.sh
+ *   2. Update contract addresses below
+ *   3. Run: npx tsx examples/local-test.ts
+ */
+
+import { createPublicClient, createWalletClient, http, parseEther } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { SlvrSDK } from '../src/index';
+
+// Local Anvil configuration
+const RPC_URL = process.env.RPC_URL || 'http://localhost:8545';
+const CHAIN_ID = 31337;
+
+// Update these addresses after deployment (from script/deployments/localhost.json)
+const CONTRACT_ADDRESSES = {
+  lottery: '0x0000000000000000000000000000000000000000' as `0x${string}`, // Update this
+  staking: '0x0000000000000000000000000000000000000000' as `0x${string}`, // Update this (SlvrVoteEscrowStaking)
+  token: '0x0000000000000000000000000000000000000000' as `0x${string}`, // Update this
+  autoCommit: '0x0000000000000000000000000000000000000000' as `0x${string}`, // Optional
+  hub: '0x0000000000000000000000000000000000000000' as `0x${string}`, // Optional: SlvrHub
+  registry: '0x0000000000000000000000000000000000000000' as `0x${string}`, // Optional: SlvrGameRegistry
+  jackpot: '0x0000000000000000000000000000000000000000' as `0x${string}`, // Optional: SlvrJackpot
+};
+
+// The veNFT tokenId to inspect for staking (update after staking a token)
+const STAKING_TOKEN_ID = 1n;
+
+// Use Anvil's first account (or set your own private key)
+const PRIVATE_KEY = process.env.PRIVATE_KEY || '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80';
+
+// Define localhost chain
+const localhostChain = {
+  id: CHAIN_ID,
+  name: 'Localhost',
+  nativeCurrency: {
+    decimals: 18,
+    name: 'Ether',
+    symbol: 'ETH',
+  },
+  rpcUrls: {
+    default: {
+      http: [RPC_URL],
+    },
+  },
+} as const;
+
+async function main() {
+  console.log('🚀 Testing SLVR SDK against local Anvil instance\n');
+  console.log(`RPC URL: ${RPC_URL}`);
+  console.log(`Chain ID: ${CHAIN_ID}\n`);
+
+  // Create clients
+  const publicClient = createPublicClient({
+    chain: localhostChain,
+    transport: http(RPC_URL),
+  });
+
+  const account = privateKeyToAccount(PRIVATE_KEY as `0x${string}`);
+  const walletClient = createWalletClient({
+    chain: localhostChain,
+    transport: http(RPC_URL),
+    account,
+  });
+
+  console.log(`Using account: ${account.address}\n`);
+
+  // Initialize SDK
+  const sdk = new SlvrSDK({
+    publicClient,
+    walletClient,
+    addresses: CONTRACT_ADDRESSES,
+  });
+
+  try {
+    // Test 1: Get current round
+    console.log('📊 Test 1: Get current round');
+    const currentRoundId = await sdk.lottery.currentRoundId();
+    console.log(`   Current round ID: ${currentRoundId}\n`);
+
+    // Test 2: Get round info
+    console.log('📊 Test 2: Get round info');
+    const roundInfo = await sdk.lottery.getRound(currentRoundId);
+    console.log(`   Round ${currentRoundId}:`, {
+      totalWager: roundInfo.totalWager.toString(),
+      resolved: roundInfo.resolved,
+      winningSquare: roundInfo.winningSquare,
+    });
+    console.log('');
+
+    // Test 3: Get token balance
+    console.log('📊 Test 3: Get token balance');
+    const tokenBalance = await sdk.token.balanceOf(account.address);
+    console.log(`   SLVR balance: ${SlvrSDK.formatToken(tokenBalance)}\n`);
+
+    // Test 4: Get staking info (veNFT staker, keyed by tokenId)
+    console.log('📊 Test 4: Get staking info');
+    const stakingInfo = await sdk.staking.getStakingInfo(STAKING_TOKEN_ID);
+    console.log(`   Token ${STAKING_TOKEN_ID} weight: ${SlvrSDK.formatToken(stakingInfo.balance)}`);
+    console.log(`   Total weight: ${SlvrSDK.formatToken(stakingInfo.totalWeight)}`);
+    console.log(`   Claimable rewards: ${SlvrSDK.formatToken(stakingInfo.rewards)}\n`);
+
+    // Test 5: Place a bet (if you have ETH)
+    console.log('📊 Test 5: Place a bet');
+    const betAmount = parseEther('0.1');
+    const squares = [5, 10, 15];
+    const amounts = [
+      betAmount / 3n,
+      betAmount / 3n,
+      betAmount / 3n + (betAmount % 3n), // Handle remainder
+    ];
+
+    console.log(`   Placing bet on squares ${squares.join(', ')}`);
+    console.log(`   Total amount: ${SlvrSDK.formatToken(betAmount)} ETH`);
+
+    // Uncomment to actually place the bet:
+    // const txHash = await sdk.lottery.bet({
+    //   roundId: currentRoundId,
+    //   squares,
+    //   amounts,
+    // });
+    // console.log(`   Transaction: ${txHash}`);
+    // console.log('   Waiting for confirmation...');
+    // await publicClient.waitForTransactionReceipt({ hash: txHash });
+    // console.log('   ✅ Bet placed!\n');
+
+    console.log('   (Skipped - uncomment in code to execute)\n');
+
+    // Test 6: Emission / registry / jackpot stats (optional bindings)
+    console.log('📊 Test 6: Emission / registry / jackpot stats');
+    if (sdk.hub) {
+      const rate = await sdk.hub.emissionRatePerSec();
+      const target = await sdk.hub.targetSupply();
+      console.log(`   Emission rate/sec: ${SlvrSDK.formatToken(rate)}`);
+      console.log(`   Target supply: ${SlvrSDK.formatToken(target)}`);
+    }
+    if (sdk.registry) {
+      const gameId = await sdk.registry.gameIdOf(CONTRACT_ADDRESSES.lottery);
+      const totalWeight = await sdk.registry.totalActiveWeight();
+      console.log(`   Lottery gameId: ${gameId}`);
+      console.log(`   Total active weight: ${totalWeight}`);
+      // Combined helper: game's weighted SLVR/sec share (requires hub + registry)
+      if (sdk.hub && gameId > 0n) {
+        const effRate = await sdk.effectiveEmissionRate(gameId);
+        const pending = await sdk.pendingEmission(gameId);
+        console.log(`   Effective emission rate: ${SlvrSDK.formatToken(effRate)}/sec`);
+        console.log(`   Pending emission: ${SlvrSDK.formatToken(pending)}`);
+      }
+    }
+    if (sdk.jackpot) {
+      const ethPool = await sdk.jackpot.jackpotPool();
+      const slvrPool = await sdk.jackpot.jackpotSlvrPool();
+      console.log(`   Jackpot ETH pool: ${SlvrSDK.formatToken(ethPool)}`);
+      console.log(`   Jackpot SLVR pool: ${SlvrSDK.formatToken(slvrPool)}`);
+    }
+    if (!sdk.hub && !sdk.registry && !sdk.jackpot) {
+      console.log('   (No hub/registry/jackpot addresses configured - skipped)');
+    }
+    console.log('');
+
+    console.log('✅ All tests completed!');
+  } catch (error) {
+    console.error('❌ Error:', error);
+    process.exit(1);
+  }
+}
+
+main();
+

package/examples/quickstart-bet.ts

@@ -0,0 +1,72 @@
+/**
+ * Quickstart 2 — place a bet with a wallet
+ * ========================================
+ *
+ * The minimal write path: build a wallet-backed SDK, sanity-check the round's
+ * expected value, place one small bet, and print how to claim once the round
+ * resolves. Bets are paid in native ETH (no token approval needed).
+ *
+ * Run it (uses a tiny stake by default — start on a testnet / small amount):
+ *   PRIVATE_KEY=0xabc... npx ts-node quickstart-bet.ts
+ *
+ * To use this in your own project, change the `../src` import to `@slvr-labs/sdk`.
+ */
+
+import { createPublicClient, createWalletClient, http, parseEther, formatEther } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { SlvrSDK, robinhoodChain, deployments } from '../src';
+
+// How much to bet, total, and which squares to spread it across (indices 0–24).
+const STAKE_ETH = '0.002';
+const SQUARES = [0, 12, 24];
+
+async function main() {
+  const privateKey = process.env.PRIVATE_KEY as `0x${string}` | undefined;
+  if (!privateKey) throw new Error('Set PRIVATE_KEY to a funded key on Robinhood Chain');
+
+  // 1. Wallet-backed SDK from the shipped chain + addresses.
+  const account = privateKeyToAccount(privateKey);
+  const publicClient = createPublicClient({ chain: robinhoodChain, transport: http() });
+  const walletClient = createWalletClient({ chain: robinhoodChain, transport: http(), account });
+  const sdk = new SlvrSDK({ publicClient, walletClient, addresses: deployments.robinhood.addresses });
+
+  console.log(`Account: ${account.address}`);
+  const ethBalance = await publicClient.getBalance({ address: account.address });
+  console.log(`ETH balance: ${formatEther(ethBalance)}\n`);
+
+  // 2. Pick the current round and make sure it's open.
+  const roundId = await sdk.lottery.currentRoundId();
+  if (!(await sdk.lottery.roundOpen(roundId))) {
+    console.log(`Round #${roundId} is closed for betting — try again next round.`);
+    return;
+  }
+
+  // 3. Optional sanity check: is mining this round +EV right now?
+  //    (Informational — we bet regardless in this demo.)
+  const ev = await sdk.estimateRoundEv({ stake: Number(STAKE_ETH) });
+  console.log(
+    `Round #${roundId} EV @ ${STAKE_ETH} ETH: ` +
+      `${ev.netEth >= 0 ? '+' : ''}${ev.netEth.toFixed(6)} ETH/round ` +
+      `(${ev.profitable ? 'profitable' : 'not profitable'}; break-even pot ${ev.breakEvenPot.toFixed(4)} ETH)`
+  );
+
+  // 4. Split the stake evenly across the chosen squares and bet.
+  const stakeWei = parseEther(STAKE_ETH);
+  const per = stakeWei / BigInt(SQUARES.length);
+  const amounts = SQUARES.map((_, i) => (i === 0 ? per + (stakeWei - per * BigInt(SQUARES.length)) : per));
+
+  console.log(`\nBetting ${STAKE_ETH} ETH on squares ${SQUARES.join(', ')}…`);
+  const txHash = await sdk.lottery.bet({ roundId, squares: SQUARES, amounts });
+  console.log(`✅ Bet placed: ${txHash}`);
+
+  // 5. How to collect. Rounds resolve after betting closes; you can only claim a
+  //    round you won (held the winning square) and haven't claimed yet.
+  console.log(`\nTo claim after the round resolves:`);
+  console.log(`  const canClaim = await sdk.canClaim(${roundId}n, "${account.address}");`);
+  console.log(`  if (canClaim) await sdk.lottery.claim({ roundId: ${roundId}n });`);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/examples/quickstart-read.ts

@@ -0,0 +1,87 @@
+/**
+ * Quickstart 1 — read-only tour (no wallet needed)
+ * ================================================
+ *
+ * The fastest way to confirm the SDK works. It needs nothing but an RPC — no
+ * private key — and prints a snapshot of the live game: the current round, the
+ * pot, and the SLVR price in both ETH and USD.
+ *
+ * Run it:
+ *   npx ts-node quickstart-read.ts
+ *   npx ts-node quickstart-read.ts 0xYourAddress   # also show that address's balance/bets
+ *
+ * To use this in your own project, change the `../src` import to `@slvr-labs/sdk`.
+ */
+
+import { createPublicClient, http, formatEther, isAddress, type Address } from 'viem';
+import { SlvrSDK, robinhoodChain, deployments } from '../src';
+
+async function main() {
+  // 1. A read-only SDK: just a public client + the shipped mainnet addresses.
+  //    No walletClient means write calls are disabled — reads are all we need here.
+  const publicClient = createPublicClient({ chain: robinhoodChain, transport: http() });
+  const sdk = new SlvrSDK({
+    publicClient,
+    addresses: deployments.robinhood.addresses,
+  });
+
+  console.log(`Connected to ${robinhoodChain.name} (chain ${robinhoodChain.id})\n`);
+
+  // 2. Current round + whether it's still open for betting.
+  const roundId = await sdk.lottery.currentRoundId();
+  const [isOpen, bettingEnd, squares] = await Promise.all([
+    sdk.lottery.roundOpen(roundId),
+    sdk.lottery.bettingEnd(roundId),
+    sdk.lottery.getRoundSquares(roundId),
+  ]);
+
+  const pot = squares.reduce((sum, s) => sum + s.total, 0n);
+  const totalBettors = squares.reduce((sum, s) => sum + s.bettors, 0n);
+  const secondsLeft = Number(bettingEnd) - Math.floor(Date.now() / 1000);
+
+  console.log(`Round #${roundId}`);
+  console.log(`  status:     ${isOpen ? 'OPEN for betting' : 'closed'}`);
+  console.log(`  betting ends: ${secondsLeft > 0 ? `in ~${secondsLeft}s` : 'passed'}`);
+  console.log(`  pot:        ${formatEther(pot)} ETH across ${squares.length} squares`);
+  console.log(`  bettors:    ${totalBettors}`);
+
+  // 3. Prices — SLVR in ETH (from the UniswapV2 pair) and USD (via the Chainlink feed).
+  const [slvr, ethUsd] = await Promise.all([sdk.getSlvrPrice(), sdk.getEthPriceUsd()]);
+  console.log(`\nPrices`);
+  console.log(`  ETH:  $${ethUsd.toFixed(2)}`);
+  console.log(
+    `  SLVR: ${slvr.eth.toExponential(4)} ETH` +
+      (slvr.usd !== null ? `  ·  $${slvr.usd.toFixed(4)}` : '  ·  (USD unavailable)')
+  );
+
+  // 4. Token supply, for context.
+  const [supply, maxSupply] = await Promise.all([
+    sdk.token.totalSupply(),
+    sdk.token.maxSupply(),
+  ]);
+  console.log(`\nSLVR supply: ${formatEther(supply)} / ${formatEther(maxSupply)} max`);
+
+  // 5. Optional: pass an address to see its SLVR balance and bets this round.
+  const who = process.argv[2];
+  if (who && isAddress(who)) {
+    const addr = who as Address;
+    const [bal, bets] = await Promise.all([
+      sdk.token.balanceOf(addr),
+      sdk.lottery.getUserBets(roundId, addr),
+    ]);
+    console.log(`\n${addr}`);
+    console.log(`  SLVR balance: ${formatEther(bal)}`);
+    console.log(
+      `  bets this round: ${
+        bets.length ? bets.map((b) => `#${b.square}=${formatEther(b.amount)}ETH`).join(', ') : 'none'
+      }`
+    );
+  } else if (who) {
+    console.log(`\n(ignoring "${who}" — not a valid address)`);
+  }
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/examples/simple-example.ts

@@ -0,0 +1,122 @@
+/**
+ * Simple example: Basic usage of the Slvr SDK
+ * 
+ * This is a minimal example showing how to:
+ * 1. Initialize the SDK
+ * 2. Get current round information
+ * 3. Place a simple bet
+ * 
+ * Set PRIVATE_KEY environment variable to use wallet operations
+ */
+
+import { SlvrSDK } from '../src';
+import { createPublicClient, createWalletClient, http, parseEther } from 'viem';
+import { defineChain } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { CONTRACTS, ROBINHOOD_CHAIN } from './constants';
+
+/**
+ * Simple example function
+ */
+export async function simpleExample() {
+  // 1. Define the Robinhood chain
+  const robinhood = defineChain(ROBINHOOD_CHAIN);
+
+  // 2. Create public client for read operations
+  const publicClient = createPublicClient({
+    chain: robinhood,
+    transport: http(),
+  });
+
+  // 3. Create wallet client for write operations (if private key is provided)
+  let walletClient: ReturnType<typeof createWalletClient> | undefined;
+  const privateKey = process.env.PRIVATE_KEY;
+  
+  if (privateKey) {
+    const account = privateKeyToAccount(privateKey as `0x${string}`);
+    walletClient = createWalletClient({
+      chain: robinhood,
+      transport: http(),
+      account,
+    });
+    console.log(`Using account: ${account.address}`);
+  } else {
+    console.log('No PRIVATE_KEY found in environment - wallet operations disabled');
+  }
+
+  // 4. 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,
+    },
+  });
+
+  // 4. Get current round
+  const roundId = await sdk.lottery.currentRoundId();
+  console.log(`Current round: ${roundId}`);
+
+  // 5. Get round information
+  const round = await sdk.lottery.getRound(roundId);
+  console.log(`Round ${roundId}:`, {
+    resolved: round.resolved,
+    totalWager: SlvrSDK.formatToken(round.totalWager),
+    winningSquare: round.winningSquare,
+  });
+
+  // 6. Check if round is open
+  const isOpen = await sdk.lottery.roundOpen(roundId);
+  console.log(`Round ${roundId} is ${isOpen ? 'open' : 'closed'} for betting`);
+
+  // 7. Get squares data
+  const squares = await sdk.lottery.getRoundSquares(roundId);
+  console.log(`Square allocations:`, squares.map(sq => ({
+    square: sq.square,
+    total: SlvrSDK.formatToken(sq.total),
+    bettors: Number(sq.bettors),
+  })));
+
+  // 8. Place a bet (requires wallet client)
+  if (isOpen && walletClient) {
+    const squaresToBet = [0, 1, 2]; // Square indices (0-24)
+    const amounts = [
+      parseEther('1'), // 1 ETH on square 0
+      parseEther('1'), // 1 ETH on square 1
+      parseEther('1'), // 1 ETH on square 2
+    ];
+
+    const txHash = await sdk.lottery.bet({
+      roundId,
+      squares: squaresToBet,
+      amounts,
+    });
+
+    console.log(`Bet placed! Transaction: ${txHash}`);
+  } else if (isOpen && !walletClient) {
+    console.log('Cannot place bet - wallet client not available (set PRIVATE_KEY env var)');
+  }
+
+  // 9. Get user's bets (if wallet client is available)
+  if (walletClient?.account) {
+    const userAddress = walletClient.account.address;
+    const userBets = await sdk.lottery.getUserBets(roundId, userAddress);
+    console.log(`Your bets:`, userBets.map(bet => ({
+      square: bet.square,
+      amount: SlvrSDK.formatToken(bet.amount),
+    })));
+
+    // 10. Check if you can claim
+    const canClaim = await sdk.canClaim(roundId, userAddress);
+    if (canClaim) {
+      console.log(`You can claim rewards for round ${roundId}`);
+      // Uncomment to actually claim:
+      // const txHash = await sdk.lottery.claim({ roundId });
+      // console.log(`Claimed! Transaction: ${txHash}`);
+    }
+  }
+}
+