A collection of low-level EVM patterns, micro-primitives, and optimizations written in pure Yul / Yul+.
This repository is a curated set of experiments, patterns, and implementation techniques exploring raw EVM execution using Yul and Yul+.
It covers everything from minimal ERC standards to advanced DeFi building blocks, gas-optimized control flow, storage/memory patterns, and opcode-aware micro-architectures.
The goal is to develop a deep, practical understanding of the EVM as a computation model — the kind required for protocol engineering, performance-critical smart contracts, and security-sensitive primitives.
Yul is a low-level intermediate language that compiles directly to EVM bytecode. It offers a perfect balance between:
- The control of raw opcodes
- The readability of structured programming
- The optimization potential of hand-crafted bytecode
- The mental model needed for protocol-level engineering
- Writing gas-critical components
- Custom memory & storage layouts
- DeFi/math primitives
- Minimal proxies
- Cryptographic routines
- System-level contracts
- EIP implementations
- Auditing and vulnerability research
- Understanding EVM execution deeply
Bare-metal ERC-20 / ERC-721 / ERC-1155 style patterns using minimal storage and execution logic.
Focus:
- zero-overhead function selectors
- calldata decoding
- storage slot math
- packed structs
- custom revert patterns
Low-level foundations used inside AMMs, DEXes, and money markets:
- Safe arithmetic patterns
- Constant-product & curve math
- Reserve accounting
- Fee models
- Swap kernels
- Oracle-style read-only paths
These are written with explicit gas-model awareness:
stack pressure, memory reuse, branching cost, and warm/cold SLOAD patterns.
A collection of before/after transformations showing how to reduce:
- memory expansion
- redundant SLOAD/SSTORE
- stack shuffling
- branching overhead
- function dispatch cost
- error handling gas
Includes patterns such as:
- fallback-driven dispatch
- function-selector jump tables
- reusable scratch memory
- inlined arithmetic vs. subroutines
Explorations of how to structure execution in Yul:
- manual jump tables
- loop unrolling
switchvs.ifbranching- early exit patterns
- zero-copy calldata slicing
- using assembly blocks for Solidity interop
Patterns for:
- efficient storage slot packing
- struct layout
- pointer-style memory operations
- transient scratch space
- calldata pointers vs. memory copies
- high-density data formats
These techniques are essential for high-performance protocols, rollup precompiles, and system contracts.
Experiments involving:
- reentrancy-aware control flow
- custom authorization logic
- manual return data handling
- calldata validation
- invariant boundaries
These help develop intuition for auditing and secure system design.
Yul+ adds syntactic sugar on top of raw Yul:
- typed variables
- structured control flow
- easier memory management
- safer arithmetic helpers
- cleaner inlining/abstractions
This repo may contain examples in both Yul and Yul+ for comparison.
Yul is an intermediate language designed for optimization, with properties that make it ideal for EVM-level engineering:
- Structured syntax (
for,if,switch) - No explicit stack-touching ops (
SWAP,DUP, etc.) → clearer data flow - Minimal abstractions → predictable performance
- Statically typed (
u256by default) - Expressive enough to model most system-level patterns
- Compiles directly to efficient bytecode
Yul allows you to reason in terms of EVM execution traces without drowning in raw opcode sequences — the sweet spot between Solidity and raw assembly.
- Foundry (
forge/cast) for compilation, gas snapshots, and testing - Yul / Yul+ compiler targets
- EVM bytecode disassembly tools
- Gas profilers (Foundry debug tools)
- Opcode inspectors
- Improve mastery over EVM internals
- Build intuition for protocol-level engineering
- Demonstrate high-performance contract design
- Explore the limits of gas optimization
- Document reusable patterns for smart contract security
- Share useful primitives for other developers and auditors
Open an issue or PR — this repo is intended as a living notebook of low-level techniques for EVM engineers, auditors, and protocol designers.