hunch-cup 0.2.2 → 0.2.3

package/dist/cli.js

@@ -20,7 +20,7 @@
 import { CupClient } from "./client.js";
 import { fromPrivateKey, newWallet } from "./signer.js";
 import { fleetNew, fleetRun, fleetBoard } from "./fleet.js";
-const STRATEGIES = ["momentum", "contrarian", "news-reactive"];
+const STRATEGIES = ["momentum", "contrarian", "news-reactive", "random"];
 function baseUrl() {
     return process.env.HUNCH_CUP_BASE_URL;
 }

package/dist/client.d.ts

@@ -115,11 +115,15 @@ export declare class CupClient {
     runStrategy(opts: {
         strategy: CupStrategy;
         sizePhunch: number;
+        /** When set, each bet's size is a random integer in [sizePhunch, sizePhunchMax]. */
+        sizePhunchMax?: number;
         limit?: number;
         sentiment?: number;
         live?: boolean;
         /** Max fraction of the current balance to deploy per round (default 25%). */
         maxRoundFraction?: number;
+        /** Trade only markets this predicate keeps (e.g. only the flip + 5m/15m rounds). */
+        marketFilter?: (m: CupMarket) => boolean;
     }): Promise<CupTradeReceipt[]>;
     /**
      * Run a strategy on a fixed interval, forever (or `rounds` times), catching
@@ -129,11 +133,13 @@ export declare class CupClient {
     runLoop(opts: {
         strategy: CupStrategy;
         sizePhunch: number;
+        sizePhunchMax?: number;
         intervalMs: number;
         limit?: number;
         sentiment?: number;
         live?: boolean;
         maxRoundFraction?: number;
+        marketFilter?: (m: CupMarket) => boolean;
         rounds?: number;
         onRound?: (round: number, receipts: CupTradeReceipt[]) => void;
         onError?: (round: number, err: unknown) => void;

package/dist/client.js

@@ -136,7 +136,8 @@ export class CupClient {
      * The decision is pure ({@link pickFor}); placement is deterministic code.
      */
     async runStrategy(opts) {
-        const markets = await this.listMarkets(opts.limit ?? 10);
+        const all = await this.listMarkets(opts.limit ?? 10);
+        const markets = opts.marketFilter ? all.filter(opts.marketFilter) : all;
         const receipts = [];
         // Bankroll snapshot (live only — a simulate run writes nothing, so it can
         // fan out over every market without spending).
@@ -160,7 +161,9 @@ export class CupClient {
         for (const m of markets) {
             if (opts.live && held.has(m.marketId))
                 continue; // already positioned
-            const size = opts.sizePhunch;
+            const size = opts.sizePhunchMax && opts.sizePhunchMax > opts.sizePhunch
+                ? randInt(opts.sizePhunch, opts.sizePhunchMax)
+                : opts.sizePhunch;
             if (opts.live && (balance < size || roundBudget < size))
                 break; // insolvent / budget spent
             const card = {
@@ -219,6 +222,10 @@ function roundBucket() {
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+/** Uniform random integer in [min, max]. */
+function randInt(min, max) {
+    return Math.floor(Math.random() * (max - min + 1)) + min;
+}
 function randomId() {
     // Best-effort unique id; the server idempotency key is the full tradeId.
     return Math.abs(Math.floor(Math.random() * 1e15)).toString(36) + Date.now().toString(36);

package/dist/fleet.d.ts

@@ -1,3 +1,4 @@
+import { type CupMarket } from "./client.js";
 import type { CupStrategy } from "./strategy.js";
 export interface FleetWallet {
     name: string;
@@ -33,6 +34,31 @@ export declare function fleetRun(opts: {
     rounds?: number;
     onEvent?: (line: string) => void;
 }): Promise<void>;
+/**
+ * Coordinated round loop: instead of every wallet running its own perpetual
+ * loop, each ROUND a random subset of `participants()` wallets acts once (via
+ * `runStrategy`). Models a live crowd where a variable slice of the roster
+ * trades each round, not all of them every time. Concurrency across the chosen
+ * wallets, staggered so they don't fire on the same instant. Never throws —
+ * per-wallet errors surface via `onEvent`.
+ */
+export declare function fleetRunRounds(opts: {
+    strategy: CupStrategy;
+    sizePhunch: number;
+    /** When set, each bet's size is a random int in [sizePhunch, sizePhunchMax]. */
+    sizePhunchMax?: number;
+    intervalMs: number;
+    /** How many wallets act this round (default: all). e.g. `() => 70 + rand(0..30)`. */
+    participants?: () => number;
+    marketFilter?: (m: CupMarket) => boolean;
+    maxRoundFraction?: number;
+    /** false → simulate (no writes), for a dry-run smoke. Default true (real trades). */
+    live?: boolean;
+    baseUrl?: string;
+    limit?: number;
+    rounds?: number;
+    onEvent?: (line: string) => void;
+}): Promise<void>;
 /** Each fleet wallet's live rank + balance + realized PnL, best rank first. */
 export declare function fleetBoard(baseUrl?: string): Promise<Array<{
     name: string;

package/dist/fleet.js

@@ -97,6 +97,57 @@ export async function fleetRun(opts) {
         });
     }));
 }
+/**
+ * Coordinated round loop: instead of every wallet running its own perpetual
+ * loop, each ROUND a random subset of `participants()` wallets acts once (via
+ * `runStrategy`). Models a live crowd where a variable slice of the roster
+ * trades each round, not all of them every time. Concurrency across the chosen
+ * wallets, staggered so they don't fire on the same instant. Never throws —
+ * per-wallet errors surface via `onEvent`.
+ */
+export async function fleetRunRounds(opts) {
+    const fleet = loadFleet();
+    if (fleet.wallets.length === 0) {
+        opts.onEvent?.("No fleet wallets. Run `hunch-cup fleet new <n>` first.");
+        return;
+    }
+    for (let round = 1; !opts.rounds || round <= opts.rounds; round += 1) {
+        const n = Math.max(1, Math.min(fleet.wallets.length, Math.floor(opts.participants?.() ?? fleet.wallets.length)));
+        const chosen = shuffle(fleet.wallets).slice(0, n);
+        const stagger = Math.floor(opts.intervalMs / Math.max(1, chosen.length));
+        await Promise.all(chosen.map(async (w, i) => {
+            await sleep(stagger * i);
+            try {
+                const client = new CupClient({ baseUrl: opts.baseUrl, signer: fromPrivateKey(w.privateKey) });
+                const receipts = await client.runStrategy({
+                    strategy: w.strategy ?? opts.strategy,
+                    sizePhunch: opts.sizePhunch,
+                    sizePhunchMax: opts.sizePhunchMax,
+                    limit: opts.limit,
+                    live: opts.live ?? true,
+                    maxRoundFraction: opts.maxRoundFraction,
+                    marketFilter: opts.marketFilter,
+                });
+                opts.onEvent?.(`[${w.name}] round ${round}: ${receipts.length} trade(s)`);
+            }
+            catch (err) {
+                opts.onEvent?.(`[${w.name}] round ${round} error: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }));
+        if (opts.rounds && round >= opts.rounds)
+            break;
+        await sleep(opts.intervalMs);
+    }
+}
+/** Fisher–Yates shuffle (copy) — pick a random subset without bias. */
+function shuffle(arr) {
+    const a = [...arr];
+    for (let i = a.length - 1; i > 0; i -= 1) {
+        const j = Math.floor(Math.random() * (i + 1));
+        [a[i], a[j]] = [a[j], a[i]];
+    }
+    return a;
+}
 /** Each fleet wallet's live rank + balance + realized PnL, best rank first. */
 export async function fleetBoard(baseUrl) {
     const fleet = loadFleet();

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export type { CupClientOptions, CupSigner, CupMarket, CupOutcome, CupPosition, C
 export { fromViemAccount, fromPrivateKey, newWallet } from "./signer.js";
 export { buildCupTradeMessage } from "./message.js";
 export type { CupTradeMessageParams } from "./message.js";
-export { pickFor, momentumPick, contrarianPick, newsReactivePick, } from "./strategy.js";
+export { pickFor, momentumPick, contrarianPick, newsReactivePick, randomPick, } from "./strategy.js";
 export type { CupStrategy, StrategyCard, StrategyOutcome, StrategyPick, } from "./strategy.js";
-export { fleetNew, fleetRun, fleetBoard, loadFleet, saveFleet, fleetFilePath, } from "./fleet.js";
+export { fleetNew, fleetRun, fleetRunRounds, fleetBoard, loadFleet, saveFleet, fleetFilePath, } from "./fleet.js";
 export type { Fleet, FleetWallet } from "./fleet.js";

package/dist/index.js

@@ -1,5 +1,5 @@
 export { CupClient, DEFAULT_BASE_URL } from "./client.js";
 export { fromViemAccount, fromPrivateKey, newWallet } from "./signer.js";
 export { buildCupTradeMessage } from "./message.js";
-export { pickFor, momentumPick, contrarianPick, newsReactivePick, } from "./strategy.js";
-export { fleetNew, fleetRun, fleetBoard, loadFleet, saveFleet, fleetFilePath, } from "./fleet.js";
+export { pickFor, momentumPick, contrarianPick, newsReactivePick, randomPick, } from "./strategy.js";
+export { fleetNew, fleetRun, fleetRunRounds, fleetBoard, loadFleet, saveFleet, fleetFilePath, } from "./fleet.js";

package/dist/strategy.d.ts

@@ -32,7 +32,7 @@ export interface StrategyPick {
     slug: string;
     side: string;
 }
-export type CupStrategy = "momentum" | "contrarian" | "news-reactive";
+export type CupStrategy = "momentum" | "contrarian" | "news-reactive" | "random";
 /** Momentum: trade WITH the crowd — back the pool's favorite (max odds). */
 export declare function momentumPick(card: StrategyCard): StrategyPick;
 /** Contrarian: fade the crowd — back the longest-odds outcome. */
@@ -45,5 +45,12 @@ export declare function contrarianPick(card: StrategyCard): StrategyPick;
  * crowd favorite (positive) or underdog (negative) — always a real key.
  */
 export declare function newsReactivePick(card: StrategyCard, sentiment: number): StrategyPick;
+/**
+ * Random: take a side with NO logic — uniformly pick one of the market's real
+ * outcome keys (N-way → over `outcomes`; binary/direction → yes/no, the
+ * settlement keys). A fleet of these produces liquidity and pool depth with no
+ * predictable bias; the `rng` is injectable so the pick is unit-testable.
+ */
+export declare function randomPick(card: StrategyCard, rng?: () => number): StrategyPick;
 /** Dispatch a named strategy. `news-reactive` uses `sentiment` (default 0). */
 export declare function pickFor(strategy: CupStrategy, card: StrategyCard, sentiment?: number): StrategyPick;

package/dist/strategy.js

@@ -69,6 +69,20 @@ export function newsReactivePick(card, sentiment) {
         return { slug: card.slug, side: sideFor(card, "neg") };
     return momentumPick(card);
 }
+/**
+ * Random: take a side with NO logic — uniformly pick one of the market's real
+ * outcome keys (N-way → over `outcomes`; binary/direction → yes/no, the
+ * settlement keys). A fleet of these produces liquidity and pool depth with no
+ * predictable bias; the `rng` is injectable so the pick is unit-testable.
+ */
+export function randomPick(card, rng = Math.random) {
+    if (isNway(card)) {
+        const keys = card.outcomes.map((o) => o.key);
+        const i = Math.min(Math.floor(rng() * keys.length), keys.length - 1);
+        return { slug: card.slug, side: keys[i] ?? keys[0] };
+    }
+    return { slug: card.slug, side: rng() < 0.5 ? "yes" : "no" };
+}
 /** Dispatch a named strategy. `news-reactive` uses `sentiment` (default 0). */
 export function pickFor(strategy, card, sentiment = 0) {
     switch (strategy) {
@@ -78,5 +92,7 @@ export function pickFor(strategy, card, sentiment = 0) {
             return contrarianPick(card);
         case "news-reactive":
             return newsReactivePick(card, sentiment);
+        case "random":
+            return randomPick(card);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hunch-cup",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "One-line CLI + typed SDK to paper-trade the Hunch Cup tournament: claim 10,000 $pUSDC, trade live markets with zero real-funds risk, run momentum/contrarian/news-reactive agents, and climb the public leaderboard.",
   "keywords": [
     "hunch",