defipy.twin

The defipy.twin module provides the State Twin abstraction — a protocol-agnostic way to construct exchange objects from declarative pool snapshots.

Key exports

StateTwinProvider — ABC defining the snapshot(pool_id) → PoolSnapshot contract
MockProvider — synthetic pool snapshots for notebooks, tests, and demos (4 canonical recipes)
LiveProvider — on-chain pool snapshots (v2.1; stub ships in v2.0)
StateTwinBuilder — dispatches on snapshot type to construct the protocol’s exchange object
PoolSnapshot — base class; subclasses V2PoolSnapshot, V3PoolSnapshot, BalancerPoolSnapshot, StableswapPoolSnapshot

Usage

from defipy.twin import MockProvider, StateTwinBuilder

provider = MockProvider()
snapshot = provider.snapshot("eth_dai_v2")
lp = StateTwinBuilder().build(snapshot)

# lp is now a live UniswapExchange — pass it to any primitive
from defipy import CheckPoolHealth
result = CheckPoolHealth().apply(lp)

Available MockProvider recipes

Recipe	Protocol	Reserves
`eth_dai_v2`	Uniswap V2	1000 ETH / 100000 DAI
`eth_dai_v3`	Uniswap V3	1000 ETH / 100000 DAI, full-range, fee=3000
`eth_dai_balancer_50_50`	Balancer 2-asset	1000 ETH / 100000 DAI, 50/50 weights
`usdc_dai_stableswap_A10`	Stableswap 2-asset	100000 USDC / 100000 DAI, A=10

For the full conceptual treatment — including custom providers, the LiveProvider stub, and the snapshot → builder → primitive pipeline — see the Twin Concept.