DeFiPy 2.1.0a2__tar.gz → 2.2.0__tar.gz

{defipy-2.1.0a2 → defipy-2.2.0}/DeFiPy.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: DeFiPy
-Version: 2.1.0a2
+Version: 2.2.0
 Summary: Python SDK for Agentic DeFi
 Home-page: http://github.com/defipy-devs/defipy
 Author: icmoore
@@ -21,15 +21,19 @@ Requires-Dist: uniswappy>=1.7.9
 Requires-Dist: balancerpy>=1.1.0
 Requires-Dist: stableswappy>=1.1.0
 Provides-Extra: chain
-Requires-Dist: web3scout>=0.2.0; extra == "chain"
+Requires-Dist: web3scout>=1.0.0; extra == "chain"
 Requires-Dist: web3<7.0,>=6.0; extra == "chain"
 Provides-Extra: book
-Requires-Dist: web3scout>=0.2.0; extra == "book"
+Requires-Dist: web3scout>=1.0.0; extra == "book"
 Requires-Dist: web3<7.0,>=6.0; extra == "book"
 Provides-Extra: anvil
 Requires-Dist: web3<7.0,>=6.0; extra == "anvil"
 Provides-Extra: mcp
 Requires-Dist: mcp>=1.27.0; extra == "mcp"
+Provides-Extra: agentic
+Requires-Dist: web3scout>=1.0.0; extra == "agentic"
+Requires-Dist: web3<7.0,>=6.0; extra == "agentic"
+Requires-Dist: mcp>=1.27.0; extra == "agentic"
 Dynamic: author
 Dynamic: author-email
 Dynamic: description
@@ -51,29 +55,42 @@ Underneath, DeFiPy is modular by protocol:
 * [BalancerPy](https://github.com/defipy-devs/balancerpy)
 * [StableSwapPy](https://github.com/defipy-devs/stableswappy)
 
-For onchain event access and scripting, pair it with [Web3Scout](https://github.com/defipy-devs/web3scout) — a companion tool for [decoding pool events](https://defipy.readthedocs.io/en/latest/onchain/pool_events.html) and [interfacing with Solidity contracts](https://defipy.readthedocs.io/en/latest/onchain/testnet_sim_univ2.html).
+For onchain event access and scripting, use [LiveProvider](https://defipy.org/live-provider/) as of v2.1 — it pulls live pool state into the same primitive surface that runs against synthetic recipes. Under the hood it's powered by [Web3Scout](https://github.com/defipy-devs/web3scout); install via the `[chain]` extra (see below). For details on architecture behind [State Twins](https://defipy.org/twin-concept/), see paper [![arXiv](https://img.shields.io/badge/arXiv-2605.11522-b31b1b.svg)](https://arxiv.org/abs/2605.11522) 
 
-🔗 SPDX-Anchor: [anchorregistry.ai/AR-2026-YdPXB5g](https://anchorregistry.ai/AR-2026-YdPXB5g)
+## 🆕 What's new in v2.2
+
+v2.2 extends `LiveProvider` from Uniswap V2/V3 to **Balancer** and **Curve-style Stableswap** — chain reads now cover all four protocol families through the same `provider.snapshot(...)` → `StateTwinBuilder().build(...)` flow.
+
+* **Balancer LiveProvider** — `provider.snapshot("balancer:0xADDR")` builds a `BalancerPoolSnapshot` from a real Balancer V2 weighted pool (2-asset). Two block-pinned round trips, since token balances live on the Vault keyed by `poolId`. Normalized weights read honestly; reserves decimal-adjusted.
+* **Stableswap LiveProvider** — `provider.snapshot("stableswap:0xADDR")` builds an N-coin `StableswapPoolSnapshot` (N ∈ {2, 3}, e.g. the DAI/USDC/USDT 3pool) from a real Curve plain pool. Coin count comes from an `n_coins` hint or an automatic `coins(0..K)` probe; plain pools only.
+* **`multicall_aggregate3_args`** — an argument-bearing Multicall3 batch (encodes calldata args, optional `allow_failure`) powering the Balancer/Curve reads alongside the no-arg getters, all block-pinned. The existing no-arg `multicall_aggregate3` and the V3 path are unchanged.
+* **web3scout `>= 1.0.0`** — the `[chain]` / `[book]` / `[agentic]` extras now pin web3scout 1.0, which carries the Balancer/Curve read ABIs.
+
+See the [CHANGELOG](./CHANGELOG.md) for the full v2.2 entry. v2.2 is a strict superset of v2.1.
 
 ## 🆕 What's new in v2.1
 
-v2.1 makes the State Twin **real**. `LiveProvider` ships for Uniswap V2 and V3 — chain reads compose with every primitive in the library, the same way `MockProvider` recipes do. The "what would happen if?" loop is now local: pull state once, simulate forever, decide before executing.
+v2.1 makes the [State Twin](https://defipy.org/twin-concept/) **real** — the substrate formalized in [our arXiv paper](https://arxiv.org/abs/2605.11522). `LiveProvider` ships for Uniswap V2 and V3 — chain reads compose with every primitive in the library, the same way `MockProvider` recipes do. The "what would happen if?" loop is now local: pull state once, simulate forever, decide before executing.
 
 * **`LiveProvider`** — `provider.snapshot("uniswap_v2:0xADDR")` and `provider.snapshot("uniswap_v3:0xADDR")` build `V2PoolSnapshot` and `V3PoolSnapshot` from real on-chain state. Block pinning is automatic — `"latest"` resolves once at the top of `.snapshot()` and every read inside that snapshot pins to the same block. Pass `block_number=N` for historical reads.
 * **Multicall3 batching for V3** — V3 snapshots batch `slot0`, `liquidity`, `fee`, `tickSpacing`, `token0`, `token1`, and block timestamp into one [Multicall3](https://github.com/mds1/multicall) `aggregate3` round trip. Hardcoded canonical Multicall3 address; works on every major EVM chain.
 * **`PoolSnapshot` enrichment** — every snapshot now carries `block_number`, `timestamp`, `chain_id` as optional fields. `LiveProvider` populates them from chain reads; `MockProvider` leaves them `None` to honestly signal "synthetic, not chain state."
+* **`PoolHealth` ergonomics for V3** — `CheckPoolHealth` now reports `fee_pips` (V3 fee tier in pips, `None` for V2), `tvl_in_token1` (symmetric to existing `tvl_in_token0`), and `tick_current` (V3 current tick, `None` for V2). All additive; no API breakage. `RugSignalReport` gets the new fields transitively.
+* **`provider.get_w3()`** — the underlying `web3.Web3` instance is now public, for callers who want to sign transactions or wire LiveProvider into their own broader chain tooling. DeFiPy stays read-only by design; bring your own signing opinion.
+* **Fork-and-evaluate worked example** — [`python/examples/state_twin_fork_evaluate.py`](./python/examples/state_twin_fork_evaluate.py) demonstrates the State Twin's multi-scenario reasoning pattern against live mainnet state. Pull a V3 pool snapshot once, fork the twin N ways under price scenarios, run primitives against each fork, aggregate into a recommendation. Walks through the pattern at [defipy.org/fork-evaluate/](https://defipy.org/fork-evaluate/).
 * **`[chain]` install extra** — `pip install defipy[chain]` adds `web3scout` and `web3.py` for users who want LiveProvider. Core install (no extras) remains free of any chain or LLM dependencies.
+* **`[agentic]` install extra** — `pip install defipy[agentic]` composes `[chain]` and `[mcp]` for the canonical *Python SDK for Agentic DeFi* full-stack install. Equivalent to `pip install defipy[chain,mcp]` but spelled with intent.
 
 V2.1 is a strict superset of v2.0 — every v2.0 primitive, MockProvider recipe, and MCP server pattern works identically. What changes is that the same primitives now run against live chain state without changing call shape.
 
-**What's deferred to v2.2:** Balancer and Stableswap LiveProvider implementations. V3 tick bitmap walking (active-liquidity-only is the v2.1 stance). Calls for those raise `NotImplementedError` pointing at the planned version.
+**What was deferred to v2.2 (now shipped):** Balancer and Stableswap LiveProvider reads landed in v2.2 (see above). Still open: V3 tick bitmap walking — V3 LiveProvider snapshots cover active-liquidity only, so primitives that depend on non-active-tick liquidity (e.g., `AssessLiquidityDepth`) and N-asset Balancer / rate-bearing Curve pools remain future work.
 
 ## v2.0 foundations
 
 The State Twin abstraction, agentic primitives, and MCP server pattern shipped in v2.0. v2.1 builds on that surface without changing it:
 
 * **`defipy.tools`** — self-describing schemas for a curated set of 10 leaf primitives, in [Model Context Protocol](https://modelcontextprotocol.io) (MCP) format. Any MCP-compatible client can discover and invoke DeFiPy primitives as tools.
-* **`defipy.twin`** — the **State Twin** abstraction. `MockProvider` ships four canonical synthetic pools (V2, V3, Balancer, Stableswap) for notebooks and tests; `LiveProvider` ships chain reads for V2 and V3 in v2.1.
+* **`defipy.twin`** — the **State Twin** abstraction. `MockProvider` ships four canonical synthetic pools (V2, V3, Balancer, Stableswap) for notebooks and tests; `LiveProvider` ships chain reads for all four families (V2/V3 in v2.1, Balancer/Stableswap in v2.2).
 * **MCP server demo** at [`python/mcp/`](./python/mcp/) — a stdio-transport server exposing DeFiPy's tools to Claude Desktop, Claude Code, or any MCP client. Install with `pip install defipy[mcp]` and see the [MCP server README](./python/mcp/README.md) for setup.
 
 ### What is MCP?
@@ -88,7 +105,9 @@ Claude reads the tool descriptions, picks `CheckPoolHealth`, calls it against a
 
 ## 🧩 What DeFiPy offers
 
-22 primitives across 7 categories. Each answers a specific LP question with exact math and returns a typed dataclass result:
+**7 [Core primitives](https://defipy.org/core-primitives/)** for cross-protocol pool execution — `Join`, `Swap`, `AddLiquidity`, `RemoveLiquidity`, `SwapDeposit`, `WithdrawSwap`, `LPQuote`. State-mutating operations that work across Uniswap V2/V3, Balancer, and Stableswap through a single abstract interface.
+
+**21 [Agentic primitives](https://defipy.org/agentic-primitives/)** across 7 categories. Each answers a specific LP question with exact math and returns a typed dataclass result:
 
 * **Position analysis** — "Why is my position losing money? What if price moves X%?" PnL decomposition (IL, fees, net result) and price-move scenarios across Uniswap V2/V3, Balancer, and Stableswap. Includes break-even pricing and time-to-breakeven analysis.
 * **Pool health** — "Is this pool healthy? Any rug signals?" TVL, LP concentration, activity, threshold-based rug detection, fee-anomaly checks (V2/V3).
@@ -113,14 +132,16 @@ DeFiPy requires **Python 3.10 or later**. Install via pip:
 > pip install defipy
 ```
 
-The core install is the pure analytics engine — AMM math, primitives, State Twin, and all 22 typed analytics functions. It has **zero web3 dependencies and zero LLM dependencies**. No chain reads, no RPC calls, no MCP. Chain reads come from [Web3Scout](https://github.com/defipy-devs/web3scout) (via the `[chain]` or `[book]` extras); MCP tool serving comes from the `[mcp]` extra. All optional.
+The core install is the pure analytics engine — AMM math, primitives, State Twin, and all 21 typed analytics functions. It has **zero web3 dependencies and zero LLM dependencies**. No chain reads, no RPC calls, no MCP. Chain reads come from [Web3Scout](https://github.com/defipy-devs/web3scout) (via the `[chain]` or `[book]` extras); MCP tool serving comes from the `[mcp]` extra. All optional.
+
+> **Note for zsh users (default on macOS):** wrap any install spec with extras in single quotes — `pip install 'defipy[agentic]'` — so zsh doesn't try to glob the brackets. Without the quotes, you'll see `zsh: no matches found`. Bash users can use either form.
 
 ### Chain install (LiveProvider — v2.1+)
 
 To use `LiveProvider` for on-chain pool snapshots, install the `[chain]` extra:
 
 ```
-> pip install defipy[chain]
+> pip install 'defipy[chain]'
 ```
 
 This pulls in `web3scout` (which `LiveProvider` uses internally for ABI loading, contract reads, and token-fetching) plus `web3.py`. With `[chain]` installed, you can construct twins from real chain state:
@@ -133,34 +154,36 @@ snapshot = provider.snapshot("uniswap_v2:0xB4e16d0168e52d35CaCD2c6185b44281Ec28C
 lp = StateTwinBuilder().build(snapshot)
 ```
 
-> **Note:** the `[chain]` extra pins `web3 < 7.0` because `web3scout 0.2.0` depends on `eth_utils.abi.get_abi_input_types`, which was removed in web3 7. If you have web3 7.x installed for other reasons, `pip install defipy[chain]` will downgrade it. Tracking upstream as v2.2 work.
+> **Note:** the `[chain]` extra pins `web3 < 7.0` because `web3scout 0.2.0` depends on `eth_utils.abi.get_abi_input_types`, which was removed in web3 7. If you have web3 7.x installed for other reasons, `pip install 'defipy[chain]'` will downgrade it. Tracking upstream as v2.2 work.
 
-### MCP install (Claude Desktop / Claude Code demo)
+### Agentic install (full LLM + chain stack)
 
-To run the MCP server that exposes DeFiPy's primitives as tools to Claude Desktop, Claude Code, or any MCP-compatible client, install the `[mcp]` extra:
+For users building LLM-driven systems against live chain state — the canonical *Python SDK for Agentic DeFi* use case — install the `[agentic]` extra:
 
 ```
-> pip install defipy[mcp]
+> pip install 'defipy[agentic]'
 ```
 
-This adds the [`mcp`](https://github.com/modelcontextprotocol/python-sdk) Python SDK on top of the core install. The MCP server itself lives at [`python/mcp/defipy_mcp_server.py`](./python/mcp/defipy_mcp_server.py); see [`python/mcp/README.md`](./python/mcp/README.md) for Claude Desktop and Claude Code configuration snippets.
+This composes `[chain]` and `[mcp]` in one step: `web3scout` and `web3.py` for `LiveProvider` chain reads, plus the `mcp` Python SDK for serving DeFiPy's primitives as tools to Claude Desktop, Claude Code, or any MCP-compatible client. Equivalent to `pip install defipy[chain,mcp]` but spelled with intent.
+
+The same `web3 < 7.0` pin from the `[chain]` extra applies.
 
-### Book install (chapter 9 agents)
+### MCP install (Claude Desktop / Claude Code demo)
 
-Chapter 9 of *Hands-On AMMs with Python* — *Building Autonomous DeFi Agents* — uses live chain integration via `web3scout`. To run those examples, install the `[book]` extra:
+To run the MCP server that exposes DeFiPy's primitives as tools to Claude Desktop, Claude Code, or any MCP-compatible client, install the `[mcp]` extra:
 
 ```
-> pip install defipy[book]
+> pip install 'defipy[mcp]'
 ```
 
-The `[book]` extra carries the same package set as `[chain]` (`web3scout` + `web3`). The split is intent-based — `[chain]` signals production live-state reads via LiveProvider; `[book]` signals textbook chapter 9 use. Either works for either purpose.
+This adds the [`mcp`](https://github.com/modelcontextprotocol/python-sdk) Python SDK on top of the core install. The MCP server itself lives at [`python/mcp/defipy_mcp_server.py`](./python/mcp/defipy_mcp_server.py); see [`python/mcp/README.md`](./python/mcp/README.md) for Claude Desktop and Claude Code configuration snippets.
 
 ### Anvil install (local Foundry workflows)
 
 If you're using `ExecuteScript` or `UniswapScriptHelper` against a local [Anvil](https://book.getfoundry.sh/anvil/) node and don't need the full `web3scout` event-monitoring stack, the lighter `[anvil]` extra just adds `web3.py`:
 
 ```
-> pip install defipy[anvil]
+> pip install 'defipy[anvil]'
 ```
 
 `[book]` and `[chain]` already include everything in `[anvil]`, so users on either of those don't need it separately.
@@ -196,13 +219,6 @@ See the [gmpy2 installation docs](https://gmpy2.readthedocs.io/en/latest/install
 DeFiPy is accompanied by educational resources for developers and researchers
 interested in on-chain analytics and DeFi modeling.
 
-### 📘 Textbook
-**_DeFiPy: Python SDK for On-Chain Analytics_**
-
-A comprehensive guide to DeFi analytics, AMM modeling, and simulation.
-
-🔗 **Buy on Amazon:** https://www.amazon.com/dp/B0G3RV5QRB
-
 ### 🎓 Course
 **On-Chain Analytics Foundations**
 
@@ -223,35 +239,29 @@ Topics include:
 
 The fastest way to see DeFiPy at work — pull a real Uniswap V2 pool's state from mainnet and run a primitive against it. Requires the `[chain]` install extra.
 
-    from defipy import AnalyzePosition
+    from defipy import CheckPoolHealth
     from defipy.twin import LiveProvider, StateTwinBuilder
-
-    # Pull live state from a real Uniswap V2 pool — WETH/USDC mainnet
-    provider = LiveProvider("https://eth-mainnet.g.alchemy.com/v2/<key>")
+    
+    # Pull live state from a real Uniswap V3 pool — USDC/WETH 500bps mainnet
+    provider = LiveProvider("https://mainnet.infura.io/v3/d2d6569915ec402b82c9379d033f8b9b")
     snapshot = provider.snapshot(
-        "uniswap_v2:0xB4e16d0168e52d35CaCD2c6185b44281Ec28C9Dc"
+        "uniswap_v3:0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640"
     )
     lp = StateTwinBuilder().build(snapshot)
-
+    lp.summary()
+    
     # Snapshot carries chain context — block_number, timestamp, chain_id
-    print(f"Block:   {snapshot.block_number}")
-    print(f"Reserves: {snapshot.token0_name}={snapshot.reserve0:.2f}, "
-          f"{snapshot.token1_name}={snapshot.reserve1:.2f}")
-
+    print(f"Block: {snapshot.block_number}")
+    
     # Run any primitive against the live twin — same call shape as MockProvider
-    result = AnalyzePosition().apply(
-        lp,
-        lp_init_amt=1.0,
-        entry_x_amt=1000,
-        entry_y_amt=3_000_000,
-    )
+    health = CheckPoolHealth().apply(lp)
+    print(f"Fee tier:        {health.fee_pips} pips")
+    print(f"TVL (USDC):      {health.tvl_in_token0:,.2f}")
+    print(f"TVL (WETH):      {health.tvl_in_token1:,.4f}")
+    print(f"Current tick:    {health.tick_current}")
+    print(f"Spot price:      {health.spot_price:.6f} WETH/USDC")
 
-    print(f"Diagnosis:   {result.diagnosis}")
-    print(f"Net PnL:     {result.net_pnl:.4f}")
-    print(f"IL %:        {result.il_percentage:.4f}")
-    print(f"Current val: {result.current_value:.4f}")
-
-The same shape works for V3 — swap `uniswap_v2:` for `uniswap_v3:` and the appropriate pool address (e.g. `0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640` for USDC/WETH 3000bps). V3 snapshots default to full-range ticks; pass `lwr_tick=N, upr_tick=N` to override. See the [LiveProvider docs](https://defipy.org/live-provider/) for block pinning, the V3 tick-range surface, and the active-liquidity-only caveat.
+The same shape works for V3 — swap `uniswap_v2:` for `uniswap_v3:` and the appropriate pool address (e.g. `0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640` for USDC/WETH 500bps). V3 snapshots default to full-range ticks; pass `lwr_tick=N, upr_tick=N` to override. See the [LiveProvider docs](https://defipy.org/live-provider/) for block pinning, the V3 tick-range surface, and the active-liquidity-only caveat.
 
 **No chain access?** Substitute `MockProvider` for `LiveProvider` and pass a recipe name (`"eth_dai_v2"`, `"eth_dai_v3"`, `"eth_dai_balancer_50_50"`, `"usdc_dai_stableswap_A10"`). Same primitive call, same result shape, no network needed:
 
@@ -307,19 +317,40 @@ To construct a Uniswap V3 pool directly (outside MockProvider's canonical recipe
 
 ## 🧪 Tests
 
-DeFiPy ships ~677 tests across primitives, tools, twin, packaging, and the MCP server dispatch layer. Run the full suite:
+DeFiPy ships ~686 tests across primitives, tools, twin, packaging, and the MCP server dispatch layer. Run the full suite:
 
     pytest python/test/ -v
 
-Run just the primitive suite (504 tests, no MCP or twin dependencies):
+Expect ~686 passed and 11 skipped — the skipped tests are the live-RPC suites, gated by the `DEFIPY_LIVE_RPC` environment variable. They run against real mainnet pools and aren't part of the default suite to keep CI deterministic.
+
+Run just the primitive suite (no MCP or twin dependencies):
 
     pytest python/test/primitives/ -v
 
-The twin suite includes opt-in live-RPC tests gated by the `DEFIPY_LIVE_RPC` environment variable — set it to a mainnet RPC URL to verify LiveProvider against real chain state:
+To run the opt-in live-RPC tests, set `DEFIPY_LIVE_RPC` to a mainnet RPC URL:
 
     DEFIPY_LIVE_RPC=https://eth-mainnet.g.alchemy.com/v2/<key> pytest -m live_rpc -v
 
+## 📄 Citation
+
+If you use DeFiPy in research, please cite the State Twin paper:
+
+```bibtex
+@misc{moore2026statetwins,
+  title={State Twins: An Off-Chain Substrate for Agentic Reasoning over Decentralized Finance Protocols},
+  author={Moore, Ian C.},
+  year={2026},
+  eprint={2605.11522},
+  archivePrefix={arXiv},
+  primaryClass={cs.DC},
+  doi={10.48550/arXiv.2605.11522}
+}
+```
+
 ## License
 Licensed under the Apache License, Version 2.0.  
 See [LICENSE](./LICENSE) and [NOTICE](./NOTICE) for details.  
 Portions of this project may include code from third-party projects under compatible open-source licenses.
+
+<!-- Machine-readable provenance anchor -->
+🔗 SPDX-Anchor: [anchorregistry.ai/AR-2026-YdPXB5g](https://anchorregistry.ai/AR-2026-YdPXB5g)

{defipy-2.1.0a2 → defipy-2.2.0}/DeFiPy.egg-info/requires.txt

@@ -10,15 +10,20 @@ uniswappy>=1.7.9
 balancerpy>=1.1.0
 stableswappy>=1.1.0
 
+[agentic]
+web3scout>=1.0.0
+web3<7.0,>=6.0
+mcp>=1.27.0
+
 [anvil]
 web3<7.0,>=6.0
 
 [book]
-web3scout>=0.2.0
+web3scout>=1.0.0
 web3<7.0,>=6.0
 
 [chain]
-web3scout>=0.2.0
+web3scout>=1.0.0
 web3<7.0,>=6.0
 
 [mcp]

{defipy-2.1.0a2 → defipy-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: DeFiPy
-Version: 2.1.0a2
+Version: 2.2.0
 Summary: Python SDK for Agentic DeFi
 Home-page: http://github.com/defipy-devs/defipy
 Author: icmoore
@@ -21,15 +21,19 @@ Requires-Dist: uniswappy>=1.7.9
 Requires-Dist: balancerpy>=1.1.0
 Requires-Dist: stableswappy>=1.1.0
 Provides-Extra: chain
-Requires-Dist: web3scout>=0.2.0; extra == "chain"
+Requires-Dist: web3scout>=1.0.0; extra == "chain"
 Requires-Dist: web3<7.0,>=6.0; extra == "chain"
 Provides-Extra: book
-Requires-Dist: web3scout>=0.2.0; extra == "book"
+Requires-Dist: web3scout>=1.0.0; extra == "book"
 Requires-Dist: web3<7.0,>=6.0; extra == "book"
 Provides-Extra: anvil
 Requires-Dist: web3<7.0,>=6.0; extra == "anvil"
 Provides-Extra: mcp
 Requires-Dist: mcp>=1.27.0; extra == "mcp"
+Provides-Extra: agentic
+Requires-Dist: web3scout>=1.0.0; extra == "agentic"
+Requires-Dist: web3<7.0,>=6.0; extra == "agentic"
+Requires-Dist: mcp>=1.27.0; extra == "agentic"
 Dynamic: author
 Dynamic: author-email
 Dynamic: description
@@ -51,29 +55,42 @@ Underneath, DeFiPy is modular by protocol:
 * [BalancerPy](https://github.com/defipy-devs/balancerpy)
 * [StableSwapPy](https://github.com/defipy-devs/stableswappy)
 
-For onchain event access and scripting, pair it with [Web3Scout](https://github.com/defipy-devs/web3scout) — a companion tool for [decoding pool events](https://defipy.readthedocs.io/en/latest/onchain/pool_events.html) and [interfacing with Solidity contracts](https://defipy.readthedocs.io/en/latest/onchain/testnet_sim_univ2.html).
+For onchain event access and scripting, use [LiveProvider](https://defipy.org/live-provider/) as of v2.1 — it pulls live pool state into the same primitive surface that runs against synthetic recipes. Under the hood it's powered by [Web3Scout](https://github.com/defipy-devs/web3scout); install via the `[chain]` extra (see below). For details on architecture behind [State Twins](https://defipy.org/twin-concept/), see paper [![arXiv](https://img.shields.io/badge/arXiv-2605.11522-b31b1b.svg)](https://arxiv.org/abs/2605.11522) 
 
-🔗 SPDX-Anchor: [anchorregistry.ai/AR-2026-YdPXB5g](https://anchorregistry.ai/AR-2026-YdPXB5g)
+## 🆕 What's new in v2.2
+
+v2.2 extends `LiveProvider` from Uniswap V2/V3 to **Balancer** and **Curve-style Stableswap** — chain reads now cover all four protocol families through the same `provider.snapshot(...)` → `StateTwinBuilder().build(...)` flow.
+
+* **Balancer LiveProvider** — `provider.snapshot("balancer:0xADDR")` builds a `BalancerPoolSnapshot` from a real Balancer V2 weighted pool (2-asset). Two block-pinned round trips, since token balances live on the Vault keyed by `poolId`. Normalized weights read honestly; reserves decimal-adjusted.
+* **Stableswap LiveProvider** — `provider.snapshot("stableswap:0xADDR")` builds an N-coin `StableswapPoolSnapshot` (N ∈ {2, 3}, e.g. the DAI/USDC/USDT 3pool) from a real Curve plain pool. Coin count comes from an `n_coins` hint or an automatic `coins(0..K)` probe; plain pools only.
+* **`multicall_aggregate3_args`** — an argument-bearing Multicall3 batch (encodes calldata args, optional `allow_failure`) powering the Balancer/Curve reads alongside the no-arg getters, all block-pinned. The existing no-arg `multicall_aggregate3` and the V3 path are unchanged.
+* **web3scout `>= 1.0.0`** — the `[chain]` / `[book]` / `[agentic]` extras now pin web3scout 1.0, which carries the Balancer/Curve read ABIs.
+
+See the [CHANGELOG](./CHANGELOG.md) for the full v2.2 entry. v2.2 is a strict superset of v2.1.
 
 ## 🆕 What's new in v2.1
 
-v2.1 makes the State Twin **real**. `LiveProvider` ships for Uniswap V2 and V3 — chain reads compose with every primitive in the library, the same way `MockProvider` recipes do. The "what would happen if?" loop is now local: pull state once, simulate forever, decide before executing.
+v2.1 makes the [State Twin](https://defipy.org/twin-concept/) **real** — the substrate formalized in [our arXiv paper](https://arxiv.org/abs/2605.11522). `LiveProvider` ships for Uniswap V2 and V3 — chain reads compose with every primitive in the library, the same way `MockProvider` recipes do. The "what would happen if?" loop is now local: pull state once, simulate forever, decide before executing.
 
 * **`LiveProvider`** — `provider.snapshot("uniswap_v2:0xADDR")` and `provider.snapshot("uniswap_v3:0xADDR")` build `V2PoolSnapshot` and `V3PoolSnapshot` from real on-chain state. Block pinning is automatic — `"latest"` resolves once at the top of `.snapshot()` and every read inside that snapshot pins to the same block. Pass `block_number=N` for historical reads.
 * **Multicall3 batching for V3** — V3 snapshots batch `slot0`, `liquidity`, `fee`, `tickSpacing`, `token0`, `token1`, and block timestamp into one [Multicall3](https://github.com/mds1/multicall) `aggregate3` round trip. Hardcoded canonical Multicall3 address; works on every major EVM chain.
 * **`PoolSnapshot` enrichment** — every snapshot now carries `block_number`, `timestamp`, `chain_id` as optional fields. `LiveProvider` populates them from chain reads; `MockProvider` leaves them `None` to honestly signal "synthetic, not chain state."
+* **`PoolHealth` ergonomics for V3** — `CheckPoolHealth` now reports `fee_pips` (V3 fee tier in pips, `None` for V2), `tvl_in_token1` (symmetric to existing `tvl_in_token0`), and `tick_current` (V3 current tick, `None` for V2). All additive; no API breakage. `RugSignalReport` gets the new fields transitively.
+* **`provider.get_w3()`** — the underlying `web3.Web3` instance is now public, for callers who want to sign transactions or wire LiveProvider into their own broader chain tooling. DeFiPy stays read-only by design; bring your own signing opinion.
+* **Fork-and-evaluate worked example** — [`python/examples/state_twin_fork_evaluate.py`](./python/examples/state_twin_fork_evaluate.py) demonstrates the State Twin's multi-scenario reasoning pattern against live mainnet state. Pull a V3 pool snapshot once, fork the twin N ways under price scenarios, run primitives against each fork, aggregate into a recommendation. Walks through the pattern at [defipy.org/fork-evaluate/](https://defipy.org/fork-evaluate/).
 * **`[chain]` install extra** — `pip install defipy[chain]` adds `web3scout` and `web3.py` for users who want LiveProvider. Core install (no extras) remains free of any chain or LLM dependencies.
+* **`[agentic]` install extra** — `pip install defipy[agentic]` composes `[chain]` and `[mcp]` for the canonical *Python SDK for Agentic DeFi* full-stack install. Equivalent to `pip install defipy[chain,mcp]` but spelled with intent.
 
 V2.1 is a strict superset of v2.0 — every v2.0 primitive, MockProvider recipe, and MCP server pattern works identically. What changes is that the same primitives now run against live chain state without changing call shape.
 
-**What's deferred to v2.2:** Balancer and Stableswap LiveProvider implementations. V3 tick bitmap walking (active-liquidity-only is the v2.1 stance). Calls for those raise `NotImplementedError` pointing at the planned version.
+**What was deferred to v2.2 (now shipped):** Balancer and Stableswap LiveProvider reads landed in v2.2 (see above). Still open: V3 tick bitmap walking — V3 LiveProvider snapshots cover active-liquidity only, so primitives that depend on non-active-tick liquidity (e.g., `AssessLiquidityDepth`) and N-asset Balancer / rate-bearing Curve pools remain future work.
 
 ## v2.0 foundations
 
 The State Twin abstraction, agentic primitives, and MCP server pattern shipped in v2.0. v2.1 builds on that surface without changing it:
 
 * **`defipy.tools`** — self-describing schemas for a curated set of 10 leaf primitives, in [Model Context Protocol](https://modelcontextprotocol.io) (MCP) format. Any MCP-compatible client can discover and invoke DeFiPy primitives as tools.
-* **`defipy.twin`** — the **State Twin** abstraction. `MockProvider` ships four canonical synthetic pools (V2, V3, Balancer, Stableswap) for notebooks and tests; `LiveProvider` ships chain reads for V2 and V3 in v2.1.
+* **`defipy.twin`** — the **State Twin** abstraction. `MockProvider` ships four canonical synthetic pools (V2, V3, Balancer, Stableswap) for notebooks and tests; `LiveProvider` ships chain reads for all four families (V2/V3 in v2.1, Balancer/Stableswap in v2.2).
 * **MCP server demo** at [`python/mcp/`](./python/mcp/) — a stdio-transport server exposing DeFiPy's tools to Claude Desktop, Claude Code, or any MCP client. Install with `pip install defipy[mcp]` and see the [MCP server README](./python/mcp/README.md) for setup.
 
 ### What is MCP?
@@ -88,7 +105,9 @@ Claude reads the tool descriptions, picks `CheckPoolHealth`, calls it against a
 
 ## 🧩 What DeFiPy offers
 
-22 primitives across 7 categories. Each answers a specific LP question with exact math and returns a typed dataclass result:
+**7 [Core primitives](https://defipy.org/core-primitives/)** for cross-protocol pool execution — `Join`, `Swap`, `AddLiquidity`, `RemoveLiquidity`, `SwapDeposit`, `WithdrawSwap`, `LPQuote`. State-mutating operations that work across Uniswap V2/V3, Balancer, and Stableswap through a single abstract interface.
+
+**21 [Agentic primitives](https://defipy.org/agentic-primitives/)** across 7 categories. Each answers a specific LP question with exact math and returns a typed dataclass result:
 
 * **Position analysis** — "Why is my position losing money? What if price moves X%?" PnL decomposition (IL, fees, net result) and price-move scenarios across Uniswap V2/V3, Balancer, and Stableswap. Includes break-even pricing and time-to-breakeven analysis.
 * **Pool health** — "Is this pool healthy? Any rug signals?" TVL, LP concentration, activity, threshold-based rug detection, fee-anomaly checks (V2/V3).
@@ -113,14 +132,16 @@ DeFiPy requires **Python 3.10 or later**. Install via pip:
 > pip install defipy
 ```
 
-The core install is the pure analytics engine — AMM math, primitives, State Twin, and all 22 typed analytics functions. It has **zero web3 dependencies and zero LLM dependencies**. No chain reads, no RPC calls, no MCP. Chain reads come from [Web3Scout](https://github.com/defipy-devs/web3scout) (via the `[chain]` or `[book]` extras); MCP tool serving comes from the `[mcp]` extra. All optional.
+The core install is the pure analytics engine — AMM math, primitives, State Twin, and all 21 typed analytics functions. It has **zero web3 dependencies and zero LLM dependencies**. No chain reads, no RPC calls, no MCP. Chain reads come from [Web3Scout](https://github.com/defipy-devs/web3scout) (via the `[chain]` or `[book]` extras); MCP tool serving comes from the `[mcp]` extra. All optional.
+
+> **Note for zsh users (default on macOS):** wrap any install spec with extras in single quotes — `pip install 'defipy[agentic]'` — so zsh doesn't try to glob the brackets. Without the quotes, you'll see `zsh: no matches found`. Bash users can use either form.
 
 ### Chain install (LiveProvider — v2.1+)
 
 To use `LiveProvider` for on-chain pool snapshots, install the `[chain]` extra:
 
 ```
-> pip install defipy[chain]
+> pip install 'defipy[chain]'
 ```
 
 This pulls in `web3scout` (which `LiveProvider` uses internally for ABI loading, contract reads, and token-fetching) plus `web3.py`. With `[chain]` installed, you can construct twins from real chain state:
@@ -133,34 +154,36 @@ snapshot = provider.snapshot("uniswap_v2:0xB4e16d0168e52d35CaCD2c6185b44281Ec28C
 lp = StateTwinBuilder().build(snapshot)
 ```
 
-> **Note:** the `[chain]` extra pins `web3 < 7.0` because `web3scout 0.2.0` depends on `eth_utils.abi.get_abi_input_types`, which was removed in web3 7. If you have web3 7.x installed for other reasons, `pip install defipy[chain]` will downgrade it. Tracking upstream as v2.2 work.
+> **Note:** the `[chain]` extra pins `web3 < 7.0` because `web3scout 0.2.0` depends on `eth_utils.abi.get_abi_input_types`, which was removed in web3 7. If you have web3 7.x installed for other reasons, `pip install 'defipy[chain]'` will downgrade it. Tracking upstream as v2.2 work.
 
-### MCP install (Claude Desktop / Claude Code demo)
+### Agentic install (full LLM + chain stack)
 
-To run the MCP server that exposes DeFiPy's primitives as tools to Claude Desktop, Claude Code, or any MCP-compatible client, install the `[mcp]` extra:
+For users building LLM-driven systems against live chain state — the canonical *Python SDK for Agentic DeFi* use case — install the `[agentic]` extra:
 
 ```
-> pip install defipy[mcp]
+> pip install 'defipy[agentic]'
 ```
 
-This adds the [`mcp`](https://github.com/modelcontextprotocol/python-sdk) Python SDK on top of the core install. The MCP server itself lives at [`python/mcp/defipy_mcp_server.py`](./python/mcp/defipy_mcp_server.py); see [`python/mcp/README.md`](./python/mcp/README.md) for Claude Desktop and Claude Code configuration snippets.
+This composes `[chain]` and `[mcp]` in one step: `web3scout` and `web3.py` for `LiveProvider` chain reads, plus the `mcp` Python SDK for serving DeFiPy's primitives as tools to Claude Desktop, Claude Code, or any MCP-compatible client. Equivalent to `pip install defipy[chain,mcp]` but spelled with intent.
+
+The same `web3 < 7.0` pin from the `[chain]` extra applies.
 
-### Book install (chapter 9 agents)
+### MCP install (Claude Desktop / Claude Code demo)
 
-Chapter 9 of *Hands-On AMMs with Python* — *Building Autonomous DeFi Agents* — uses live chain integration via `web3scout`. To run those examples, install the `[book]` extra:
+To run the MCP server that exposes DeFiPy's primitives as tools to Claude Desktop, Claude Code, or any MCP-compatible client, install the `[mcp]` extra:
 
 ```
-> pip install defipy[book]
+> pip install 'defipy[mcp]'
 ```
 
-The `[book]` extra carries the same package set as `[chain]` (`web3scout` + `web3`). The split is intent-based — `[chain]` signals production live-state reads via LiveProvider; `[book]` signals textbook chapter 9 use. Either works for either purpose.
+This adds the [`mcp`](https://github.com/modelcontextprotocol/python-sdk) Python SDK on top of the core install. The MCP server itself lives at [`python/mcp/defipy_mcp_server.py`](./python/mcp/defipy_mcp_server.py); see [`python/mcp/README.md`](./python/mcp/README.md) for Claude Desktop and Claude Code configuration snippets.
 
 ### Anvil install (local Foundry workflows)
 
 If you're using `ExecuteScript` or `UniswapScriptHelper` against a local [Anvil](https://book.getfoundry.sh/anvil/) node and don't need the full `web3scout` event-monitoring stack, the lighter `[anvil]` extra just adds `web3.py`:
 
 ```
-> pip install defipy[anvil]
+> pip install 'defipy[anvil]'
 ```
 
 `[book]` and `[chain]` already include everything in `[anvil]`, so users on either of those don't need it separately.
@@ -196,13 +219,6 @@ See the [gmpy2 installation docs](https://gmpy2.readthedocs.io/en/latest/install
 DeFiPy is accompanied by educational resources for developers and researchers
 interested in on-chain analytics and DeFi modeling.
 
-### 📘 Textbook
-**_DeFiPy: Python SDK for On-Chain Analytics_**
-
-A comprehensive guide to DeFi analytics, AMM modeling, and simulation.
-
-🔗 **Buy on Amazon:** https://www.amazon.com/dp/B0G3RV5QRB
-
 ### 🎓 Course
 **On-Chain Analytics Foundations**
 
@@ -223,35 +239,29 @@ Topics include:
 
 The fastest way to see DeFiPy at work — pull a real Uniswap V2 pool's state from mainnet and run a primitive against it. Requires the `[chain]` install extra.
 
-    from defipy import AnalyzePosition
+    from defipy import CheckPoolHealth
     from defipy.twin import LiveProvider, StateTwinBuilder
-
-    # Pull live state from a real Uniswap V2 pool — WETH/USDC mainnet
-    provider = LiveProvider("https://eth-mainnet.g.alchemy.com/v2/<key>")
+    
+    # Pull live state from a real Uniswap V3 pool — USDC/WETH 500bps mainnet
+    provider = LiveProvider("https://mainnet.infura.io/v3/d2d6569915ec402b82c9379d033f8b9b")
     snapshot = provider.snapshot(
-        "uniswap_v2:0xB4e16d0168e52d35CaCD2c6185b44281Ec28C9Dc"
+        "uniswap_v3:0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640"
     )
     lp = StateTwinBuilder().build(snapshot)
-
+    lp.summary()
+    
     # Snapshot carries chain context — block_number, timestamp, chain_id
-    print(f"Block:   {snapshot.block_number}")
-    print(f"Reserves: {snapshot.token0_name}={snapshot.reserve0:.2f}, "
-          f"{snapshot.token1_name}={snapshot.reserve1:.2f}")
-
+    print(f"Block: {snapshot.block_number}")
+    
     # Run any primitive against the live twin — same call shape as MockProvider
-    result = AnalyzePosition().apply(
-        lp,
-        lp_init_amt=1.0,
-        entry_x_amt=1000,
-        entry_y_amt=3_000_000,
-    )
+    health = CheckPoolHealth().apply(lp)
+    print(f"Fee tier:        {health.fee_pips} pips")
+    print(f"TVL (USDC):      {health.tvl_in_token0:,.2f}")
+    print(f"TVL (WETH):      {health.tvl_in_token1:,.4f}")
+    print(f"Current tick:    {health.tick_current}")
+    print(f"Spot price:      {health.spot_price:.6f} WETH/USDC")
 
-    print(f"Diagnosis:   {result.diagnosis}")
-    print(f"Net PnL:     {result.net_pnl:.4f}")
-    print(f"IL %:        {result.il_percentage:.4f}")
-    print(f"Current val: {result.current_value:.4f}")
-
-The same shape works for V3 — swap `uniswap_v2:` for `uniswap_v3:` and the appropriate pool address (e.g. `0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640` for USDC/WETH 3000bps). V3 snapshots default to full-range ticks; pass `lwr_tick=N, upr_tick=N` to override. See the [LiveProvider docs](https://defipy.org/live-provider/) for block pinning, the V3 tick-range surface, and the active-liquidity-only caveat.
+The same shape works for V3 — swap `uniswap_v2:` for `uniswap_v3:` and the appropriate pool address (e.g. `0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640` for USDC/WETH 500bps). V3 snapshots default to full-range ticks; pass `lwr_tick=N, upr_tick=N` to override. See the [LiveProvider docs](https://defipy.org/live-provider/) for block pinning, the V3 tick-range surface, and the active-liquidity-only caveat.
 
 **No chain access?** Substitute `MockProvider` for `LiveProvider` and pass a recipe name (`"eth_dai_v2"`, `"eth_dai_v3"`, `"eth_dai_balancer_50_50"`, `"usdc_dai_stableswap_A10"`). Same primitive call, same result shape, no network needed:
 
@@ -307,19 +317,40 @@ To construct a Uniswap V3 pool directly (outside MockProvider's canonical recipe
 
 ## 🧪 Tests
 
-DeFiPy ships ~677 tests across primitives, tools, twin, packaging, and the MCP server dispatch layer. Run the full suite:
+DeFiPy ships ~686 tests across primitives, tools, twin, packaging, and the MCP server dispatch layer. Run the full suite:
 
     pytest python/test/ -v
 
-Run just the primitive suite (504 tests, no MCP or twin dependencies):
+Expect ~686 passed and 11 skipped — the skipped tests are the live-RPC suites, gated by the `DEFIPY_LIVE_RPC` environment variable. They run against real mainnet pools and aren't part of the default suite to keep CI deterministic.
+
+Run just the primitive suite (no MCP or twin dependencies):
 
     pytest python/test/primitives/ -v
 
-The twin suite includes opt-in live-RPC tests gated by the `DEFIPY_LIVE_RPC` environment variable — set it to a mainnet RPC URL to verify LiveProvider against real chain state:
+To run the opt-in live-RPC tests, set `DEFIPY_LIVE_RPC` to a mainnet RPC URL:
 
     DEFIPY_LIVE_RPC=https://eth-mainnet.g.alchemy.com/v2/<key> pytest -m live_rpc -v
 
+## 📄 Citation
+
+If you use DeFiPy in research, please cite the State Twin paper:
+
+```bibtex
+@misc{moore2026statetwins,
+  title={State Twins: An Off-Chain Substrate for Agentic Reasoning over Decentralized Finance Protocols},
+  author={Moore, Ian C.},
+  year={2026},
+  eprint={2605.11522},
+  archivePrefix={arXiv},
+  primaryClass={cs.DC},
+  doi={10.48550/arXiv.2605.11522}
+}
+```
+
 ## License
 Licensed under the Apache License, Version 2.0.  
 See [LICENSE](./LICENSE) and [NOTICE](./NOTICE) for details.  
 Portions of this project may include code from third-party projects under compatible open-source licenses.
+
+<!-- Machine-readable provenance anchor -->
+🔗 SPDX-Anchor: [anchorregistry.ai/AR-2026-YdPXB5g](https://anchorregistry.ai/AR-2026-YdPXB5g)