@senpi/runtime 3.0.0-dev.openclaw-upgrade-mai.20260623210452 → 3.0.0-dev.runtime-phase-2.20260623210537

package/examples/scanners-single-strategy.mjs

@@ -0,0 +1,198 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  createScannerRuntimeModule,
+  emergingMoversScanner,
+  momentumScanner,
+  oiTrackerScanner,
+  prescreenerScanner,
+} from "../dist/scanners/index.js";
+
+function createInstruments() {
+  return [
+    {
+      name: "BTC",
+      isDelisted: false,
+      maxLeverage: 10,
+      context: {
+        markPx: 106,
+        prevDayPx: 100,
+        midPx: 106,
+        dayNtlVlm: 80_000_000,
+        openInterest: 2_000_000_000,
+        funding: 0.001,
+      },
+    },
+    {
+      name: "ETH",
+      isDelisted: false,
+      maxLeverage: 8,
+      context: {
+        markPx: 101,
+        prevDayPx: 100,
+        midPx: 101,
+        dayNtlVlm: 40_000_000,
+        openInterest: 1_000_000_000,
+        funding: 0.001,
+      },
+    },
+  ];
+}
+
+function createCandles() {
+  return {
+    BTC: {
+      candles: {
+        "1h": [
+          {
+            timestamp: 1,
+            open: 100,
+            high: 102,
+            low: 99,
+            close: 100,
+            volume: 1000,
+          },
+          {
+            timestamp: 2,
+            open: 100,
+            high: 107,
+            low: 100,
+            close: 106,
+            volume: 1400,
+          },
+        ],
+      },
+    },
+    ETH: {
+      candles: {
+        "1h": [
+          {
+            timestamp: 1,
+            open: 100,
+            high: 101,
+            low: 99,
+            close: 100,
+            volume: 900,
+          },
+          {
+            timestamp: 2,
+            open: 100,
+            high: 101,
+            low: 99,
+            close: 100.4,
+            volume: 920,
+          },
+        ],
+      },
+    },
+  };
+}
+
+function createSmDataRun1() {
+  return [
+    {
+      token: "SOL",
+      direction: "up",
+      pctOfTopTradersGain: 0.18,
+      traderCount: 220,
+      tokenPriceChangePct4h: 2.1,
+    },
+    {
+      token: "AVAX",
+      direction: "up",
+      pctOfTopTradersGain: 0.16,
+      traderCount: 200,
+      tokenPriceChangePct4h: 1.9,
+    },
+  ];
+}
+
+function createSmDataRun2() {
+  return [
+    {
+      token: "AVAX",
+      direction: "up",
+      pctOfTopTradersGain: 0.17,
+      traderCount: 230,
+      tokenPriceChangePct4h: 2.0,
+    },
+    {
+      token: "SOL",
+      direction: "up",
+      pctOfTopTradersGain: 0.35,
+      traderCount: 250,
+      tokenPriceChangePct4h: 4.2,
+    },
+  ];
+}
+
+async function main() {
+  const stateDir = await mkdtemp(join(tmpdir(), "scanners-example-single-"));
+  let smDataRun = 0;
+
+  const module = createScannerRuntimeModule({
+    stateDir,
+    scanners: [prescreenerScanner, oiTrackerScanner, momentumScanner, emergingMoversScanner],
+    strategies: [
+      {
+        id: "alpha",
+        name: "Alpha",
+        scannerOverrides: {
+          momentum: {
+            config: {
+              timeframe: "1h",
+              minMovePct: 1.5,
+              maxCandidates: 10,
+              minDayVolume: 1_000_000,
+              minSignalScore: 0.2,
+              requirePrescreened: true,
+            },
+          },
+          "emerging-movers": {
+            config: {
+              topN: 10,
+              minRankJump: 1,
+              minTopTradersGain: 0.15,
+              minScansBeforeSignals: 2,
+              historyLimit: 30,
+            },
+          },
+        },
+      },
+    ],
+    providers: {
+      getInstruments: async () => createInstruments(),
+      getCandles: async () => createCandles(),
+      getSmData: async () => {
+        smDataRun += 1;
+        return smDataRun === 1 ? createSmDataRun1() : createSmDataRun2();
+      },
+    },
+  });
+
+  try {
+    await module.runOnce("alpha", "prescreener");
+    await module.runOnce("alpha", "oi-tracker");
+    const momentumResult = await module.runOnce("alpha", "momentum");
+    await module.runOnce("alpha", "emerging-movers");
+    const emergingResult = await module.runOnce("alpha", "emerging-movers");
+
+    const signals = await module.querySignals({
+      strategyId: "alpha",
+      limit: 20,
+    });
+
+    console.log("single-strategy: momentum signals =", momentumResult.signals.length);
+    console.log("single-strategy: emerging signals =", emergingResult.signals.length);
+    console.log("single-strategy: queried signals =", signals.length);
+  } finally {
+    await module.stop();
+    await rm(stateDir, { recursive: true, force: true });
+  }
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/examples/strategies/README.md

@@ -1,17 +1,12 @@
-# Strategy Examples
+# Strategy Templates
 
-Four supervised **runtime-v2** strategies ship as worked examples. Each is a
-complete, validated recipe (`version: 2.0.0`) with its own supervised
-`scanners/scan.py` (the runtime spawns a scaffold child and calls
-`scan(inputs, ctx)` on `interval_seconds` — there is no producer/push model).
-Each has its own README with the full thesis, scanner shape, and DSL profile.
-
-| Strategy | Thesis | Recipe(s) | README |
-|----------|--------|-----------|--------|
-| **iguana** | XYZ macro index-trend — index-fund-style equity exposure on Hyperliquid, no stock-picking. Two indices, one decision per tick. | `iguana/recipe.yaml` | [iguana/README.md](iguana/README.md) |
-| **raptor** | Whale copy-follow — takes a currently-winning quality trader's highest-conviction position when smart money agrees. | `raptor/recipe.yaml` | [raptor/README.md](raptor/README.md) |
-| **turbine** | Funding-fade rotation — one shared signal, two recipes that differ only in sizing + DSL exit + risk (volume vs runners). | `turbine/recipe-volume.yaml`, `turbine/recipe-runners.yaml` | [turbine/README.md](turbine/README.md) |
-| **spider** | Two genuinely different legs on separate wallets: `swing` (tech/AI multi-day momentum) + `scalp` (macro/majors fast mean-reversion). | `spider/swing/recipe.yaml`, `spider/scalp/recipe.yaml` | [spider/README.md](spider/README.md) |
+| File | Style | Scanners | Decision | Use case |
+|------|-------|----------|----------|----------|
+| minimal.yaml | Watch-only | emerging_movers | no_decision | Verify setup; no positions |
+| wolf.yaml | Aggressive | emerging_movers | llm | Early entry on FIRST_JUMP |
+| viper.yaml | Moderate | prescreener + momentum | llm | Candle-based breakouts |
+| fox.yaml | OI-driven | prescreener + oi_tracker | no_decision | OI spike entries |
+| dsl-showcase.yaml | DSL reference | emerging_movers | no_decision | Annotated exit config |
 
 ## Quickstart
 
@@ -20,16 +15,16 @@ Each has its own README with the full thesis, scanner shape, and DSL profile.
    openclaw plugins install @senpi-ai/runtime
    ```
 
-2. Copy a recipe and fill in its wallet env var:
+2. Copy a template and fill in your wallet:
    ```bash
-   cp iguana/recipe.yaml my-recipe.yaml
-   # edit: set the strategy's wallet env var (iguana uses ${IGUANA_WALLET})
+   cp wolf.yaml my-recipe.yaml
+   # edit: replace ${WALLET_ADDRESS}
    ```
 
 3. Set environment variables:
    ```bash
    cp ../.env.example .env
-   # edit: SENPI_API_KEY plus the recipe's wallet env var
+   # edit: SENPI_API_KEY, WALLET_ADDRESS
    source .env
    ```
 

package/examples/strategies/dsl-showcase.yaml

@@ -0,0 +1,68 @@
+# DSL showcase — every DSL field annotated for reference.
+# Use as a copy-paste reference when tuning exit behavior.
+name: dsl-showcase
+version: 1.0.0
+description: >
+  Annotated DSL exit config reference.
+  Onchain position tracker — monitors the strategy wallet on Hyperliquid
+  for position lifecycle events (open, close, edit, flip) and wires them
+  into the DSL exit engine for automated trailing stop-loss management.
+
+
+notifications:
+  telegram_chat_id: "${TELEGRAM_CHAT_ID}"
+
+strategy:
+  wallet: "${WALLET_ADDRESS}"
+  slots: 2
+  margin_pct: 15
+  trading_risk: conservative
+  enabled: true
+
+# ── SCANNERS ──
+scanners:
+  - name: position_tracker
+    type: position_tracker
+    interval: 10s
+
+# ── ACTIONS ──
+actions:
+  - name: position_tracker_action
+    action_type: POSITION_TRACKER
+    decision_mode: rule
+    scanners: [position_tracker]
+
+exit:
+  engine: dsl
+  # interval_seconds — how often the price monitor runs
+  interval_seconds: 30
+  # order_type — execution method for DSL exit closes: MARKET (default) or FEE_OPTIMIZED_LIMIT
+  order_type: FEE_OPTIMIZED_LIMIT
+  # fee_optimized_limit_options — only used when order_type is FEE_OPTIMIZED_LIMIT
+  fee_optimized_limit_options:
+    ensure_execution_as_taker: true       # fall back to market if maker doesn't fill
+    execution_timeout_seconds: 15         # seconds to wait for maker fill (default 45)
+  # dsl_preset — single exit profile (required for DslPlugin).
+  dsl_preset:
+    hard_timeout:
+      enabled: true
+      interval_in_minutes: 360
+    weak_peak_cut:
+      enabled: true
+      interval_in_minutes: 120
+      min_value: 5
+    dead_weight_cut:
+      enabled: true
+      interval_in_minutes: 5
+    phase1:
+      enabled: true
+      max_loss_pct: 4.0
+      retrace_threshold: 7
+      consecutive_breaches_required: 1
+    phase2:
+      enabled: true
+      tiers:
+        - { trigger_pct: 7,  lock_hw_pct: 40 }
+        - { trigger_pct: 12, lock_hw_pct: 55 }
+        - { trigger_pct: 15, lock_hw_pct: 75 }
+        - { trigger_pct: 20, lock_hw_pct: 85 }

package/examples/strategies/dsl.yaml

@@ -0,0 +1,51 @@
+name: position-tracker
+version: 1.0.0
+description: >
+  Onchain position tracker — monitors the strategy wallet on Hyperliquid
+  for position lifecycle events (open, close, edit, flip) and wires them
+  into the DSL exit engine for automated trailing stop-loss management.
+
+# ── STRATEGY ──
+# Minimal: only wallet address + optional fields (no slots/margin needed for watch-only)
+strategy:
+  wallet: "${WALLET_ADDRESS}"
+  enabled: true
+
+# ── SCANNERS ──
+scanners:
+  - name: position_tracker
+    type: position_tracker
+    interval: 10s
+
+# ── ACTIONS ──
+actions:
+  - name: position_tracker_action
+    action_type: POSITION_TRACKER
+    decision_mode: rule
+    scanners: [position_tracker]
+
+# ── EXIT (DSL) ──
+exit:
+  engine: dsl
+  interval_seconds: 30
+  order_type: FEE_OPTIMIZED_LIMIT
+  fee_optimized_limit_options:
+    ensure_execution_as_taker: true
+    execution_timeout_seconds: 15
+  dsl_preset:
+    phase1:
+      enabled: true
+      max_loss_pct: 3.0
+      retrace_threshold: 7
+      consecutive_breaches_required: 3
+    phase2:
+      enabled: true
+      tiers:
+        - { trigger_pct: 7,  lock_hw_pct: 40 }
+        - { trigger_pct: 12, lock_hw_pct: 55 }
+        - { trigger_pct: 15, lock_hw_pct: 75 }
+        - { trigger_pct: 20, lock_hw_pct: 85 }
+
+# ── NOTIFICATIONS ──
+notifications:
+  telegram_chat_id: "${TELEGRAM_CHAT_ID}"

package/examples/strategies/fox-minimal-loosened.yaml

@@ -0,0 +1,240 @@
+name: fox-minimal-loosened
+version: 1.0.0
+description: >
+  FOX v1.6 — loosened configuration for functional evaluation.
+  Scanner thresholds relaxed, LLM gauntlet simplified, and slots increased
+  to maximize signal volume. NOT for live trading.
+
+notifications:
+  telegram_chat_id: "${TELEGRAM_CHAT_ID}"
+
+strategy:
+  wallet: "${FOX_WALLET}"
+  slots: 3
+  margin_pct: 10
+  trading_risk: aggressive
+  enabled: true
+
+scanners:
+  # References in depends_on/actions use these scanner names, not the built-in types.
+  # ── Primary signal: emerging movers (every 60s, faster for eval) ──
+  - name: emerging_movers
+    type: emerging_movers
+    interval: 60s
+    depends_on:
+      - scanner: market_regime
+        required: false
+        max_age: 2h
+        on_missing: degrade
+        on_stale: degrade
+    blocked_assets: []
+    config:
+      topN: 100
+      minRankJump: 2
+      minTopTradersGain: 0.02
+      minScansBeforeSignals: 1
+      historyLimit: 60
+      immediateJumpThreshold: 5
+      deepClimbRankThreshold: 40
+      contribExplosionMultiplier: 1.5
+      contribAccelThreshold: 0.001
+      minVelocityForDeepClimber: 0.0001
+      erraticReversalThreshold: 10
+      climbStreakScans: 2
+      rankClimbThreshold: 2
+      firstJumpMinPrevRank: 15
+      minLeverage: 2
+      blacklist: []
+
+  # ── Macro context: BTC+ETH regime classification (every 4h) ──
+  - name: market_regime
+    type: market_regime
+    interval: 14400s
+    config:
+      btcWeight: 0.6
+      ethWeight: 0.4
+      emaFast: 9
+      emaSlow: 21
+      neutralThreshold: 0.3
+
+  # ── SM conviction reversal detection (every 5 min) ──
+  - name: sm_flip
+    type: sm_flip
+    interval: 300s
+    config:
+      minConviction: 4
+
+  # ── Margin safety net (every 5 min) ──
+  - name: watchdog
+    type: liquidation_watchdog
+    interval: 300s
+    config:
+      bufferWarningPct: 50
+      bufferCriticalPct: 30
+      liqDistanceWarningPct: 30
+      roeDangerPct: -15
+
+  # ── Infrastructure: prescreener for opportunity scanner (every 60s) ──
+  - name: prescreener
+    type: prescreener
+    interval: 60s
+    config:
+      topN: 50
+      minDayVolume: 200000
+      minLeverage: 2
+      minOpenInterest: 0
+
+  # ── Secondary deep scan: 4-pillar opportunity scoring (every 10 min) ──
+  - name: opportunity
+    type: opportunity
+    interval: 600s
+    depends_on:
+      - scanner: prescreener
+        required: true
+        max_age: 5m
+      - scanner: market_regime
+        required: false
+        max_age: 4h
+        on_missing: degrade
+        on_stale: degrade
+    config:
+      minCompositeScore: 30
+      maxCandidates: 30
+      minDayVolume: 200000
+
+actions:
+  # ── Entry: LLM relaxed filter on emerging mover signals ──
+  - name: fox_entry
+    action_type: OPEN_POSITION
+    decision_mode: llm
+    decision_model: ${DECISION_MODEL}
+    scanners: [emerging_movers]
+    min_confidence: 4
+    params:
+      order_type: FEE_OPTIMIZED_LIMIT
+      fee_optimized_limit_options:
+        ensure_execution_as_taker: true
+        execution_timeout_seconds: 15
+    context:
+      - type: signal
+        scanner: emerging_movers
+      - type: context
+        scanner: market_regime
+    decision_prompt: |
+      You are the FOX v1.6 entry filter in EVALUATION MODE. Evaluate emerging mover
+      signals with relaxed thresholds to maximize signal throughput for functional testing.
+
+      SIGNAL DATA:
+      {{emerging_movers}}
+
+      MARKET REGIME:
+      {{regime}}
+
+      ═══ LAYER 1: SIGNAL DETECTION (relaxed) ═══
+      - Must have at least one of: FIRST_JUMP, IMMEDIATE_MOVER, DEEP_CLIMBER, CONTRIB_EXPLOSION
+      - rankJumpThisScan ≥ 5 OR contribVelocity > 5
+      - Asset at #1-5 for 3+ scans → SKIP (move is over)
+
+      ═══ LAYER 2: SCORING (minimum 4 points) ═══
+      FIRST_JUMP:           +3
+      IMMEDIATE_MOVER:      +2
+      contribVelocity > 5:  +2
+      CONTRIB_EXPLOSION:    +2
+      DEEP_CLIMBER:         +1
+      RANK_UP:              +1
+      CLIMBING:             +1
+      ACCEL:                +1
+      STREAK:               +1
+      BTC 1h bias aligned:  +1
+
+      Minimum requirements: score ≥ 4, reasons ≥ 2, contribVelocity > 2
+
+      ═══ LAYER 3: VELOCITY & PRICE ACTION (relaxed) ═══
+      - Negative velocity without any jump reason → SKIP
+      - Any positive velocity is sufficient for all signal types
+      - Erratic rank history → SKIP only if no strong reason (FIRST_JUMP/CONTRIB_EXPLOSION)
+
+      ═══ LAYER 4: LEVERAGE & ASSET CHECKS (relaxed) ═══
+      - Max leverage for asset must be ≥ 2x
+      - XYZ equities: ignore trader count, use leverageType "ISOLATED" and dex "xyz"
+      - ≥ 5 SM traders required (crypto only, waived for XYZ)
+
+      ═══ LAYER 5: MARKET REGIME (relaxed) ═══
+      - BEARISH: prefer SHORT, but LONG allowed if score ≥ 6
+      - BULLISH: prefer LONG, but SHORT allowed if score ≥ 6
+      - NEUTRAL or stale: both directions allowed
+
+      ═══ ROTATION (slots full + new signal) ═══
+      - Weakest position has negative ROE → CUT and ENTER new
+      - Weakest has positive ROE or SM conviction 3+ → HOLD
+      - Never rotate positions younger than 5 minutes
+
+      ═══ ANTI-PATTERNS (hard blocks) ═══
+      - Rank #1-5 for 3+ scans → move is over
+      - Burned/blacklisted asset → SKIP
+
+      Respond:
+      {
+        "execute": true/false,
+        "actionType": "OPEN_POSITION",
+        "confidence": 1-10,
+        "reasoning": "one sentence",
+        "payload": {
+          "signals": [
+            { "asset": "<ticker>", "direction": "LONG" or "SHORT", "reason": "one sentence", "rotate_out": "<asset_to_cut>", "leverage": "<optional number>", "margin": "<optional $ amount>" }
+          ]
+        }
+      }
+
+  # ── SM flip: immediate close on conviction reversal ──
+  - name: sm_flip_close
+    action_type: CLOSE_POSITION
+    decision_mode: rule
+    scanners: [sm_flip]
+    min_confidence: 1
+    params:
+      order_type: FEE_OPTIMIZED_LIMIT
+      fee_optimized_limit_options:
+        ensure_execution_as_taker: true
+        execution_timeout_seconds: 10
+
+  # ── Watchdog: emergency close on margin danger ──
+  - name: watchdog_close
+    action_type: CLOSE_POSITION
+    decision_mode: rule
+    scanners: [watchdog]
+    min_confidence: 1
+    params:
+      order_type: MARKET
+
+# ── DSL — trailing exit
+exit:
+  engine: dsl
+  interval_seconds: 30
+  order_type: FEE_OPTIMIZED_LIMIT
+  fee_optimized_limit_options:
+    ensure_execution_as_taker: true
+    execution_timeout_seconds: 15
+  dsl_preset:
+    hard_timeout:
+      enabled: false
+      interval_in_minutes: 360
+    weak_peak_cut:
+      enabled: false
+      interval_in_minutes: 120
+      min_value: 5
+    dead_weight_cut:
+      enabled: false
+      interval_in_minutes: 60
+    phase1:
+      enabled: true
+      max_loss_pct: 4.0
+      retrace_threshold: 3.0
+      consecutive_breaches_required: 1
+    phase2:
+      enabled: true
+      tiers:
+        - { trigger_pct: 7,  lock_hw_pct: 40 }
+        - { trigger_pct: 12, lock_hw_pct: 55 }
+        - { trigger_pct: 15, lock_hw_pct: 75 }
+        - { trigger_pct: 20, lock_hw_pct: 85 }