DeFiPy 2.1.0__tar.gz → 2.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: DeFiPy
-Version: 2.1.0
+Version: 2.2.0
 Summary: Python SDK for Agentic DeFi
 Home-page: http://github.com/defipy-devs/defipy
 Author: icmoore
@@ -21,17 +21,17 @@ 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>=0.2.0; 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
@@ -55,13 +55,22 @@ 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, 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 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](https://defipy.org/twin-concept/) **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.
@@ -74,14 +83,14 @@ v2.1 makes the [State Twin](https://defipy.org/twin-concept/) **real**. `LivePro
 
 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 raise `NotImplementedError` pointing at the planned version. V3 tick bitmap walking is also v2.2 work; in v2.1, V3 LiveProvider snapshots cover active-liquidity only — primitives that depend on non-active-tick liquidity (e.g., `AssessLiquidityDepth`) ship in v2.2.
+**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?
@@ -125,12 +134,14 @@ DeFiPy requires **Python 3.10 or later**. Install via pip:
 
 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:
@@ -143,14 +154,14 @@ 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.
 
 ### Agentic install (full LLM + chain stack)
 
 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[agentic]
+> pip install 'defipy[agentic]'
 ```
 
 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.
@@ -162,27 +173,17 @@ The same `web3 < 7.0` pin from the `[chain]` extra applies.
 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[mcp]
+> pip install 'defipy[mcp]'
 ```
 
 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.
 
-### Book install (chapter 9 agents)
-
-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:
-
-```
-> pip install defipy[book]
-```
-
-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.
-
 ### 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.
@@ -218,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**
 
@@ -245,34 +239,27 @@ 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,
-    )
-
-    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}")
+    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")
 
 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.
 
@@ -344,7 +331,26 @@ 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.0 → defipy-2.2.0}/DeFiPy.egg-info/requires.txt

@@ -11,7 +11,7 @@ balancerpy>=1.1.0
 stableswappy>=1.1.0
 
 [agentic]
-web3scout>=0.2.0
+web3scout>=1.0.0
 web3<7.0,>=6.0
 mcp>=1.27.0
 
@@ -19,11 +19,11 @@ mcp>=1.27.0
 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.0 → defipy-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: DeFiPy
-Version: 2.1.0
+Version: 2.2.0
 Summary: Python SDK for Agentic DeFi
 Home-page: http://github.com/defipy-devs/defipy
 Author: icmoore
@@ -21,17 +21,17 @@ 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>=0.2.0; 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
@@ -55,13 +55,22 @@ 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, 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 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](https://defipy.org/twin-concept/) **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.
@@ -74,14 +83,14 @@ v2.1 makes the [State Twin](https://defipy.org/twin-concept/) **real**. `LivePro
 
 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 raise `NotImplementedError` pointing at the planned version. V3 tick bitmap walking is also v2.2 work; in v2.1, V3 LiveProvider snapshots cover active-liquidity only — primitives that depend on non-active-tick liquidity (e.g., `AssessLiquidityDepth`) ship in v2.2.
+**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?
@@ -125,12 +134,14 @@ DeFiPy requires **Python 3.10 or later**. Install via pip:
 
 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:
@@ -143,14 +154,14 @@ 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.
 
 ### Agentic install (full LLM + chain stack)
 
 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[agentic]
+> pip install 'defipy[agentic]'
 ```
 
 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.
@@ -162,27 +173,17 @@ The same `web3 < 7.0` pin from the `[chain]` extra applies.
 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[mcp]
+> pip install 'defipy[mcp]'
 ```
 
 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.
 
-### Book install (chapter 9 agents)
-
-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:
-
-```
-> pip install defipy[book]
-```
-
-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.
-
 ### 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.
@@ -218,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**
 
@@ -245,34 +239,27 @@ 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,
-    )
-
-    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}")
+    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")
 
 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.
 
@@ -344,7 +331,26 @@ 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)