Digital Twin
A digital twin is the foundation of how Shepherd tests your protocol. This page explains what it is, what it contains, and why it matters.
What is a Digital Twin?
A digital twin is an isolated, high-fidelity replica of your protocol and the onchain environment it operates in. It captures:
Your deployed contracts with their current state
Account balances and token holdings
External protocols your contracts interact with (DEXs, oracles, lending pools)
Current market conditions and liquidity
The twin runs in a sandboxed environment. Nothing that happens in the twin affects production. It exists so Shepherd's agents can attack your protocol under realistic conditions without risk.
Why not just test against source code?
Source code alone doesn't capture how a protocol behaves in production. A few reasons:
Repo ≠ deployment: Proxy contracts, configuration parameters, and admin state can differ between what's in your repo and what's actually onchain. Many exploits target these gaps.
Composability matters: Your contracts dont exist in isolation. They call oracles, route through DEXs, interact with lending pools, etc. A vulnerability might only be exploitable through a specific interaction with an external protocol, which you'd miss by analyzing your code alone.
State-dependent bugs: Some vulnerabilities only appear under specific conditions: a particular liquidity level, a certain oracle price, a specific ordering of transactions. The twin preserves these conditions.
Offchain inputs matter: Many protocols depend on data that originates offchain like oracle price feeds, bridge messages, keeper transactions, and API-driven parameters. The twin can simulate external data being fed into your smart contracts, testing how your onchain logic behaves under manipulated or unexpected offchain conditions. This is particularly relevant for systems with both offchain and onchain components.
What a Twin Contains
A Shepherd digital twin consists of 4 artifacts:
1. Snapshot
The snapshot defines your protocol at a specific point in time. It records:
Chain + block number
Pins the twin to a specific onchain state
Deployed addresses
All contracts in scope
Proxy → implementation mapping
What code is actually running
Bytecode hashes
Verifies deployed code matches source
Configuration values
LTV ratios, fee params, oracle addresses, admin roles
Dependency set
External contracts your protocol interacts with
2. Knowledge Graph
A structured model of your protocol's architecture - contracts, functions, roles, assets. dependencies, and their relationships. Every node and edge is backed by evidence from chain data, source code, or runtime traces.
3. Episode Library
A growing record of every test run against your twin. Each episode stores the hypothesis tested, the transaction sequence executed, state diffs, invariant results, and replay pack for reproducibility.
4. Invariant Definitions
Properties that should always hold true for your protocol. Shepherd checks these during every episode and flags violations.
Twin Lifecycle
Creation
When you onboard, Shepherd takes a snapshot of your deployed protocol and builds the initial twin. This involves reading onchain state, resolving proxies, and mapping dependencies.
Updates
Your twin stays current with your protocol. When you deploy an upgrade or change a parameter, a new snapshot is taken and the twin is rebuilt. Previous episodes become regression tests - Shepherd re-runs them against the updated twin to verify that changes didn't introduce old vulnerabilities.
Accumulation
Over time, the twin accumulates intelligence. Each episode adds to the knowledge graph and episode library. This means Shepherd's understanding of your protocol deepens with every test cycle. Coverage compounds rather than resetting with each engagement.
Last updated