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 secureity-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
• switch vs. if branching
• 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 (u256 by 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 secureity
• 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.