Core Concepts
Key terms and ideas you'll encounter using Shepherd
Digital Twin
A digital twin is a high-fidelity replica of your protocol running in a sandboxed environment. It includes your deployed contracts, real balances, historical transactions, and the surrounding ecosystem (oracles, DEX pools, routers, etc.), all captured at a specific block number.
Shepherd uses your digital twin as a safe testing ground. Attacks run against the twin, not your protocol deployment.
Learn more about Digital Twins
Snapshot
A snapshot defines "your protocol at time T." It captures:
Chain and block number
Deployed contract addresses
Proxy-to-implementation mappings
Bytecode hashes
Configuration values (LTV ratios, fee parameters, orcale addresses, admin roles, etc.)
External dependencies (DEX pools, oracles, routers, etc.)
Snapshots anchor the digital twin to onchain reality. This matters because what's in your repository isn't always what's deployed, and most exploits happen at the boundary between intended code and deployed state.
Exploit Proof
An exploit proof is Shepherd's primary output. It's a validated demonstration that a specific vulnerability is exploitable, consisting of:
The exact transaction sequence that triggers the exploit
State changes at each step (balance diffs, storage mutations)
The attack path through your contracts
A reproducible test (Foundry/Hardhat) you can run locally
Unlike a flag or alert, an exploit proof shows the attack working, not just that a pattern exists in the code.
Episode
An episode is a single test run - one hypothesis tested against your digital twin. Each episode records:
The hypothesis being tested
The exact transaction sequence executed
State diffs (what changed in balances, storage, etc.)
Whether the exploit succeeded or failed
A replay pack for reproducibility
Episodes accumulate into an episode library, a complete record of what's been tested and what was found.
Knowledge Graph
Shepherd builds a structured model of your protocol's architecture, not just a call graph, but a typed map of contracts, functions, roles, assets, dependencies, and how they relate to each other. Each node and edge is backed by evidence from chain data, source code, or runtime traces.
The knowledge graph lets Shepherd's agents navigate cross-contract interactions systematically rather than reasoning about your entire codebase at once.
Adversarial Agents
Shepherd's AI agents are autonomous systems that generate and execute strategies against your digital twin. They reason about DeFi attack patterns across both the code layer (logic bugs, access control, reentrancy) and the economic layer (oracle manipulation, flash loan sequences, liquidation cascades).
When an agent discovers a viable attack path, it executes the full sequence on the fork and captures the results as an exploit proof.
Invariant
An invariant is a property of your protocol that should always hold true. For example:
"Total deposits should always be ≥ total withdrawals"
"No single transaction should be able to drain more than X% of the vault"
"Only the admin role can call upgradeProxy()"
Shepherd tests invariants during episodes and reports any violations as part of the exploit proof.
Last updated