@zenx-labs/godl-supply 0.1.0 → 0.1.2

package/README.md

@@ -1,6 +1,6 @@
 # @zenx-labs/godl-supply
 
-TypeScript SDK for interacting with the [GODL](https://godl.dev) on-chain program on Solana. Provides real-time WebSocket streaming, account fetching with caching, transaction building, and full type safety.
+TypeScript SDK for interacting with the [GODL](https://godl.supply) on-chain program on Solana. Provides real-time WebSocket streaming, account fetching with caching, transaction building, and full type safety.
 
 ## Installation
 
@@ -11,56 +11,62 @@ npm install @zenx-labs/godl-supply
 ## Quick Start
 
 ```typescript
-import { GodlSupply } from '@zenx-labs/godl-supply'
+import { GodlSupply } from "@zenx-labs/godl-supply";
 
-const sdk = new GodlSupply(signer, {
-  rpcUrl: 'https://api.mainnet-beta.solana.com', // optional, defaults to public mainnet
-})
+// Load signer from a keypair.json file (Solana CLI format)
+const sdk = await GodlSupply.create("~/.config/solana/id.json", {
+  rpcUrl: "https://api.mainnet-beta.solana.com", // optional, defaults to public mainnet
+});
 
 // Connect to real-time WebSocket stream
-await sdk.connect()
+await sdk.connect();
 
 // Listen for events
-sdk.on('board', (board) => {
-  console.log('Round:', board.roundId)
-})
+sdk.on("board", (board) => {
+  console.log("Round:", board.roundId);
+});
 
-sdk.on('treasury', (treasury) => {
-  console.log('Balance:', treasury.balance)
-})
+sdk.on("treasury", (treasury) => {
+  console.log("Balance:", treasury.balance);
+});
 
 // Fetch account data (cached + RPC fallback)
-const board = await sdk.getBoard()
-const miner = await sdk.getMiner('68m3ocDFeJ1iQE9Pyu9Exn1HdpGcTgh12zpjWM7K8pKU')
+const board = await sdk.getBoard();
+const miner = await sdk.getMiner(
+  "68m3ocDFeJ1iQE9Pyu9Exn1HdpGcTgh12zpjWM7K8pKU",
+);
 
 // Disconnect when done
-sdk.disconnect()
+sdk.disconnect();
 ```
 
 ## Signer
 
-The SDK expects a `Signer` compatible with the [gill](https://github.com/solana-developers/gill) library:
+The SDK uses [gill](https://github.com/solana-developers/gill)'s `KeyPairSigner`. The easiest way is to use `GodlSupply.create()` with a path to your keypair.json file (Solana CLI format):
 
 ```typescript
-import type { Signer } from '@zenx-labs/godl-supply'
-
-const signer: Signer = {
-  address: address('YourPublicKey...'),
-  async signAndSendTransactions(transactions, config) {
-    // Sign and submit transactions to the network
-  },
-}
+const sdk = await GodlSupply.create("~/.config/solana/id.json");
+```
+
+For advanced use cases, you can pass a `KeyPairSigner` directly to the constructor:
+
+```typescript
+import { GodlSupply } from "@zenx-labs/godl-supply";
+import { loadKeypairSignerFromFile } from "gill/node";
+
+const signer = await loadKeypairSignerFromFile("~/.config/solana/id.json");
+const sdk = new GodlSupply(signer, { rpcUrl: "https://your-rpc.com" });
 ```
 
 ## Configuration
 
 ```typescript
 type GodlSupplyConfig = {
-  rpcUrl?: string      // Solana RPC endpoint (default: public mainnet)
-  wsUrl?: string       // GODL stream WebSocket URL (default: wss://stream.godl.dev/stream)
-  streamApiUrl?: string // GODL stream REST API URL (default: https://stream.godl.dev)
-  commitment?: 'confirmed' | 'finalized' | 'processed' // default: 'confirmed'
-}
+  rpcUrl?: string; // Solana RPC endpoint (default: public mainnet)
+  wsUrl?: string; // GODL stream WebSocket URL (default: wss://stream.godl.dev/stream)
+  streamApiUrl?: string; // GODL stream REST API URL (default: https://stream.godl.dev)
+  commitment?: "confirmed" | "finalized" | "processed"; // default: 'confirmed'
+};
 ```
 
 ## API Reference
@@ -68,9 +74,9 @@ type GodlSupplyConfig = {
 ### Lifecycle
 
 ```typescript
-await sdk.connect()       // Connect to WebSocket stream and sync initial state
-sdk.disconnect()          // Disconnect and clear cache
-sdk.isConnected           // boolean
+await sdk.connect(); // Connect to WebSocket stream and sync initial state
+sdk.disconnect(); // Disconnect and clear cache
+sdk.isConnected; // boolean
 ```
 
 ### Events
@@ -79,42 +85,44 @@ The SDK emits typed events via WebSocket. Subscribe with `on()` and unsubscribe
 
 ```typescript
 // Subscribe
-const unsub = sdk.on('board', (board) => { /* ... */ })
+const unsub = sdk.on("board", (board) => {
+  /* ... */
+});
 
 // Unsubscribe
-unsub()
+unsub();
 // or
-sdk.off('board', handler)
+sdk.off("board", handler);
 ```
 
 #### Available Events
 
-| Event            | Data Type       | Description                              |
-|------------------|-----------------|------------------------------------------|
-| `board`          | `Board`         | Current board state (round info, slots)  |
-| `round`          | `Round`         | Round deployment data and results        |
-| `resetEvent`     | `ResetEvent`    | Round reset with winners and payouts     |
-| `treasury`       | `Treasury`      | Treasury balances and reward factors     |
-| `miner`          | `Miner`         | Your miner account updates               |
-| `automation`     | `Automation`    | Your autominer account updates           |
-| `slotData`       | `SlotData`      | Slot synchronization data                |
-| `solMotherlode`  | `SolMotherlode` | SOL motherlode amount                    |
-| `poolMember`     | `PoolMember`    | Your pool membership data                |
-| `poolRound`      | `PoolRound`     | Pool round deployment data               |
-| `slotTick`       | `bigint`        | Emitted every ~400ms with current slot   |
-| `connected`      | `boolean`       | WebSocket connection state changes       |
-| `error`          | `Error`         | WebSocket errors                         |
+| Event           | Data Type       | Description                             |
+| --------------- | --------------- | --------------------------------------- |
+| `board`         | `Board`         | Current board state (round info, slots) |
+| `round`         | `Round`         | Round deployment data and results       |
+| `resetEvent`    | `ResetEvent`    | Round reset with winners and payouts    |
+| `treasury`      | `Treasury`      | Treasury balances and reward factors    |
+| `miner`         | `Miner`         | Your miner account updates              |
+| `automation`    | `Automation`    | Your autominer account updates          |
+| `slotData`      | `SlotData`      | Slot synchronization data               |
+| `solMotherlode` | `SolMotherlode` | SOL motherlode amount                   |
+| `poolMember`    | `PoolMember`    | Your pool membership data               |
+| `poolRound`     | `PoolRound`     | Pool round deployment data              |
+| `slotTick`      | `bigint`        | Emitted every ~400ms with current slot  |
+| `connected`     | `boolean`       | WebSocket connection state changes      |
+| `error`         | `Error`         | WebSocket errors                        |
 
 ### Slot Tracking
 
 The SDK maintains a local slot counter that increments every ~400ms after the initial sync from the WebSocket.
 
 ```typescript
-const currentSlot = sdk.getSlot()
+const currentSlot = sdk.getSlot();
 
 const unsub = sdk.onSlotTick((slot) => {
-  console.log('Slot:', slot)
-})
+  console.log("Slot:", slot);
+});
 ```
 
 ### Account Getters
@@ -123,43 +131,44 @@ All account getters use a two-tier strategy: check the in-memory cache first (15
 
 ```typescript
 // Global state
-const board    = await sdk.getBoard()
-const treasury = await sdk.getTreasury()
-const config   = await sdk.getConfig()
+const board = await sdk.getBoard();
+const treasury = await sdk.getTreasury();
+const config = await sdk.getConfig();
 
 // Per-user accounts (defaults to signer if no authority provided)
-const miner      = await sdk.getMiner()
-const miner2     = await sdk.getMiner('SomeOtherPublicKey...')
-const automation = await sdk.getAutomation()       // returns null if not set up
-const stake      = await sdk.getStake()
-const stakeV2    = await sdk.getStakeV2(0n)        // by stake ID
-const allStakes  = await sdk.getStakeV2Accounts()  // all StakeV2 accounts
+const miner = await sdk.getMiner();
+const miner2 = await sdk.getMiner("SomeOtherPublicKey...");
+const automation = await sdk.getAutomation(); // returns null if not set up
+const stake = await sdk.getStake();
+const stakeV2 = await sdk.getStakeV2(0n); // by stake ID
+const allStakes = await sdk.getStakeV2Accounts(); // all StakeV2 accounts
 
 // Round data
-const round     = await sdk.getRound(42n)          // returns null if not found
-const poolRound = await sdk.getPoolRound(42n)
+const round = await sdk.getRound(42n); // returns null if not found
+const poolRound = await sdk.getPoolRound(42n);
 
 // Pool and referral
-const poolMember = await sdk.getPoolMember()       // returns null if not a member
-const referrer   = await sdk.getReferrer()         // returns null if not a referrer
+const poolMember = await sdk.getPoolMember(); // returns null if not a member
+const referrer = await sdk.getReferrer(); // returns null if not a referrer
 ```
 
 ### Mining
 
 ```typescript
 // Deploy to the board
+// amount is lamports PER SQUARE — total SOL spent = amount × squares.length
 const sig = await sdk.deploy({
-  amount: 100,
+  amount: 100, // 100 lamports per square (500 lamports total for 5 squares)
   squares: [0, 5, 12, 18, 24],
-  varAddress: address('...'),
-  isPooled: false,             // optional, default: false
-})
+  varAddress: address("..."),
+  isPooled: false, // optional, default: false
+});
 
 // Claim rewards
 const sig = await sdk.claim({
   claimSol: true,
   claimGodl: true,
-})
+});
 ```
 
 ### Autominer
@@ -172,37 +181,37 @@ const sig = await sdk.setupAutominer({
   squares: [0, 5, 12, 18, 24],
   strategy: 1,
   numRounds: 10,
-  claimAndFund: false,  // optional
-  isPooled: false,      // optional
-})
+  claimAndFund: false, // optional
+  isPooled: false, // optional
+});
 
 // Fund autominer
-const sig = await sdk.fundAutomation(1_000_000)
+const sig = await sdk.fundAutomation(1_000_000);
 
 // Stop autominer
-const sig = await sdk.stopAutominer()
+const sig = await sdk.stopAutominer();
 ```
 
 ### Staking
 
 ```typescript
 // V1 Staking
-const sig = await sdk.stakeDeposit(1_000_000n)
-const sig = await sdk.stakeWithdraw(500_000n)
-const sig = await sdk.stakeClaimYield(100_000n)
+const sig = await sdk.stakeDeposit(1_000_000n);
+const sig = await sdk.stakeWithdraw(500_000n);
+const sig = await sdk.stakeClaimYield(100_000n);
 
 // V2 Staking (with lock duration and multiplier)
-const sig = await sdk.stakeV2Deposit(0n, 1_000_000n, 30n)   // id, amount, lockDuration
-const sig = await sdk.stakeV2Withdraw(0n, 500_000n)
-const sig = await sdk.stakeV2ClaimYield(0n, 100_000n)
-const sig = await sdk.stakeV2CompoundYield(0n)
+const sig = await sdk.stakeV2Deposit(0n, 1_000_000n, 30n); // id, amount, lockDuration
+const sig = await sdk.stakeV2Withdraw(0n, 500_000n);
+const sig = await sdk.stakeV2ClaimYield(0n, 100_000n);
+const sig = await sdk.stakeV2CompoundYield(0n);
 
 // Set executor for V2 stake
-const sig = await sdk.setStakeExecutor(0n, address('executor...'))
+const sig = await sdk.setStakeExecutor(0n, address("executor..."));
 
 // NFT boost
-const sig = await sdk.stakeNft(0n, address('nftAsset...'))
-const sig = await sdk.unstakeNft(0n, address('nftAsset...'))
+const sig = await sdk.stakeNft(0n, address("nftAsset..."));
+const sig = await sdk.unstakeNft(0n, address("nftAsset..."));
 ```
 
 ## Low-Level Instruction Builders
@@ -228,7 +237,7 @@ import {
   getSetStakeExecutorV2Instruction,
   getStakeNftInstruction,
   getUnstakeNftInstruction,
-} from '@zenx-labs/godl-supply'
+} from "@zenx-labs/godl-supply";
 ```
 
 ## PDA Derivation
@@ -247,13 +256,13 @@ import {
   getStakeV2Pda,
   getPoolRoundPda,
   getPoolMemberPda,
-  getGodlAta,         // returns Promise<Address>
-} from '@zenx-labs/godl-supply'
+  getGodlAta, // returns Promise<Address>
+} from "@zenx-labs/godl-supply";
 
-const [boardKey, bump] = getBoardPda()
-const [minerKey, bump] = getMinerPda(publicKey)
-const [stakeKey, bump] = getStakeV2Pda(publicKey, 0n)
-const ata = await getGodlAta(address('owner...'))
+const [boardKey, bump] = getBoardPda();
+const [minerKey, bump] = getMinerPda(publicKey);
+const [stakeKey, bump] = getStakeV2Pda(publicKey, 0n);
+const ata = await getGodlAta(address("owner..."));
 ```
 
 ## Advanced Usage
@@ -261,27 +270,27 @@ const ata = await getGodlAta(address('owner...'))
 The SDK exports internal components for custom integrations:
 
 ```typescript
-import { HotCache, SlotTracker, AccountFetcher } from '@zenx-labs/godl-supply'
+import { HotCache, SlotTracker, AccountFetcher } from "@zenx-labs/godl-supply";
 
 // Custom cache with 5s TTL
-const cache = new HotCache(5_000)
+const cache = new HotCache(5_000);
 
 // Direct account fetching without the full client
-const fetcher = new AccountFetcher(rpc, cache, 'https://stream.godl.dev')
-const initData = await fetcher.fetchInitData()
+const fetcher = new AccountFetcher(rpc, cache, "https://stream.godl.dev");
+const initData = await fetcher.fetchInitData();
 ```
 
 ## Constants
 
 ```typescript
 import {
-  GODL_PROGRAM_ID,         // Program public key
-  GODL_MINT,               // GODL token mint address
-  ENTROPY_PROGRAM_ADDRESS,  // Entropy program for randomness
-  EXECUTOR_ADDRESS,         // Autominer executor
-  AUTOMATION_FEE,           // Fee per automation round (30,000 lamports)
-  NFT_BOOST_COLLECTION,     // NFT collection for stake boosts
-} from '@zenx-labs/godl-supply'
+  GODL_PROGRAM_ID, // Program public key
+  GODL_MINT, // GODL token mint address
+  ENTROPY_PROGRAM_ADDRESS, // Entropy program for randomness
+  EXECUTOR_ADDRESS, // Autominer executor
+  AUTOMATION_FEE, // Fee per automation round (30,000 lamports)
+  NFT_BOOST_COLLECTION, // NFT collection for stake boosts
+} from "@zenx-labs/godl-supply";
 ```
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zenx-labs/godl-supply",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "TypeScript SDK for interacting with the GODL on-chain program",
   "license": "ISC",
   "author": "bootapollo",
@@ -23,7 +23,8 @@
     "build": "tsc",
     "dev": "tsc --watch",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "sniper": "npx tsx tests/ev-sniper.test.ts"
   },
   "dependencies": {
     "@msgpack/msgpack": "^3.1.2",