Introduction to Solidity inline assembly (Yul)

13 Feb, 2025

Yul is the low-level language used in Solidity inline assembly. (official documentation)

In a Solidity smart contract, Yul is always written within an inline assembly block.

There are no semicolons.
There's only one data-type in Yul -- the 32 byte word.
New variables are declared within the assembly block via the let keyword.
Values are assigned to variables via the := colon-equals symbol.

contract YulExample {
	function add() external {
		assembly {
			let x := 1
			let y := 2
			
			let result := add(x,y)
		}
	}
}

You can reference variables declared in the function's arguments, return values and body.

contract YulExample {
	function add(uint256 value) external view returns (uint256 ret) {
		assembly {
			let x := 1
			ret := add(x,value)
		}
	}
}

You can reference variables declared in the contract storage with the .slot or .offset suffixes. These are used to determine the storage location of the value.

contract YulExample {
	// Slot-0: 0x-[A-32-bytes]
	uint256 public A;
	
	// Slot-1: 0x-[empty-1-byte][E-1-byte][D-2-bytes][C-12-bytes][B-16-bytes]
	uint128 public B;
	uint96 public C;
	uint16 public D;
	uint8 public E;
	
	function add_D(uint256 val) external returns (uint256 ret) {
		assembly {
			let slot := D.slot // slot-1 packs B,C,D,E
			
			// 0x-[empty-1-byte][E-1-byte][D-2-bytes][C-12-bytes][B-16-bytes]
			let current := sload(slot)
			
			// `D.offset` is 28-bytes (B.len + C.len)
			let dOffsetBits := mul(D.offset, 8)
			
			// 0x-[empty-2-bytes][full-2-bytes][empty-28-bytes]
			let dMask := shl(dOffsetBits, 0xffff)
			// 0x-[empty-1-byte][full-1-byte][empty-2-bytes][full-28-bytes]
			let notDMask := not(dMask)
			
			// 0x-[empty-2-bytes][D-2-bytes][empty-28-bytes]
			let d := and(dMask, current)
			// 0x-[empty-1-byte][E-1-byte][empty-2-bytes][C-12-bytes][B-16-bytes]
			let notd := and(notDMask, current)
			
			// 0x-[empty-30-bytes][New-D-2-bytes]
			ret := and(add(shr(dOffsetBits, d), val), 0xffff)
			
			// 0x-[empty-1-byte][E-1-byte][New-D-2-bytes][C-12-bytes][B-16-bytes]
			let newVal := or(notd, shl(dOffsetBits, ret))
			
			sstore(slot, newVal)
		}
	}
}

You can write if-statements (no else-statements) and for-loops.

contract YulExample {	
	function isPrime(uint256 num) external pure returns (bool ret) {
		assert(num > 0);
		
		ret = true;
		assembly {
			let x := num
			let halfX := add(div(x, 2), 1)
			
			for { let i := 2 } lt(i, halfX) { i := add(i,1) }
			{
				if iszero(mod(x, i)) {
					ret := 0
					break
				}
			}
		}
	}
}

Within assembly blocks, value assignments via := colon-equals manipulate the stack, and you manipulate memory and storage by invoking opcodes directly.