pruf

Massive Proof of Concept engine for web3 bug hunters.

pruf has a fast Rust core built on the Foundry ecosystem (revm and alloy) with a thin Python API on top. The core executes EVM transactions in-process. The Python layer provides modular, composable, and serializable building blocks.

Example

Demonstrate an MEV sandwich attack on a Solidity project.

from pruf import Solidity
from pruf.blockchain import Ethereum, Base, Polygon

env = Ethereum() | Base() | Polygon()
env.from_config("https://example.com/project_audit_scopes.json")

victim_pre = (
    env.contracts.TokenA.approve(env.addresses.Marketplace, "12345e6")
    | env.contracts.Marketplace.swap(env.addresses.TokenA, env.addresses.TokenB, "12345e6").gas_price("1e6")
)

attacker_mid = env.contracts.Marketplace.swap(
    env.addresses.TokenA, env.addresses.TokenB, "12345e6"
).gas_price("1e18")

victim_post = env.contracts.Marketplace.swap(
    env.addresses.TokenB, env.addresses.TokenA, "12345e6"
)

poc = Solidity(env)
poc.watch(env.contracts.TokenA.balanceOf("0xabc"))
poc.watch(env.contracts.TokenA.balanceOf("0xwyz"), label="attacker balance")

# Watch a computed value: the lambda receives an evaluator that
# resolves a view Call to its decoded value.
poc.watch(
    lambda ev: ev(env.contracts.TokenA.balanceOf("0xabc"))
    + ev(env.contracts.TokenB.balanceOf("0xabc")),
    label="total balance",
)

poc.act(victim_pre, actor=poc.actor.Victim)
poc.act(attacker_mid, actor=poc.actor.Attacker)
poc.act(victim_post, actor=poc.actor.Victim)

poc.proof()
poc.export_as_json("myfile.json")

Generating scopes documents

The pruf-scopes command generates a scopes JSON from a Foundry or Hardhat project, so you never write deployment JSON by hand. The command reads the compiled artifacts and deployment records, then writes deploy steps with real constructor arguments.

From a Foundry project:

uv run pruf-scopes foundry \
  --out out \
  --broadcast broadcast \
  --out-file scopes.json

The broadcast can be a run-latest.json file or the broadcast directory. The tool picks the newest single-chain run.

From a Hardhat project (hardhat-deploy):

uv run pruf-scopes hardhat \
  --artifacts artifacts \
  --deployments deployments \
  --network sepolia \
  --out-file scopes.json

You can load the generated file with env.from_config("scopes.json") and run the PoC exactly as the example above shows.

Options:

• --chain-name NAME: set the chain key in the generated document
• --chain-id ID: set the chain id (default: from the artifacts)
• --deployer ADDRESS: deployer used to compute engine addresses (default: the pruf FUNDER)

Output:

[STATE BEFORE ATTACK]
TokenA.balanceOf("0xabc") = 12345e6
attacker balance = 0
[STATE AFTER ATTACK]
TokenA.balanceOf("0xabc") = 0
attacker balance = 12345e6

transaction log:
  TokenA.approve -> ok
  TokenB.approve -> ok
  Marketplace.swap -> ok
  Marketplace.swap -> ok
  Marketplace.swap -> revert: insufficient balance

reloaded from myfile.json, proof again:
[STATE BEFORE ATTACK]
TokenA.balanceOf("0xabc") = 12345e6
attacker balance = 0
[STATE AFTER ATTACK]
TokenA.balanceOf("0xabc") = 0
attacker balance = 12345e6

Development

Requirements:

• Python 3.13 or newer
• Rust 1.91 or newer (for the core crate)
• uv

Build the native core and install the package in editable mode:

uv sync
uv run maturin develop

Run the test suite:

uv run pytest

Run the demo:

uv run python examples/mev_sandwich.py

Run the Sherlock OPoC example (Metric OMM Protocol audit competition):

uv run python examples/sherlock_metric_opoc.py

Layout

• crates/pruf-core: the Rust EVM execution core (revm + PyO3)
• src/pruf: the Python API (includes pruf.sherlock, pre-built audit competition environments)
• fixtures: Solidity demo contracts and the sample scopes document
• examples: runnable demos (MEV sandwich, Sherlock Metric OPoC)
• tests: the pytest suite