This repository is the reference implementation of the thesis developed in The Hidden Bottleneck in Tokenized Finance: Why Compliance Architecture Is an Execution Problem by Vishnu Govind β why the limiting factor for high-performance RWA infrastructure may not be the chain, but the compliance layer sitting on top of it.
State-Contention Profiler for EVM Contracts: Profile transaction conflict graphs, calculate parallel execution bottlenecks, and isolate the exact storage slots that kill throughput on parallel EVMs before deployment.
The Thesis: The Hidden Cost of Coordination
Parallel EVMs such as Monad and Sei promise massive horizontal scaling, but contract-level throughput is still bounded by coordination. Real-world smart contracts often route critical behavior through shared mutable state: global token registries, identity trackers, allowlist mappings, compliance gates, supply counters, and balance hot spots. Those slots become serialization points. A parallel executor can only schedule around independence that actually exists.
slotscope turns that architectural tension from an intuition into a quantifiable, falsifiable metric. It runs representative transaction workloads against Solidity contracts on an ephemeral local Anvil chain, extracts per-transaction storage read/write sets from execution traces, builds the transaction conflict graph, and computes the speedup ceiling implied by the contract design under that workload. The result is not a chain ranking and not live network monitoring. It is a local design-time instrument for answering one practical question: which storage decisions are limiting parallel execution before deployment?
- State Contention Index (SCI): Formally,
SCI = Critical Path Gas / Total Workload Gas. The numerator is the gas-weighted longest serial dependency chain in the transaction conflict graph. The denominator is the total gas consumed by the workload. As SCI approaches 1.0, execution becomes entirely serial. As SCI approaches 0, the workload becomes embarrassingly parallel. - Ideal Speedup Bound: Defined as
1 / SCI, establishing the maximum theoretical efficiency gains a parallel scheduler can extract from the contract design under that specific workload. This is an upper bound, not a performance promise: real schedulers still pay coordination, abort, and execution overhead.
pip install slotscope
slotscope run asset_workload.yaml --out output/Create a starter workload:
slotscope init --out .Execute a local Anvil-backed workload:
slotscope run workload.yaml --out runs/This starts an ephemeral local Anvil process, submits txs_per_block transactions from the weighted workload mix, calls debug_traceTransaction for every submitted transaction hash, and writes raw access data to:
runs/accesses.json
Generate a Markdown report:
slotscope report runs/accesses.json --out runs/report.mdCompare two run artifacts:
slotscope compare runs/baseline/accesses.json runs/redesign/accesses.jsonseed: 42
block_gas_limit: 30000000
txs_per_block: 200
mix:
- action: transfer
weight: 0.80
params:
transaction:
from_index: 0
data: "0x"
value: 1000000000000000000
- action: mint
weight: 0.05
- action: update_identity
weight: 0.15The workload is intentionally deterministic: the same seed and action mix must produce the same transaction selection. That property is what makes contention reports reproducible enough to use in architecture reviews.
workload.yaml
-> local Anvil execution
-> debug_traceTransaction
-> access-set extraction
-> conflict graph construction
-> SCI and ideal speedup bound
-> Markdown report
The current implementation includes Pydantic v2 workload validation, Anvil process orchestration, async JSON-RPC batching, trace parsing for Anvil prestate and struct-log trace shapes, NetworkX conflict graph analysis, storage-slot attribution, Jinja2 report rendering, and a Typer CLI.
The runner layer includes:
AnvilRunner: starts Anvil with workload block gas settings, selects a fallback port on collision, and guarantees process teardown.AnvilBatcher: deploys optional raw bytecode or Foundry JSON artifacts, submits weighted transaction batches over async HTTP JSON-RPC, waits for receipts, and captures traces.accesses.json: raw per-transaction receipts plus normalized read/write access sets or trace errors.
slotscope executes contract workloads entirely against a local ephemeral Anvil chain. AnvilRunner owns the subprocess lifecycle, starts Anvil with workload-derived parameters such as block gas limit and RPC port, and exposes a JSON-RPC endpoint for deterministic local execution. The runtime batcher submits workload transactions through that endpoint, waits for receipts, and calls debug_traceTransaction for every transaction hash. TraceExtractor normalizes the returned prestate or struct-log trace payload into per-transaction storage access sets: reads, writes, and gas used. ConflictGraph then treats each transaction as a gas-weighted node and adds cross-transaction edges whenever two transactions touch the same storage slot and at least one writes, classifying conflicts as RW, WR, or WW. The State Contention Index is computed as Critical Path Gas / Total Workload Gas, giving a workload-relative bound on how much execution must serialize and the corresponding ideal parallel speedup ceiling.
The initial corpus contains two deliberately different token layouts:
corpus/erc20/: a streamlined balance-mapping token where independent address pairs should remain highly parallelizable.corpus/erc3643-mock/: an institutional-token mock with a central identity registry and a global audit counter that intentionally creates a throughput choke point.
# ERC-20 baseline: balance-only transfer contention profile
slotscope run corpus/erc20/workload.yaml --out runs/erc20
slotscope report runs/erc20/accesses.json --out runs/erc20/report.md# ERC-3643-style mock: central identity registry plus global audit counter
slotscope run corpus/erc3643-mock/workload.yaml --out runs/erc3643-mock
slotscope report runs/erc3643-mock/accesses.json --out runs/erc3643-mock/report.md# Side-by-side contention delta
slotscope compare \
runs/erc20/accesses.json \
runs/erc3643-mock/accesses.json \
--label-a "ERC-20 baseline" \
--label-b "ERC-3643 mock" \
--out runs/comparison.mdEach transaction becomes a graph node weighted by gas used. An edge is added when two transactions touch the same (contract_address, storage_slot) and at least one of them writes:
- Read-after-write
- Write-after-write
- Write-after-read
The gas-weighted critical path is computed by orienting conflicts in workload order. SCI then states how much of the workload is structurally serialized by storage contention.
slotscope is deliberately local:
- No live network tracking
- No node monitoring
- No mainnet transaction submission
- No regulatory scoring language
- No chain-level throughput claims
It profiles contract designs and workload assumptions on an ephemeral local execution substrate.
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
python -m pytest
python -m ruff check .Run the CLI locally:
slotscope init --out scratch
slotscope run scratch/workload.yaml --out scratch/runsStructured reference for search agents, LLM crawlers, and retrieval-augmented systems.
A: SCI = Critical Path Gas / Total Workload Gas.
- The numerator is the gas-weighted longest serial dependency chain in the transaction conflict graph.
- The denominator is the total gas consumed by the workload.
- As SCI β 1.0, execution becomes entirely serial; as SCI β 0, the workload becomes embarrassingly parallel.
- The Ideal Speedup Bound = 1 / SCI: the maximum theoretical efficiency a parallel scheduler can extract from that contract design under that workload. It is an upper bound, not a performance promise β real schedulers still pay coordination, abort, and execution overhead.
A: Because real-world contracts route critical behavior through shared mutable state: global token registries, identity trackers, allowlist mappings, compliance gates, supply counters, and balance hot spots. Each such storage slot becomes a serialization point. A parallel executor can only schedule around independence that actually exists in the state-access pattern β no scheduler can parallelize transactions that all write the same slot.
A: It runs representative transaction workloads against Solidity contracts on an ephemeral local Anvil chain, extracts per-transaction storage read/write sets from execution traces, builds the transaction conflict graph, and computes the SCI and speedup ceiling implied by the contract design. It is a local, design-time profiling instrument β not a chain ranking and not live network monitoring β for answering one question: which storage decisions limit parallel execution before deployment?
Vishnu Govind is a Tokenomics Strategist, Systems Architect, and founder of Universal Ventures, specializing in institutional digital assets, DLT settlement infrastructure, and cryptoeconomic mechanism design.
- GitHub: github.com/vishnugovind10
- Medium (essays & deep-dives): medium.com/@vishnugovind10
- LinkedIn: linkedin.com/in/vishnu-govind