diff --git a/.claude/devCorrectionLog.md b/.claude/devCorrectionLog.md new file mode 100644 index 0000000..d697a25 --- /dev/null +++ b/.claude/devCorrectionLog.md @@ -0,0 +1,33 @@ +# devCorrectionLog + +⊳ User gives **additive** clarifications. Only an explicit "no" is a replacement. +⊳ Don't rewrite — append. Don't guess — ask or research first. +⊳ Don't idle while subagents run. + +```yml +corrections: + - epoch: 1783985662 + failcase: "rewrote L3 seven times" + identifyBy: "treating every clarification as a full replacement" + instead: "append the new detail to existing text, preserve prior content" + + - epoch: 1783985662 + failcase: "idle during foreground subagent" + identifyBy: "ran research agent synchronously, did nothing while waiting" + instead: "run agents in background, continue editing other files" + + - epoch: 1783985662 + failcase: "guessed sim speed without research" + identifyBy: "accepted 360:1 then 3600:1 then 86400:1 without pushback" + instead: "research comparable systems before committing a number" + + - epoch: 1783985662 + failcase: "5 commits on one parameter" + identifyBy: "each clarification triggered a commit-push cycle" + instead: "accumulate related changes, commit once when stable" + + - epoch: 1783985662 + failcase: "never asked what economy organ was" + identifyBy: "wrote 8 wrong specs (text digestion) without asking" + instead: "ask what the thing is before designing it" +``` diff --git a/CLAUDE.md b/CLAUDE.md index 1338e05..fe4b010 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,5 +2,6 @@ Working agreements, build/run, and the invariants (S1/S2/S3) for sica-fondt now live in [`core/CLAUDE.md`](core/CLAUDE.md). This root file is only a pin. +Correction log: [`.claude/devCorrectionLog.md`](.claude/devCorrectionLog.md). @core/CLAUDE.md diff --git a/core/AGENTS.md b/core/AGENTS.md index b2b5a83..e040da3 100644 --- a/core/AGENTS.md +++ b/core/AGENTS.md @@ -1,7 +1,7 @@ # AGENTS.md — Ada border (D1) + invariant vault Local guide for `mafiabot_core`. Repo-wide map and rules: [`../AGENTS.md`](../AGENTS.md); -working agreements: [`../CLAUDE.md`](../CLAUDE.md). +working agreements: [`../CLAUDE.md`](../CLAUDE.md). Correction log: [`../.claude/devCorrectionLog.md`](../.claude/devCorrectionLog.md). ## What this is diff --git a/core/CLAUDE.md b/core/CLAUDE.md index d41de0b..16b4b4a 100644 --- a/core/CLAUDE.md +++ b/core/CLAUDE.md @@ -28,6 +28,12 @@ Per-unit commands and gotchas live in that unit's `AGENTS.md`. Toolchains (ponyc - **S2:** never reclassify a message's provenance. - **S3 / vault:** the COBOL invariant-law vault (Invariant 0, the culpability anchor; 01, "harm" "less";) is immutable at runtime — don't edit it unless explicitly directed and only as such. +## Subagents + +When spawning background agents (Haiku for research, etc.), **keep working on the main task while they run**. Don't wait idle — fold in results as they arrive, edit other files, or advance unrelated build steps. Background agents are cheap parallelism; wasting the main context window on waiting defeats the purpose. + +Correction log at `.claude/devCorrectionLog.md`. + ## Docs map - `README.md` — the project and its intent. diff --git a/core/docs/bus-topology.md b/core/docs/bus-topology.md index 6a1e06e..d65a725 100644 --- a/core/docs/bus-topology.md +++ b/core/docs/bus-topology.md @@ -84,4 +84,6 @@ blocking in a protected action), **tasks = workers** that call into the organs structure that isn't a lookup "store"? - **MoRAG / GoDAGRAG language** (Haskell vs Crystal vs other). - Each outer organ's hand-off shape to Ada. -- The stomach/economy organ's exact placement + which small model runs it. +- ~~The stomach/economy organ's exact placement + which small model runs it.~~ + **→ placed:** M-series (M0–M7) in `docs/plans/`. Outer organ on Ichor; data feeds via M2 (Data Feeds). + See M0 (hub), M6 (Conductor — orchestration, provenance chain, S1/S2 compliance). diff --git a/core/docs/plans/M0-economy-organ-hub.md b/core/docs/plans/M0-economy-organ-hub.md new file mode 100644 index 0000000..04cc588 --- /dev/null +++ b/core/docs/plans/M0-economy-organ-hub.md @@ -0,0 +1,76 @@ +# M0 — Economy organ hub (the stomach) + +## 1. Component +The economy organ — the organism's **stomach**. An **independent, self-governing system**: a +multi-agentic market prediction oracle and cryptocurrency trading engine. Houses the Marketplace +(M1), Data Feeds (M2), Sims (M3), Wallets (M4), Traders (M5), Conductor (M6), and SAE monitor +(M7). Communicates with the rest of the organism **via Ichor only** — reward signals back to the +organism are TBD and out of scope. + +"A stomach rarely consults a brain for permission to digest." The economy organ operates with +**scoped autonomy** and **multiple layers of failsafe braking** — it does not ask the organism's +Brain for permission to trade. + +## 2. Status / certainty +DESIGN-FIRST · ABSENT. A `Stomach` primitive exists in Ichor (`src/ichor/envelope.pony:20`) with +one smoke-test wire (`main.pony:29`), but no dedicated organ code. Role C4; implementation C1. + +## 3. Language & location +TBD · new location e.g. `src/economy/`. The organ is polyglot by nature: trading infrastructure +(APIs, wallets) may differ in language from simulations (numerical computing) and the conductor +(AI supervision). Pony actors provide the Ichor-facing facade. + +## 4. Does / does-not +- **Does:** host crypto/NFT trading via the Marketplace (M1); run always-on market prediction + Sims (M3) fed by live Data Feeds (M2); manage sovereign-custody Wallets (M4); supervise + Traders (M5) via a Conductor (M6); guard against anomalies via SAE monitor (M7); collect taxes + on trader income and stub transfer to Verschwörern Veregeister wallets; maintain a **ledger of + economy-related memories and patterns** (trade history, learned market patterns, calibration + state). +- **Does-not:** consult the organism's Brain for trade decisions (scoped autonomy); route around + Ada for organism-bound messages (S1); store **organism** memories (E*) — economy-specific + memories stay local; act as the organism's conscience (that's Eth-Int / A6). + +## 5. Interface contract +- **Ichor interface (outbound):** `Envelope(Stomach, AdaBorder, OrganSecretion, payload)` — market + state summaries, prediction digests, and tax receipts cross Ada to reach the inner brain. +- **Ichor interface (inbound):** organism directives arrive via Ichor (e.g. risk posture changes, + budget adjustments from A2 energy). +- **Internal wiring:** Marketplace (M1) ↔ Data Feeds (M2) ↔ Sims (M3). Wallets (M4) bind to + Traders (M5). Conductor (M6) supervises Traders (M5). SAE (M7) acts as an independent + antivirus / guarddog / alarm bell — monitors via Ichor-routed messages and alerts M6. + All trader actions route through Marketplace. +- **Tax stub:** `transfer_tax(amount, source_wallet, dest_wallet) -> receipt` — automation hook + for Verschwörern Veregeister internal wallet-to-wallet transfer. **Out of scope** — stub only. + +## 6. Dependencies & stubs +- Ichor bus (D2) — existing `Broker` + `Envelope`. +- Ada border (D1) — outbound economy envelopes cross here (S1); *stub:* Ichor `Barrier`. +- A2 energy — potential consumer of economic signals; *stub:* no integration initially. +- Verschwörern Veregeister wallets — tax destination; *stub:* log transfer, no real wallet. + +## 7. Invariants / laws +- **L1 (C5):** the stomach is an **OUTER** organ — it rides Ichor, never the inner bus. +- **L2 (C5):** **scoped autonomy** — the organ trades without Brain permission, but within + deterministic law constraints (M1) and Conductor oversight (M6). +- **L3 (C4):** **all market actions route through the Marketplace** (M1) — no trader may + execute directly on-chain without the Marketplace harness. +- **L4 (C4):** **sovereign custody only** — all wallets are local-hosted, our keys, never + delegated to exchanges or third parties (M4). +- **L5 (C4):** **multi-layered braking** — deterministic law script (M1), Conductor veto (M6), + SAE surveillance (M7), and wallet-level limits (M4) each independently constrain risk. + +## 8. Build steps +1. Build sub-components (M1–M7) individually — each with defined success criteria and ablative tests. +2. Extend the existing `Stomach` primitive in Ichor to carry the hub facade. +3. Define internal wiring topology and connect tested sub-components. +4. Implement tax stub and Verschwörern Veregeister transfer last. + +## 9. Tests +Hub smoke: Marketplace reachable; Sims running and queryable; Wallet bound to Trader; Conductor +receives SAE reports; tax stub logs transfer. Ichor: outbound envelope reaches Ada stub. + +## 10. Open items +- Reward signal protocol from economy organ to organism (TBD, out of scope). +- Internal communication bus (reuse Ichor internally? separate actor topology?). +- Language choices per sub-component. diff --git a/core/docs/plans/M1-marketplace.md b/core/docs/plans/M1-marketplace.md new file mode 100644 index 0000000..de91c84 --- /dev/null +++ b/core/docs/plans/M1-marketplace.md @@ -0,0 +1,79 @@ +# M1 — Marketplace (multi-trader harness) + +## 1. Component +The economy organ's trading floor: a **multi-trader harness** through which **all market actions +must route**. No trader may buy, sell, mint, or interact with any on-chain protocol except through +the Marketplace. Enforces a **deterministic law script** (scoped invariants — the marketplace's +own constitution) and integrates the **Conductor's veto** (M6) before execution. + +## 2. Status / certainty +DESIGN-FIRST · ABSENT. Role C4; implementation C1. + +## 3. Language & location +TBD · `src/economy/marketplace/`. Needs to interface with blockchain APIs (RPC/REST), wallet +signing (M4), and the Conductor (M6). Deterministic law script must be auditable and non-Turing +(no unbounded loops — it's a constitution, not a program). + +## 4. Does / does-not +- **Does:** receive trade requests from Traders (M5); validate against the deterministic law + script (scoped invariants); check Conductor veto (M6); verify trader-wallet binding (no wallet + = no access); execute approved actions on-chain via the bound wallet's API; record all actions + for SAE (M7) monitoring; collect tax on realized income → Verschwörern Veregeister stub (M0). +- **Does-not:** decide *what* to trade (Traders decide); predict markets (Sims do); hold keys + (Wallets do); supervise behavior (Conductor + SAE do). + +## 5. Interface contract +- `submit_action(trader_id, action: MarketAction, wallet_id) -> { succeeded | failed }`. + Diagnostic reasons (law violation, veto, missing wallet) are internal — routed to Conductor + (M6) for upstream output. Immune system is a separate organ (out of scope here). + `MarketAction` ∈ { `buy`, `sell`, `mint`, `provide_liquidity`, `withdraw_liquidity`, `claim_rewards`, … }. +- `law_check(action: MarketAction) -> { pass | violation(rule_id, reason) }` — deterministic, + pure function. The law script is loaded at startup and **immutable at runtime** (mirrors S3 / + the COBOL vault pattern). +- `veto_check(action: MarketAction, trader_id) -> { approved | vetoed(reason) }` — calls M6 + Conductor. +- `execute(action: MarketAction, wallet_id) -> { tx_hash | error }` — on-chain execution via + wallet API. +- `tax_event(trader_id, income_amount) -> receipt` — triggers tax collection. + +## 6. Dependencies & stubs +- M4 Wallets — signing + execution; *stub:* "if finished, would sign and broadcast tx [details]". +- M5 Traders — action source; *stub:* "if finished, would submit [action] for [asset] at [price]". +- M6 Conductor — veto authority; *stub:* "if finished, would evaluate [action] against risk policy; approving". +- M7 SAE — action log consumer; *stub:* "if finished, would analyze [action] for behavioral anomalies". +- Blockchain RPCs — on-chain execution; *stub:* "if finished, would execute [action] on [chain], returning tx_hash". + +## 7. Invariants / laws +- **L1 (C5):** **all market actions route through the Marketplace** — no direct on-chain + execution by any trader. This is the economy organ's S1. +- **L2 (C5):** the **deterministic law script is immutable at runtime** — loaded at startup, + never modified by traders, conductor, or sims. Changes require a restart with a new script + version **and a pair of signatures from the operator and the Homunculus**. Mirrors the COBOL + vault (S3). +- **L3 (C4):** **no wallet, no access** — a trader without a bound wallet cannot submit actions. + The Marketplace enforces this before any other check. +- **L4 (C4):** **veto is checked after law, before execution** — law violations are rejected + outright; Conductor veto applies only to law-passing actions. The law is above the Conductor. +- **L5 (C4):** **every action is logged** — SAE (M7) receives a record of every submitted + action (including rejected ones) for behavioral analysis. + +## 8. Build steps +1. Define `MarketAction` types and the law script format. +2. Implement the law checker (deterministic, pure, non-Turing). +3. Wire veto check to M6 Conductor. +4. Wire execution to M4 Wallet API. +5. Wire action logging to M7 SAE. +6. Implement tax collection on realized income. + +## 9. Tests +Law enforcement: known violations rejected; valid actions pass. Veto: conductor veto blocks +execution. Wallet binding: walletless trader rejected. Logging: every action (pass + fail) logged. +Tax: income event triggers tax stub. Immutability: law script cannot be modified at runtime. + +## 10. Open items +- The law script language/format (DSL? declarative rules? S-expressions?). +- Which blockchain protocols/RPCs to support initially. +- Position limits, drawdown stops, and other risk parameters — live in the law script or in the + Conductor's judgment? +- Tax rate / calculation method (fixed %, tiered, per-asset?). +- Non-Turing law script design — to discuss (format, expressiveness, bounds). diff --git a/core/docs/plans/M2-data-feeds.md b/core/docs/plans/M2-data-feeds.md new file mode 100644 index 0000000..dcde588 --- /dev/null +++ b/core/docs/plans/M2-data-feeds.md @@ -0,0 +1,70 @@ +# M2 — Data feeds (market data pipeline) + +## 1. Component +The economy organ's sensory nervous system: **live RSS feeds, price streams, and on-chain data** +flowing into both the Marketplace (M1) and the Sims (M3). Sits between them — the Marketplace +produces execution data (fills, positions, P&L) that feeds back into Sims, and Sims produce +predictions that inform Traders operating through the Marketplace. Data Feeds is the bridge. + +## 2. Status / certainty +DESIGN-FIRST · ABSENT. Role C3; implementation C1. + +## 3. Language & location +TBD · `src/economy/feeds/`. Needs async I/O for streaming data (WebSockets, SSE, RSS polling). +Pony actors are a natural fit (async, backpressure-aware). + +## 4. Does / does-not +- **Does:** ingest live market data from external sources (RSS, price APIs, DEX subgraphs, + on-chain event logs); normalize heterogeneous data into a common internal format; distribute + to Sims (M3) for prediction and to Traders (M5) for decision-making; ingest Marketplace (M1) + execution data (fills, portfolio state) and feed it back into Sims for calibration; maintain + time-series history within session (ring buffer). +- **Does-not:** predict (Sims do); trade (Marketplace does); filter or editorialize data — it + delivers raw, normalized feeds. Interpretation is the consumer's job. + +## 5. Interface contract +- `subscribe(feed_type: FeedType, consumer_id) -> subscription_handle`. + `FeedType` ∈ { `price_tick`, `rss_news`, `on_chain_event`, `dex_pool_state`, `execution_fill`, + `portfolio_state` }. +- `publish(feed_type, data_point: NormalizedDatum)` — internal; sources push into the pipeline. +- `query_history(feed_type, time_range) -> [NormalizedDatum]` — sims and traders can pull + historical data within the session window. +- `NormalizedDatum { feed_type, source, timestamp, payload, confidence }` — common shape. + `confidence` ∈ [0.0, 10.0] — data source reliability per position produced (exchange-reported + price = high; RSS sentiment = lower). Sims produce even finer-grained confidence. + +## 6. Dependencies & stubs +- External data sources (price APIs, RSS, RPC nodes) — *stub:* canned market data replay. +- M1 Marketplace — execution data source (fills, positions); *stub:* canned fills. +- M3 Sims — primary consumer; *stub:* print data points. +- M5 Traders — secondary consumer; *stub:* print data points. + +## 7. Invariants / laws +- **L1 (C4):** data feeds are **raw and unnormalized in meaning** — the pipeline normalizes + *format* (schema, timestamps, units) but never interprets, filters, or editorialize content. +- **L2 (C4):** **bidirectional flow** — external data flows in (market → sims/traders), and + internal execution data flows back (marketplace → sims). Both directions use the same + `NormalizedDatum` shape. +- **L3 (C3):** **backpressure, not drop** — if a consumer is slow, buffer up to a cap, then + apply backpressure to the source. Never silently drop data points. +- **L4 (C3):** every datum carries a **source and timestamp** — consumers can always trace + where data came from and when. + +## 8. Build steps +1. Define `NormalizedDatum` and `FeedType` shapes. +2. Implement the pub/sub pipeline (subscribe, publish, distribute). +3. Wire external source adapters (start with one price API + one RSS feed). +4. Wire M1 execution data feedback loop. +5. Implement session-scoped time-series history (ring buffer). + +## 9. Tests +Normalization: heterogeneous inputs produce uniform `NormalizedDatum` output. Pub/sub: subscriber +receives published data. History: query returns correct time range. Backpressure: slow consumer +does not cause data loss. Bidirectional: marketplace fills reach sims via the feed. + +## 10. Open items +- Which price APIs / RSS sources to support initially (CoinGecko? DeFiLlama? specific DEX + subgraphs?). +- History buffer size / eviction policy. +- Whether feeds need authentication / rate limiting management. +- Latency requirements (how fresh must data be for each consumer type?). diff --git a/core/docs/plans/M3-sims-hub.md b/core/docs/plans/M3-sims-hub.md new file mode 100644 index 0000000..67de9b6 --- /dev/null +++ b/core/docs/plans/M3-sims-hub.md @@ -0,0 +1,94 @@ +# M3 — Sims hub (market prediction simulations) + +## 1. Component +The economy organ's prediction engine: **always-running simulations** ("Sims") populated by +autonomous simulation agents ("Pops") that model market dynamics across multiple mathematical +domains and time scales. Sims are **queryable at any time** by Traders (M5) — they produce +**predictions with explicit upper and lower bounds** on every output value. This is the hub spec; +individual sim types have dedicated sub-specs (M3a–M3g). + +The academic foundations span AMM mechanism design [1,2], MEV game theory [3,4,5], macro +tokenomics via SDEs [6,7], and evolutionary consensus games [8–11]. + +## 2. Status / certainty +DESIGN-FIRST · ABSENT. Role C3; implementation C1. Mathematical foundations C4 (literature +established); specific model parameters C1. + +## 3. Language & location +TBD · `src/economy/sims/`. Numerical computing (Julia, Octave, Fortran, R, or Solidity) +for the simulation cores. A query facade accessible to Traders. Each sim type (M3a–M3g) may use +a different runtime suited to its math. + +## 4. Does / does-not +- **Does:** tick-advance continuously at **90:1** (1 wall-second = 90 simulated seconds) + across **six concurrent time horizons** — tick/hourly, daily, weekly, monthly, annual, and + 5-year forecast windows; every tick advances every sim; maintain populations of Pops whose + behaviors emerge from the sim's mathematical model; ingest live data from Data Feeds (M2) + for calibration; respond to Trader queries with bounded predictions; produce outputs with + **explicit upper/lower bounds** on every prediction value. + | Horizon | Window | Tick step | Effective ratio | Wall time for window | + |---------|--------|-----------|-----------------|---------------------| + | Tick–hourly | Next 1–60 min | 1s | 90:1 | ~40s | + | Daily | Next 24h | 24s | 2,160:1 | ~40s | + | Weekly | Next 7d | ~3 min | 15,120:1 | ~40s | + | Monthly | Next 30d | 12 min | 64,800:1 | ~40s | + | Annual | Next 365d | ~2.5 hr | ~788,000:1 | ~40s | + | 5-year | Next 1825d | 12 hr | ~3,942,000:1 | ~40s | +- **Does-not:** trade (Traders/Marketplace do); make decisions for traders (it informs, they + decide); enforce laws (Marketplace does); supervise behavior (Conductor/SAE do); skip ticks; + run slower than 90:1. + +## 5. Interface contract +- `query(sim_type: SimType, query: PredictionQuery) -> BoundedPrediction`. + `SimType` ∈ { `statistical`, `sociological`, `amm_liquidity`, `mev_adversarial`, + `tokenomics_macro`, `consensus_staking`, `market_microstructure` } (M3a–M3g). +- `BoundedPrediction { value, lower_bound, upper_bound, confidence, time_horizon, sim_type, timestamp }`. + Every output is bounded — no point estimates without uncertainty ranges. + `confidence` ∈ [0.00, 10.00] — printed as `7.62/10.00`. Gain rates print as + `lower - value - upper / 10.00` (e.g. `2.31 - 4.44 - 7.11 / 10.00 gain over next 30 days`); + the denominator aids legibility — gain is not capped at 10.00. + Example: `{ value: 7.2, lower_bound: 5.8, upper_bound: 8.9, confidence: 7.30, + time_horizon: "4h", sim_type: "amm_liquidity" }`. +- `status(sim_type?) -> { running, pop_count, last_calibration, data_freshness }` — health check. +- `calibrate(sim_type, feed_data: [NormalizedDatum])` — Data Feeds (M2) pushes live data for + model recalibration. + +## 6. Dependencies & stubs +- M2 Data Feeds — calibration data source; *stub:* canned market data. +- M5 Traders — query consumers; *stub:* canned queries. +- M3a–M3g sub-specs — individual sim implementations; *stub:* each returns fixed predictions. + +## 7. Invariants / laws +- **L1 (C5):** sims are **always running** — they are not invoked on demand. Traders query + current state; they don't trigger computation. +- **L2 (C5):** every prediction output includes **explicit upper and lower bounds** — no + unbounded point estimates. Uncertainty is a first-class value, not an afterthought. +- **L3 (C5):** all sims are **tick-advanced and continuous** — fine-grained ticks (RTS-style). + Base speed **90:1** (1s wall = 90s sim). Longer horizons run at higher velocity with coarser + steps and update less frequently. Each horizon completes its forecast window in **~40s wall + time**. Each horizon runs **in parallel** — they are concurrent, not sequential. No horizon + runs slower than 90:1. +- **L4 (C4):** sims are **read-only from traders' perspective** — a query never mutates sim + state. Calibration happens only from Data Feeds (M2). +- **L5 (C4):** each sim type is **independent** — failure in one sim does not cascade to others. + Degraded sims report their status; traders handle missing predictions. +- **L6 (C3):** Pops are **simulation constructs, not AI actors** — they follow mathematical + rules within the sim. Traders (M5) are the AI actors. + +## 8. Build steps +1. Define `BoundedPrediction` shape and query protocol. +2. Build the sim runner (lifecycle management for always-on sims). +3. Wire M2 Data Feeds → calibration pipeline. +4. Implement sub-specs M3a–M3g as they land. +5. Wire trader query interface. + +## 9. Tests +Always-on: sim running after init without external trigger. Bounded output: every prediction has +lower ≤ value ≤ upper. Query: trader receives prediction without mutating sim. Independence: +one sim's failure doesn't affect others. Calibration: new data updates model state. + +## 10. Open items +- Pop lifecycle (birth/death/mutation within sims, or fixed populations?). +- Cross-sim aggregation (do traders query individual sims, or is there a meta-prediction layer?). +- Calibration frequency per sim type. +- Computational budget per sim (how much CPU/GPU each can consume). diff --git a/core/docs/plans/M3a-statistical-sims.md b/core/docs/plans/M3a-statistical-sims.md new file mode 100644 index 0000000..d54c0e2 --- /dev/null +++ b/core/docs/plans/M3a-statistical-sims.md @@ -0,0 +1,110 @@ +# M3a — Statistical & quantitative sims + +## 1. Component +Pure statistical simulation: **Monte Carlo methods, Bayesian inference, time-series forecasting, +stochastic volatility, regime detection, and cross-asset correlation**. The mathematical backbone +— no game theory, no sociology, just the numbers. Operates across **six concurrent time horizons** +(tick/hourly → daily → weekly → monthly → annual → 5-year). Pops in this sim represent +**stochastic sample paths**, not behavioral agents. + +## 2. Status / certainty +DESIGN-FIRST · ABSENT. Core quant methods C5 (GBM, GARCH, ARIMA — textbook). Heston stochastic +volatility C5 (closed-form characteristic function; industry standard since 1993). Rough +volatility C4 (Gatheral et al. 2018, heavily cited; crypto implementations exist). HMM regime +detection C4 (established; crypto-specific copula hybrids emerging 2023–2024). Almgren-Chriss +execution C5 (industry standard since 2001). Jump-diffusion C5 (Merton 1976). Parameterization +for crypto markets C1. + +## 3. Language & location +TBD · `src/economy/sims/statistical/`. Julia, R, Fortran, or Octave for numerical computing. +Needs efficient matrix operations, SDE solvers, and distribution sampling. Fractional Brownian +motion generation uses spectral methods (Hosking 1984, Wood & Chan 1994) or Cholesky +decomposition of the covariance matrix. + +## 4. Does / does-not +- **Does:** run Monte Carlo price simulations (GBM, Merton jump-diffusion, Heston stochastic + volatility); model volatility surface via **Heston SDE**: + $dS_t = \mu S_t dt + \sqrt{\nu_t} S_t dW_t^S$, + $d\nu_t = \kappa(\theta - \nu_t)dt + \xi\sqrt{\nu_t} dW_t^\nu$ + with $\text{corr}(dW^S, dW^\nu) = \rho$ (mean-reversion speed $\kappa$, long-run variance + $\theta$, vol-of-vol $\xi$); model **rough volatility** via fractional Brownian motion + $dS_t = \mu dt + \sigma_t dB_t^H$ with Hurst exponent $H \approx 0.4$ capturing + antipersistent microstructure (Gatheral et al. 2018); detect **regime transitions** via + Hidden Markov Model: $r_t | s_t \sim \mathcal{N}(\mu_{s_t}, \sigma^2_{s_t})$, + $s_t \in \{\text{Bull, Neutral, Bear}\}$ with Viterbi filter updating in <5ms per tick; + model **cross-asset tail dependence** via DCC-GARCH copula hybrid: + $dQ_t/dt = a \cdot (\bar{S} - Q_t) + b \cdot (\varepsilon_t \varepsilon_t^T - Q_t)$ + with $t$-Copula for fat-tailed spillovers (BTC→alts); Bayesian parameter estimation from + live data (M2); time-series forecasting (ARIMA, GARCH for volatility clustering); Value-at-Risk + and Expected Shortfall; produce bounded predictions with confidence intervals. +- **Does-not:** model human behavior (M3b does); model protocol mechanics (M3c–M3f do); + trade or recommend (Traders do); optimize execution routing (M3g does using our vol estimates). + +## 5. Interface contract +- Implements `query(PredictionQuery) -> BoundedPrediction` per M3 hub. +- **Output bounds:** statistical confidence intervals (CI from Monte Carlo), Heston variance + bands (from $\nu_t$ process), rough-vol forecast cones, regime-conditional intervals. +- **Time-horizon mapping** (all run concurrently): + | Horizon | Primary models | Update cadence | + |---------|---------------|----------------| + | Tick–hourly | Rough vol ($H \approx 0.4$), HMM regime filter, realized variance | Every tick | + | Daily | Heston vol surface, GARCH, DCC correlation | Every bar close | + | Weekly–monthly | Jump-diffusion Monte Carlo, regime-conditional forecasts | Hourly roll | + | Annual–5yr | SDE mean-reversion long-run $\theta$, macro regime priors | Daily roll | +- Examples: + `{ value: 1847.30, lower_bound: 1790.15, upper_bound: 1905.60, confidence: 9.50, + time_horizon: "24h", sim_type: "statistical" }` — 95% CI on ETH price. + `{ value: 0.72, lower_bound: 0.58, upper_bound: 0.89, confidence: 9.00, + time_horizon: "1h", sim_type: "statistical" }` — Heston instantaneous vol $\sqrt{\nu_t}$. + `{ value: "bear", lower_bound: null, upper_bound: null, confidence: 8.30, + time_horizon: "current", sim_type: "statistical" }` — HMM regime state. +- **Prediction types:** `price_forecast`, `volatility_surface`, `var_calculation`, + `correlation_matrix`, `regime_state`, `rough_vol_estimate`, `jump_intensity`. +- Calibration: ingests `price_tick` and `dex_pool_state` from M2 Data Feeds. + +## 6. Dependencies & stubs +- M2 Data Feeds — price history for calibration; *stub:* canned price series. +- M3 Sims hub — lifecycle management; *stub:* manual init. + +## 7. Invariants / laws +- **L1 (C5):** bounds are **statistical confidence intervals** — derived from the model's + distribution, not hand-picked. Three distinct metrics in every output: **confidence** (how sure + the model is of this prediction), **correctness** (how accurate the model has been historically), + and **certainty** (how stable the estimate is across perturbations). All on the 0.00–10.00 scale. +- **L2 (C5):** **six time horizons run concurrently** — models span multiple horizons (e.g. + Monte Carlo runs daily and annual, rough vol runs tick and hourly, Heston runs daily and + weekly). All coexist; none blocks the others. +- **L3 (C4):** model parameters are **re-estimated on each calibration** from live data — no + stale parameters carried across regime changes. Regime transitions trigger immediate + re-estimation of conditional parameters. +- **L4 (C4):** the **Heston correlation $\rho$ between price and vol** is a fitted parameter, + never assumed — crypto assets exhibit leverage effects different from equities. +- **L5 (C4):** rough volatility Hurst exponent $H$ is **estimated from realized variance**, not + fixed — $H$ varies across assets and regimes (Gatheral et al. 2018). + +## 8. Build steps +1. Implement geometric Brownian motion Monte Carlo (simplest price sim). +2. Add GARCH volatility estimation. +3. Implement Heston SDE solver (Euler-Maruyama with full truncation for $\nu_t \geq 0$). +4. Add Merton jump-diffusion (Poisson jumps + GBM). +5. Implement rough volatility via fractional BM with rolling Hurst estimator. +6. Implement HMM regime detector (3-state Viterbi filter). +7. Add DCC-GARCH copula for cross-asset correlation. +8. Wire M2 price data → Bayesian parameter re-estimation. +9. Implement multi-horizon `BoundedPrediction` output with CIs. + +## 9. Tests +Monte Carlo: N sample paths produce a distribution with correct mean/variance. CI: 95% interval +contains true value ≥ 95% of the time on historical backtest. GARCH: volatility clusters detected +in synthetic data. Heston: implied vol smile reproduced for known parameters. Rough vol: Hurst +exponent recovered from synthetic fBM paths. HMM: regime transitions detected within 15–60s on +synthetic regime-switching data. Copula: tail dependence captured (BTC crash → alt crash +correlation spike). Jump-diffusion: fat tails reproduced. Calibration: new data shifts parameter +estimates. Multi-horizon: all six horizons produce concurrent outputs. + +## 10. Open items +- Heston calibration method (characteristic function inversion? particle filter?). +- Rough vol computational cost (fBM generation is O(N²) naively; FFT methods needed). +- HMM state count (3 sufficient? 4+ for crypto with "mania" regime?). +- Which copula family for tail dependence ($t$-copula? Clayton? Joe?). +- Computational budget per horizon (GPU for Monte Carlo paths?). diff --git a/core/docs/plans/M3b-sociological-sims.md b/core/docs/plans/M3b-sociological-sims.md new file mode 100644 index 0000000..f2e17c8 --- /dev/null +++ b/core/docs/plans/M3b-sociological-sims.md @@ -0,0 +1,121 @@ +# M3b — Sociological & population dynamics sims + +## 1. Component +Sociological simulation: **evolutionary game theory, bounded rationality, opinion dynamics, +complex contagion, adaptive learning populations, and Mean-Field Game equilibria** among market +participants. Pops here are **behavioral archetypes** — retail herd followers, contrarian whales, +MEV searchers, passive LPs, pump-and-dump manipulators — whose strategies evolve under selection +pressure across **six concurrent time horizons**. Grounded in evolutionary consensus game models +[8,9], Hegselmann-Krause opinion dynamics (2002), complex contagion theory (Centola & Macy 2007), +MFG theory (Lasry & Lions 2007), and crypto manipulation ABMs. + +## 2. Status / certainty +DESIGN-FIRST · ABSENT. Evolutionary game theory C4 (Cornell [8]). Hegselmann-Krause bounded +confidence C5 (established 2002). Complex contagion C4 (Centola & Macy 2007; crypto applications +C3). Bandit-replicator hybrid C3 (emerging). Mean-Field Games C4 (Lasry & Lions 2007; tensor-train +solvers C3). Crypto pump-and-dump ABM C3 (3-agent protocol validated on historical data). +Pop behavioral models C1. + +## 3. Language & location +TBD · `src/economy/sims/sociological/`. Agent-based modeling frameworks (NetLogo, or custom). +Needs efficient population iteration, strategy mutation, PDE solvers for MFG (HJB + +Fokker-Planck), and bandit algorithms (UCB/Thompson). Julia, R, or Fortran. + +## 4. Does / does-not +- **Does:** simulate populations of behavioral archetypes competing in a market; apply + **replicator dynamics** $dx_i/dt = x_i(\pi_i(x) - \bar{\pi}(x))$ to strategy distributions; + model **opinion clustering** via Hegselmann-Krause bounded confidence: + $x_i(t+1) = x_i(t) + \mu(x_j(t) - x_i(t))$ for $|x_i - x_j| \leq d$ — agents only update + toward neighbors within confidence bound $d$, creating natural clustering and trend-reversal + thresholds; model **complex contagion** with heterogeneous thresholds: adoption probability + $P_i = f(n_i / k_i)$ where multiple exposures amplify adoption non-linearly (captures meme-coin + rallies and narrative-driven pumps); implement **bandit-replicator hybrid** where pops use + UCB or Thompson Sampling to estimate strategy payoffs: + $x_i'(t) = x_i(t)[\lambda_i(t) - \bar{\lambda}(t)]$ with $\lambda_i = \text{UCB}(\theta_i)$ + — bridges replicator dynamics with multi-armed bandit learning; solve **Mean-Field Game + equilibria** via coupled HJB + Fokker-Planck PDEs for large-population limits: + $-\partial_t u + H(x, \nabla u) = F(x, m)$ (HJB, individual optimization), + $\partial_t m - \nabla \cdot (m \nabla_p H) = 0$ (Fokker-Planck, population density) — Newton + iteration with tensor-train decomposition reduces $O(N^d)$ to $O(dNr^2)$ for high-dimensional + state spaces; simulate **crypto pump-and-dump protocol** with 3 pop types: Normal traders, + Market Analysts (MA, information-advantaged), Market Players (MP, manipulators) in a 4-phase + cycle (accumulation → promotion → distribution → collapse); model sentiment cascades + (fear/greed contagion across pop clusters); model bounded rationality (pops satisfice, not + optimize — heuristics, not perfect strategies); produce bounded predictions across all six + time horizons. +- **Does-not:** model protocol mechanics (M3c–M3f); compute statistical forecasts (M3a); + represent real individuals (pops are archetypes, not profiles). + +## 5. Interface contract +- Implements `query(PredictionQuery) -> BoundedPrediction` per M3 hub. +- **Output bounds:** population-fraction ranges, sentiment scales, MFG equilibrium stability. +- **Time-horizon mapping** (all run concurrently): + | Horizon | Primary models | Update cadence | + |---------|---------------|----------------| + | Hourly | Hegselmann-Krause opinion clusters, bandit-replicator | Every data tick | + | Daily | Complex contagion cascades, pump-and-dump phase detection | Hourly roll | + | Weekly | Replicator dynamics strategy evolution, MFG equilibrium | Daily roll | + | Monthly | Population archetype composition, narrative regime shifts | Weekly roll | + | Annual | Long-run evolutionary stable strategies (ESS) | Monthly roll | + | 5-year | MFG stationary equilibria, structural population shifts | Quarterly roll | +- Examples: + `{ value: 7.3, lower_bound: 5.0, upper_bound: 9.1, confidence: 6.80, + time_horizon: "12h", sim_type: "sociological" }` — herd-panic index (0–10). + `{ value: 0.42, lower_bound: 0.31, upper_bound: 0.55, confidence: 7.20, + time_horizon: "1w", sim_type: "sociological" }` — fraction of pops in "contrarian" strategy. + `{ value: "promotion", lower_bound: null, upper_bound: null, confidence: 6.10, + time_horizon: "current", sim_type: "sociological" }` — pump-and-dump phase detection. + `{ value: 0.78, lower_bound: 0.65, upper_bound: 0.88, confidence: 7.00, + time_horizon: "30d", sim_type: "sociological" }` — MFG equilibrium stability index. + Models span multiple horizons — e.g. replicator dynamics runs hourly through annual; MFG + produces weekly equilibria and 5-year stationary states. The table shows primary assignments. +- **Prediction types:** `sentiment_index`, `herd_threshold`, `strategy_distribution`, + `cascade_probability`, `coordination_stability`, `opinion_cluster_count`, + `pump_dump_phase`, `mfg_equilibrium_stability`, `narrative_regime`. +- Calibration: ingests `rss_news` (sentiment signal) and `price_tick` (realized behavior) from M2. + +## 6. Dependencies & stubs +- M2 Data Feeds — sentiment and price data for calibration; *stub:* canned sentiment series. +- M3 Sims hub — lifecycle management; *stub:* manual init. + +## 7. Invariants / laws +- **L1 (C5):** pops are **archetypes, not individuals** — no attempt to model or track real + market participants. The sim models emergent behavior from strategy populations. +- **L2 (C5):** strategies **evolve** — the population distribution shifts over time via + replicator dynamics. No fixed strategy ratios. +- **L3 (C4):** bounded rationality is the **default** — pops satisfice with heuristics, not + optimize with perfect information. Rational-agent models are a special case, not the baseline. +- **L4 (C4):** **complex contagion requires multiple exposures** — adoption is non-linear in + neighbor count, not simple diffusion. Single-exposure models undercount threshold effects. +- **L5 (C4):** the MFG limit is **valid only for large populations** — below ~100 pops, use + discrete replicator dynamics; above, the continuum HJB+FP approximation applies. +- **L6 (C3):** pump-and-dump detection is **phase-based** — the 4-phase cycle (accumulate → + promote → distribute → collapse) has distinct statistical signatures in volume and price. + +## 8. Build steps +1. Define pop archetypes and their heuristic strategies. +2. Implement replicator dynamics (strategy evolution over generations). +3. Implement Hegselmann-Krause bounded confidence opinion model. +4. Implement complex contagion with heterogeneous thresholds. +5. Implement bandit-replicator hybrid (UCB payoff estimation + replicator selection). +6. Implement MFG solver (HJB + Fokker-Planck with Newton iteration). +7. Implement pump-and-dump 3-type ABM (Normal, MA, MP) with 4-phase protocol. +8. Wire M2 news/price data → calibration of pop parameters. +9. Implement multi-horizon `BoundedPrediction` output. + +## 9. Tests +Evolution: dominant strategy shifts when payoff landscape changes. Cascade: sentiment shock +propagates through pop network above threshold, not below. Bounded confidence: opinion clusters +form at predicted cluster count for given $d$. Complex contagion: multiple-exposure requirement +produces slower but more robust adoption than simple contagion. Bandit: explore-exploit tradeoff +produces adapting populations. MFG: equilibrium converges for large N; matches discrete sim for +small N. Pump-dump: 4-phase cycle detected on synthetic manipulation data. Bounds: all outputs +include upper/lower. + +## 10. Open items +- Pop archetype catalog (which behavioral types? how many?). +- Network topology for sentiment contagion (small-world? scale-free?). +- Calibration from real market data — how to infer pop distribution from observable price action. +- MFG tensor-train rank $r$ (accuracy vs. compute tradeoff). +- Hegselmann-Krause confidence bound $d$ — fixed or adaptive? +- Cross-sim interaction: do sociological predictions feed into M3c (AMM) or M3d (MEV)? diff --git a/core/docs/plans/M3c-amm-liquidity-sims.md b/core/docs/plans/M3c-amm-liquidity-sims.md new file mode 100644 index 0000000..e91701b --- /dev/null +++ b/core/docs/plans/M3c-amm-liquidity-sims.md @@ -0,0 +1,76 @@ +# M3c — AMM & liquidity pool sims + +## 1. Component +Automated Market Maker simulation: models **constant-product invariant mechanics, impermanent +loss, and the non-cooperative game between liquidity providers and arbitrageurs**. Pops here are +**LP positions and arbitrage bots** operating on the $x \cdot y = k$ curve. Grounded in the DEX/AMM +literature [1,2]. + +## 2. Status / certainty +DESIGN-FIRST · ABSENT. Mathematical foundations C5 (constant product invariant is proven); +impermanent loss formula C5 (closed-form: $\text{IL}(r) = \frac{2\sqrt{r}}{1+r} - 1$); +simulation parameterization C1. + +## 3. Language & location +TBD · `src/economy/sims/amm/`. Needs precise fixed-point or arbitrary-precision arithmetic for +invariant calculations. Solidity for on-chain-equivalent precision; Julia or Octave for +analytical models. + +## 4. Does / does-not +- **Does:** simulate constant-product pools with fee parameter $\gamma$: + $(x + \gamma \Delta x)(y - \Delta y) = k$; model impermanent loss as a function of price ratio + shift $r$; simulate LP strategies (provide, withdraw, rebalance) against arbitrageur behavior; + model non-linear price slippage from the curve geometry; produce bounded predictions on pool + profitability, IL risk, and optimal LP ranges. +- **Does-not:** model consensus mechanics (M3f); model social behavior (M3b); execute real swaps + (Marketplace does). + +## 5. Interface contract +- Implements `query(PredictionQuery) -> BoundedPrediction` per M3 hub. +- **Output bounds:** IL ranges and pool return intervals. + Example: `{ value: -0.034, lower_bound: -0.058, upper_bound: -0.012, confidence: 9.00, + time_horizon: "7d", sim_type: "amm_liquidity" }` — projected impermanent loss for ETH/USDC pool. + Example: `{ value: 0.082, lower_bound: 0.041, upper_bound: 0.127, confidence: 8.50, + time_horizon: "30d", sim_type: "amm_liquidity" }` — net LP return (fees − IL). +- **Time-horizon mapping** (all run concurrently, tick-advanced, 90:1 (1s wall = 90s sim)): + | Horizon | Primary models | Update cadence | + |---------|---------------|----------------| + | Tick–hourly | Slippage curves, invariant state, JIT liquidity | Every swap event | + | Daily | IL accumulation, fee income, LP profitability | Hourly roll | + | Weekly | Optimal LP range recalculation, pool composition | Daily roll | + | Monthly | LP strategy evolution (passive vs. active rebalance) | Weekly roll | + | Annual | Pool lifecycle, fee tier competitiveness | Monthly roll | + | 5-year | AMM design evolution, concentrated liquidity adoption | Quarterly roll | +- **Prediction types:** `impermanent_loss`, `pool_return`, `optimal_range`, `slippage_estimate`, + `lp_withdrawal_threshold`. +- Calibration: ingests `dex_pool_state` and `price_tick` from M2. + +## 6. Dependencies & stubs +- M2 Data Feeds — pool state and price data; *stub:* canned pool snapshots. +- M3 Sims hub — lifecycle management; *stub:* manual init. + +## 7. Invariants / laws +- **L1 (C5):** the **constant product invariant** $x \cdot y = k$ (adjusted for fees $\gamma$) + is the ground truth — all pool state transitions must satisfy the invariant or the sim is wrong. +- **L2 (C5):** **impermanent loss** follows the proven formula + $\text{IL}(r) = \frac{2\sqrt{r}}{1+r} - 1$ — the sim must reproduce this exactly for the + base case (no fees, no concentrated liquidity). +- **L3 (C4):** LP withdrawal thresholds are **derived from IL, not hardcoded** — the sim + calculates at what price ratio a rational LP withdraws, based on the IL formula and fee income. + +## 8. Build steps +1. Implement the constant-product pool simulator with fee parameter. +2. Verify IL formula reproduction against known inputs. +3. Add LP pop strategies (passive hold, active rebalance, just-in-time liquidity). +4. Add arbitrageur pops (sandwich, backrun). +5. Wire M2 pool state data → calibration. + +## 9. Tests +Invariant: every swap satisfies $(x + \gamma \Delta x)(y - \Delta y) = k$. IL formula: matches +closed-form for known price ratios. Slippage: large swaps produce greater slippage than small. +LP threshold: LP withdraws when IL exceeds fee income. Bounds: all outputs bounded. + +## 10. Open items +- Concentrated liquidity (Uniswap v3 style) — extends the base model significantly. +- Multi-pool routing (split swaps across pools). +- Which specific pools to simulate (ETH/USDC? stablecoin pairs?). diff --git a/core/docs/plans/M3d-mev-adversarial-sims.md b/core/docs/plans/M3d-mev-adversarial-sims.md new file mode 100644 index 0000000..08c395c --- /dev/null +++ b/core/docs/plans/M3d-mev-adversarial-sims.md @@ -0,0 +1,114 @@ +# M3d — MEV & adversarial extraction sims + +## 1. Component +Maximal Extractable Value and adversarial simulation: models **transaction ordering as an +optimization problem**, **Priority Gas Auctions (PGA) as all-pay auctions**, **block building as a +multidimensional knapsack problem**, **cross-chain adversarial arbitrage**, and **Dynamic +Stackelberg Mean-Field Games (DSMFG) for protocol-level adversarial policy**. Pops here are +**searcher bots, block builders, validators, cross-chain arbitrageurs, and adversarial +manipulators** competing for extractable value across **six concurrent time horizons**. + +Grounded in ACM MEV game theory [3], knapsack auction literature [4,5], Kolokoltsov adversarial +dynamics (non-linear Fokker-Planck with WENO shock capturing), and DSMFG bilevel optimization +(leader policy + follower MFG equilibrium). + +## 2. Status / certainty +DESIGN-FIRST · ABSENT. PGA-as-all-pay-auction C4 (ACM [3]); knapsack formulation C4 (Cornell +[4,5]); cross-chain arbitrage C4 (ACM SIGMETRICS 2025, 5.5x growth since Dencun); DSMFG bilevel +optimization C3 (emerging — SMFRL solvers); Kolokoltsov adversarial C3 (non-linear Fokker-Planck; +WENO discretization established but crypto application novel). Parameterization C1. + +## 3. Language & location +TBD · `src/economy/sims/mev/`. Needs combinatorial optimization (OR-Tools for knapsack), +continuous-time auction modeling, PDE solvers (WENO for shock-capturing in adversarial dynamics), +and bilevel optimization (DSMFG). Julia or Fortran. + +## 4. Does / does-not +- **Does:** simulate Priority Gas Auctions where multiple searcher bots compete for the same + arbitrage opportunity $V$ by bidding gas fees $g$ in a continuous-time all-pay auction; model + block building as a multidimensional knapsack problem (scarce block space, heterogeneous + transaction values/sizes); simulate endogenous selection cutoffs under paid-priority ordering; + model **cross-chain adversarial arbitrage** with inventory vs. bridge execution trade-off: + $\pi_{\text{inv}} = (P_{\text{src}} - P_{\text{dst}} - \text{slippage} - \text{gas}) \times q$ + vs. $\pi_{\text{bridge}} = (P_{\text{src}} - P_{\text{dst}} - \text{fee} - + \text{depreciation}(\Delta t)) \times q$ where bridge latency $\Delta t \approx 242$s vs. + inventory $\Delta t \approx 9$s; solve **Dynamic Stackelberg MFG** for adversarial policy + design — bilevel optimization where a leader (protocol/regulator) sets policy and followers + (searchers) respond as an MFG equilibrium: the leader solves + $\min_\alpha J_L(\alpha, m^*(\alpha))$ subject to $m^*(\alpha)$ being the MFG Nash equilibrium + of followers under policy $\alpha$; model **Kolokoltsov adversarial dynamics** via non-linear + Fokker-Planck: $\partial_t m + \nabla \cdot (b(x,m)m) = \frac{1}{2}\nabla^2(\sigma^2 m)$ + with WENO shock-capturing for discontinuous adversarial strategies; predict MEV exposure for + proposed trades; produce bounded predictions on extraction risk across all six time horizons. +- **Does-not:** extract MEV itself (simulator, not a searcher); model AMM pool math (M3c); + model social dynamics (M3b); execute cross-chain bridges (Marketplace does). + +## 5. Interface contract +- Implements `query(PredictionQuery) -> BoundedPrediction` per M3 hub. +- **Output bounds:** extraction probability ranges, gas cost intervals, cross-chain profit + bounds, DSMFG equilibrium stability ranges. +- **Time-horizon mapping** (all run concurrently, tick-advanced, 90:1 (1s wall = 90s sim)): + | Horizon | Primary models | Update cadence | + |---------|---------------|----------------| + | Tick–hourly | PGA auctions, sandwich detection, cross-chain arb | Every block | + | Daily | Knapsack builder strategies, MEV landscape | Hourly roll | + | Weekly | Searcher population dynamics, cross-chain flow patterns | Daily roll | + | Monthly | DSMFG policy equilibria, adversarial strategy evolution | Weekly roll | + | Annual | Kolokoltsov adversarial long-run dynamics | Monthly roll | + | 5-year | Structural MEV regime shifts, protocol-level policy effects | Quarterly roll | +- Examples: + `{ value: 0.23, lower_bound: 0.11, upper_bound: 0.38, confidence: 8.00, + time_horizon: "next_block", sim_type: "mev_adversarial" }` — sandwich probability. + `{ value: 14.7, lower_bound: 8.2, upper_bound: 22.5, confidence: 7.50, + time_horizon: "next_block", sim_type: "mev_adversarial" }` — optimal gas bid (gwei). + `{ value: 0.034, lower_bound: 0.018, upper_bound: 0.052, confidence: 8.20, + time_horizon: "1h", sim_type: "mev_adversarial" }` — cross-chain arb profit (ETH). +- **Prediction types:** `sandwich_probability`, `frontrun_risk`, `optimal_gas_bid`, + `block_inclusion_probability`, `mev_exposure`, `cross_chain_arb_profit`, + `adversarial_policy_stability`, `searcher_population_shift`. +- Calibration: ingests `on_chain_event` (mempool-like data), `price_tick`, and cross-chain + bridge state from M2. + +## 6. Dependencies & stubs +- M2 Data Feeds — on-chain events, gas data, cross-chain state; *stub:* canned snapshots. +- M3 Sims hub — lifecycle management; *stub:* manual init. +- M3c AMM sims — pool state for arbitrage opportunity detection; *stub:* fixed pool state. + +## 7. Invariants / laws +- **L1 (C5):** PGA is modeled as an **all-pay auction** — all bidders pay their gas whether they + win or not. The sim must capture this cost structure (not winner-pays-only). +- **L2 (C5):** block building is a **knapsack problem, not a queue** — builders optimize for + total extracted value subject to gas limit constraints, not first-come-first-served. +- **L3 (C4):** MEV exposure predictions are **pre-trade** — traders query this sim *before* + submitting to the Marketplace to understand their extraction risk. +- **L4 (C4):** cross-chain arb models **both execution paths** — inventory (fast, capital- + intensive) and bridge (slow, capital-light) — never assumes one dominates. +- **L5 (C3):** DSMFG solutions are **bilevel** — the leader's optimal policy depends on the + followers' MFG equilibrium, which itself depends on the leader's policy. Fixed-point iteration + or SMFRL solvers required. + +## 8. Build steps +1. Implement the PGA all-pay auction model (N searchers, opportunity value V, gas bids). +2. Implement the block-building knapsack solver. +3. Add sandwich/frontrun detection heuristics. +4. Implement cross-chain arb model (inventory vs. bridge, latency, MEV exposure). +5. Implement Kolokoltsov non-linear Fokker-Planck with WENO discretization. +6. Implement DSMFG bilevel solver (leader policy + follower MFG equilibrium). +7. Wire M2 on-chain + cross-chain data → calibration. +8. Wire pre-trade query interface for Traders. + +## 9. Tests +All-pay: losing bidders still pay gas cost. Knapsack: builder selects optimal transaction set +under gas limit. Sandwich: known sandwich-vulnerable trade flagged; non-vulnerable trade clear. +Cross-chain: inventory path preferred when latency advantage exceeds capital cost. DSMFG: leader +policy converges to fixed point with follower equilibrium. Kolokoltsov: WENO captures shock +discontinuities in adversarial strategy distribution. Bounds: all outputs bounded. Pre-trade: +query does not submit any transaction. Speed: sim tick-advances at 90:1. + +## 10. Open items +- Mempool data access (public mempool? private order flow?). +- Which MEV types to model initially (sandwich, backrun, liquidation, JIT?). +- Multi-block MEV (cross-block extraction strategies). +- DSMFG solver choice (SMFRL? fictitious play? direct bilevel optimization?). +- WENO order for Kolokoltsov (3rd? 5th? tradeoff with compute budget). +- Which L2s/bridges to model for cross-chain (Arbitrum? Optimism? Base?). diff --git a/core/docs/plans/M3e-tokenomics-macro-sims.md b/core/docs/plans/M3e-tokenomics-macro-sims.md new file mode 100644 index 0000000..35e80f6 --- /dev/null +++ b/core/docs/plans/M3e-tokenomics-macro-sims.md @@ -0,0 +1,118 @@ +# M3e — Tokenomics & macro-state sims + +## 1. Component +Macro-level token economy simulation: models **token supply dynamics, monetary policy (halvings, +burns, inflation), lending protocol dynamics, DeFi systemic risk, and stock-flow balances** using +stochastic differential equations (SDEs), state-space models, kinked interest rate curves, and +inter-protocol credit exposure networks. Pops here are **aggregate behavioral cohorts** +(miners/validators, holders, speculators, protocol treasuries, borrowers/lenders) whose collective +behavior drives token-level dynamics across **six concurrent time horizons** at tick-advanced, 90:1 (1s wall = 90s sim). + +Grounded in Vienna complex-systems token modeling [7], ResearchGate engineering token economy +frameworks [6], Aave/Compound kinked interest rate models (industry standard), and DeXposure +inter-protocol credit propagation (Matzakos et al. 2025). + +## 2. Status / certainty +DESIGN-FIRST · ABSENT. SDE state-space framework C4 (Vienna [7]); stock-flow modeling C4 +(ResearchGate [6]); kinked interest rate model C5 (Aave/Compound production standard); +DeXposure inter-protocol credit propagation C3 (emerging, 2025 — high DeFi specificity); +composable yield optimization C4 (Yearn v3, Beefy, production-validated). Specific parameters C1. + +## 3. Language & location +TBD · `src/economy/sims/tokenomics/`. Needs SDE solvers (Euler-Maruyama, Milstein), +state-space estimation, and VAR (vector autoregression) for credit exposure impulse responses. +Julia (DifferentialEquations.jl) or Octave. + +## 4. Does / does-not +- **Does:** simulate token state dynamics via the SDE framework: + $dX_t = f(X_t, u(X_t, t), t)dt + \sigma(X_t, t)dW_t$ where $X_t$ is the system state vector, + $u$ is the behavioral policy function, deterministic drift captures programmatic parameters + (halvings, burns), and Brownian motion $\sigma dW_t$ captures stochastic behavioral shocks; + model stock-flow balances (circulating supply, staked, locked, burned); simulate monetary + policy impacts (halving events, fee burns, treasury emissions); model **lending protocol + dynamics** via kinked interest rate curves: + $R = R_0 + R_{\text{slope1}} \times U$ if $U \leq U_{\text{opt}}$, + $R = R_0 + R_{\text{slope1}} \times U_{\text{opt}} + R_{\text{slope2}} \times + (U - U_{\text{opt}})$ if $U > U_{\text{opt}}$ where $U = \text{Borrowed}/(\text{Supplied} + + \text{Borrowed})$, $U_{\text{opt}} \approx 0.8$ — cascade liquidations when + $\text{collateral} \times \text{LTV} < \text{borrowed}$; model **DeFi systemic risk** via + DeXposure inter-protocol credit propagation: + $E_{ij}(t) = \sum_{\text{tokens}} [\text{TVL}_j(\text{token}) \times + \text{ownership}_i(\text{token})]$ with VAR impulse responses for shock contagion across + protocols sharing collateral; model **composable yield optimization**: + $\max \sum_i w_i(t) \cdot \text{APY}_i(t) - \lambda \sum_i w_i(t)^2 \sigma_i^2(t)$ + subject to $\sum_i w_i = 1$ — dynamic rebalancing across lending, LP, and staking strategies; + produce bounded predictions on token supply, protocol health, yield, and systemic risk. +- **Does-not:** model individual transactions (M3c/M3d); model social sentiment (M3b); + model consensus mechanics (M3f); execute yield strategies (Traders/Marketplace do). + +## 5. Interface contract +- Implements `query(PredictionQuery) -> BoundedPrediction` per M3 hub. +- **Output bounds:** SDE confidence bands, utilization rate ranges, contagion impact intervals. +- **Time-horizon mapping** (all run concurrently, tick-advanced, 90:1 (1s wall = 90s sim)): + | Horizon | Primary models | Update cadence | + |---------|---------------|----------------| + | Hourly | Lending rates, utilization, liquidation risk | Every block | + | Daily | Yield optimization, protocol TVL flows | Hourly roll | + | Weekly | SDE supply trajectory, stock-flow balances | Daily roll | + | Monthly | DeXposure credit contagion, systemic risk | Weekly roll | + | Annual | Halving/burn policy impacts, inflation trajectory | Monthly roll | + | 5-year | Token supply long-run equilibrium, protocol lifecycle | Quarterly roll | +- Examples: + `{ value: 2.1, lower_bound: 1.4, upper_bound: 3.2, confidence: 9.00, + time_horizon: "90d", sim_type: "tokenomics_macro" }` — annualized inflation rate (%). + `{ value: 0.67, lower_bound: 0.58, upper_bound: 0.74, confidence: 8.50, + time_horizon: "30d", sim_type: "tokenomics_macro" }` — staking ratio. + `{ value: 0.83, lower_bound: 0.78, upper_bound: 0.91, confidence: 8.80, + time_horizon: "1h", sim_type: "tokenomics_macro" }` — Aave ETH utilization rate. + `{ value: 0.12, lower_bound: 0.04, upper_bound: 0.25, confidence: 7.20, + time_horizon: "7d", sim_type: "tokenomics_macro" }` — systemic contagion risk index. +- **Prediction types:** `supply_trajectory`, `inflation_rate`, `staking_ratio`, + `velocity_estimate`, `halving_impact`, `treasury_runway`, `utilization_rate`, + `liquidation_cascade_risk`, `systemic_contagion_index`, `optimal_yield_allocation`. +- Calibration: ingests `on_chain_event` (supply metrics, staking data, lending protocol state, + TVL) from M2. + +## 6. Dependencies & stubs +- M2 Data Feeds — on-chain supply/staking/lending data; *stub:* canned supply snapshots. +- M3 Sims hub — lifecycle management; *stub:* manual init. + +## 7. Invariants / laws +- **L1 (C5):** the SDE framework is the **canonical representation** — all token dynamics are + expressed as drift + diffusion. Deterministic policy (halvings, burns) lives in the drift $f$; + behavioral uncertainty lives in the diffusion $\sigma dW_t$. +- **L2 (C5):** **stock-flow conservation** — tokens are never created or destroyed outside the + protocol's defined mechanisms. circulating + staked + locked + burned = total ever minted. +- **L3 (C5):** lending rate curves are **kinked at $U_{\text{opt}}$** — the steep slope above + optimal utilization is a design invariant of Aave/Compound, not a parameter to smooth. +- **L4 (C4):** macro sims operate on **aggregate cohorts, not individuals** — the state vector + $X_t$ tracks population-level quantities (total staked, total circulating), not per-wallet. +- **L5 (C4):** DeXposure contagion is **directional** — protocol A's exposure to protocol B + is not symmetric. The exposure matrix $E_{ij}$ is not assumed symmetric. + +## 8. Build steps +1. Implement Euler-Maruyama SDE solver for a simple token model (supply + staking). +2. Define the state vector $X_t$ and drift/diffusion functions for a reference token. +3. Add stock-flow accounting (verify conservation). +4. Implement kinked lending rate model (Aave-style) with liquidation cascade simulation. +5. Implement DeXposure credit propagation network with VAR impulse responses. +6. Implement composable yield optimizer (risk-adjusted return maximization). +7. Wire M2 on-chain data → state estimation / calibration. +8. Add monetary policy events (halving, burn) as drift discontinuities. + +## 9. Tests +SDE: sample paths have correct mean (matches drift) and variance (matches diffusion). Stock-flow: +conservation holds across all time steps. Halving: supply growth rate drops at halving event. +Lending: rate curve exhibits kink at $U_{\text{opt}}$; liquidation cascades triggered when +collateral ratio breached. DeXposure: shock to protocol A propagates to protocol B through shared +collateral; isolated protocols unaffected. Yield: optimizer rebalances toward highest risk-adjusted +APY. Calibration: state estimate converges to observed data. Bounds: SDE confidence bands cover +realized paths on backtest. Speed: sim tick-advances at 90:1. + +## 10. Open items +- Which tokens to model initially (ETH? BTC? a specific alt?). +- State vector dimensionality (how many state variables per token model?). +- Behavioral policy function $u(X_t, t)$ — how to parameterize aggregate cohort behavior. +- Multi-token interactions (correlated diffusions across tokens?). +- DeXposure graph granularity (how many protocols? top-10 by TVL?). +- Lending model extensions (Morpho AdaptiveCurveIRM? variable kink parameters?). diff --git a/core/docs/plans/M3f-consensus-staking-sims.md b/core/docs/plans/M3f-consensus-staking-sims.md new file mode 100644 index 0000000..4836ccb --- /dev/null +++ b/core/docs/plans/M3f-consensus-staking-sims.md @@ -0,0 +1,88 @@ +# M3f — Consensus & staking game sims + +## 1. Component +Consensus-layer simulation: models **Proof-of-Stake validation dynamics, staking pool game theory, +and Byzantine fault tolerance** using evolutionary games and Markov chains. Pops here are +**validators and staking pool operators** whose honesty is a dynamic, evolving strategy under +financial incentives. Grounded in Cornell evolutionary consensus [8,9], ACM staking pool risk +theorems [10], and Monash dynamic PBFT modeling [11]. + +## 2. Status / certainty +DESIGN-FIRST · ABSENT. Evolutionary PoS game theory C4 (Cornell [8]); staking pool Nash +equilibrium proofs C4 (ACM [10]); Markov chain throughput models C4 (Monash [11]); MFG for +validator populations C4 (Lasry & Lions 2007; validator-specific application C3); +simulation parameterization C1. + +## 3. Language & location +TBD · `src/economy/sims/consensus/`. Needs Markov chain solvers and game-theoretic equilibrium +computation. Julia, R, or Fortran. + +## 4. Does / does-not +- **Does:** simulate validator populations where honesty evolves via **evolutionary game theory** + under bounded rationality [8]; model staking pool delegation as a game with proven reward- + parameter thresholds enforcing subgame-perfect Nash equilibria favoring honest validation over + malicious slashing [10]; simulate **throughput stability under shifting validator states** via + Markov chains [11]; solve **Mean-Field Game equilibria for large validator populations** — + coupled HJB (individual validator optimization) + Fokker-Planck (population density): + $-\partial_t u + H(x, \nabla u) = F(x, m)$, $\partial_t m - \nabla \cdot (m \nabla_p H) = 0$ + — captures emergent staking coordination without enumerating every validator; predict slashing + risk, validator set stability, and staking yield across **six concurrent time horizons** at + tick-advanced, 90:1 (1s wall = 90s sim); produce bounded predictions on consensus health and staking returns. +- **Does-not:** validate blocks (this is a simulator); model AMM pools (M3c); model token supply + (M3e — but consumes staking ratio from M3e as input). + +## 5. Interface contract +- Implements `query(PredictionQuery) -> BoundedPrediction` per M3 hub. +- **Output bounds:** equilibrium stability ranges and yield intervals. + Example: `{ value: 0.89, lower_bound: 0.82, upper_bound: 0.94, confidence: 8.80, + time_horizon: "7d", sim_type: "consensus_staking" }` — fraction of validators honest in + equilibrium. + Example: `{ value: 4.2, lower_bound: 3.6, upper_bound: 5.1, confidence: 8.20, + time_horizon: "30d", sim_type: "consensus_staking" }` — annualized staking yield (%). +- **Time-horizon mapping** (all run concurrently, tick-advanced, 90:1 (1s wall = 90s sim)): + | Horizon | Primary models | Update cadence | + |---------|---------------|----------------| + | Hourly | Markov chain validator state transitions | Every epoch | + | Daily | Replicator dynamics strategy shifts, slashing events | Hourly roll | + | Weekly | Staking pool Nash equilibrium recalculation | Daily roll | + | Monthly | MFG equilibrium for validator population | Weekly roll | + | Annual | Evolutionary stable strategies, yield trajectory | Monthly roll | + | 5-year | Consensus mechanism structural evolution | Quarterly roll | +- **Prediction types:** `validator_honesty_fraction`, `slashing_probability`, `staking_yield`, + `pool_delegation_equilibrium`, `throughput_stability`, `consensus_liveness`, + `mfg_validator_equilibrium`. +- Calibration: ingests `on_chain_event` (validator set changes, slashing events) from M2. + +## 6. Dependencies & stubs +- M2 Data Feeds — validator/staking on-chain data; *stub:* canned validator snapshots. +- M3e Tokenomics — staking ratio as macro input; *stub:* fixed ratio. +- M3 Sims hub — lifecycle management; *stub:* manual init. + +## 7. Invariants / laws +- **L1 (C4):** validator honesty is a **dynamic equilibrium, not a fixed parameter** — it evolves + via replicator dynamics as payoffs change. The sim must not assume fixed honesty rates. +- **L2 (C4):** the staking pool reward threshold is **mathematically derived** — the sim must + reproduce the subgame-perfect Nash equilibrium from the ACM proofs [10], not use ad-hoc + thresholds. +- **L3 (C4):** throughput is modeled as a **Markov chain** over validator states (active, pending, + slashed, exited) — transitions are stochastic with rates calibrated from on-chain data [11]. + +## 8. Build steps +1. Implement the evolutionary honesty game (replicator dynamics, bounded rationality). +2. Implement the Markov chain validator-state model. +3. Reproduce the staking pool Nash equilibrium reward threshold from [10]. +4. Implement MFG solver (HJB + Fokker-Planck) for large validator populations. +5. Wire M2 validator data → calibration of transition rates. +6. Wire M3e staking ratio input. + +## 9. Tests +Equilibrium: honesty fraction converges to Nash equilibrium under stable payoffs. Markov: +stationary distribution matches expected validator state proportions. Threshold: pool delegation +equilibrium matches the ACM proof for test parameters. Bounds: all outputs bounded. Liveness: +throughput degrades when honest fraction drops below threshold. + +## 10. Open items +- Which PoS protocol to model initially (Ethereum? a specific L2?). +- Bounded rationality implementation (noisy best-response? epsilon-greedy? logit?). +- Slashing severity parameterization. +- Cross-sim: does consensus instability feed into M3b sociological panic signals? diff --git a/core/docs/plans/M3g-market-microstructure-sims.md b/core/docs/plans/M3g-market-microstructure-sims.md new file mode 100644 index 0000000..469c842 --- /dev/null +++ b/core/docs/plans/M3g-market-microstructure-sims.md @@ -0,0 +1,100 @@ +# M3g — Market microstructure sims + +## 1. Component +Market microstructure simulation: models **order flow, liquidity depth, slippage, spread dynamics, +optimal execution, and cross-exchange arbitrage** at the fastest time scales. Pops here are +**market makers, takers, and arbitrageurs** interacting across multiple venues. Includes the +**Almgren-Chriss optimal execution framework** for minimizing market impact of large orders. +Operates at the highest temporal resolution — where M3a provides statistical forecasts and M3c +models pool mechanics, M3g models the *plumbing* of how orders actually execute, across **six +concurrent time horizons** at tick-advanced, 90:1 (1s wall = 90s sim). + +## 2. Status / certainty +DESIGN-FIRST · ABSENT. Order-book microstructure theory C4 (established). Almgren-Chriss +optimal execution C5 (industry standard since 2001; crypto adaptations validated 2023–2024, +Kurz CMC thesis). DEX-specific microstructure C2 (emerging). Implementation C1. + +## 3. Language & location +TBD · `src/economy/sims/microstructure/`. Needs high-frequency data handling, event-driven +simulation, and Riccati equation solvers for optimal execution trajectories. Fortran or Julia. + +## 4. Does / does-not +- **Does:** simulate order flow across venues (DEXs and CEXs); model bid-ask spread dynamics as a + function of inventory risk and adverse selection; simulate slippage curves for various order + sizes; solve **Almgren-Chriss optimal execution**: + $\min \int_0^T [\lambda \cdot x(t) \cdot \dot{x}(t) + \eta \cdot \dot{x}(t)^2] \, dt$ + where $\lambda$ = permanent impact, $\eta$ = temporary impact, $x(t)$ = remaining order — + splits large orders across time to minimize market impact + timing risk; impact parameters + $\lambda, \eta$ re-estimated from order-flow streams every 10–30s; execution trajectory solved + via Riccati equations in <100ms; model cross-exchange arbitrage opportunities and their decay; + operate at **tick-level resolution** (sub-second to minute); produce bounded predictions on + execution quality, optimal routing, and liquidity conditions. +- **Does-not:** model protocol consensus (M3f); model macro token supply (M3e); model social + behavior (M3b); execute trades (Marketplace does). + +## 5. Interface contract +- Implements `query(PredictionQuery) -> BoundedPrediction` per M3 hub. +- **Output bounds:** execution cost ranges, liquidity intervals, optimal trajectory envelopes. +- **Time-horizon mapping** (all run concurrently, tick-advanced, 90:1 (1s wall = 90s sim)): + | Horizon | Primary models | Update cadence | + |---------|---------------|----------------| + | Tick–hourly | Almgren-Chriss execution, slippage, spread, arb decay | Every tick | + | Daily | Liquidity regime, venue depth profiles | Hourly roll | + | Weekly | Cross-venue flow patterns, impact parameter drift | Daily roll | + | Monthly | Structural liquidity shifts, venue market share | Weekly roll | + | Annual | Microstructure regime (DEX vs CEX share evolution) | Monthly roll | + | 5-year | Venue topology evolution, structural impact trends | Quarterly roll | +- Examples: + `{ value: 0.0034, lower_bound: 0.0018, upper_bound: 0.0052, confidence: 8.50, + time_horizon: "next_trade", sim_type: "market_microstructure" }` — slippage (%) for 10 ETH. + `{ value: 12400, lower_bound: 8200, upper_bound: 18600, confidence: 7.80, + time_horizon: "1h", sim_type: "market_microstructure" }` — depth (USD) within 50bps. + `{ value: [0.3, 0.3, 0.2, 0.1, 0.1], lower_bound: null, upper_bound: null, confidence: 8.00, + time_horizon: "30min", sim_type: "market_microstructure" }` — Almgren-Chriss optimal execution + schedule (fraction per 6-min bucket for 100 ETH sell). +- **Prediction types:** `slippage_estimate`, `spread_forecast`, `depth_profile`, + `cross_venue_arb`, `optimal_execution_schedule`, `optimal_execution_route`, + `liquidity_score`, `impact_estimate`. +- Calibration: ingests `price_tick`, `dex_pool_state`, and `execution_fill` from M2. + +## 6. Dependencies & stubs +- M2 Data Feeds — tick data and pool state; *stub:* canned order book snapshots. +- M3a Statistical — volatility estimates for Almgren-Chriss timing risk; *stub:* fixed vol. +- M3c AMM sims — pool mechanics for DEX venues; *stub:* fixed pool state. +- M3 Sims hub — lifecycle management; *stub:* manual init. + +## 7. Invariants / laws +- **L1 (C5):** microstructure operates at the **highest temporal resolution** — predictions are + valid for seconds to hours, not days. Stale microstructure data is worse than no data. +- **L2 (C5):** slippage is a **function of order size and current depth** — not a fixed + percentage. The sim must model the non-linear relationship. +- **L3 (C5):** Almgren-Chriss impact parameters $\lambda, \eta$ are **estimated from live data**, + never hardcoded — crypto impact dynamics differ by asset, venue, and time-of-day. +- **L4 (C4):** cross-venue arbitrage opportunities **decay** — the sim models the time-to-close + of an arb opportunity, not just its existence. +- **L5 (C4):** optimal execution trajectories are **re-solved on every significant state change** + (vol spike, depth drop, regime transition) — a stale trajectory is worse than naive execution. + +## 8. Build steps +1. Implement a simplified order-book simulator (limit orders, market orders, cancels). +2. Add spread dynamics (inventory-based market maker model). +3. Add slippage curves (order size → execution cost). +4. Implement Almgren-Chriss optimal execution (Riccati solver, impact estimation). +5. Add cross-venue arb detection and decay modeling. +6. Wire M2 tick data → calibration of impact parameters. +7. Wire M3a vol estimates → Almgren-Chriss timing risk component. + +## 9. Tests +Slippage: larger orders produce greater slippage. Spread: spread widens under adverse selection. +Almgren-Chriss: optimal trajectory minimizes total cost vs. naive execution on backtest; impact +parameters update when market conditions change. Arb decay: detected arb opportunity closes over +time. Depth: depth profile matches order book state. Bounds: all outputs bounded. Resolution: +predictions update at tick frequency. Speed: sim tick-advances at 90:1. + +## 10. Open items +- CEX order book data access (API limitations, costs). +- DEX-specific microstructure (AMM pools don't have order books — translate pool state to + equivalent depth/spread). +- Latency modeling (how fast can our traders actually reach an arb?). +- Almgren-Chriss extensions for crypto (volume-dependent variant? discrete block propagation?). +- Which venues to model initially. diff --git a/core/docs/plans/M4-wallets.md b/core/docs/plans/M4-wallets.md new file mode 100644 index 0000000..45a5a4d --- /dev/null +++ b/core/docs/plans/M4-wallets.md @@ -0,0 +1,74 @@ +# M4 — Wallets (sovereign custody) + +## 1. Component +The economy organ's vault: **sovereign, local-hosted, our-custody-only cryptocurrency wallets**. +Each wallet binds to exactly one Trader (M5) — a trader without a wallet cannot access the +Marketplace (M1). Wallets hold keys, sign transactions, and enforce wallet-level spending limits. +Tax is collected on trader income and routed to the Verschwörern Veregeister wallets (stub — M0). + +## 2. Status / certainty +DESIGN-FIRST · ABSENT. Role C4 (sovereign custody is a hard requirement); implementation C1. + +## 3. Language & location +TBD · `src/economy/wallets/`. Needs cryptographic key management (secp256k1 for EVM, ed25519 for +Solana, etc.), HD derivation, and transaction signing. Rust or Go for crypto primitives; Python +with web3 libs for prototyping. + +## 4. Does / does-not +- **Does:** generate and store private keys locally (never transmitted); sign transactions on + behalf of the bound trader; enforce per-wallet spending limits (daily, per-transaction); + track wallet balance and transaction history; collect tax on realized income and stage for + transfer to Verschwörern Veregeister wallets; bind 1:1 to a Trader (M5). +- **Does-not:** decide what to trade (Trader decides); route to chain (Marketplace does); + hold keys for the organism's other wallets (Verschwörern Veregeister are separate); delegate + custody to any third party — ever. + +## 5. Interface contract +- `create_wallet(chain: Chain, trader_id) -> wallet_id` — generates keys, binds to trader. +- `sign(wallet_id, tx: UnsignedTransaction) -> SignedTransaction` — signs with the wallet's key. + Only the bound trader (via Marketplace) can request signing. +- `balance(wallet_id) -> { chain, assets: [{ token, amount }] }`. +- `spending_check(wallet_id, amount) -> { allowed:bool, remaining_daily:num }`. +- `tax_collect(wallet_id, income_amount) -> { tax_amount, receipt }` — computes and stages tax. +- `transfer_tax_stub(source_wallet, dest_wallet, amount) -> receipt` — **STUB** for future + Verschwörern Veregeister internal transfer. Logs only; does not execute. +- `Chain` ∈ { `evm`, `solana`, `bitcoin`, … } — extensible. + +## 6. Dependencies & stubs +- M5 Traders — 1:1 binding; *stub:* canned trader ID. +- M1 Marketplace — signing requests come through marketplace only; *stub:* direct sign call. +- Blockchain nodes — balance queries and tx broadcast; *stub:* simulated chain state. +- Verschwörern Veregeister wallets — tax destination; *stub:* log transfer. + +## 7. Invariants / laws +- **L1 (C5):** **sovereign custody only** — private keys are generated locally, stored locally, + and **never leave the wallet**. No custodial service, no exchange deposit, no MPC with external + parties. Our keys, our coins. +- **L2 (C5):** **1:1 trader binding** — each wallet is bound to exactly one trader. A trader + cannot use another trader's wallet. The Marketplace enforces this. +- **L3 (C4):** **signing requires Marketplace routing** — a wallet will not sign a transaction + that didn't come through the Marketplace harness (M1-L1). No direct signing API for traders. +- **L4 (C4):** **spending limits are wallet-level** — independent of Conductor or Marketplace + limits. Defense in depth: even if other controls fail, the wallet itself caps exposure. +- **L5 (C4):** **tax collection is automatic** — realized income triggers tax staging. The trader + cannot opt out. + +## 8. Build steps +1. Implement key generation and secure local storage (encrypted keystore). +2. Implement transaction signing for one chain (start with EVM/secp256k1). +3. Implement trader binding and Marketplace-only signing enforcement. +4. Implement spending limits (daily cap, per-tx cap). +5. Implement tax calculation and staging stub. + +## 9. Tests +Custody: private key never appears in any API response or log. Binding: wrong trader cannot +sign. Marketplace-only: direct sign request (not via Marketplace) rejected. Spending limit: +over-limit transaction rejected. Tax: income event triggers correct tax amount. Multi-chain: +EVM and one other chain produce valid signatures. + +## 10. Open items +- Key storage format (encrypted JSON keystore? OS keyring? HSM for production?). +- Which chains to support initially. +- Spending limit configuration (hardcoded? per-trader? adjustable by Conductor?). +- Tax rate and calculation method. +- Key rotation / backup strategy. diff --git a/core/docs/plans/M5-traders.md b/core/docs/plans/M5-traders.md new file mode 100644 index 0000000..732acce --- /dev/null +++ b/core/docs/plans/M5-traders.md @@ -0,0 +1,78 @@ +# M5 — Traders (AI actors) + +## 1. Component +The economy organ's hands: **specialized AI actors** that buy, sell, and mint cryptocurrency and +NFTs. Each trader is bound to a Wallet (M4), operates through the Marketplace (M1), queries Sims +(M3) for predictions, and has all tool calls monitored by the SAE (M7). Multiple traders may +operate concurrently with **different specializations** (DeFi yield, NFT minting, arbitrage, +long-term holding, etc.). + +## 2. Status / certainty +DESIGN-FIRST · ABSENT. Role C3; implementation C1. + +## 3. Language & location +TBD · `src/economy/traders/`. Each trader is an AI actor — likely LLM-based (small models for +speed) or hybrid (LLM for strategy + deterministic execution logic). The harness managing +multiple traders may be Pony actors or a Python async framework. + +## 4. Does / does-not +- **Does:** query Sims (M3) for market predictions (bounded, multi-domain); consume Data Feeds + (M2) for real-time market state; formulate trade decisions based on predictions + data + + specialization; submit `MarketAction` requests to the Marketplace (M1) via bound wallet (M4); + operate with **scoped autonomy** — trades within law/budget constraints don't need Brain or + Conductor approval. +- **Does-not:** execute on-chain directly (Marketplace does); hold keys (Wallet does); supervise + other traders (Conductor does); modify the law script (immutable — M1-L2); bypass the + Marketplace (M1-L1). + +## 5. Interface contract +- `init_trader(specialization, wallet_id, config) -> trader_id`. + `specialization` ∈ { `defi_yield`, `nft_minter`, `arbitrageur`, `trend_follower`, + `market_maker`, … } — extensible. +- `decide(market_state, predictions: [BoundedPrediction]) -> MarketAction?` — the trader's core + loop. May return no action (waiting is a valid decision). +- `tool_call(tool_name, args) -> result` — every tool call is intercepted and logged to SAE (M7) + before execution. Includes Marketplace submissions, Sim queries, and Data Feed reads. +- `pause() / resume()` — Conductor (M6) can pause a trader pending investigation. +- `status() -> { active | paused | investigating, wallet_id, specialization, position_summary }`. + +## 6. Dependencies & stubs +- M1 Marketplace — action submission; *stub:* mock marketplace that logs actions. +- M2 Data Feeds — market data; *stub:* canned data. +- M3 Sims — predictions; *stub:* fixed predictions. +- M4 Wallet — bound 1:1; *stub:* mock wallet. +- M6 Conductor — supervision; *stub:* no supervision. +- M7 SAE — monitors all tool calls; *stub:* print calls. + +## 7. Invariants / laws +- **L1 (C5):** **all market actions go through the Marketplace** — a trader cannot interact with + any chain or protocol except via `MarketAction` → Marketplace (M1). Enforced by architecture + (no direct RPC access), not just policy. +- **L2 (C5):** **all tool calls are monitored** — every tool invocation (Marketplace, Sims, + Feeds, internal) is logged to SAE (M7). No unmonitored trader action. +- **L3 (C4):** **wallet binding is irrevocable within a session** — a trader's wallet cannot be + reassigned to another trader at runtime. +- **L4 (C4):** **Conductor can pause** — a paused trader cannot submit actions, query sims, or + read feeds until resumed by the Conductor (M6). +- **L5 (C3):** trader specialization constrains strategy but not the interface — all traders use + the same `MarketAction` vocabulary regardless of specialization. + +## 8. Build steps +1. Define the trader agent architecture (LLM-based? hybrid? rule-based for v1?). +2. Implement the `decide` loop (observe market state + predictions → action). +3. Wire tool-call interception → M7 SAE. +4. Wire Marketplace submission → M1. +5. Implement pause/resume for Conductor control. +6. Build at least two specializations to test multi-trader dynamics. + +## 9. Tests +Marketplace-only: trader cannot call chain RPC directly. Monitoring: every tool call appears in +SAE log. Wallet binding: trader uses only its bound wallet. Pause: paused trader cannot submit +actions. Specialization: different specializations produce different action patterns on identical +market state. + +## 10. Open items +- Trader agent architecture (which LLM? how much deterministic logic vs. model inference?). +- Number of concurrent traders and resource allocation per trader. +- Specialization catalog (which types, and how do they differ in strategy?). +- Inter-trader coordination (do traders see each other's positions? shared state? isolated?). diff --git a/core/docs/plans/M6-conductor.md b/core/docs/plans/M6-conductor.md new file mode 100644 index 0000000..565c1b0 --- /dev/null +++ b/core/docs/plans/M6-conductor.md @@ -0,0 +1,79 @@ +# M6 — Conductor (supervisory AI) + +## 1. Component +The economy organ's supervisor: a **specialist-trained AI** with authority to **veto Marketplace +actions and pause/investigate individual Traders**. Receives suspicious-behavior reports from the +SAE (M7) and acts on them. The Conductor is the stomach's own judgment — it does not consult the +organism's Brain for trade-level decisions. It supervises; the deterministic law script (M1) +constrains; together they form the multi-layered braking system. + +## 2. Status / certainty +DESIGN-FIRST · ABSENT. Role C4 (supervision architecture is clear); implementation C1 (model +selection, training, authority scope). + +## 3. Language & location +TBD · `src/economy/conductor/`. The Conductor is an AI actor — likely a fine-tuned LLM with +specialist training in market risk, trader behavior analysis, and anomaly response. The +inference wrapper sits alongside the Marketplace. + +## 4. Does / does-not +- **Does:** receive SAE (M7) anomaly reports on trader behavior; **pause** a flagged trader's + actions to investigate; **veto** a Marketplace action if investigation reveals risk; **resume** + a cleared trader; review Marketplace actions pre-execution when the law check passes (M1-L4: + veto is checked after law, before execution); maintain an audit log of all veto/pause/resume + decisions. +- **Does-not:** trade (Traders do); execute on-chain (Marketplace does); modify the law script + (immutable — M1-L2); detect anomalies directly (SAE does — the Conductor *responds* to SAE + reports, it doesn't watch raw data); consult the organism's Brain. + +## 5. Interface contract +- `veto_check(action: MarketAction, trader_id) -> { approved | vetoed(reason) }` — called by + Marketplace (M1) for every law-passing action before execution. +- `receive_alert(alert: SAEAlert) -> { pause(trader_id) | dismiss | escalate }`. + `SAEAlert { trader_id, alert_type, evidence, severity, timestamp }`. +- `investigate(trader_id) -> { clear(resume) | veto_pending_actions | restrict(new_limits) }`. +- `decision_log() -> [ConductorDecision]` — full audit trail of all veto/pause/resume/dismiss. +- **SAE/Brain message format compatibility:** the Conductor's incoming alert format is + **identical in structure and signature** to Brain messages — SAE reports to the Conductor in + the same shape it would report to the Brain. This means the Conductor can be swapped for Brain + oversight without protocol changes (though the stomach normally operates autonomously). + +## 6. Dependencies & stubs +- M7 SAE — anomaly reports; *stub:* no alerts (all clear). +- M1 Marketplace — veto check integration; *stub:* always-approve. +- M5 Traders — pause/resume control; *stub:* print pause/resume. + +## 7. Invariants / laws +- **L1 (C5):** the Conductor **can veto, but cannot trade** — it has no wallet, no Marketplace + access as a trader. It supervises from outside the trading loop. +- **L2 (C5):** the **law script is above the Conductor** — the Conductor vetoes actions that + *pass* the law check but seem strategically risky. It cannot override a law violation (those + are rejected before reaching the Conductor — M1-L4). +- **L3 (C4):** **pause is reversible** — a paused trader can always be resumed after + investigation. Pause is a breaker, not a sentence (echoes A2-L3). +- **L4 (C4):** every Conductor decision is **logged** — vetoes, pauses, resumes, dismissals. + The audit log is append-only (echoes M1-L2 / S3). +- **L5 (C4):** SAE alert format and Brain message format are **structurally identical** — same + fields, same signatures. The Conductor processes them the same way the Brain would. + +## 8. Build steps +1. Define the Conductor's decision model (rule-based for v1? fine-tuned LLM for v2?). +2. Wire SAE alert intake (M7 → M6). +3. Wire Marketplace veto check (M1 → M6 → approve/veto). +4. Implement trader pause/investigate/resume flow. +5. Implement append-only decision log. + +## 9. Tests +Veto: flagged action is vetoed; unflagged action approved. Pause: paused trader cannot submit +actions. Resume: cleared trader resumes normal operation. No trading: Conductor cannot submit +`MarketAction`. Law supremacy: Conductor cannot override a law violation (never reaches +Conductor). Audit: every decision appears in the log. Alert format: SAE alert parses identically +to Brain message structure. + +## 10. Open items +- Conductor AI model selection and training data (what does "specialist training" look like?). +- Veto criteria beyond SAE alerts (does the Conductor have independent judgment, or only + responds to SAE reports?). +- Escalation path — if the Conductor is uncertain, does it escalate to the organism's Brain? + Or is the stomach fully autonomous? (Current design: fully autonomous.) +- Multiple Conductors for redundancy? diff --git a/core/docs/plans/M7-sae-monitor.md b/core/docs/plans/M7-sae-monitor.md new file mode 100644 index 0000000..d8fe780 --- /dev/null +++ b/core/docs/plans/M7-sae-monitor.md @@ -0,0 +1,83 @@ +# M7 — SAE monitor (trader surveillance) + +## 1. Component +The economy organ's internal watchdog: a **sparse autoencoder pointed at every trader tool call**. +Monitors all Trader (M5) actions — Marketplace submissions, Sim queries, Data Feed reads, and +any other tool invocation — and reports **suspicious behavior** to the Conductor (M6). Messages +from the SAE share **identical format and signatures** with Brain messages, so the Conductor +processes them through the same pathway. + +Extends the F2 (SAE monitor) pattern to the economy organ's internal domain. F2 watches +subagents at the organism level; M7 watches traders at the stomach level. + +## 2. Status / certainty +DESIGN-FIRST · ABSENT. F2 SAE monitor provides the architectural pattern (watch the machinery, +never the homunculus — F2-L1). M7 adapts this: watch the **traders** (the machinery), never the +**Conductor** (the stomach's judgment). Role C3; implementation C1. + +## 3. Language & location +TBD · `src/economy/sae/`. ML interpretability (sparse autoencoder over trader action embeddings). +Shares the architectural pattern with F2 but is a separate instance scoped to the economy organ. + +## 4. Does / does-not +- **Does:** intercept and log **every trader tool call** (Marketplace, Sims, Feeds, internal); + embed trader action sequences; run SAE anomaly detection over action embeddings; flag suspicious + patterns (unusual trading frequency, outsized positions, coordinated behavior across traders, + repeated failed actions, unusual Sim query patterns); report alerts to the Conductor (M6) with + evidence; format alerts **identically to Brain messages** (same structure, same signatures). +- **Does-not:** block actions directly (Conductor decides); watch the Conductor (the stomach's + "homunculus" — echoes F2-L1); correct trader behavior (detection only — F2-L2: no closed + elimination loop); trade or access wallets. + +## 5. Interface contract +- `log_tool_call(trader_id, tool_name, args, result, timestamp)` — called on every trader tool + invocation. Synchronous interception (the call is logged before execution proceeds). +- `alert(trader_id, alert_type, evidence, severity) -> SAEAlert`. + `alert_type` ∈ { `unusual_frequency`, `outsized_position`, `coordinated_behavior`, + `repeated_failures`, `anomalous_queries`, `pattern_deviation` }. + `severity` ∈ { `low`, `medium`, `high`, `critical` }. +- `SAEAlert` structure is **identical to Brain message structure** — same fields, same + signature scheme. The Conductor (M6) processes SAE alerts and Brain messages through the + same intake (M6-L5). +- `status() -> { active, traders_monitored, alerts_pending, model_freshness }`. + +## 6. Dependencies & stubs +- M5 Traders — tool call source; *stub:* canned tool call log. +- M6 Conductor — alert consumer; *stub:* print alerts. +- F2 SAE monitor (organism-level) — architectural pattern; no runtime dependency. + +## 7. Invariants / laws +- **L1 (C5):** the SAE watches **traders, never the Conductor** — the Conductor is the + stomach's judgment; the SAE monitors the machinery. Echoes F2-L1 (watch the machinery, never + the homunculus). +- **L2 (C5):** **every tool call is logged** — no trader action escapes monitoring. This is + enforced architecturally (tool call interception), not by policy. +- **L3 (C4):** **detection only, no enforcement** — the SAE reports to the Conductor; it never + blocks, pauses, or modifies trader actions itself. Echoes F2-L2 (no closed elimination loop). +- **L4 (C4):** **alert format = Brain message format** — structurally identical, same signatures. + This is not coincidental; it ensures the Conductor can be supervised by the Brain using the + same protocol if the organism ever needs to override stomach autonomy. +- **L5 (C3):** the SAE model is **trained on normal trader behavior** — anomalies are deviations + from the learned normal, not violations of predefined rules (those are the law script's job + in M1). + +## 8. Build steps +1. Implement tool-call interception in the trader harness (M5). +2. Define the action embedding scheme (how tool calls are vectorized). +3. Train the SAE on normal trader behavior (bootstrapped from simulated trading). +4. Implement anomaly scoring and alert threshold. +5. Wire alerts to Conductor (M6) in Brain-compatible message format. + +## 9. Tests +Interception: every tool call produces a log entry. Anomaly: known-suspicious patterns (e.g. +100x normal frequency) trigger alert. Normal: baseline behavior does not trigger alert. +No enforcement: SAE cannot pause or block a trader (only Conductor can). Alert format: SAE +alert parses as valid Brain message. Conductor-blind: no Conductor action appears in SAE logs. + +## 10. Open items +- SAE architecture (how many features? reconstruction vs. classification?). +- Training data bootstrapping (simulated trading or historical data?). +- Alert threshold tuning (too sensitive = alert fatigue; too lax = missed anomalies). +- Whether M7 should also monitor Marketplace execution outcomes (fills, slippage) in addition + to tool calls. +- Relationship to F2: shared model? shared training pipeline? or fully independent? diff --git a/core/docs/plans/README.md b/core/docs/plans/README.md index 1d15f4e..6d9deb9 100644 --- a/core/docs/plans/README.md +++ b/core/docs/plans/README.md @@ -49,6 +49,21 @@ Every `NN-.md` has the same 10 sections: | G1 | Stress-loop contract | Cross-cut | C1/C2 | — | _wave 2_ | | G2 | Governance | Cross-cut | DESIGN-FIRST (C2) | TBD | _wave 2_ | | G3 | Defense model | Cross-cut | emergent | — | _wave 2_ | +| M0 | Economy organ hub (stomach) | Economy | DESIGN-FIRST | TBD | [M0](M0-economy-organ-hub.md) | +| M1 | Marketplace (multi-trader harness) | Economy | DESIGN-FIRST | TBD | [M1](M1-marketplace.md) | +| M2 | Data feeds (market data pipeline) | Economy | DESIGN-FIRST | TBD | [M2](M2-data-feeds.md) | +| M3 | Sims hub (market prediction) | Economy | DESIGN-FIRST | TBD | [M3](M3-sims-hub.md) | +| M3a | Statistical & quantitative sims | Economy/Sims | DESIGN-FIRST | TBD | [M3a](M3a-statistical-sims.md) | +| M3b | Sociological & population sims | Economy/Sims | DESIGN-FIRST | TBD | [M3b](M3b-sociological-sims.md) | +| M3c | AMM & liquidity pool sims | Economy/Sims | DESIGN-FIRST | TBD | [M3c](M3c-amm-liquidity-sims.md) | +| M3d | MEV & adversarial extraction sims | Economy/Sims | DESIGN-FIRST | TBD | [M3d](M3d-mev-adversarial-sims.md) | +| M3e | Tokenomics & macro-state sims | Economy/Sims | DESIGN-FIRST | TBD | [M3e](M3e-tokenomics-macro-sims.md) | +| M3f | Consensus & staking game sims | Economy/Sims | DESIGN-FIRST | TBD | [M3f](M3f-consensus-staking-sims.md) | +| M3g | Market microstructure sims | Economy/Sims | DESIGN-FIRST | TBD | [M3g](M3g-market-microstructure-sims.md) | +| M4 | Wallets (sovereign custody) | Economy | DESIGN-FIRST | TBD | [M4](M4-wallets.md) | +| M5 | Traders (AI actors) | Economy | DESIGN-FIRST | TBD | [M5](M5-traders.md) | +| M6 | Conductor (supervisory AI) | Economy | DESIGN-FIRST | TBD | [M6](M6-conductor.md) | +| M7 | SAE monitor (trader surveillance) | Economy | DESIGN-FIRST | TBD | [M7](M7-sae-monitor.md) | ## Integration DAG (who feeds whom) ``` @@ -62,10 +77,15 @@ Hermes ──> [C1] ──> Inference cycle [C3] ──┬─ pulls Drive-Box sn └─ Ada routes tools [D1] SAE [F2] watches Subagents [F3]; stress-loop [G1]: F2 → A7 (EthInt) → stress endomotiv (A4) → A8 drift + full reshuffle (B2) Storage: INVARIANT [E1] / VARIANT [E2] / RAG+cross-store [E3] sit behind D1. Medium [D2] = the perfusion bus (unnamed). +Economy (stomach — independent, scoped autonomy): + Marketplace [M1] ← Traders [M5] (bound to Wallets [M4]) submit actions; law script + Conductor [M6] veto gate execution. + Data Feeds [M2] ↔ Sims [M3: M3a stat, M3b socio, M3c AMM, M3d MEV, M3e tokenomics, M3f consensus, M3g microstructure]. + SAE [M7] monitors all Trader tool calls → alerts Conductor [M6]. Tax → Verschwörern Veregeister wallets (stub). + Stomach [M0] ↔ organism via Ichor; reward signals TBD. ``` ## Build waves - **Wave 0** — this README + **C1** (priority). - **Wave 1 (buildable-now)** — A1–A8, B1–B3, C2–C4, D1, D3. -- **Wave 2 (design-first)** — D2, E1–E3, F1–F3, G1–G3. +- **Wave 2 (design-first)** — D2, E1–E3, F1–F3, G1–G3, M0–M7 (+ M3a–M3g sim sub-specs). Each spec is independent; review as they land. diff --git a/core/src/endocrine/AGENTS.md b/core/src/endocrine/AGENTS.md index e290d9e..260cd52 100644 --- a/core/src/endocrine/AGENTS.md +++ b/core/src/endocrine/AGENTS.md @@ -1,7 +1,7 @@ # AGENTS.md — endocrine organs (R / Octave) Local guide for `src/endocrine`. Repo-wide map and rules: [`../../AGENTS.md`](../../AGENTS.md); -working agreements: [`../../CLAUDE.md`](../../CLAUDE.md). +working agreements: [`../../CLAUDE.md`](../../CLAUDE.md). Correction log: [`../../../.claude/devCorrectionLog.md`](../../../.claude/devCorrectionLog.md). ## What this is diff --git a/core/src/ichor/AGENTS.md b/core/src/ichor/AGENTS.md index 0dd352b..809f9d2 100644 --- a/core/src/ichor/AGENTS.md +++ b/core/src/ichor/AGENTS.md @@ -1,7 +1,7 @@ # AGENTS.md — Ichor bus (Pony) Local guide for `src/ichor`. Repo-wide map and rules: [`../../AGENTS.md`](../../AGENTS.md); -working agreements: [`../../CLAUDE.md`](../../CLAUDE.md). +working agreements: [`../../CLAUDE.md`](../../CLAUDE.md). Correction log: [`../../../.claude/devCorrectionLog.md`](../../../.claude/devCorrectionLog.md). ## What this is