This is a 3-part series that assumes you know Solidity and want to understand YUL. We will start from absolute basics and build up to writing real contracts.
YUL is a low-level language that compiles to EVM bytecode. When you write Solidity, the compiler turns it into YUL, then into bytecode. Writing YUL directly gives you precise control over what the EVM executes.
Code Repository: All code examples from this guide are available in the YUL Examples repository. Each part has its own directory with working examples you can compile and test.
What YUL Is (Briefly)
YUL is a human-readable, low-level intermediate language that compiles to EVM bytecode. It is what Solidity compiles to before becoming the bytecode that runs on Ethereum.
Important distinction: YUL is not raw EVM assembly. It is a structured intermediate representation (IR) that compiles to EVM opcodes. YUL provides higher-level constructs (functions, variables, control flow) that are then compiled down to the stack-based EVM opcodes.
You can write YUL in two ways:
Inline assembly inside Solidity contracts (using assembly { } blocks)Standalone YUL files (.yul files that compile directly to bytecode)
This guide covers both approaches. We start with inline assembly to bridge from Solidity, then show standalone YUL contracts.
How to Think in YUL
Before diving into syntax, understand these core principles:
Everything is a 256-bit word: All values are 32-byte words, no exceptionsAll operations are stack-based: Operations push and pop values from the stackNothing is implicit: No ABI encoding/decoding, no safety checks, no type systemMemory and calldata must be managed manually: You decide where to read from and write to
This mental model will help you understand why YUL code looks the way it does.
Basic Syntax
YUL syntax is minimal:
Comments: // Single-line or /* Multi-line */Literals: Numbers as decimal (42) or hex (0x2A)Blocks: Code in curly braces { }Statements: Separated by newlines or semicolons
The Stack: The Foundation
The EVM is a stack-based machine. All operations work with values on a stack. You push values, operate on them, and pop them off. The stack has a maximum depth of 1024 items.
How the Stack Works
5 // Push 5 → stack: [5]
3 // Push 3 → stack: [5, 3]
add // Pop 3 and 5, add them, push 8 → stack: [8]
Visualization:
Initial: []
After 5: [5]
After 3: [5, 3]
After add: [8]
Common Stack Operations
dup1, dup2, … dup16: Duplicate value from positionswap1, swap2, … swap16: Swap top with value at positionpop: Remove top value
Arithmetic Operations
add // Addition
sub // Subtraction (second – top)
mul // Multiplication
div // Division (second / top)
mod // Modulo (second % top)
Important: For sub, div, and mod, the operation is second_value op top_value.
Example:
// Stack: [10, 3]
sub // 10 – 3 = 7 (result: [7])
div // 10 / 3 = 3 (result: [3])
mod // 10 % 3 = 1 (result: [1])
Comparison Operations
eq // Equal (returns 1 if equal, 0 if not)
lt // Less than (second < top)
gt // Greater than (second > top)
iszero // Is zero (returns 1 if top is 0)
Logical Operations
and // Bitwise AND (commonly used as logical when values are 0 or 1; YUL does not have a boolean type)
or // Bitwise OR (commonly used as logical when values are 0 or 1; YUL does not have a boolean type)
xor // XOR
not // Bitwise NOT (flips all 256 bits)
Bit Shift Operations
Bit shifting moves bits left or right in a number:
shl(bits, value): Shift left (multiply by 2^bits)
Moves all bits to the left, fills right with zerosshl(1, 5) = 5 << 1 = 10 (binary: 101 → 1010)
shr(bits, value): Shift right (divide by 2^bits)
Moves all bits to the right, fills left with zerosshr(1, 10) = 10 >> 1 = 5 (binary: 1010 → 101)
Why shifting matters:
Extract specific parts of a valuePosition bits for packing/unpackingRemove unwanted data from the left or right
Data Types
YUL has only one data type: 256-bit unsigned integers (u256). No strings, arrays, structs, or booleans. Use 0 for false, 1 for true.
From Stack Operations to Functions
Inline assembly still uses the stack underneath. When you write add(a, b) in an assembly block, Solidity automatically places a and b on the stack, then add pops both values, adds them, and pushes the result. This is the same stack operations as the raw 5, 3, add example.
The difference is syntax: inline assembly lets you use function-like syntax while the stack operations happen automatically. In standalone YUL, you are responsible for value lifetimes and ordering, even though YUL provides expression syntax (like add(x, y)) that abstracts individual dup and swap instructions.
Inline Assembly: Your Bridge from Solidity
The easiest way to start with YUL is using inline assembly inside Solidity contracts. This lets you write YUL code within familiar Solidity syntax.
Your First Inline Assembly
Let us start with a simple Solidity function and convert it to inline assembly:
Solidity version:
function add(uint256 a, uint256 b) public pure returns (uint256) {
return a + b;
}
Inline assembly version:
function add(uint256 a, uint256 b) public pure returns (uint256 result) {
assembly {
result := add(a, b)
}
}
What changed:
The assembly { } block contains YUL codeadd(a, b) is the YUL addition operationresult := assigns the result to the return variableSolidity still handles function parameters and return values automatically
Note: You can also define variables inside the assembly block using let:
assembly {
let sum := add(a, b) // Define variable inside assembly
// Use sum here
}
Why this is useful:
You can optimize specific functionsYou learn YUL graduallyYou keep Solidity’s safety features (function selectors, ABI encoding)
Memory: Where Return Values Live
Memory is a temporary byte array used to store intermediate values and return data. It is not persisted between calls.
Memory Layout
Memory is organized in 32-byte words. Address 0 = first 32 bytes, address 32 = next 32 bytes, and so on.
Memory Operations
mstore(position, value): Stores a 256-bit value at a memory position
mstore(0, 42) // Store 42 at position 0-31
mstore(32, 100) // Store 100 at position 32-63
mload(position): Loads a 256-bit value from memory
mstore(0, 42)
let value := mload(0) // value is now 42
Why we need memory:
To return values from functionsTo prepare data for function callsTo work with temporary data
Important note for inline assembly in Solidity:
For learning clarity, we use memory slot 0 in examples. Production Solidity inline assembly should allocate memory using the free memory pointer.
What is scratch space?
Solidity uses memory positions 0 to 0x3F (64 bytes) as “scratch space” for temporary operationsSolidity may overwrite data you store in these positions at any timeUsing mstore(0, …) in production code is unsafe because Solidity might overwrite it
What is the free memory pointer?
Solidity tracks where free memory starts at position 0x40The value stored at 0x40 tells you the next available memory addressThis is how Solidity knows where to safely allocate new memory
How to use it in production:
assembly {
// Get the current free memory pointer
let freeMemPtr := mload(0x40)
// Use this address for your data
mstore(freeMemPtr, yourData)
// Update the free memory pointer (move it forward by 32 bytes)
mstore(0x40, add(freeMemPtr, 32))
}
For standalone YUL contracts, you have full control and can use any memory position.
Memory Alignment
Important: mstore and mload always operate on 32 bytes, regardless of the starting position.
If you use unaligned addresses (not multiples of 32), you can overwrite adjacent data:
mstore(7, 42) // Writes 32 bytes starting at byte 7 → writes to bytes 7-38
mstore(18, 100) // Writes 32 bytes starting at byte 18 → writes to bytes 18-49
// These writes overlap! Bytes 18-38 are overwritten by both operations.
Problems with unaligned writes:
Overwrites adjacent data (writes span word boundaries)mload reads 32 bytes, so you might read overlapping dataUnpredictable results when reading back
Best practice: Always use aligned addresses (0, 32, 64, 96, …) for mstore and mload. Use mstore8 if you need byte-level writes.
Return Operations
To return data from a function, you must:
Store the data in memoryUse return(offset, size) to return it
return(offset, size): Returns size bytes starting from memory position offset
let result := 42
mstore(0, result) // Store result in memory
return(0, 32) // Return 32 bytes from position 0
⚠️ Important for inline assembly: In inline assembly, return() immediately exits the entire Solidity function and returns raw bytes, bypassing Solidity’s normal return handling. Use it only when you intend to fully control the return data.
Complete example:
function getValue() public pure returns (uint256) {
assembly {
let value := 42
mstore(0, value)
return(0, 32) // Exits function immediately, returns raw bytes
}
}
Calldata: Reading Function Inputs
Calldata is the input data sent with a transaction. It contains the function selector (first 4 bytes) and function parameters (ABI-encoded).
Calldata Layout
For a function like transfer(address to, uint256 amount):
Bytes 0–3: Function selectorBytes 4–35: to (address, padded to 32 bytes)Bytes 36–67: amount (uint256)
Calldata Operations
calldataload(position): Loads 32 bytes from calldata
let selector := calldataload(0) // Loads bytes 0-31
Important: Production YUL code should check calldatasize() before reading parameters to avoid out-of-bounds reads. The examples in this guide assume calldata is long enough for demonstration purposes.
Extracting the function selector:
calldataload(0) loads 32 bytes, but the function selector is only the first 4 bytes. We need to extract just those 4 bytes.
The problem:
Calldata: [selector (4 bytes)][padding (28 bytes)]calldataload(0) returns: [selector][padding] (all 32 bytes)We want: just the selector (4 bytes)
The solution: Shift right by 224 bits
let selector := shr(224, calldataload(0)) // Shift right by 224 bits
Why 224 bits?
32 bytes = 256 bits totalSelector = 4 bytes = 32 bitsPadding = 28 bytes = 224 bitsShift right by 224 bits moves the selector to the rightmost position and removes the padding
Visual example:
Before shift (32 bytes):
[selector (4 bytes)][padding (28 bytes)]
0xa9059cbb00000000000000000000000000000000000000000000000000000000After shr(224, …):
[zeros][selector (4 bytes)]
0x00000000000000000000000000000000000000000000000000000000a9059cbb
^^^^^^^^
Just the selector
The selector is now in the rightmost 4 bytes, with zeros on the left.
Reading function parameters:
// Read ‘to’ (skip 4 bytes for selector)
let to := calldataload(4)
// Mask to get just the address (20 bytes)
to := and(to, 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF)// Read ‘amount’ (skip 4 + 32 = 36 bytes)
let amount := calldataload(36)
Why mask addresses:
Addresses are 20 bytes, but calldata pads them to 32 bytesThe leftmost 12 bytes are zerosMasking keeps only the rightmost 20 bytes
How masking works:
The and operation performs bitwise AND: it keeps bits where both values are 1, and clears bits where either is 0.
The mask 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF is 20 bytes of all 1s (rightmost 20 bytes). When you and a value with this mask:
Leftmost 12 bytes: AND with 0 → becomes 0 (cleared)Rightmost 20 bytes: AND with 1 → stays the same (kept)
Why masking is necessary:
Masking is defensive programming: it ensures we only use the rightmost 20 bytes even if calldata is malformed or contains unexpected values.
In normal cases, addresses are already left-padded with zeros:
Input: 0x0000000000000000000000001234567890123456789012345678901234567890
^^^^^^^^^^^^^^^^^^^^^^^^ already zeros
kept ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
But what if calldata is malformed or a malicious caller passes non-zero values in the leftmost 12 bytes?
Malicious input: 0xFFFFFFFFFFFFFFFFFFFFFFFF1234567890123456789012345678901234567890
^^^^^^^^^^^^^^^^^^^^^^^^^^ garbage (could cause issues)
What could go wrong without masking:
If you use an unmasked address value directly, the garbage bytes could:
Incorrect storage slot calculations: When computing keccak256(address, slot) for mappings, the garbage bytes change the hash, leading to wrong storage slotsSecurity vulnerabilities: An attacker could manipulate storage by crafting addresses with specific leftmost bytesBroken assumptions: Your code might assume addresses are 20 bytes, but unmasked values are 32 bytes with garbageUnexpected behavior: Comparisons, equality checks, and other operations could fail or behave unexpectedly
⚠️ Always mask addresses from calldata.
Note: This function is not meant to be realistic. It is a mechanical demonstration of concepts covered in Part 1.
Here is a complete function demonstrating all concepts from Part 1:
function processAddressAndAmount(address addr, uint256 amount) public pure returns (uint256)
assembly {
// 1. Extract function selector (demonstrates bit shifting)
// calldataload(0) loads 32 bytes, but selector is only 4 bytes
// Shift right by 224 bits (28 bytes) to move selector to rightmost position
let selector := shr(224, calldataload(0))
// 2. Read address from calldata (position 4, after selector)
let addr := calldataload(4)
// 3. Mask address to ensure only 20 bytes (demonstrates defensive programming)
// Addresses are 20 bytes, but calldata pads them to 32 bytes
// Masking clears any potential garbage in the leftmost 12 bytes
addr := and(addr, 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF)
// 4. Read uint256 from calldata (position 36, after selector + address)
let amount := calldataload(36)
// 5. Store values in memory (demonstrates memory operations)
mstore(0, addr) // Store address at position 0
mstore(32, amount) // Store amount at position 32
// 6. Perform a calculation (e.g., add selector to amount for demonstration)
// In a real contract, you’d do something meaningful with addr and amount
let result := add(selector, amount)
// 7. Return the result
mstore(0, result) // Store result at memory position 0
return(0, 32) // Return 32 bytes from memory position 0
}
}
Note: The function has parameters (`address addr, uint256 amount`) that Solidity would normally handle automatically. The parameters are intentionally unused in the function body. We read from calldata manually to demonstrate how calldata parsing works. In practice, you would use the parameters directly, but reading from calldata shows the low-level mechanics.
What happens step by step:
Function selector extraction: shr(224, calldataload(0)) extracts the 4-byte selector from calldataAddress reading: calldataload(4) reads the address parameter (32 bytes)Address masking: and(…, mask) ensures only the rightmost 20 bytes are used, clearing any garbageAmount reading: calldataload(36) reads the uint256 parameterMemory storage: mstore stores both values in memory for potential useCalculation: Performs an operation (in this example, adds selector to amount)Return: Stores result in memory and returns it
Standalone YUL Contracts
Standalone YUL files (.yul) compile directly to bytecode. They require more setup but give you full control.
Contract Structure
A standalone YUL contract has two parts:
object “ContractName” {
code {
// Deployment code – runs once when contract is created
datacopy(0, dataoffset(“runtime”), datasize(“runtime”))
return(0, datasize(“runtime”))
}
object “runtime” {
code {
// Runtime code – this is the actual contract
// Your functions go here
}
}
}
What each part does:
code block: Runs during deployment. It copies the runtime code and returns it. This is what gets stored on-chain.runtime code block: The actual contract code that runs on every call.
Deployment Operations
datacopy(dest, offset, size): Copies data to memory
dest: Memory position to copy tooffset: Source data offsetsize: Number of bytes to copy
dataoffset(“name”): Returns the offset of a named object’s data
datasize(“name”): Returns the size of a named object’s data
Why this structure:
The code block sets up the contractThe runtime block contains the actual logicThis separation is required for standalone YUL contracts
Complete Standalone YUL Example
Important: This standalone contract does not implement ABI dispatch. Any calldata sent is interpreted as raw arguments (function selector + parameters). Any call to this contract, regardless of selector, will execute the same code. In a real contract, you would check the function selector and route to different handlers (we’ll cover this in Part 3).
Here is a complete standalone YUL contract demonstrating all Part 1 concepts:
object “ProcessAddress” {
code {
// Deployment code – runs once when contract is created
// 1. Copy runtime code to memory using datacopy
// – Destination: memory position 0
// – Source: dataoffset(“runtime”) – where the runtime object’s data starts
// – Size: datasize(“runtime”) – how many bytes the runtime code is
datacopy(0, dataoffset(“runtime”), datasize(“runtime”))
// 2. Return the runtime code (this is what gets stored on-chain)
// – Offset: 0 (where we copied the code in memory)
// – Size: datasize(“runtime”) (how many bytes to return)
return(0, datasize(“runtime”))
}
object “runtime” {
code {
// Runtime code – this runs on every function call
// 1. Extract function selector (demonstrates bit shifting)
// calldataload(0) loads 32 bytes, but selector is only 4 bytes
// Shift right by 224 bits to move selector to rightmost position
let selector := shr(224, calldataload(0))
// 2. Read address from calldata (position 4, after selector)
let addr := calldataload(4)
// 3. Mask address to ensure only 20 bytes (demonstrates defensive programming)
// Addresses are 20 bytes, but calldata pads them to 32 bytes
// Masking clears any potential garbage in the leftmost 12 bytes
addr := and(addr, 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF)
// 4. Read uint256 from calldata (position 36, after selector + address)
let amount := calldataload(36)
// 5. Store values in memory (demonstrates memory operations)
mstore(0, addr) // Store address at position 0
mstore(32, amount) // Store amount at position 32
// 6. Perform a calculation (e.g., add selector to amount)
// In a real contract, you’d do something meaningful with addr and amount
let result := add(selector, amount)
// 7. Return the result
mstore(0, result) // Store result at memory position 0
return(0, 32) // Return 32 bytes from memory position 0
}
}
}
What each part does:
Deployment (code block):
datacopy(0, dataoffset(“runtime”), datasize(“runtime”)):Copies the runtime code from the runtime object into memory at position 0dataoffset(“runtime”) returns where the runtime object’s data starts in the contract bytecodedatasize(“runtime”) returns the size of the runtime code in bytes
2. return(0, datasize(“runtime”)):
Returns the runtime code from memoryThis returned code is what gets stored on-chain as the contract
Runtime (runtime object’s code block):
Function selector extraction: Uses shr(224, calldataload(0)) to extract the 4-byte selectorAddress reading and masking: Reads address from calldata and masks it to ensure only 20 bytesAmount reading: Reads uint256 from calldataMemory operations: Stores values in memory using mstoreCalculation: Performs an operation with the valuesReturn: Returns the result
Common Beginner Mistakes
Avoid these common pitfalls when learning YUL:
1. Forgetting to mask addresses
Addresses from calldata are 32 bytes, but only 20 bytes are validAlways mask: addr := and(addr, 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF)Unmasked addresses can corrupt storage slot calculations
2. Using unaligned mstore addresses
mstore always writes 32 bytes, regardless of starting positionUse aligned addresses (0, 32, 64, 96, …) to avoid overlapping writesUse mstore8 for byte-level writes if needed
3. Assuming Solidity safety checks exist
YUL has no type system, no overflow protection, no bounds checkingYou must validate all inputs manuallyCheck calldatasize() before reading parameters
4. Using return() in inline assembly without understanding
return() in inline assembly bypasses Solidity’s return handlingIt immediately exits the function with raw bytesOnly use when you need full control over return data
5. Using memory slot 0 in production Solidity code
Memory below 0x40 is scratch space and may be overwrittenAlways use the free memory pointer: mload(0x40)Examples in this guide use slot 0 for learning clarity only
What We Learned
The stack underlies everything: All operations work with the stackInline assembly bridges Solidity and YUL: Start here to learn graduallyMemory is for temporary data: Use it to store return valuesCalldata contains function inputs: Read parameters manuallyReturn requires memory: Store data in memory, then return itStandalone YUL needs structure: code block for deployment, runtime for logic
In the next part, we will dive deep into storage, the persistent database where contract state lives. We’ll see why incorrect storage access is far more dangerous than incorrect memory usage.
Questions? Drop a comment below and I’ll do my best to help!
Want to stay updated? Follow to get notified when Part 2 is published.
YUL: Solidity’s Low-Level Language (Without the Tears), Part 1: Stack, Memory, and Calldata was originally published in Coinmonks on Medium, where people are continuing the conversation by highlighting and responding to this story.