Metadata-Version: 2.4
Name: pruf
Version: 0.2.0
Requires-Dist: httpx>=0.28
License-File: LICENSE
Summary: Massive Proof of Concept engine for web3 bug hunters
Author-email: Haxors <hanzhaxors@gmail.com>
License-Expression: Apache-2.0
Requires-Python: >=3.13
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# 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.

```python
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:

```bash
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):

```bash
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:

```text
[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:

```bash
uv sync
uv run maturin develop
```

Run the test suite:

```bash
uv run pytest
```

Run the demo:

```bash
uv run python examples/mev_sandwich.py
```

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

```bash
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

