State Twins: An Off-Chain Substrate for Agentic Reasoning over Decentralized Finance Protocols

TL;DR

The paper introduces the State Twin, an off-chain replica of DeFi AMM pools that enables agentic reasoning, backtesting, and analysis without on-chain constraints, improving flexibility and speed.

Contribution

It formalizes the State Twin as an off-chain substrate for DeFi protocols, enabling replay, branching, and counterfactual analysis while maintaining mathematical fidelity.

Findings

Proves fidelity bounds between twin and on-chain states.

Demonstrates sub-second replay of multiple scenarios.

Provides an open-source Python toolkit for DeFi analysis.

Abstract

We introduce the State Twin: a typed, in-memory, replayable replica of an on-chain automated market maker (AMM) pool that serves as a substrate for agentic reasoning over decentralized finance (DeFi) protocols. Agentic DeFi stacks today couple reasoning to chain time, since every "what if?" query incurs a new RPC read or a real transaction, so the agent's effective action space is bounded by block confirmation latency and gas. We argue this coupling is a structural problem rather than a performance one, and that the missing layer is an off-chain substrate that preserves the protocol's exact mathematics while admitting the operations on-chain state cannot: forking, replay, branching, counterfactual rollout. We formalize each AMM family (Uniswap V2, V3, Balancer, Stableswap) as a discrete-time controlled dynamical system, prove a quantitative fidelity bound on the divergence between twin and chain, and give the open architecture used in DeFiPy v2, an open-source Python toolkit that ships the State Twin substrate and a reference Model Context Protocol server exposing typed analytical primitives as LLM tools. The same primitive (i.e., one Python class, one calling pattern) serves a notebook quant, a backtest, and an LLM agent without modification. We close with a fork-and-evaluate worked example: a single live RPC read seeds N independent in-memory twins under distinct price-shock scenarios, in sub-second wall-clock time. The contribution is the substrate, not a particular agent, which is what the specification of what an agentic DeFi substrate must look like