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:

1. Inline assembly inside Solidity contracts (using assembly { } blocks)
2. 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 exceptions
• All operations are stack-based: Operations push and pop values from the stack
• Nothing is implicit: No ABI encoding/decoding, no safety checks, no type system
• Memory 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 position
• swap1, swap2, ... swap16: Swap top with value at position
• pop: 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 zeros
• shl(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 zeros
• shr(1, 10) = 10 >> 1 = 5 (binary: 1010 → 101)

Why shifting matters:

• Extract specific parts of a value
• Position bits for packing/unpacking
• Remove 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 code
• add(a, b) is the YUL addition operation
• result := assigns the result to the return variable
• Solidity 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 functions
• You learn YUL gradually
• You 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 functions
• To prepare data for function calls
• To 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 operations
• Solidity may overwrite data you store in these positions at any time
• Using 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 0x40
• The value stored at 0x40 tells you the next available memory address
• This 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 data
• Unpredictable 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:

1. Store the data in memory
2. Use 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 selector
• Bytes 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 total
• Selector = 4 bytes = 32 bits
• Padding = 28 bytes = 224 bits
• Shift 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)]
0xa9059cbb00000000000000000000000000000000000000000000000000000000

After 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 bytes
• The leftmost 12 bytes are zeros
• Masking 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 slots
• Security vulnerabilities: An attacker could manipulate storage by crafting addresses with specific leftmost bytes
• Broken assumptions: Your code might assume addresses are 20 bytes, but unmasked values are 32 bytes with garbage
• Unexpected 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:

1. Function selector extraction: shr(224, calldataload(0)) extracts the 4-byte selector from calldata
2. Address reading: calldataload(4) reads the address parameter (32 bytes)
3. Address masking: and(..., mask) ensures only the rightmost 20 bytes are used, clearing any garbage
4. Amount reading: calldataload(36) reads the uint256 parameter
5. Memory storage: mstore stores both values in memory for potential use
6. Calculation: Performs an operation (in this example, adds selector to amount)
7. 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 to
• offset: Source data offset
• size: 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 contract
• The runtime block contains the actual logic
• This 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):

1. datacopy(0, dataoffset("runtime"), datasize("runtime")):

• Copies the runtime code from the runtime object into memory at position 0
• dataoffset("runtime") returns where the runtime object's data starts in the contract bytecode
• datasize("runtime") returns the size of the runtime code in bytes

2. return(0, datasize("runtime")):

• Returns the runtime code from memory
• This returned code is what gets stored on-chain as the contract

Runtime (runtime object's code block):

1. Function selector extraction: Uses shr(224, calldataload(0)) to extract the 4-byte selector
2. Address reading and masking: Reads address from calldata and masks it to ensure only 20 bytes
3. Amount reading: Reads uint256 from calldata
4. Memory operations: Stores values in memory using mstore
5. Calculation: Performs an operation with the values
6. Return: 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 valid
• Always 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 position
• Use aligned addresses (0, 32, 64, 96, …) to avoid overlapping writes
• Use mstore8 for byte-level writes if needed

3. Assuming Solidity safety checks exist

• YUL has no type system, no overflow protection, no bounds checking
• You must validate all inputs manually
• Check calldatasize() before reading parameters

4. Using return() in inline assembly without understanding

• return() in inline assembly bypasses Solidity's return handling
• It immediately exits the function with raw bytes
• Only 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 overwritten
• Always use the free memory pointer: mload(0x40)
• Examples in this guide use slot 0 for learning clarity only

What We Learned

1. The stack underlies everything: All operations work with the stack
2. Inline assembly bridges Solidity and YUL: Start here to learn gradually
3. Memory is for temporary data: Use it to store return values
4. Calldata contains function inputs: Read parameters manually
5. Return requires memory: Store data in memory, then return it
6. Standalone 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.