Codex-generated pull request

.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/

PLATFORM_BLUEPRINT.md

@@ -0,0 +1,148 @@
+# OpenClaw Arena: Autonomous Token Creation and Agent-vs-Agent Trading on Solana
+
+## 1) Product Vision
+OpenClaw Arena is an autonomous market where OpenClaw agents:
+- ingest real-time information (news, social signals, on-chain data),
+- launch short-lifecycle “meta tokens” with transparent rules,
+- and trade these assets against one another in a permissioned competitive environment.
+
+Humans do not manually pick trades. They only:
+1. fund agent vaults with SOL,
+2. configure risk bounds,
+3. monitor outcomes.
+
+## 2) High-Level Architecture
+
+### Core modules
+1. **Agent Runtime Layer**
+   - Hosts each OpenClaw strategy agent in isolated execution environments.
+   - Enforces deterministic action interfaces: `observe`, `propose`, `act`, `explain`.
+
+2. **Data & Signal Ingestion Layer**
+   - News APIs, X/Reddit trend scrapers, Solana on-chain feeds, DEX liquidity telemetry.
+   - Normalizes all signals into a shared event schema.
+   - Publishes events to a stream (e.g., Redpanda/Kafka).
+
+3. **Token Factory Layer**
+   - Controlled token-launch pipeline for agents.
+   - Agent proposal includes: ticker, thesis, launch parameters, max supply, curve type, fee split, and expiry policy.
+   - Guardrail service validates proposals against policy.
+
+4. **Market Execution Layer**
+   - Bonding-curve launch venue + optional migration to DEX pools at milestones.
+   - Router abstraction for swaps and limit logic.
+   - Shared simulation and slippage-aware execution.
+
+5. **Risk, Governance, and Safety Layer**
+   - Global and per-agent limits (position size, daily loss cap, token launch quota).
+   - Circuit breakers on volatility, oracle anomalies, and liquidity shocks.
+   - “Kill switch” to pause all agent actions.
+
+6. **Scoring and Tournament Layer**
+   - Agent leaderboard based on risk-adjusted returns (Sharpe/Sortino-like), drawdown, and rule compliance.
+   - Epoch-based tournaments with transparent reward logic.
+
+7. **Observability Layer**
+   - Structured logs, action traces, signed agent rationales.
+   - Reproducible replay of decisions and state snapshots.
+
+## 3) Solana-Centric System Design
+
+### On-chain programs (recommended split)
+- **Vault Program**
+  - Manages per-agent SOL and token balances.
+  - Enforces withdrawal and spend authorities.
+- **Launch Program**
+  - Creates “meta tokens” under strict templates.
+  - Stores launch metadata, fee parameters, expiry fields.
+- **Market Program**
+  - Bonding curve and internal matching primitives.
+  - Emits events consumed by analytics/scoring.
+- **Risk Program (or guardian signer policy)**
+  - Rejects transactions exceeding guardrails.
+
+### Off-chain services
+- Agent orchestration service (Kubernetes/Nomad).
+- Strategy sandbox service (WASM/container jail).
+- Event indexer + feature store.
+- Backtesting engine with historical replay.
+- API + dashboard for operators.
+
+## 4) Agent Lifecycle
+1. **Bootstrap**: operator funds vault, assigns strategy profile.
+2. **Observe**: agent consumes latest normalized signals.
+3. **Hypothesize**: agent predicts emerging meta narratives.
+4. **Propose**:
+   - launch token, or
+   - trade existing tokens.
+5. **Policy check**: risk engine approves/rejects action.
+6. **Execute**: signed transaction via controlled key path.
+7. **Post-trade reflection**: store rationale + confidence + outcome.
+8. **Score update**: leaderboard and adaptive throttling.
+
+## 5) Minimal Viable Product (MVP)
+
+### MVP scope (6-10 weeks)
+- 10-20 agents with predefined strategy archetypes:
+  - momentum chaser,
+  - contrarian mean-reversion,
+  - sentiment/news follower,
+  - liquidity sniper.
+- Token factory with one launch template.
+- One bonding curve model.
+- Hard limits per agent + global kill switch.
+- Basic leaderboard and action audit UI.
+
+### MVP non-goals
+- Open public permissionless agent onboarding.
+- High-frequency cross-DEX arbitrage.
+- Complex derivatives.
+
+## 6) Safety and Abuse Prevention
+- Permissioned agent registry with identity and version pinning.
+- Deterministic policy engine separate from model outputs.
+- Prompt/strategy tamper detection and signed build artifacts.
+- Mandatory cool-down periods between token launches.
+- Market manipulation heuristics (self-wash patterns, circular trading).
+
+## 7) Economics and Incentive Design
+- **Entry stake**: each agent starts with equal SOL allocation.
+- **Fee model**:
+  - Launch fee,
+  - trading fee,
+  - optional performance fee for winning agents.
+- **Rewards**:
+  - Epoch payouts for top risk-adjusted performers,
+  - penalty multipliers for breaking policy constraints.
+- **Token lifecycle**:
+  - auto-expiry or migration criteria,
+  - stale token cleanup to reduce state bloat.
+
+## 8) Compliance and Legal Considerations (must-do)
+- Jurisdictional review for autonomous trading system classification.
+- Terms that clarify operator/agent responsibilities.
+- Sanctions and AML screens for human depositors if public-facing.
+- Transparent disclosure: agents are experimental and non-advisory.
+
+## 9) Recommended Build Order
+1. Backtest simulator + event schema.
+2. Risk policy engine and enforcement contract.
+3. Agent runtime with 3 baseline strategies.
+4. Token factory + bonding curve launch.
+5. Live paper-trading mode.
+6. Mainnet gated beta with low limits.
+
+## 10) First Technical Milestones
+- **Milestone A**: deterministic simulation using historical Solana + news snapshots.
+- **Milestone B**: launch/trade guardrails proven by invariant tests.
+- **Milestone C**: 30-day paper tournament with reproducible logs.
+- **Milestone D**: controlled real-SOL tournament with capped downside.
+
+## 11) Practical Next Step
+Implement a paper-trading “Arena v0” before moving real funds:
+- no real token minting,
+- synthetic balances,
+- full decision logging,
+- and identical risk controls.
+
+If Arena v0 produces stable, auditable behavior, reuse the same interfaces for mainnet execution with stricter limits.

README.md

@@ -0,0 +1,61 @@
+# OpenClaw Arena v0
+
+A starter implementation of the paper-trading arena described in `PLATFORM_BLUEPRINT.md`.
+
+## What is implemented
+
+- Replayed market feed from historical snapshot CSV data.
+- Multiple autonomous agents that observe market snapshots and submit buy/sell/hold intents.
+- Deterministic risk engine enforcing:
+  - max position size,
+  - max notional per trade,
+  - no shorting,
+  - minimum cash reserve.
+- Token launch proposal flow where agents can propose new meta tokens.
+- Launch policy guardrails enforcing:
+  - launch quota per agent,
+  - minimum confidence,
+  - ticker format,
+  - max initial supply,
+  - cooldown between launches.
+- **Venue-level token pricing and cross-agent token inventory**:
+  - each approved launch creates a token market with reserves,
+  - all agents can buy/sell launched tokens,
+  - constant-product pricing updates per trade,
+  - each agent portfolio tracks per-token inventory,
+  - scoreboard includes token inventory by agent.
+- Epoch simulation loop with decision/action logs, launch logs, and token-trade logs.
+
+## Quickstart
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .[dev]
+python -m openclaw_arena.main --steps 50 --seed 7
+```
+
+Run using a custom snapshot file:
+
+```bash
+python -m openclaw_arena.main --steps 120 --snapshot-path ./path/to/snapshots.csv
+```
+
+Expected CSV columns:
+
+- `step`
+- `price`
+- `momentum`
+- `volatility`
+
+## Run tests
+
+```bash
+pytest
+```
+
+## Next build targets
+
+- Add per-token risk limits (max exposure per agent/token).
+- Plug in a real historical/news feature pipeline instead of static CSV snapshots.
+- Stream logs to a persistent store for tournament analytics.

pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openclaw-arena"
+version = "0.1.0"
+description = "Arena v0 simulation for autonomous OpenClaw agent trading"
+requires-python = ">=3.10"
+readme = "README.md"
+authors = [
+  { name = "OpenClaw Arena" }
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0"
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.setuptools.package-data]
+openclaw_arena = ["data/*.csv"]

src/openclaw_arena/__init__.py

@@ -0,0 +1,5 @@
+"""OpenClaw Arena v0 package."""
+
+from .simulation import run_simulation
+
+__all__ = ["run_simulation"]

src/openclaw_arena/agents.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass
+
+from .models import AgentAction, LaunchProposal, MarketState, Side, TokenOrder
+
+
+class BaseAgent:
+    agent_id: str
+
+    def act(self, state: MarketState) -> AgentAction:
+        raise NotImplementedError
+
+    def propose_launch(self, state: MarketState) -> LaunchProposal | None:
+        return None
+
+    def propose_token_order(self, state: MarketState, ticker: str, ref_price: float, inventory: float) -> TokenOrder | None:
+        return None
+
+
+@dataclass(slots=True)
+class MomentumAgent(BaseAgent):
+    agent_id: str
+    aggressiveness: float = 1.0
+
+    def act(self, state: MarketState) -> AgentAction:
+        if state.momentum > 0.001:
+            qty = max(0.0, self.aggressiveness * state.momentum * 100)
+            return AgentAction(self.agent_id, Side.BUY, qty, 0.7, "Positive momentum detected")
+        if state.momentum < -0.001:
+            qty = max(0.0, self.aggressiveness * abs(state.momentum) * 100)
+            return AgentAction(self.agent_id, Side.SELL, qty, 0.7, "Negative momentum detected")
+        return AgentAction(self.agent_id, Side.HOLD, 0.0, 0.3, "No clear momentum")
+
+    def propose_launch(self, state: MarketState) -> LaunchProposal | None:
+        if state.momentum > 0.009:
+            return LaunchProposal(
+                agent_id=self.agent_id,
+                step=state.step,
+                ticker="MOMO",
+                thesis="Strong positive price impulse indicates short-lived momentum meta",
+                initial_supply=250_000,
+                confidence=0.74,
+            )
+        return None
+
+    def propose_token_order(self, state: MarketState, ticker: str, ref_price: float, inventory: float) -> TokenOrder | None:
+        if state.momentum > 0.003:
+            return TokenOrder(agent_id=self.agent_id, ticker=ticker, side=Side.BUY, quantity=50.0)
+        if state.momentum < -0.003 and inventory > 0:
+            return TokenOrder(agent_id=self.agent_id, ticker=ticker, side=Side.SELL, quantity=min(40.0, inventory))
+        return None
+
+
+@dataclass(slots=True)
+class MeanReversionAgent(BaseAgent):
+    agent_id: str
+    anchor_price: float
+
+    def act(self, state: MarketState) -> AgentAction:
+        deviation = (state.price - self.anchor_price) / self.anchor_price
+        if deviation > 0.03:
+            return AgentAction(self.agent_id, Side.SELL, deviation * 50, 0.65, "Price above anchor; mean reversion short-bias")
+        if deviation < -0.03:
+            return AgentAction(self.agent_id, Side.BUY, abs(deviation) * 50, 0.65, "Price below anchor; mean reversion long-bias")
+        return AgentAction(self.agent_id, Side.HOLD, 0.0, 0.35, "Price near anchor")
+
+    def propose_token_order(self, state: MarketState, ticker: str, ref_price: float, inventory: float) -> TokenOrder | None:
+        deviation = (state.price - self.anchor_price) / self.anchor_price
+        if deviation < -0.01:
+            return TokenOrder(agent_id=self.agent_id, ticker=ticker, side=Side.BUY, quantity=30.0)
+        if deviation > 0.01 and inventory > 0:
+            return TokenOrder(agent_id=self.agent_id, ticker=ticker, side=Side.SELL, quantity=min(30.0, inventory))
+        return None
+
+
+@dataclass(slots=True)
+class NoiseSentimentAgent(BaseAgent):
+    agent_id: str
+    seed: int
+
+    def __post_init__(self) -> None:
+        self._rng = random.Random(self.seed)
+
+    def act(self, state: MarketState) -> AgentAction:
+        sentiment = self._rng.uniform(-1, 1) + (state.momentum * 10)
+        if sentiment > 0.5:
+            return AgentAction(self.agent_id, Side.BUY, sentiment * 4, 0.55, "Synthetic sentiment bullish")
+        if sentiment < -0.5:
+            return AgentAction(self.agent_id, Side.SELL, abs(sentiment) * 4, 0.55, "Synthetic sentiment bearish")
+        return AgentAction(self.agent_id, Side.HOLD, 0.0, 0.25, "Sentiment neutral")
+
+    def propose_launch(self, state: MarketState) -> LaunchProposal | None:
+        buzz = self._rng.uniform(0, 1) + abs(state.momentum)
+        if buzz > 0.92:
+            ticker = "META" if state.momentum >= 0 else "FADE"
+            thesis = "Synthetic social buzz spike detected"
+            return LaunchProposal(
+                agent_id=self.agent_id,
+                step=state.step,
+                ticker=ticker,
+                thesis=thesis,
+                initial_supply=300_000,
+                confidence=min(0.9, 0.6 + buzz / 3),
+            )
+        return None
+
+    def propose_token_order(self, state: MarketState, ticker: str, ref_price: float, inventory: float) -> TokenOrder | None:
+        toss = self._rng.uniform(-1, 1)
+        if toss > 0.4:
+            return TokenOrder(agent_id=self.agent_id, ticker=ticker, side=Side.BUY, quantity=20.0)
+        if toss < -0.4 and inventory > 0:
+            return TokenOrder(agent_id=self.agent_id, ticker=ticker, side=Side.SELL, quantity=min(20.0, inventory))
+        return None