Syntax

Yul parses comments, literals and identifiers in the same way as Solidity,so you can e.g. use// and/**/ to denote comments.There is one exception: Identifiers in Yul can contain dots:..

Yul can specify “objects” that consist of code, data and sub-objects.Please seeYul Objects below for details on that.In this section, we are only concerned with the code part of such an object.This code part always consists of a curly-bracesdelimited block. Most tools support specifying just a code blockwhere an object is expected.

Inside a code block, the following elements can be used(see the later sections for more details):

• literals, i.e.0x123,42 or"abc" (strings up to 32 characters)

• calls to builtin functions, e.g.add(1,mload(0))

• variable declarations, e.g.letx:=7,letx:=add(y,3) orletx (initial value of 0 is assigned)

• identifiers (variables), e.g.add(3,x)

• assignments, e.g.x:=add(y,3)

• blocks where local variables are scoped inside, e.g.{letx:=3{lety:=add(x,1)}}

• if statements, e.g.iflt(a,b){sstore(0,1)}

• switch statements, e.g.switchmload(0)case0{revert()}default{mstore(0,1)}

• for loops, e.g.for{leti:=0}lt(i,10){i:=add(i,1)}{mstore(i,7)}

• function definitions, e.g.functionf(a,b)->c{c:=add(a,b)}`

Multiple syntactical elements can follow each other simply separated bywhitespace, i.e. there is no terminating; or newline required.

Literals

As literals, you can use:

• Integer constants in decimal or hexadecimal notation.

• ASCII strings (e.g."abc"), which may contain hex escapes\xNN and Unicode escapes\uNNNN whereN are hexadecimal digits.

• Hex strings (e.g.hex"616263").

In the EVM dialect of Yul, literals represent 256-bit words as follows:

• Decimal or hexadecimal constants must be less than2**256.They represent the 256-bit word with that value as an unsigned integer in big endian encoding.

• An ASCII string is first viewed as a byte sequence, by viewinga non-escape ASCII character as a single byte whose value is the ASCII code,an escape\xNN as single byte with that value, andan escape\uNNNN as the UTF-8 sequence of bytes for that code point.The byte sequence must not exceed 32 bytes.The byte sequence is padded with zeros on the right to reach 32 bytes in length;in other words, the string is stored left-aligned.The padded byte sequence represents a 256-bit word whose most significant 8 bits are the ones from the first byte,i.e. the bytes are interpreted in big endian form.

• A hex string is first viewed as a byte sequence, by viewingeach pair of contiguous hex digits as a byte.The byte sequence must not exceed 32 bytes (i.e. 64 hex digits), and is treated as above.

When compiling for the EVM, this will be translated into anappropriatePUSHi instruction. In the following example,3 and2 are added resulting in 5 and then thebitwiseand with the string “abc” is computed.The final value is assigned to a local variable calledx.

The 32-byte limit above does not apply to string literals passed to builtin functions that requireliteral arguments (e.g.setimmutable orloadimmutable). Those strings never end up in thegenerated bytecode.

letx:=and("abc",add(3,2))

Unless it is the default type, the type of a literalhas to be specified after a colon:

// This will not compile (u32 and u256 type not implemented yet)letx:=and("abc":u32,add(3:u256,2:u256))

Function Calls

Both built-in and user-defined functions (see below) can be calledin the same way as shown in the previous example.If the function returns a single value, it can be directly usedinside an expression again. If it returns multiple values,they have to be assigned to local variables.

functionf(x,y)->a,b{/* ... */}mstore(0x80,add(mload(0x80),3))// Here, the user-defined function `f` returns two values.letx,y:=f(1,mload(0))

For built-in functions of the EVM, functional expressionscan be directly translated to a stream of opcodes:You just read the expression from right to left to obtain theopcodes. In the case of the first line in the example, thisisPUSH13PUSH10x80MLOADADDPUSH10x80MSTORE.

For calls to user-defined functions, the arguments are alsoput on the stack from right to left and this is the orderin which argument lists are evaluated. The return values,though, are expected on the stack from left to right,i.e. in this example,y is on top of the stack andxis below it.

Variable Declarations

You can use thelet keyword to declare variables.A variable is only visible inside the{...}-block it was defined in. When compiling to the EVM,a new stack slot is created that is reservedfor the variable and automatically removed again when the end of the blockis reached. You can provide an initial value for the variable.If you do not provide a value, the variable will be initialized to zero.

Since variables are stored on the stack, they do not directlyinfluence memory or storage, but they can be used as pointersto memory or storage locations in the built-in functionsmstore,mload,sstore andsload.Future dialects might introduce specific types for such pointers.

When a variable is referenced, its current value is copied.For the EVM, this translates to aDUP instruction.

{letzero:=0letv:=calldataload(zero){lety:=add(sload(v),1)v:=y}// y is "deallocated" heresstore(v,zero)}// v and zero are "deallocated" here

If the declared variable should have a type different from the default type,you denote that following a colon. You can also declare multiplevariables in one statement when you assign from a function callthat returns multiple values.

// This will not compile (u32 and u256 type not implemented yet){letzero:u32:=0:u32letv:u256,t:u32:=f()letx,y:=g()}

Depending on the optimiser settings, the compiler can free the stack slotsalready after the variable has been used forthe last time, even though it is still in scope.

Assignments

Variables can be assigned to after their definition using the:= operator. It is possible to assign multiplevariables at the same time. For this, the number and types of thevalues have to match.If you want to assign the values returned from a function that hasmultiple return parameters, you have to provide multiple variables.The same variable may not occur multiple times on the left-hand side ofan assignment, e.g.x,x:=f() is invalid.

letv:=0// re-assign vv:=2lett:=add(v,2)functionf()->a,b{}// assign multiple valuesv,t:=f()

If

The if statement can be used for conditionally executing code.No “else” block can be defined. Consider using “switch” instead (see below) ifyou need multiple alternatives.

iflt(calldatasize(),4){revert(0,0)}

The curly braces for the body are required.

Switch

You can use a switch statement as an extended version of the if statement.It takes the value of an expression and compares it to several literal constants.The branch corresponding to the matching constant is taken.Contrary to other programming languages, for safety reasons, control flow doesnot continue from one case to the next. There can be a fallback or defaultcase calleddefault which is taken if none of the literal constants matches.

{letx:=0switchcalldataload(4)case0{x:=calldataload(0x24)}default{x:=calldataload(0x44)}sstore(0,div(x,2))}

The list of cases is not enclosed by curly braces, but the body of acase does require them.

Loops

Yul supports for-loops which consist ofa header containing an initializing part, a condition, a post-iterationpart and a body. The condition has to be an expression, whilethe other three are blocks. If the initializing partdeclares any variables at the top level, the scope of these variables extends to all otherparts of the loop.

Thebreak andcontinue statements can be used in the body to exit the loopor skip to the post-part, respectively.

The following example computes the sum of an area in memory.

{letx:=0for{leti:=0}lt(i,0x100){i:=add(i,0x20)}{x:=add(x,mload(i))}}

For loops can also be used as a replacement for while loops:Simply leave the initialization and post-iteration parts empty.

{letx:=0leti:=0for{}lt(i,0x100){}{// while(i < 0x100)x:=add(x,mload(i))i:=add(i,0x20)}}

Function Declarations

Yul allows the definition of functions. These should not be confused with functionsin Solidity since they are never part of an external interface of a contract andare part of a namespace separate from the one for Solidity functions.

For the EVM, Yul functions take theirarguments (and a return PC) from the stack and also put the results onto thestack. User-defined functions and built-in functions are called in exactly the same way.

Functions can be defined anywhere and are visible in the block they aredeclared in. Inside a function, you cannot access local variablesdefined outside of that function.

Functions declare parameters and return variables, similar to Solidity.To return a value, you assign it to the return variable(s).

If you call a function that returns multiple values, you have to assignthem to multiple variables usinga,b:=f(x) orleta,b:=f(x).

Theleave statement can be used to exit the current function. Itworks like thereturn statement in other languages just that it doesnot take a value to return, it just exits the functions and the functionwill return whatever values are currently assigned to the return variable(s).

Note that the EVM dialect has a built-in function calledreturn thatquits the full execution context (internal message call) and not justthe current yul function.

The following example implements the power function by square-and-multiply.

{functionpower(base,exponent)->result{switchexponentcase0{result:=1}case1{result:=base}default{result:=power(mul(base,base),div(exponent,2))switchmod(exponent,2)case1{result:=mul(base,result)}}}}

Restrictions on the Grammar

Apart from those directly imposed by the grammar, the followingrestrictions apply:

Switches must have at least one case (including the default case).All case values need to have the same type and distinct values.If all possible values of the expression type are covered, a default case isnot allowed (i.e. a switch with abool expression that has both atrue and a false case do not allow a default case).

Every expression evaluates to zero or more values. Identifiers and Literalsevaluate to exactlyone value and function calls evaluate to a number of values equal to thenumber of return variables of the function called.

In variable declarations and assignments, the right-hand-side expression(if present) has to evaluate to a number of values equal to the number ofvariables on the left-hand-side.This is the only situation where an expression evaluatingto more than one value is allowed.The same variable name cannot occur more than once in the left-hand-side ofan assignment or variable declaration.

Expressions that are also statements (i.e. at the block level) have toevaluate to zero values.

In all other situations, expressions have to evaluate to exactly one value.

Thecontinue andbreak statements can only be used inside loop bodiesand have to be in the same function as the loop (or both have to be at thetop level). Thecontinue andbreak statements cannot be usedin other parts of a loop, not even when it is scoped inside a second loop’s body.

The condition part of the for-loop has to evaluate to exactly one value.

Theleave statement can only be used inside a function.

Functions cannot be defined anywhere inside for loop init blocks.

Literals cannot be larger than their type. The largest type defined is 256-bit wide.

During assignments and function calls, the types of the respective values have to match.There is no implicit type conversion. Type conversion in general can only be achievedif the dialect provides an appropriate built-in function that takes a value of onetype and returns a value of a different type.

Scoping Rules

Scopes in Yul are tied to Blocks (exceptions are functions and the for loopas explained below) and all declarations(FunctionDefinition,VariableDeclaration)introduce new identifiers into these scopes.

Identifiers are visible inthe block they are defined in (including all sub-nodes and sub-blocks):Functions are visible in the whole block (even before their definitions) whilevariables are only visible starting from the statement after theVariableDeclaration.

In particular,variables cannot be referenced in the right hand side of their own variabledeclaration.Functions can be referenced already before their declaration (if they are visible).

As an exception to the general scoping rule, the scope of the “init” part of the for-loop(the first block) extends across all other parts of the for loop.This means that variables (and functions) declared in the init part (but not inside ablock inside the init part) are visible in all other parts of the for-loop.

Identifiers declared in the other parts of the for loop respect the regularsyntactical scoping rules.

This means a for-loop of the formfor{I...}C{P...}{B...} is equivalentto{I...for{}C{P...}{B...}}.

The parameters and return parameters of functions are visible in thefunction body and their names have to be distinct.

Inside functions, it is not possible to reference a variable that was declaredoutside of that function.

Shadowing is disallowed, i.e. you cannot declare an identifier at a pointwhere another identifier with the same name is also visible, even if it isnot possible to reference it because it was declared outside the current function.

Formal Specification

We formally specify Yul by providing an evaluation function E overloadedon the various nodes of the AST. As builtin functions can have side effects,E takes two state objects and the AST node and returns two newstate objects and a variable number of other values.The two state objects are the global state object(which in the context of the EVM is the memory, storage and state of theblockchain) and the local state object (the state of local variables, i.e. asegment of the stack in the EVM).

If the AST node is a statement, E returns the two state objects and a “mode”,which is used for thebreak,continue andleave statements.If the AST node is an expression, E returns the two state objects andas many values as the expression evaluates to.

The exact nature of the global state is unspecified for this high leveldescription. The local stateL is a mapping of identifiersi to valuesv,denoted asL[i]=v.

For an identifierv, let$v be the name of the identifier.

We will use a destructuring notation for the AST nodes.

E(G, L, <{St1, ..., Stn}>: Block) =    let G1, L1, mode = E(G, L, St1, ..., Stn)    let L2 be a restriction of L1 to the identifiers of L    G1, L2, modeE(G, L, St1, ..., Stn: Statement) =    if n is zero:        G, L, regular    else:        let G1, L1, mode = E(G, L, St1)        if mode is regular then            E(G1, L1, St2, ..., Stn)        otherwise            G1, L1, modeE(G, L, FunctionDefinition) =    G, L, regularE(G, L, <let var_1, ..., var_n := rhs>: VariableDeclaration) =    E(G, L, <var_1, ..., var_n := rhs>: Assignment)E(G, L, <let var_1, ..., var_n>: VariableDeclaration) =    let L1 be a copy of L where L1[$var_i] = 0 for i = 1, ..., n    G, L1, regularE(G, L, <var_1, ..., var_n := rhs>: Assignment) =    let G1, L1, v1, ..., vn = E(G, L, rhs)    let L2 be a copy of L1 where L2[$var_i] = vi for i = 1, ..., n    G, L2, regularE(G, L, <for { i1, ..., in } condition post body>: ForLoop) =    if n >= 1:        let G1, L, mode = E(G, L, i1, ..., in)        // mode has to be regular or leave due to the syntactic restrictions        if mode is leave then            G1, L1 restricted to variables of L, leave        otherwise            let G2, L2, mode = E(G1, L1, for {} condition post body)            G2, L2 restricted to variables of L, mode    else:        let G1, L1, v = E(G, L, condition)        if v is false:            G1, L1, regular        else:            let G2, L2, mode = E(G1, L, body)            if mode is break:                G2, L2, regular            otherwise if mode is leave:                G2, L2, leave            else:                G3, L3, mode = E(G2, L2, post)                if mode is leave:                    G2, L3, leave                otherwise                    E(G3, L3, for {} condition post body)E(G, L, break: BreakContinue) =    G, L, breakE(G, L, continue: BreakContinue) =    G, L, continueE(G, L, leave: Leave) =    G, L, leaveE(G, L, <if condition body>: If) =    let G0, L0, v = E(G, L, condition)    if v is true:        E(G0, L0, body)    else:        G0, L0, regularE(G, L, <switch condition case l1:t1 st1 ... case ln:tn stn>: Switch) =    E(G, L, switch condition case l1:t1 st1 ... case ln:tn stn default {})E(G, L, <switch condition case l1:t1 st1 ... case ln:tn stn default st'>: Switch) =    let G0, L0, v = E(G, L, condition)    // i = 1 .. n    // Evaluate literals, context doesn't matter    let _, _, v1 = E(G0, L0, l1)    ...    let _, _, vn = E(G0, L0, ln)    if there exists smallest i such that vi = v:        E(G0, L0, sti)    else:        E(G0, L0, st')E(G, L, <name>: Identifier) =    G, L, L[$name]E(G, L, <fname(arg1, ..., argn)>: FunctionCall) =    G1, L1, vn = E(G, L, argn)    ...    G(n-1), L(n-1), v2 = E(G(n-2), L(n-2), arg2)    Gn, Ln, v1 = E(G(n-1), L(n-1), arg1)    Let <function fname (param1, ..., paramn) -> ret1, ..., retm block>    be the function of name $fname visible at the point of the call.    Let L' be a new local state such that    L'[$parami] = vi and L'[$reti] = 0 for all i.    Let G'', L'', mode = E(Gn, L', block)    G'', Ln, L''[$ret1], ..., L''[$retm]E(G, L, l: StringLiteral) = G, L, utf8EncodeLeftAligned(l),    where utf8EncodeLeftAligned performs a UTF-8 encoding of l    and aligns it left into 32 bytesE(G, L, n: HexNumber) = G, L, hex(n)    where hex is the hexadecimal decoding functionE(G, L, n: DecimalNumber) = G, L, dec(n),    where dec is the decimal decoding function

EVM Dialect

The default dialect of Yul currently is the EVM dialect for the currently selected version of the EVM.with a version of the EVM. The only type available in this dialectisu256, the 256-bit native type of the Ethereum Virtual Machine.Since it is the default type of this dialect, it can be omitted.

The following table lists all builtin functions(depending on the EVM version) and provides a short description of thesemantics of the function / opcode.This document does not want to be a full description of the Ethereum virtual machine.Please refer to a different document if you are interested in the precise semantics.

Opcodes marked with- do not return a result and all others return exactly one value.Opcodes marked withF,H,B,C,I andL are present since Frontier, Homestead,Byzantium, Constantinople, Istanbul or London respectively.

In the following,mem[a...b) signifies the bytes of memory starting at positiona up tobut not including positionb andstorage[p] signifies the storage contents at slotp.

Since Yul manages local variables and control-flow,opcodes that interfere with these features are not available. This includesthedup andswap instructions as well asjump instructions, labels and thepush instructions.

In some internal dialects, there are additional functions:

leta:=linkersymbol("file.sol:Math")

leta:=0x1234567890123456789012345678901234567890

letx:=calldataload(0)letdouble:=verbatim_1i_1o(hex"600202",x)

Optimization Step Sequence

By default the Yul optimizer applies its predefined sequence of optimization steps to the generated assembly.You can override this sequence and supply your own using the--yul-optimizations option:

solc --optimize --ir-optimized --yul-optimizations'dhfoD[xarrscLMcCTU]uljmul'

The order of steps is significant and affects the quality of the output.Moreover, applying a step may uncover new optimization opportunities for others that were alreadyapplied so repeating steps is often beneficial.By enclosing part of the sequence in square brackets ([]) you tell the optimizer to repeatedlyapply that part until it no longer improves the size of the resulting assembly.You can use brackets multiple times in a single sequence but they cannot be nested.

The following optimization steps are available:

Some steps depend on properties ensured byBlockFlattener,FunctionGrouper,ForLoopInitRewriter.For this reason the Yul optimizer always applies them before applying any steps supplied by the user.

The ReasoningBasedSimplifier is an optimizer step that is currently not enabledin the default set of steps. It uses an SMT solver to simplify arithmetic expressionsand boolean conditions. It has not received thorough testing or validation yet and can producenon-reproducible results, so please use with care!