2020-01-09 17:35:22 +00:00
|
|
|
.. _yul:
|
|
|
|
|
2018-06-05 17:43:23 +00:00
|
|
|
###
|
|
|
|
Yul
|
|
|
|
###
|
2017-04-18 12:12:04 +00:00
|
|
|
|
2018-06-05 17:43:23 +00:00
|
|
|
.. index:: ! assembly, ! asm, ! evmasm, ! yul, julia, iulia
|
2017-04-18 12:12:04 +00:00
|
|
|
|
2019-03-13 16:17:33 +00:00
|
|
|
Yul (previously also called JULIA or IULIA) is an intermediate language that can be
|
|
|
|
compiled to bytecode for different backends.
|
|
|
|
|
2020-10-30 19:44:59 +00:00
|
|
|
Support for EVM 1.0, EVM 1.5 and Ewasm is planned, and it is designed to
|
2020-01-09 17:35:22 +00:00
|
|
|
be a usable common denominator of all three
|
|
|
|
platforms. It can already be used in stand-alone mode and
|
|
|
|
for "inline assembly" inside Solidity
|
|
|
|
and there is an experimental implementation of the Solidity compiler
|
|
|
|
that uses Yul as an intermediate language. Yul is a good target for
|
|
|
|
high-level optimisation stages that can benefit all target platforms equally.
|
|
|
|
|
|
|
|
Motivation and High-level Description
|
|
|
|
=====================================
|
|
|
|
|
|
|
|
The design of Yul tries to achieve several goals:
|
|
|
|
|
|
|
|
1. Programs written in Yul should be readable, even if the code is generated by a compiler from Solidity or another high-level language.
|
|
|
|
2. Control flow should be easy to understand to help in manual inspection, formal verification and optimization.
|
|
|
|
3. The translation from Yul to bytecode should be as straightforward as possible.
|
|
|
|
4. Yul should be suitable for whole-program optimization.
|
|
|
|
|
|
|
|
In order to achieve the first and second goal, Yul provides high-level constructs
|
|
|
|
like ``for`` loops, ``if`` and ``switch`` statements and function calls. These should
|
|
|
|
be sufficient for adequately representing the control flow for assembly programs.
|
2020-07-02 11:14:31 +00:00
|
|
|
Therefore, no explicit statements for ``SWAP``, ``DUP``, ``JUMPDEST``, ``JUMP`` and ``JUMPI``
|
2020-01-09 17:35:22 +00:00
|
|
|
are provided, because the first two obfuscate the data flow
|
|
|
|
and the last two obfuscate control flow. Furthermore, functional statements of
|
|
|
|
the form ``mul(add(x, y), 7)`` are preferred over pure opcode statements like
|
|
|
|
``7 y x add mul`` because in the first form, it is much easier to see which
|
|
|
|
operand is used for which opcode.
|
|
|
|
|
|
|
|
Even though it was designed for stack machines, Yul does not expose the complexity of the stack itself.
|
|
|
|
The programmer or auditor should not have to worry about the stack.
|
|
|
|
|
|
|
|
The third goal is achieved by compiling the
|
|
|
|
higher level constructs to bytecode in a very regular way.
|
|
|
|
The only non-local operation performed
|
|
|
|
by the assembler is name lookup of user-defined identifiers (functions, variables, ...)
|
|
|
|
and cleanup of local variables from the stack.
|
|
|
|
|
|
|
|
To avoid confusions between concepts like values and references,
|
|
|
|
Yul is statically typed. At the same time, there is a default type
|
|
|
|
(usually the integer word of the target machine) that can always
|
|
|
|
be omitted to help readability.
|
|
|
|
|
|
|
|
To keep the language simple and flexible, Yul does not have
|
|
|
|
any built-in operations, functions or types in its pure form.
|
|
|
|
These are added together with their semantics when specifying a dialect of Yul,
|
2020-11-04 11:01:12 +00:00
|
|
|
which allows specializing Yul to the requirements of different
|
2020-01-09 17:35:22 +00:00
|
|
|
target platforms and feature sets.
|
|
|
|
|
|
|
|
Currently, there is only one specified dialect of Yul. This dialect uses
|
|
|
|
the EVM opcodes as builtin functions
|
|
|
|
(see below) and defines only the type ``u256``, which is the native 256-bit
|
|
|
|
type of the EVM. Because of that, we will not provide types in the examples below.
|
|
|
|
|
|
|
|
|
|
|
|
Simple Example
|
|
|
|
==============
|
|
|
|
|
|
|
|
The following example program is written in the EVM dialect and computes exponentiation.
|
|
|
|
It can be compiled using ``solc --strict-assembly``. The builtin functions
|
|
|
|
``mul`` and ``div`` compute product and division, respectively.
|
2019-03-13 16:17:33 +00:00
|
|
|
|
docs: use Yul lexer to highlight Yul code segments.
Many commits squashed; turns out that with the combination of:
* Python v2.7,
* Sphinx v1.8.5, and
* Pygments v2.3.1
versions (old!) used in the CI, the only viable approach is:
* to use `code-block` directives with explicit language specification,
* to provide no file-local default using `highlight`, and
* to set language as `none` for grammar specifications.
Underlying are the following issues (again, for the old versions
listed above):
* Generic RST `code` doesn't work when language is `none`:
Warning, treated as error:
/root/project/docs/yul.rst:430:Cannot analyze code. No Pygments lexer found for "none".
Additionally, it might be trying to fall back to the default
(Solidity) if left unspecified.
* If a file-local default is specified using `highlight`, then
`code-block` _must_ also provide a language:
Warning, treated as error:
/root/project/docs/yul.rst:185:Error in "code-block" directive:
1 argument(s) required, 0 supplied.
* Sphinx seems to try the file-local default "yul" (specified with
`highlight`) on `code` marked having language `json`:
Warning, treated as error:
/root/project/docs/yul.rst:130:Could not lex literal_block as "yul". Highlighting skipped.
* The only well-lexed highlighter for two of the three grammar
specifications is `peg`, but it was added in Pygments v2.6.
One of the grammars - in the "Formal Specification" section,
the one after "We will use a destructuring notation for the
AST nodes." - _must_ be left unhighlighted, with language set
to `none`: all lexers do really poorly.
... And one should never, ever start treating warnings as mere
warnings, without having exhausted all other options.
Otherwise, it's a slippery slope, - and look where that brought
Gandhi: to being a strawman in every lousy argument to be had!..
2020-04-26 08:36:05 +00:00
|
|
|
.. code-block:: yul
|
2020-01-09 17:35:22 +00:00
|
|
|
|
|
|
|
{
|
|
|
|
function power(base, exponent) -> result
|
|
|
|
{
|
|
|
|
switch exponent
|
|
|
|
case 0 { result := 1 }
|
|
|
|
case 1 { result := base }
|
|
|
|
default
|
|
|
|
{
|
|
|
|
result := power(mul(base, base), div(exponent, 2))
|
|
|
|
switch mod(exponent, 2)
|
|
|
|
case 1 { result := mul(base, result) }
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
It is also possible to implement the same function using a for-loop
|
|
|
|
instead of with recursion. Here, ``lt(a, b)`` computes whether ``a`` is less than ``b``.
|
|
|
|
less-than comparison.
|
|
|
|
|
docs: use Yul lexer to highlight Yul code segments.
Many commits squashed; turns out that with the combination of:
* Python v2.7,
* Sphinx v1.8.5, and
* Pygments v2.3.1
versions (old!) used in the CI, the only viable approach is:
* to use `code-block` directives with explicit language specification,
* to provide no file-local default using `highlight`, and
* to set language as `none` for grammar specifications.
Underlying are the following issues (again, for the old versions
listed above):
* Generic RST `code` doesn't work when language is `none`:
Warning, treated as error:
/root/project/docs/yul.rst:430:Cannot analyze code. No Pygments lexer found for "none".
Additionally, it might be trying to fall back to the default
(Solidity) if left unspecified.
* If a file-local default is specified using `highlight`, then
`code-block` _must_ also provide a language:
Warning, treated as error:
/root/project/docs/yul.rst:185:Error in "code-block" directive:
1 argument(s) required, 0 supplied.
* Sphinx seems to try the file-local default "yul" (specified with
`highlight`) on `code` marked having language `json`:
Warning, treated as error:
/root/project/docs/yul.rst:130:Could not lex literal_block as "yul". Highlighting skipped.
* The only well-lexed highlighter for two of the three grammar
specifications is `peg`, but it was added in Pygments v2.6.
One of the grammars - in the "Formal Specification" section,
the one after "We will use a destructuring notation for the
AST nodes." - _must_ be left unhighlighted, with language set
to `none`: all lexers do really poorly.
... And one should never, ever start treating warnings as mere
warnings, without having exhausted all other options.
Otherwise, it's a slippery slope, - and look where that brought
Gandhi: to being a strawman in every lousy argument to be had!..
2020-04-26 08:36:05 +00:00
|
|
|
.. code-block:: yul
|
2020-01-09 17:35:22 +00:00
|
|
|
|
|
|
|
{
|
|
|
|
function power(base, exponent) -> result
|
|
|
|
{
|
|
|
|
result := 1
|
|
|
|
for { let i := 0 } lt(i, exponent) { i := add(i, 1) }
|
|
|
|
{
|
|
|
|
result := mul(result, base)
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2020-04-16 09:57:07 +00:00
|
|
|
At the :ref:`end of the section <erc20yul>`, a complete implementation of
|
|
|
|
the ERC-20 standard can be found.
|
2020-01-09 17:35:22 +00:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Stand-Alone Usage
|
|
|
|
=================
|
|
|
|
|
|
|
|
You can use Yul in its stand-alone form in the EVM dialect using the Solidity compiler.
|
2020-03-16 15:48:32 +00:00
|
|
|
This will use the :ref:`Yul object notation <yul-object>` so that it is possible to refer
|
2020-01-09 17:35:22 +00:00
|
|
|
to code as data to deploy contracts. This Yul mode is available for the commandline compiler
|
|
|
|
(use ``--strict-assembly``) and for the :ref:`standard-json interface <compiler-api>`:
|
2017-04-21 14:34:40 +00:00
|
|
|
|
docs: use Yul lexer to highlight Yul code segments.
Many commits squashed; turns out that with the combination of:
* Python v2.7,
* Sphinx v1.8.5, and
* Pygments v2.3.1
versions (old!) used in the CI, the only viable approach is:
* to use `code-block` directives with explicit language specification,
* to provide no file-local default using `highlight`, and
* to set language as `none` for grammar specifications.
Underlying are the following issues (again, for the old versions
listed above):
* Generic RST `code` doesn't work when language is `none`:
Warning, treated as error:
/root/project/docs/yul.rst:430:Cannot analyze code. No Pygments lexer found for "none".
Additionally, it might be trying to fall back to the default
(Solidity) if left unspecified.
* If a file-local default is specified using `highlight`, then
`code-block` _must_ also provide a language:
Warning, treated as error:
/root/project/docs/yul.rst:185:Error in "code-block" directive:
1 argument(s) required, 0 supplied.
* Sphinx seems to try the file-local default "yul" (specified with
`highlight`) on `code` marked having language `json`:
Warning, treated as error:
/root/project/docs/yul.rst:130:Could not lex literal_block as "yul". Highlighting skipped.
* The only well-lexed highlighter for two of the three grammar
specifications is `peg`, but it was added in Pygments v2.6.
One of the grammars - in the "Formal Specification" section,
the one after "We will use a destructuring notation for the
AST nodes." - _must_ be left unhighlighted, with language set
to `none`: all lexers do really poorly.
... And one should never, ever start treating warnings as mere
warnings, without having exhausted all other options.
Otherwise, it's a slippery slope, - and look where that brought
Gandhi: to being a strawman in every lousy argument to be had!..
2020-04-26 08:36:05 +00:00
|
|
|
.. code-block:: json
|
2017-04-21 14:34:40 +00:00
|
|
|
|
|
|
|
{
|
|
|
|
"language": "Yul",
|
|
|
|
"sources": { "input.yul": { "content": "{ sstore(0, 1) }" } },
|
|
|
|
"settings": {
|
|
|
|
"outputSelection": { "*": { "*": ["*"], "": [ "*" ] } },
|
|
|
|
"optimizer": { "enabled": true, "details": { "yul": true } }
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2019-03-13 16:17:33 +00:00
|
|
|
.. warning::
|
2018-01-04 16:19:45 +00:00
|
|
|
|
2020-01-09 17:35:22 +00:00
|
|
|
Yul is in active development and bytecode generation is only fully implemented for the EVM dialect of Yul
|
|
|
|
with EVM 1.0 as target.
|
2018-01-04 16:19:45 +00:00
|
|
|
|
2017-04-18 12:12:04 +00:00
|
|
|
|
2020-01-09 17:35:22 +00:00
|
|
|
Informal Description of Yul
|
|
|
|
===========================
|
|
|
|
|
|
|
|
In the following, we will talk about each individual aspect
|
|
|
|
of the Yul language. In examples, we will use the default EVM dialect.
|
|
|
|
|
|
|
|
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.
|
2020-03-16 15:48:32 +00:00
|
|
|
Please see :ref:`Yul Objects <yul-object>` below for details on that.
|
2020-01-09 17:35:22 +00:00
|
|
|
In this section, we are only concerned with the code part of such an object.
|
|
|
|
This code part always consists of a curly-braces
|
|
|
|
delimited block. Most tools support specifying just a code block
|
|
|
|
where an object is expected.
|
|
|
|
|
|
|
|
Inside a code block, the following elements can be used
|
|
|
|
(see the later sections for more details):
|
|
|
|
|
2021-07-14 15:55:05 +00:00
|
|
|
- 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. ``let x := 7``, ``let x := add(y, 3)`` or ``let x`` (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. ``{ let x := 3 { let y := add(x, 1) } }``
|
|
|
|
- if statements, e.g. ``if lt(a, b) { sstore(0, 1) }``
|
|
|
|
- switch statements, e.g. ``switch mload(0) case 0 { revert() } default { mstore(0, 1) }``
|
|
|
|
- for loops, e.g. ``for { let i := 0} lt(i, 10) { i := add(i, 1) } { mstore(i, 7) }``
|
2021-12-05 07:58:03 +00:00
|
|
|
- function definitions, e.g. ``function f(a, b) -> c { c := add(a, b) }``
|
2020-01-09 17:35:22 +00:00
|
|
|
|
|
|
|
Multiple syntactical elements can follow each other simply separated by
|
|
|
|
whitespace, i.e. there is no terminating ``;`` or newline required.
|
|
|
|
|
|
|
|
Literals
|
|
|
|
--------
|
|
|
|
|
2021-09-15 23:52:56 +00:00
|
|
|
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`` where ``N`` 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 than ``2**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 viewing
|
|
|
|
a non-escape ASCII character as a single byte whose value is the ASCII code,
|
|
|
|
an escape ``\xNN`` as single byte with that value, and
|
|
|
|
an 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 viewing
|
|
|
|
each 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.
|
2021-03-25 16:00:05 +00:00
|
|
|
|
2020-01-09 17:35:22 +00:00
|
|
|
When compiling for the EVM, this will be translated into an
|
|
|
|
appropriate ``PUSHi`` instruction. In the following example,
|
|
|
|
``3`` and ``2`` are added resulting in 5 and then the
|
|
|
|
bitwise ``and`` with the string "abc" is computed.
|
|
|
|
The final value is assigned to a local variable called ``x``.
|
2020-06-19 11:39:01 +00:00
|
|
|
|
2021-09-15 23:52:56 +00:00
|
|
|
The 32-byte limit above does not apply to string literals passed to builtin functions that require
|
2020-06-19 11:39:01 +00:00
|
|
|
literal arguments (e.g. ``setimmutable`` or ``loadimmutable``). Those strings never end up in the
|
|
|
|
generated bytecode.
|
2020-01-09 17:35:22 +00:00
|
|
|
|
docs: use Yul lexer to highlight Yul code segments.
Many commits squashed; turns out that with the combination of:
* Python v2.7,
* Sphinx v1.8.5, and
* Pygments v2.3.1
versions (old!) used in the CI, the only viable approach is:
* to use `code-block` directives with explicit language specification,
* to provide no file-local default using `highlight`, and
* to set language as `none` for grammar specifications.
Underlying are the following issues (again, for the old versions
listed above):
* Generic RST `code` doesn't work when language is `none`:
Warning, treated as error:
/root/project/docs/yul.rst:430:Cannot analyze code. No Pygments lexer found for "none".
Additionally, it might be trying to fall back to the default
(Solidity) if left unspecified.
* If a file-local default is specified using `highlight`, then
`code-block` _must_ also provide a language:
Warning, treated as error:
/root/project/docs/yul.rst:185:Error in "code-block" directive:
1 argument(s) required, 0 supplied.
* Sphinx seems to try the file-local default "yul" (specified with
`highlight`) on `code` marked having language `json`:
Warning, treated as error:
/root/project/docs/yul.rst:130:Could not lex literal_block as "yul". Highlighting skipped.
* The only well-lexed highlighter for two of the three grammar
specifications is `peg`, but it was added in Pygments v2.6.
One of the grammars - in the "Formal Specification" section,
the one after "We will use a destructuring notation for the
AST nodes." - _must_ be left unhighlighted, with language set
to `none`: all lexers do really poorly.
... And one should never, ever start treating warnings as mere
warnings, without having exhausted all other options.
Otherwise, it's a slippery slope, - and look where that brought
Gandhi: to being a strawman in every lousy argument to be had!..
2020-04-26 08:36:05 +00:00
|
|
|
.. code-block:: yul
|
2017-04-18 15:40:31 +00:00
|
|
|
|
2020-01-09 17:35:22 +00:00
|
|
|
let x := and("abc", add(3, 2))
|
2017-04-18 12:12:04 +00:00
|
|
|
|
2020-01-09 17:35:22 +00:00
|
|
|
Unless it is the default type, the type of a literal
|
|
|
|
has to be specified after a colon:
|
|
|
|
|
docs: use Yul lexer to highlight Yul code segments.
Many commits squashed; turns out that with the combination of:
* Python v2.7,
* Sphinx v1.8.5, and
* Pygments v2.3.1
versions (old!) used in the CI, the only viable approach is:
* to use `code-block` directives with explicit language specification,
* to provide no file-local default using `highlight`, and
* to set language as `none` for grammar specifications.
Underlying are the following issues (again, for the old versions
listed above):
* Generic RST `code` doesn't work when language is `none`:
Warning, treated as error:
/root/project/docs/yul.rst:430:Cannot analyze code. No Pygments lexer found for "none".
Additionally, it might be trying to fall back to the default
(Solidity) if left unspecified.
* If a file-local default is specified using `highlight`, then
`code-block` _must_ also provide a language:
Warning, treated as error:
/root/project/docs/yul.rst:185:Error in "code-block" directive:
1 argument(s) required, 0 supplied.
* Sphinx seems to try the file-local default "yul" (specified with
`highlight`) on `code` marked having language `json`:
Warning, treated as error:
/root/project/docs/yul.rst:130:Could not lex literal_block as "yul". Highlighting skipped.
* The only well-lexed highlighter for two of the three grammar
specifications is `peg`, but it was added in Pygments v2.6.
One of the grammars - in the "Formal Specification" section,
the one after "We will use a destructuring notation for the
AST nodes." - _must_ be left unhighlighted, with language set
to `none`: all lexers do really poorly.
... And one should never, ever start treating warnings as mere
warnings, without having exhausted all other options.
Otherwise, it's a slippery slope, - and look where that brought
Gandhi: to being a strawman in every lousy argument to be had!..
2020-04-26 08:36:05 +00:00
|
|
|
.. code-block:: yul
|
2020-01-09 17:35:22 +00:00
|
|
|
|
2021-07-05 17:38:41 +00:00
|
|
|
// This will not compile (u32 and u256 type not implemented yet)
|
|
|
|
let x := and("abc":u32, add(3:u256, 2:u256))
|
2020-01-09 17:35:22 +00:00
|
|
|
|
|
|
|
|
|
|
|
Function Calls
|
|
|
|
--------------
|
|
|
|
|
|
|
|
Both built-in and user-defined functions (see below) can be called
|
|
|
|
in the same way as shown in the previous example.
|
|
|
|
If the function returns a single value, it can be directly used
|
|
|
|
inside an expression again. If it returns multiple values,
|
|
|
|
they have to be assigned to local variables.
|
|
|
|
|
docs: use Yul lexer to highlight Yul code segments.
Many commits squashed; turns out that with the combination of:
* Python v2.7,
* Sphinx v1.8.5, and
* Pygments v2.3.1
versions (old!) used in the CI, the only viable approach is:
* to use `code-block` directives with explicit language specification,
* to provide no file-local default using `highlight`, and
* to set language as `none` for grammar specifications.
Underlying are the following issues (again, for the old versions
listed above):
* Generic RST `code` doesn't work when language is `none`:
Warning, treated as error:
/root/project/docs/yul.rst:430:Cannot analyze code. No Pygments lexer found for "none".
Additionally, it might be trying to fall back to the default
(Solidity) if left unspecified.
* If a file-local default is specified using `highlight`, then
`code-block` _must_ also provide a language:
Warning, treated as error:
/root/project/docs/yul.rst:185:Error in "code-block" directive:
1 argument(s) required, 0 supplied.
* Sphinx seems to try the file-local default "yul" (specified with
`highlight`) on `code` marked having language `json`:
Warning, treated as error:
/root/project/docs/yul.rst:130:Could not lex literal_block as "yul". Highlighting skipped.
* The only well-lexed highlighter for two of the three grammar
specifications is `peg`, but it was added in Pygments v2.6.
One of the grammars - in the "Formal Specification" section,
the one after "We will use a destructuring notation for the
AST nodes." - _must_ be left unhighlighted, with language set
to `none`: all lexers do really poorly.
... And one should never, ever start treating warnings as mere
warnings, without having exhausted all other options.
Otherwise, it's a slippery slope, - and look where that brought
Gandhi: to being a strawman in every lousy argument to be had!..
2020-04-26 08:36:05 +00:00
|
|
|
.. code-block:: yul
|
2020-01-09 17:35:22 +00:00
|
|
|
|
2021-07-05 17:38:41 +00:00
|
|
|
function f(x, y) -> a, b { /* ... */ }
|
2020-01-09 17:35:22 +00:00
|
|
|
mstore(0x80, add(mload(0x80), 3))
|
2021-07-05 17:38:41 +00:00
|
|
|
// Here, the user-defined function `f` returns two values.
|
2020-01-09 17:35:22 +00:00
|
|
|
let x, y := f(1, mload(0))
|
|
|
|
|
|
|
|
For built-in functions of the EVM, functional expressions
|
|
|
|
can be directly translated to a stream of opcodes:
|
|
|
|
You just read the expression from right to left to obtain the
|
|
|
|
opcodes. In the case of the first line in the example, this
|
|
|
|
is ``PUSH1 3 PUSH1 0x80 MLOAD ADD PUSH1 0x80 MSTORE``.
|
|
|
|
|
|
|
|
For calls to user-defined functions, the arguments are also
|
|
|
|
put on the stack from right to left and this is the order
|
|
|
|
in 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 and ``x``
|
|
|
|
is below it.
|
|
|
|
|
|
|
|
Variable Declarations
|
|
|
|
---------------------
|
|
|
|
|
|
|
|
You can use the ``let`` 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 reserved
|
|
|
|
for the variable and automatically removed again when the end of the block
|
|
|
|
is 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 directly
|
|
|
|
influence memory or storage, but they can be used as pointers
|
|
|
|
to memory or storage locations in the built-in functions
|
|
|
|
``mstore``, ``mload``, ``sstore`` and ``sload``.
|
2020-09-14 10:52:15 +00:00
|
|
|
Future dialects might introduce specific types for such pointers.
|
2020-01-09 17:35:22 +00:00
|
|
|
|
|
|
|
When a variable is referenced, its current value is copied.
|
|
|
|
For the EVM, this translates to a ``DUP`` instruction.
|
2017-04-18 12:12:04 +00:00
|
|
|
|
docs: use Yul lexer to highlight Yul code segments.
Many commits squashed; turns out that with the combination of:
* Python v2.7,
* Sphinx v1.8.5, and
* Pygments v2.3.1
versions (old!) used in the CI, the only viable approach is:
* to use `code-block` directives with explicit language specification,
* to provide no file-local default using `highlight`, and
* to set language as `none` for grammar specifications.
Underlying are the following issues (again, for the old versions
listed above):
* Generic RST `code` doesn't work when language is `none`:
Warning, treated as error:
/root/project/docs/yul.rst:430:Cannot analyze code. No Pygments lexer found for "none".
Additionally, it might be trying to fall back to the default
(Solidity) if left unspecified.
* If a file-local default is specified using `highlight`, then
`code-block` _must_ also provide a language:
Warning, treated as error:
/root/project/docs/yul.rst:185:Error in "code-block" directive:
1 argument(s) required, 0 supplied.
* Sphinx seems to try the file-local default "yul" (specified with
`highlight`) on `code` marked having language `json`:
Warning, treated as error:
/root/project/docs/yul.rst:130:Could not lex literal_block as "yul". Highlighting skipped.
* The only well-lexed highlighter for two of the three grammar
specifications is `peg`, but it was added in Pygments v2.6.
One of the grammars - in the "Formal Specification" section,
the one after "We will use a destructuring notation for the
AST nodes." - _must_ be left unhighlighted, with language set
to `none`: all lexers do really poorly.
... And one should never, ever start treating warnings as mere
warnings, without having exhausted all other options.
Otherwise, it's a slippery slope, - and look where that brought
Gandhi: to being a strawman in every lousy argument to be had!..
2020-04-26 08:36:05 +00:00
|
|
|
.. code-block:: yul
|
2017-04-18 12:12:04 +00:00
|
|
|
|
|
|
|
{
|
2020-01-09 17:35:22 +00:00
|
|
|
let zero := 0
|
|
|
|
let v := calldataload(zero)
|
2017-04-18 12:12:04 +00:00
|
|
|
{
|
2020-01-09 17:35:22 +00:00
|
|
|
let y := add(sload(v), 1)
|
|
|
|
v := y
|
|
|
|
} // y is "deallocated" here
|
|
|
|
sstore(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 multiple
|
|
|
|
variables in one statement when you assign from a function call
|
|
|
|
that returns multiple values.
|
|
|
|
|
docs: use Yul lexer to highlight Yul code segments.
Many commits squashed; turns out that with the combination of:
* Python v2.7,
* Sphinx v1.8.5, and
* Pygments v2.3.1
versions (old!) used in the CI, the only viable approach is:
* to use `code-block` directives with explicit language specification,
* to provide no file-local default using `highlight`, and
* to set language as `none` for grammar specifications.
Underlying are the following issues (again, for the old versions
listed above):
* Generic RST `code` doesn't work when language is `none`:
Warning, treated as error:
/root/project/docs/yul.rst:430:Cannot analyze code. No Pygments lexer found for "none".
Additionally, it might be trying to fall back to the default
(Solidity) if left unspecified.
* If a file-local default is specified using `highlight`, then
`code-block` _must_ also provide a language:
Warning, treated as error:
/root/project/docs/yul.rst:185:Error in "code-block" directive:
1 argument(s) required, 0 supplied.
* Sphinx seems to try the file-local default "yul" (specified with
`highlight`) on `code` marked having language `json`:
Warning, treated as error:
/root/project/docs/yul.rst:130:Could not lex literal_block as "yul". Highlighting skipped.
* The only well-lexed highlighter for two of the three grammar
specifications is `peg`, but it was added in Pygments v2.6.
One of the grammars - in the "Formal Specification" section,
the one after "We will use a destructuring notation for the
AST nodes." - _must_ be left unhighlighted, with language set
to `none`: all lexers do really poorly.
... And one should never, ever start treating warnings as mere
warnings, without having exhausted all other options.
Otherwise, it's a slippery slope, - and look where that brought
Gandhi: to being a strawman in every lousy argument to be had!..
2020-04-26 08:36:05 +00:00
|
|
|
.. code-block:: yul
|
2020-01-09 17:35:22 +00:00
|
|
|
|
2021-07-05 17:38:41 +00:00
|
|
|
// This will not compile (u32 and u256 type not implemented yet)
|
2020-01-09 17:35:22 +00:00
|
|
|
{
|
2021-07-05 17:38:41 +00:00
|
|
|
let zero:u32 := 0:u32
|
|
|
|
let v:u256, t:u32 := f()
|
2020-01-09 17:35:22 +00:00
|
|
|
let x, y := g()
|
|
|
|
}
|
|
|
|
|
|
|
|
Depending on the optimiser settings, the compiler can free the stack slots
|
|
|
|
already after the variable has been used for
|
|
|
|
the 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 multiple
|
|
|
|
variables at the same time. For this, the number and types of the
|
|
|
|
values have to match.
|
|
|
|
If you want to assign the values returned from a function that has
|
|
|
|
multiple return parameters, you have to provide multiple variables.
|
2020-07-06 15:25:55 +00:00
|
|
|
The same variable may not occur multiple times on the left-hand side of
|
|
|
|
an assignment, e.g. ``x, x := f()`` is invalid.
|
2020-01-09 17:35:22 +00:00
|
|
|
|
docs: use Yul lexer to highlight Yul code segments.
Many commits squashed; turns out that with the combination of:
* Python v2.7,
* Sphinx v1.8.5, and
* Pygments v2.3.1
versions (old!) used in the CI, the only viable approach is:
* to use `code-block` directives with explicit language specification,
* to provide no file-local default using `highlight`, and
* to set language as `none` for grammar specifications.
Underlying are the following issues (again, for the old versions
listed above):
* Generic RST `code` doesn't work when language is `none`:
Warning, treated as error:
/root/project/docs/yul.rst:430:Cannot analyze code. No Pygments lexer found for "none".
Additionally, it might be trying to fall back to the default
(Solidity) if left unspecified.
* If a file-local default is specified using `highlight`, then
`code-block` _must_ also provide a language:
Warning, treated as error:
/root/project/docs/yul.rst:185:Error in "code-block" directive:
1 argument(s) required, 0 supplied.
* Sphinx seems to try the file-local default "yul" (specified with
`highlight`) on `code` marked having language `json`:
Warning, treated as error:
/root/project/docs/yul.rst:130:Could not lex literal_block as "yul". Highlighting skipped.
* The only well-lexed highlighter for two of the three grammar
specifications is `peg`, but it was added in Pygments v2.6.
One of the grammars - in the "Formal Specification" section,
the one after "We will use a destructuring notation for the
AST nodes." - _must_ be left unhighlighted, with language set
to `none`: all lexers do really poorly.
... And one should never, ever start treating warnings as mere
warnings, without having exhausted all other options.
Otherwise, it's a slippery slope, - and look where that brought
Gandhi: to being a strawman in every lousy argument to be had!..
2020-04-26 08:36:05 +00:00
|
|
|
.. code-block:: yul
|
2020-01-09 17:35:22 +00:00
|
|
|
|
|
|
|
let v := 0
|
|
|
|
// re-assign v
|
|
|
|
v := 2
|
|
|
|
let t := add(v, 2)
|
|
|
|
function f() -> a, b { }
|
|
|
|
// assign multiple values
|
|
|
|
v, 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) if
|
|
|
|
you need multiple alternatives.
|
|
|
|
|
docs: use Yul lexer to highlight Yul code segments.
Many commits squashed; turns out that with the combination of:
* Python v2.7,
* Sphinx v1.8.5, and
* Pygments v2.3.1
versions (old!) used in the CI, the only viable approach is:
* to use `code-block` directives with explicit language specification,
* to provide no file-local default using `highlight`, and
* to set language as `none` for grammar specifications.
Underlying are the following issues (again, for the old versions
listed above):
* Generic RST `code` doesn't work when language is `none`:
Warning, treated as error:
/root/project/docs/yul.rst:430:Cannot analyze code. No Pygments lexer found for "none".
Additionally, it might be trying to fall back to the default
(Solidity) if left unspecified.
* If a file-local default is specified using `highlight`, then
`code-block` _must_ also provide a language:
Warning, treated as error:
/root/project/docs/yul.rst:185:Error in "code-block" directive:
1 argument(s) required, 0 supplied.
* Sphinx seems to try the file-local default "yul" (specified with
`highlight`) on `code` marked having language `json`:
Warning, treated as error:
/root/project/docs/yul.rst:130:Could not lex literal_block as "yul". Highlighting skipped.
* The only well-lexed highlighter for two of the three grammar
specifications is `peg`, but it was added in Pygments v2.6.
One of the grammars - in the "Formal Specification" section,
the one after "We will use a destructuring notation for the
AST nodes." - _must_ be left unhighlighted, with language set
to `none`: all lexers do really poorly.
... And one should never, ever start treating warnings as mere
warnings, without having exhausted all other options.
Otherwise, it's a slippery slope, - and look where that brought
Gandhi: to being a strawman in every lousy argument to be had!..
2020-04-26 08:36:05 +00:00
|
|
|
.. code-block:: yul
|
2020-01-09 17:35:22 +00:00
|
|
|
|
2021-07-05 17:38:41 +00:00
|
|
|
if lt(calldatasize(), 4) { revert(0, 0) }
|
2020-01-09 17:35:22 +00:00
|
|
|
|
|
|
|
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 does
|
|
|
|
not continue from one case to the next. There can be a fallback or default
|
|
|
|
case called ``default`` which is taken if none of the literal constants matches.
|
|
|
|
|
docs: use Yul lexer to highlight Yul code segments.
Many commits squashed; turns out that with the combination of:
* Python v2.7,
* Sphinx v1.8.5, and
* Pygments v2.3.1
versions (old!) used in the CI, the only viable approach is:
* to use `code-block` directives with explicit language specification,
* to provide no file-local default using `highlight`, and
* to set language as `none` for grammar specifications.
Underlying are the following issues (again, for the old versions
listed above):
* Generic RST `code` doesn't work when language is `none`:
Warning, treated as error:
/root/project/docs/yul.rst:430:Cannot analyze code. No Pygments lexer found for "none".
Additionally, it might be trying to fall back to the default
(Solidity) if left unspecified.
* If a file-local default is specified using `highlight`, then
`code-block` _must_ also provide a language:
Warning, treated as error:
/root/project/docs/yul.rst:185:Error in "code-block" directive:
1 argument(s) required, 0 supplied.
* Sphinx seems to try the file-local default "yul" (specified with
`highlight`) on `code` marked having language `json`:
Warning, treated as error:
/root/project/docs/yul.rst:130:Could not lex literal_block as "yul". Highlighting skipped.
* The only well-lexed highlighter for two of the three grammar
specifications is `peg`, but it was added in Pygments v2.6.
One of the grammars - in the "Formal Specification" section,
the one after "We will use a destructuring notation for the
AST nodes." - _must_ be left unhighlighted, with language set
to `none`: all lexers do really poorly.
... And one should never, ever start treating warnings as mere
warnings, without having exhausted all other options.
Otherwise, it's a slippery slope, - and look where that brought
Gandhi: to being a strawman in every lousy argument to be had!..
2020-04-26 08:36:05 +00:00
|
|
|
.. code-block:: yul
|
2020-01-09 17:35:22 +00:00
|
|
|
|
|
|
|
{
|
|
|
|
let x := 0
|
|
|
|
switch calldataload(4)
|
|
|
|
case 0 {
|
|
|
|
x := calldataload(0x24)
|
|
|
|
}
|
|
|
|
default {
|
|
|
|
x := calldataload(0x44)
|
2017-04-18 12:12:04 +00:00
|
|
|
}
|
2020-01-09 17:35:22 +00:00
|
|
|
sstore(0, div(x, 2))
|
2017-04-18 12:12:04 +00:00
|
|
|
}
|
|
|
|
|
2020-01-09 17:35:22 +00:00
|
|
|
The list of cases is not enclosed by curly braces, but the body of a
|
|
|
|
case does require them.
|
|
|
|
|
|
|
|
Loops
|
|
|
|
-----
|
|
|
|
|
|
|
|
Yul supports for-loops which consist of
|
|
|
|
a header containing an initializing part, a condition, a post-iteration
|
|
|
|
part and a body. The condition has to be an expression, while
|
|
|
|
the other three are blocks. If the initializing part
|
|
|
|
declares any variables at the top level, the scope of these variables extends to all other
|
|
|
|
parts of the loop.
|
|
|
|
|
|
|
|
The ``break`` and ``continue`` statements can be used in the body to exit the loop
|
|
|
|
or skip to the post-part, respectively.
|
|
|
|
|
|
|
|
The following example computes the sum of an area in memory.
|
2017-04-18 12:12:04 +00:00
|
|
|
|
docs: use Yul lexer to highlight Yul code segments.
Many commits squashed; turns out that with the combination of:
* Python v2.7,
* Sphinx v1.8.5, and
* Pygments v2.3.1
versions (old!) used in the CI, the only viable approach is:
* to use `code-block` directives with explicit language specification,
* to provide no file-local default using `highlight`, and
* to set language as `none` for grammar specifications.
Underlying are the following issues (again, for the old versions
listed above):
* Generic RST `code` doesn't work when language is `none`:
Warning, treated as error:
/root/project/docs/yul.rst:430:Cannot analyze code. No Pygments lexer found for "none".
Additionally, it might be trying to fall back to the default
(Solidity) if left unspecified.
* If a file-local default is specified using `highlight`, then
`code-block` _must_ also provide a language:
Warning, treated as error:
/root/project/docs/yul.rst:185:Error in "code-block" directive:
1 argument(s) required, 0 supplied.
* Sphinx seems to try the file-local default "yul" (specified with
`highlight`) on `code` marked having language `json`:
Warning, treated as error:
/root/project/docs/yul.rst:130:Could not lex literal_block as "yul". Highlighting skipped.
* The only well-lexed highlighter for two of the three grammar
specifications is `peg`, but it was added in Pygments v2.6.
One of the grammars - in the "Formal Specification" section,
the one after "We will use a destructuring notation for the
AST nodes." - _must_ be left unhighlighted, with language set
to `none`: all lexers do really poorly.
... And one should never, ever start treating warnings as mere
warnings, without having exhausted all other options.
Otherwise, it's a slippery slope, - and look where that brought
Gandhi: to being a strawman in every lousy argument to be had!..
2020-04-26 08:36:05 +00:00
|
|
|
.. code-block:: yul
|
2017-04-18 12:12:04 +00:00
|
|
|
|
|
|
|
{
|
2020-01-09 17:35:22 +00:00
|
|
|
let x := 0
|
|
|
|
for { let i := 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.
|
|
|
|
|
docs: use Yul lexer to highlight Yul code segments.
Many commits squashed; turns out that with the combination of:
* Python v2.7,
* Sphinx v1.8.5, and
* Pygments v2.3.1
versions (old!) used in the CI, the only viable approach is:
* to use `code-block` directives with explicit language specification,
* to provide no file-local default using `highlight`, and
* to set language as `none` for grammar specifications.
Underlying are the following issues (again, for the old versions
listed above):
* Generic RST `code` doesn't work when language is `none`:
Warning, treated as error:
/root/project/docs/yul.rst:430:Cannot analyze code. No Pygments lexer found for "none".
Additionally, it might be trying to fall back to the default
(Solidity) if left unspecified.
* If a file-local default is specified using `highlight`, then
`code-block` _must_ also provide a language:
Warning, treated as error:
/root/project/docs/yul.rst:185:Error in "code-block" directive:
1 argument(s) required, 0 supplied.
* Sphinx seems to try the file-local default "yul" (specified with
`highlight`) on `code` marked having language `json`:
Warning, treated as error:
/root/project/docs/yul.rst:130:Could not lex literal_block as "yul". Highlighting skipped.
* The only well-lexed highlighter for two of the three grammar
specifications is `peg`, but it was added in Pygments v2.6.
One of the grammars - in the "Formal Specification" section,
the one after "We will use a destructuring notation for the
AST nodes." - _must_ be left unhighlighted, with language set
to `none`: all lexers do really poorly.
... And one should never, ever start treating warnings as mere
warnings, without having exhausted all other options.
Otherwise, it's a slippery slope, - and look where that brought
Gandhi: to being a strawman in every lousy argument to be had!..
2020-04-26 08:36:05 +00:00
|
|
|
.. code-block:: yul
|
2020-01-09 17:35:22 +00:00
|
|
|
|
|
|
|
{
|
|
|
|
let x := 0
|
|
|
|
let i := 0
|
|
|
|
for { } 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 functions
|
|
|
|
in Solidity since they are never part of an external interface of a contract and
|
|
|
|
are part of a namespace separate from the one for Solidity functions.
|
|
|
|
|
|
|
|
For the EVM, Yul functions take their
|
|
|
|
arguments (and a return PC) from the stack and also put the results onto the
|
|
|
|
stack. 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 are
|
|
|
|
declared in. Inside a function, you cannot access local variables
|
|
|
|
defined 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 assign
|
|
|
|
them to multiple variables using ``a, b := f(x)`` or ``let a, b := f(x)``.
|
|
|
|
|
|
|
|
The ``leave`` statement can be used to exit the current function. It
|
|
|
|
works like the ``return`` statement in other languages just that it does
|
|
|
|
not take a value to return, it just exits the functions and the function
|
|
|
|
will return whatever values are currently assigned to the return variable(s).
|
|
|
|
|
|
|
|
Note that the EVM dialect has a built-in function called ``return`` that
|
|
|
|
quits the full execution context (internal message call) and not just
|
|
|
|
the current yul function.
|
|
|
|
|
|
|
|
The following example implements the power function by square-and-multiply.
|
|
|
|
|
docs: use Yul lexer to highlight Yul code segments.
Many commits squashed; turns out that with the combination of:
* Python v2.7,
* Sphinx v1.8.5, and
* Pygments v2.3.1
versions (old!) used in the CI, the only viable approach is:
* to use `code-block` directives with explicit language specification,
* to provide no file-local default using `highlight`, and
* to set language as `none` for grammar specifications.
Underlying are the following issues (again, for the old versions
listed above):
* Generic RST `code` doesn't work when language is `none`:
Warning, treated as error:
/root/project/docs/yul.rst:430:Cannot analyze code. No Pygments lexer found for "none".
Additionally, it might be trying to fall back to the default
(Solidity) if left unspecified.
* If a file-local default is specified using `highlight`, then
`code-block` _must_ also provide a language:
Warning, treated as error:
/root/project/docs/yul.rst:185:Error in "code-block" directive:
1 argument(s) required, 0 supplied.
* Sphinx seems to try the file-local default "yul" (specified with
`highlight`) on `code` marked having language `json`:
Warning, treated as error:
/root/project/docs/yul.rst:130:Could not lex literal_block as "yul". Highlighting skipped.
* The only well-lexed highlighter for two of the three grammar
specifications is `peg`, but it was added in Pygments v2.6.
One of the grammars - in the "Formal Specification" section,
the one after "We will use a destructuring notation for the
AST nodes." - _must_ be left unhighlighted, with language set
to `none`: all lexers do really poorly.
... And one should never, ever start treating warnings as mere
warnings, without having exhausted all other options.
Otherwise, it's a slippery slope, - and look where that brought
Gandhi: to being a strawman in every lousy argument to be had!..
2020-04-26 08:36:05 +00:00
|
|
|
.. code-block:: yul
|
2020-01-09 17:35:22 +00:00
|
|
|
|
|
|
|
{
|
|
|
|
function power(base, exponent) -> result {
|
|
|
|
switch exponent
|
|
|
|
case 0 { result := 1 }
|
|
|
|
case 1 { result := base }
|
|
|
|
default {
|
|
|
|
result := power(mul(base, base), div(exponent, 2))
|
|
|
|
switch mod(exponent, 2)
|
|
|
|
case 1 { result := mul(base, result) }
|
2017-04-18 12:12:04 +00:00
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2018-06-05 17:43:23 +00:00
|
|
|
Specification of Yul
|
|
|
|
====================
|
2017-04-18 12:12:04 +00:00
|
|
|
|
2020-01-09 17:35:22 +00:00
|
|
|
This chapter describes Yul code formally. Yul code is usually placed inside Yul objects,
|
|
|
|
which are explained in their own chapter.
|
2017-04-21 16:35:56 +00:00
|
|
|
|
docs: use Yul lexer to highlight Yul code segments.
Many commits squashed; turns out that with the combination of:
* Python v2.7,
* Sphinx v1.8.5, and
* Pygments v2.3.1
versions (old!) used in the CI, the only viable approach is:
* to use `code-block` directives with explicit language specification,
* to provide no file-local default using `highlight`, and
* to set language as `none` for grammar specifications.
Underlying are the following issues (again, for the old versions
listed above):
* Generic RST `code` doesn't work when language is `none`:
Warning, treated as error:
/root/project/docs/yul.rst:430:Cannot analyze code. No Pygments lexer found for "none".
Additionally, it might be trying to fall back to the default
(Solidity) if left unspecified.
* If a file-local default is specified using `highlight`, then
`code-block` _must_ also provide a language:
Warning, treated as error:
/root/project/docs/yul.rst:185:Error in "code-block" directive:
1 argument(s) required, 0 supplied.
* Sphinx seems to try the file-local default "yul" (specified with
`highlight`) on `code` marked having language `json`:
Warning, treated as error:
/root/project/docs/yul.rst:130:Could not lex literal_block as "yul". Highlighting skipped.
* The only well-lexed highlighter for two of the three grammar
specifications is `peg`, but it was added in Pygments v2.6.
One of the grammars - in the "Formal Specification" section,
the one after "We will use a destructuring notation for the
AST nodes." - _must_ be left unhighlighted, with language set
to `none`: all lexers do really poorly.
... And one should never, ever start treating warnings as mere
warnings, without having exhausted all other options.
Otherwise, it's a slippery slope, - and look where that brought
Gandhi: to being a strawman in every lousy argument to be had!..
2020-04-26 08:36:05 +00:00
|
|
|
.. code-block:: none
|
2017-04-18 12:12:04 +00:00
|
|
|
|
|
|
|
Block = '{' Statement* '}'
|
|
|
|
Statement =
|
|
|
|
Block |
|
|
|
|
FunctionDefinition |
|
|
|
|
VariableDeclaration |
|
|
|
|
Assignment |
|
2018-09-29 17:42:44 +00:00
|
|
|
If |
|
2017-04-18 12:12:04 +00:00
|
|
|
Expression |
|
|
|
|
Switch |
|
|
|
|
ForLoop |
|
2019-10-28 14:25:02 +00:00
|
|
|
BreakContinue |
|
|
|
|
Leave
|
2017-04-18 12:12:04 +00:00
|
|
|
FunctionDefinition =
|
2017-04-21 16:04:27 +00:00
|
|
|
'function' Identifier '(' TypedIdentifierList? ')'
|
|
|
|
( '->' TypedIdentifierList )? Block
|
2017-04-18 12:12:04 +00:00
|
|
|
VariableDeclaration =
|
2017-04-21 16:04:27 +00:00
|
|
|
'let' TypedIdentifierList ( ':=' Expression )?
|
2017-04-18 12:12:04 +00:00
|
|
|
Assignment =
|
2017-04-21 16:04:27 +00:00
|
|
|
IdentifierList ':=' Expression
|
2017-04-18 12:12:04 +00:00
|
|
|
Expression =
|
|
|
|
FunctionCall | Identifier | Literal
|
2017-11-22 13:17:31 +00:00
|
|
|
If =
|
|
|
|
'if' Expression Block
|
2017-04-18 12:12:04 +00:00
|
|
|
Switch =
|
2018-09-10 05:51:51 +00:00
|
|
|
'switch' Expression ( Case+ Default? | Default )
|
2017-04-18 12:12:04 +00:00
|
|
|
Case =
|
2017-05-19 22:15:07 +00:00
|
|
|
'case' Literal Block
|
2018-09-10 05:51:51 +00:00
|
|
|
Default =
|
|
|
|
'default' Block
|
2017-04-18 12:12:04 +00:00
|
|
|
ForLoop =
|
|
|
|
'for' Block Expression Block Block
|
|
|
|
BreakContinue =
|
|
|
|
'break' | 'continue'
|
2019-10-28 14:25:02 +00:00
|
|
|
Leave = 'leave'
|
2017-04-18 12:12:04 +00:00
|
|
|
FunctionCall =
|
|
|
|
Identifier '(' ( Expression ( ',' Expression )* )? ')'
|
2019-04-24 11:16:43 +00:00
|
|
|
Identifier = [a-zA-Z_$] [a-zA-Z_$0-9.]*
|
2017-04-18 12:12:04 +00:00
|
|
|
IdentifierList = Identifier ( ',' Identifier)*
|
2020-01-09 17:35:22 +00:00
|
|
|
TypeName = Identifier
|
|
|
|
TypedIdentifierList = Identifier ( ':' TypeName )? ( ',' Identifier ( ':' TypeName )? )*
|
2017-04-18 12:12:04 +00:00
|
|
|
Literal =
|
2020-08-12 22:59:37 +00:00
|
|
|
(NumberLiteral | StringLiteral | TrueLiteral | FalseLiteral) ( ':' TypeName )?
|
2017-04-18 12:12:04 +00:00
|
|
|
NumberLiteral = HexNumber | DecimalNumber
|
|
|
|
StringLiteral = '"' ([^"\r\n\\] | '\\' .)* '"'
|
2017-05-19 23:05:14 +00:00
|
|
|
TrueLiteral = 'true'
|
|
|
|
FalseLiteral = 'false'
|
2017-04-18 12:12:04 +00:00
|
|
|
HexNumber = '0x' [0-9a-fA-F]+
|
|
|
|
DecimalNumber = [0-9]+
|
|
|
|
|
2020-01-09 17:35:22 +00:00
|
|
|
|
2017-04-18 12:12:04 +00:00
|
|
|
Restrictions on the Grammar
|
|
|
|
---------------------------
|
|
|
|
|
2020-01-09 17:35:22 +00:00
|
|
|
Apart from those directly imposed by the grammar, the following
|
|
|
|
restrictions apply:
|
|
|
|
|
2017-07-12 18:09:13 +00:00
|
|
|
Switches must have at least one case (including the default case).
|
2020-01-09 17:35:22 +00:00
|
|
|
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 is
|
|
|
|
not allowed (i.e. a switch with a ``bool`` expression that has both a
|
|
|
|
true and a false case do not allow a default case).
|
2017-04-21 16:49:04 +00:00
|
|
|
|
2017-07-12 18:09:13 +00:00
|
|
|
Every expression evaluates to zero or more values. Identifiers and Literals
|
|
|
|
evaluate to exactly
|
2017-04-21 12:56:19 +00:00
|
|
|
one value and function calls evaluate to a number of values equal to the
|
2020-01-09 17:35:22 +00:00
|
|
|
number of return variables of the function called.
|
2017-04-18 12:12:04 +00:00
|
|
|
|
2017-07-12 18:09:13 +00:00
|
|
|
In variable declarations and assignments, the right-hand-side expression
|
2017-04-21 12:56:19 +00:00
|
|
|
(if present) has to evaluate to a number of values equal to the number of
|
|
|
|
variables on the left-hand-side.
|
2017-07-12 18:09:13 +00:00
|
|
|
This is the only situation where an expression evaluating
|
|
|
|
to more than one value is allowed.
|
2020-07-06 15:25:55 +00:00
|
|
|
The same variable name cannot occur more than once in the left-hand-side of
|
|
|
|
an assignment or variable declaration.
|
2017-04-21 12:56:19 +00:00
|
|
|
|
2017-07-12 18:09:13 +00:00
|
|
|
Expressions that are also statements (i.e. at the block level) have to
|
|
|
|
evaluate to zero values.
|
2017-04-21 12:56:19 +00:00
|
|
|
|
2017-07-12 18:09:13 +00:00
|
|
|
In all other situations, expressions have to evaluate to exactly one value.
|
|
|
|
|
2021-12-08 07:07:19 +00:00
|
|
|
A ``continue`` or ``break`` statement can only be used inside the body of a for-loop, as follows.
|
|
|
|
Consider the innermost loop that contains the statement.
|
|
|
|
The loop and the statement must be in the same function, or both must be at the top level.
|
|
|
|
The statement must be in the loop's body block;
|
|
|
|
it cannot be in the loop's initialization block or update block.
|
|
|
|
It is worth emphasizing that this restriction applies just
|
|
|
|
to the innermost loop that contains the ``continue`` or ``break`` statement:
|
|
|
|
this innermost loop, and therefore the ``continue`` or ``break`` statement,
|
|
|
|
may appear anywhere in an outer loop, possibly in an outer loop's initialization block or update block.
|
|
|
|
For example, the following is legal,
|
|
|
|
because the ``break`` occurs in the body block of the inner loop,
|
|
|
|
despite also occurring in the update block of the outer loop:
|
|
|
|
|
|
|
|
.. code-block:: yul
|
|
|
|
|
|
|
|
for {} true { for {} true {} { break } }
|
|
|
|
{
|
|
|
|
}
|
2020-01-09 17:35:22 +00:00
|
|
|
|
2017-04-21 12:56:19 +00:00
|
|
|
The condition part of the for-loop has to evaluate to exactly one value.
|
2020-01-09 17:35:22 +00:00
|
|
|
|
|
|
|
The ``leave`` statement can only be used inside a function.
|
|
|
|
|
2019-11-20 15:47:38 +00:00
|
|
|
Functions cannot be defined anywhere inside for loop init blocks.
|
2017-04-21 12:56:19 +00:00
|
|
|
|
2020-11-04 11:01:12 +00:00
|
|
|
Literals cannot be larger than their type. The largest type defined is 256-bit wide.
|
2017-04-18 12:12:04 +00:00
|
|
|
|
2020-01-09 17:35:22 +00:00
|
|
|
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 achieved
|
|
|
|
if the dialect provides an appropriate built-in function that takes a value of one
|
|
|
|
type and returns a value of a different type.
|
|
|
|
|
2017-07-12 18:09:13 +00:00
|
|
|
Scoping Rules
|
|
|
|
-------------
|
|
|
|
|
2018-06-05 17:43:23 +00:00
|
|
|
Scopes in Yul are tied to Blocks (exceptions are functions and the for loop
|
2017-07-12 18:09:13 +00:00
|
|
|
as explained below) and all declarations
|
|
|
|
(``FunctionDefinition``, ``VariableDeclaration``)
|
|
|
|
introduce new identifiers into these scopes.
|
|
|
|
|
|
|
|
Identifiers are visible in
|
2021-08-02 07:58:20 +00:00
|
|
|
the block they are defined in (including all sub-nodes and sub-blocks):
|
|
|
|
Functions are visible in the whole block (even before their definitions) while
|
|
|
|
variables are only visible starting from the statement after the ``VariableDeclaration``.
|
2019-11-19 15:10:46 +00:00
|
|
|
|
2021-08-02 07:58:20 +00:00
|
|
|
In particular,
|
|
|
|
variables cannot be referenced in the right hand side of their own variable
|
|
|
|
declaration.
|
|
|
|
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
|
2020-01-09 17:35:22 +00:00
|
|
|
(the first block) extends across all other parts of the for loop.
|
2021-08-02 07:58:20 +00:00
|
|
|
This means that variables (and functions) declared in the init part (but not inside a
|
2020-01-09 17:35:22 +00:00
|
|
|
block inside the init part) are visible in all other parts of the for-loop.
|
|
|
|
|
2017-07-12 18:09:13 +00:00
|
|
|
Identifiers declared in the other parts of the for loop respect the regular
|
2018-12-21 15:49:11 +00:00
|
|
|
syntactical scoping rules.
|
2019-11-19 15:10:46 +00:00
|
|
|
|
|
|
|
This means a for-loop of the form ``for { I... } C { P... } { B... }`` is equivalent
|
|
|
|
to ``{ I... for {} C { P... } { B... } }``.
|
|
|
|
|
2017-07-12 18:09:13 +00:00
|
|
|
The parameters and return parameters of functions are visible in the
|
2020-01-09 17:35:22 +00:00
|
|
|
function body and their names have to be distinct.
|
2017-07-12 18:09:13 +00:00
|
|
|
|
2021-08-02 07:58:20 +00:00
|
|
|
Inside functions, it is not possible to reference a variable that was declared
|
|
|
|
outside of that function.
|
2017-07-12 18:09:13 +00:00
|
|
|
|
|
|
|
Shadowing is disallowed, i.e. you cannot declare an identifier at a point
|
|
|
|
where another identifier with the same name is also visible, even if it is
|
2021-08-02 07:58:20 +00:00
|
|
|
not possible to reference it because it was declared outside the current function.
|
2017-07-12 18:09:13 +00:00
|
|
|
|
2017-04-18 12:12:04 +00:00
|
|
|
Formal Specification
|
|
|
|
--------------------
|
|
|
|
|
2018-06-05 17:43:23 +00:00
|
|
|
We formally specify Yul by providing an evaluation function E overloaded
|
2020-01-09 17:35:22 +00:00
|
|
|
on the various nodes of the AST. As builtin functions can have side effects,
|
2017-07-12 18:09:13 +00:00
|
|
|
E takes two state objects and the AST node and returns two new
|
|
|
|
state objects and a variable number of other values.
|
|
|
|
The two state objects are the global state object
|
2017-04-18 12:12:04 +00:00
|
|
|
(which in the context of the EVM is the memory, storage and state of the
|
2017-07-12 18:09:13 +00:00
|
|
|
blockchain) and the local state object (the state of local variables, i.e. a
|
2017-04-18 12:12:04 +00:00
|
|
|
segment of the stack in the EVM).
|
2020-01-09 17:35:22 +00:00
|
|
|
|
2017-07-12 18:09:13 +00:00
|
|
|
If the AST node is a statement, E returns the two state objects and a "mode",
|
2019-10-28 14:25:02 +00:00
|
|
|
which is used for the ``break``, ``continue`` and ``leave`` statements.
|
2017-07-12 18:09:13 +00:00
|
|
|
If the AST node is an expression, E returns the two state objects and
|
|
|
|
as many values as the expression evaluates to.
|
2017-04-18 12:12:04 +00:00
|
|
|
|
|
|
|
|
2017-04-21 10:22:58 +00:00
|
|
|
The exact nature of the global state is unspecified for this high level
|
2017-07-12 18:09:13 +00:00
|
|
|
description. The local state ``L`` is a mapping of identifiers ``i`` to values ``v``,
|
|
|
|
denoted as ``L[i] = v``.
|
|
|
|
|
|
|
|
For an identifier ``v``, let ``$v`` be the name of the identifier.
|
|
|
|
|
|
|
|
We will use a destructuring notation for the AST nodes.
|
2017-04-18 12:12:04 +00:00
|
|
|
|
docs: use Yul lexer to highlight Yul code segments.
Many commits squashed; turns out that with the combination of:
* Python v2.7,
* Sphinx v1.8.5, and
* Pygments v2.3.1
versions (old!) used in the CI, the only viable approach is:
* to use `code-block` directives with explicit language specification,
* to provide no file-local default using `highlight`, and
* to set language as `none` for grammar specifications.
Underlying are the following issues (again, for the old versions
listed above):
* Generic RST `code` doesn't work when language is `none`:
Warning, treated as error:
/root/project/docs/yul.rst:430:Cannot analyze code. No Pygments lexer found for "none".
Additionally, it might be trying to fall back to the default
(Solidity) if left unspecified.
* If a file-local default is specified using `highlight`, then
`code-block` _must_ also provide a language:
Warning, treated as error:
/root/project/docs/yul.rst:185:Error in "code-block" directive:
1 argument(s) required, 0 supplied.
* Sphinx seems to try the file-local default "yul" (specified with
`highlight`) on `code` marked having language `json`:
Warning, treated as error:
/root/project/docs/yul.rst:130:Could not lex literal_block as "yul". Highlighting skipped.
* The only well-lexed highlighter for two of the three grammar
specifications is `peg`, but it was added in Pygments v2.6.
One of the grammars - in the "Formal Specification" section,
the one after "We will use a destructuring notation for the
AST nodes." - _must_ be left unhighlighted, with language set
to `none`: all lexers do really poorly.
... And one should never, ever start treating warnings as mere
warnings, without having exhausted all other options.
Otherwise, it's a slippery slope, - and look where that brought
Gandhi: to being a strawman in every lousy argument to be had!..
2020-04-26 08:36:05 +00:00
|
|
|
.. code-block:: none
|
2017-04-18 12:12:04 +00:00
|
|
|
|
|
|
|
E(G, L, <{St1, ..., Stn}>: Block) =
|
2017-07-12 18:09:13 +00:00
|
|
|
let G1, L1, mode = E(G, L, St1, ..., Stn)
|
|
|
|
let L2 be a restriction of L1 to the identifiers of L
|
|
|
|
G1, L2, mode
|
2017-04-21 12:56:19 +00:00
|
|
|
E(G, L, St1, ..., Stn: Statement) =
|
|
|
|
if n is zero:
|
2017-08-07 14:28:10 +00:00
|
|
|
G, L, regular
|
2017-04-21 12:56:19 +00:00
|
|
|
else:
|
2017-07-12 18:09:13 +00:00
|
|
|
let G1, L1, mode = E(G, L, St1)
|
2017-04-21 12:56:19 +00:00
|
|
|
if mode is regular then
|
2017-07-12 18:09:13 +00:00
|
|
|
E(G1, L1, St2, ..., Stn)
|
2017-04-21 12:56:19 +00:00
|
|
|
otherwise
|
2017-07-12 18:09:13 +00:00
|
|
|
G1, L1, mode
|
|
|
|
E(G, L, FunctionDefinition) =
|
2017-04-21 12:56:19 +00:00
|
|
|
G, L, regular
|
2019-09-12 17:36:37 +00:00
|
|
|
E(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
|
2017-07-12 18:09:13 +00:00
|
|
|
G, L1, regular
|
2019-09-12 17:36:37 +00:00
|
|
|
E(G, L, <var_1, ..., var_n := rhs>: Assignment) =
|
2017-07-12 18:09:13 +00:00
|
|
|
let G1, L1, v1, ..., vn = E(G, L, rhs)
|
2019-09-12 17:36:37 +00:00
|
|
|
let L2 be a copy of L1 where L2[$var_i] = vi for i = 1, ..., n
|
2017-07-12 18:09:13 +00:00
|
|
|
G, L2, regular
|
2017-04-21 12:56:19 +00:00
|
|
|
E(G, L, <for { i1, ..., in } condition post body>: ForLoop) =
|
|
|
|
if n >= 1:
|
2019-10-28 14:25:02 +00:00
|
|
|
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
|
2017-04-21 12:56:19 +00:00
|
|
|
else:
|
2017-07-12 18:09:13 +00:00
|
|
|
let G1, L1, v = E(G, L, condition)
|
2017-04-21 12:56:19 +00:00
|
|
|
if v is false:
|
2017-07-12 18:09:13 +00:00
|
|
|
G1, L1, regular
|
2017-04-21 12:56:19 +00:00
|
|
|
else:
|
2017-07-12 18:09:13 +00:00
|
|
|
let G2, L2, mode = E(G1, L, body)
|
2017-04-21 12:56:19 +00:00
|
|
|
if mode is break:
|
2017-07-12 18:09:13 +00:00
|
|
|
G2, L2, regular
|
2019-10-28 14:25:02 +00:00
|
|
|
otherwise if mode is leave:
|
|
|
|
G2, L2, leave
|
2017-04-21 12:56:19 +00:00
|
|
|
else:
|
2017-07-12 18:09:13 +00:00
|
|
|
G3, L3, mode = E(G2, L2, post)
|
2019-10-28 14:25:02 +00:00
|
|
|
if mode is leave:
|
|
|
|
G2, L3, leave
|
|
|
|
otherwise
|
|
|
|
E(G3, L3, for {} condition post body)
|
2017-04-21 12:56:19 +00:00
|
|
|
E(G, L, break: BreakContinue) =
|
|
|
|
G, L, break
|
|
|
|
E(G, L, continue: BreakContinue) =
|
|
|
|
G, L, continue
|
2019-10-28 14:25:02 +00:00
|
|
|
E(G, L, leave: Leave) =
|
|
|
|
G, L, leave
|
2017-11-22 13:17:31 +00:00
|
|
|
E(G, L, <if condition body>: If) =
|
|
|
|
let G0, L0, v = E(G, L, condition)
|
2017-11-23 17:52:04 +00:00
|
|
|
if v is true:
|
2017-11-22 13:17:31 +00:00
|
|
|
E(G0, L0, body)
|
|
|
|
else:
|
|
|
|
G0, L0, regular
|
2017-08-15 19:15:43 +00:00
|
|
|
E(G, L, <switch condition case l1:t1 st1 ... case ln:tn stn>: Switch) =
|
2017-11-22 13:17:31 +00:00
|
|
|
E(G, L, switch condition case l1:t1 st1 ... case ln:tn stn default {})
|
2017-08-15 19:15:43 +00:00
|
|
|
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
|
2017-08-16 10:29:12 +00:00
|
|
|
let _, _, v1 = E(G0, L0, l1)
|
2017-08-15 19:15:43 +00:00
|
|
|
...
|
2017-08-16 10:29:12 +00:00
|
|
|
let _, _, vn = E(G0, L0, ln)
|
2017-08-15 19:15:43 +00:00
|
|
|
if there exists smallest i such that vi = v:
|
|
|
|
E(G0, L0, sti)
|
|
|
|
else:
|
|
|
|
E(G0, L0, st')
|
2017-04-21 12:56:19 +00:00
|
|
|
|
|
|
|
E(G, L, <name>: Identifier) =
|
2017-08-07 14:28:10 +00:00
|
|
|
G, L, L[$name]
|
2017-04-21 12:56:19 +00:00
|
|
|
E(G, L, <fname(arg1, ..., argn)>: FunctionCall) =
|
2017-04-18 12:12:04 +00:00
|
|
|
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)
|
2017-04-21 10:22:58 +00:00
|
|
|
Let <function fname (param1, ..., paramn) -> ret1, ..., retm block>
|
2017-07-12 18:09:13 +00:00
|
|
|
be the function of name $fname visible at the point of the call.
|
2017-04-21 12:56:19 +00:00
|
|
|
Let L' be a new local state such that
|
2017-07-12 18:09:13 +00:00
|
|
|
L'[$parami] = vi and L'[$reti] = 0 for all i.
|
2017-08-07 14:28:10 +00:00
|
|
|
Let G'', L'', mode = E(Gn, L', block)
|
|
|
|
G'', Ln, L''[$ret1], ..., L''[$retm]
|
2021-09-29 20:05:08 +00:00
|
|
|
E(G, L, l: StringLiteral) = G, L, str(l),
|
|
|
|
where str is the string evaluation function,
|
|
|
|
which for the EVM dialect is defined in the section 'Literals' above
|
2017-04-18 12:12:04 +00:00
|
|
|
E(G, L, n: HexNumber) = G, L, hex(n)
|
2021-09-29 20:05:08 +00:00
|
|
|
where hex is the hexadecimal evaluation function,
|
|
|
|
which turns a sequence of hexadecimal digits into their big endian value
|
2017-04-18 12:12:04 +00:00
|
|
|
E(G, L, n: DecimalNumber) = G, L, dec(n),
|
2021-09-29 20:05:08 +00:00
|
|
|
where dec is the decimal evaluation function,
|
|
|
|
which turns a sequence of decimal digits into their big endian value
|
2017-04-18 12:41:16 +00:00
|
|
|
|
2020-01-09 17:35:22 +00:00
|
|
|
.. _opcodes:
|
|
|
|
|
|
|
|
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 dialect
|
|
|
|
is ``u256``, 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 the
|
|
|
|
semantics 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.
|
2021-07-12 14:50:37 +00:00
|
|
|
Opcodes marked with ``F``, ``H``, ``B``, ``C``, ``I`` and ``L`` are present since Frontier, Homestead,
|
|
|
|
Byzantium, Constantinople, Istanbul or London respectively.
|
2020-01-09 17:35:22 +00:00
|
|
|
|
|
|
|
In the following, ``mem[a...b)`` signifies the bytes of memory starting at position ``a`` up to
|
|
|
|
but not including position ``b`` and ``storage[p]`` signifies the storage contents at slot ``p``.
|
|
|
|
|
|
|
|
Since Yul manages local variables and control-flow,
|
|
|
|
opcodes that interfere with these features are not available. This includes
|
|
|
|
the ``dup`` and ``swap`` instructions as well as ``jump`` instructions, labels and the ``push`` instructions.
|
|
|
|
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| Instruction | | | Explanation |
|
|
|
|
+=========================+=====+===+=================================================================+
|
2022-02-17 09:57:28 +00:00
|
|
|
| stop() | `-` | F | stop execution, identical to return(0, 0) |
|
2020-01-09 17:35:22 +00:00
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| add(x, y) | | F | x + y |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| sub(x, y) | | F | x - y |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| mul(x, y) | | F | x * y |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| div(x, y) | | F | x / y or 0 if y == 0 |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| sdiv(x, y) | | F | x / y, for signed numbers in two's complement, 0 if y == 0 |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| mod(x, y) | | F | x % y, 0 if y == 0 |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| smod(x, y) | | F | x % y, for signed numbers in two's complement, 0 if y == 0 |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| exp(x, y) | | F | x to the power of y |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| not(x) | | F | bitwise "not" of x (every bit of x is negated) |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| lt(x, y) | | F | 1 if x < y, 0 otherwise |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| gt(x, y) | | F | 1 if x > y, 0 otherwise |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| slt(x, y) | | F | 1 if x < y, 0 otherwise, for signed numbers in two's complement |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| sgt(x, y) | | F | 1 if x > y, 0 otherwise, for signed numbers in two's complement |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| eq(x, y) | | F | 1 if x == y, 0 otherwise |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| iszero(x) | | F | 1 if x == 0, 0 otherwise |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| and(x, y) | | F | bitwise "and" of x and y |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| or(x, y) | | F | bitwise "or" of x and y |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| xor(x, y) | | F | bitwise "xor" of x and y |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| byte(n, x) | | F | nth byte of x, where the most significant byte is the 0th byte |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| shl(x, y) | | C | logical shift left y by x bits |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| shr(x, y) | | C | logical shift right y by x bits |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| sar(x, y) | | C | signed arithmetic shift right y by x bits |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| addmod(x, y, m) | | F | (x + y) % m with arbitrary precision arithmetic, 0 if m == 0 |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| mulmod(x, y, m) | | F | (x * y) % m with arbitrary precision arithmetic, 0 if m == 0 |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| signextend(i, x) | | F | sign extend from (i*8+7)th bit counting from least significant |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| keccak256(p, n) | | F | keccak(mem[p...(p+n))) |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| pc() | | F | current position in code |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| pop(x) | `-` | F | discard value x |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| mload(p) | | F | mem[p...(p+32)) |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| mstore(p, v) | `-` | F | mem[p...(p+32)) := v |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| mstore8(p, v) | `-` | F | mem[p] := v & 0xff (only modifies a single byte) |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| sload(p) | | F | storage[p] |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| sstore(p, v) | `-` | F | storage[p] := v |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| msize() | | F | size of memory, i.e. largest accessed memory index |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| gas() | | F | gas still available to execution |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| address() | | F | address of the current contract / execution context |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| balance(a) | | F | wei balance at address a |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| selfbalance() | | I | equivalent to balance(address()), but cheaper |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| caller() | | F | call sender (excluding ``delegatecall``) |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| callvalue() | | F | wei sent together with the current call |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| calldataload(p) | | F | call data starting from position p (32 bytes) |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| calldatasize() | | F | size of call data in bytes |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| calldatacopy(t, f, s) | `-` | F | copy s bytes from calldata at position f to mem at position t |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| codesize() | | F | size of the code of the current contract / execution context |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| codecopy(t, f, s) | `-` | F | copy s bytes from code at position f to mem at position t |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| extcodesize(a) | | F | size of the code at address a |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| extcodecopy(a, t, f, s) | `-` | F | like codecopy(t, f, s) but take code at address a |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| returndatasize() | | B | size of the last returndata |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| returndatacopy(t, f, s) | `-` | B | copy s bytes from returndata at position f to mem at position t |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| extcodehash(a) | | C | code hash of address a |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| create(v, p, n) | | F | create new contract with code mem[p...(p+n)) and send v wei |
|
2021-03-25 17:10:20 +00:00
|
|
|
| | | | and return the new address; returns 0 on error |
|
2020-01-09 17:35:22 +00:00
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| create2(v, p, n, s) | | C | create new contract with code mem[p...(p+n)) at address |
|
|
|
|
| | | | keccak256(0xff . this . s . keccak256(mem[p...(p+n))) |
|
|
|
|
| | | | and send v wei and return the new address, where ``0xff`` is a |
|
|
|
|
| | | | 1 byte value, ``this`` is the current contract's address |
|
2021-03-25 17:10:20 +00:00
|
|
|
| | | | as a 20 byte value and ``s`` is a big-endian 256-bit value; |
|
|
|
|
| | | | returns 0 on error |
|
2020-01-09 17:35:22 +00:00
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| call(g, a, v, in, | | F | call contract at address a with input mem[in...(in+insize)) |
|
|
|
|
| insize, out, outsize) | | | providing g gas and v wei and output area |
|
|
|
|
| | | | mem[out...(out+outsize)) returning 0 on error (eg. out of gas) |
|
|
|
|
| | | | and 1 on success |
|
2020-01-21 13:18:05 +00:00
|
|
|
| | | | :ref:`See more <yul-call-return-area>` |
|
2020-01-09 17:35:22 +00:00
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| callcode(g, a, v, in, | | F | identical to ``call`` but only use the code from a and stay |
|
|
|
|
| insize, out, outsize) | | | in the context of the current contract otherwise |
|
2020-01-21 13:18:05 +00:00
|
|
|
| | | | :ref:`See more <yul-call-return-area>` |
|
2020-01-09 17:35:22 +00:00
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| delegatecall(g, a, in, | | H | identical to ``callcode`` but also keep ``caller`` |
|
|
|
|
| insize, out, outsize) | | | and ``callvalue`` |
|
2020-01-21 13:18:05 +00:00
|
|
|
| | | | :ref:`See more <yul-call-return-area>` |
|
2020-01-09 17:35:22 +00:00
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| staticcall(g, a, in, | | B | identical to ``call(g, a, 0, in, insize, out, outsize)`` but do |
|
|
|
|
| insize, out, outsize) | | | not allow state modifications |
|
2020-01-21 13:18:05 +00:00
|
|
|
| | | | :ref:`See more <yul-call-return-area>` |
|
2020-01-09 17:35:22 +00:00
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| return(p, s) | `-` | F | end execution, return data mem[p...(p+s)) |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| revert(p, s) | `-` | B | end execution, revert state changes, return data mem[p...(p+s)) |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| selfdestruct(a) | `-` | F | end execution, destroy current contract and send funds to a |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| invalid() | `-` | F | end execution with invalid instruction |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| log0(p, s) | `-` | F | log without topics and data mem[p...(p+s)) |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| log1(p, s, t1) | `-` | F | log with topic t1 and data mem[p...(p+s)) |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| log2(p, s, t1, t2) | `-` | F | log with topics t1, t2 and data mem[p...(p+s)) |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| log3(p, s, t1, t2, t3) | `-` | F | log with topics t1, t2, t3 and data mem[p...(p+s)) |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| log4(p, s, t1, t2, t3, | `-` | F | log with topics t1, t2, t3, t4 and data mem[p...(p+s)) |
|
|
|
|
| t4) | | | |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
2021-07-12 14:50:37 +00:00
|
|
|
| chainid() | | I | ID of the executing chain (EIP-1344) |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| basefee() | | L | current block's base fee (EIP-3198 and EIP-1559) |
|
2020-01-09 17:35:22 +00:00
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| origin() | | F | transaction sender |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| gasprice() | | F | gas price of the transaction |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| blockhash(b) | | F | hash of block nr b - only for last 256 blocks excluding current |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| coinbase() | | F | current mining beneficiary |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| timestamp() | | F | timestamp of the current block in seconds since the epoch |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| number() | | F | current block number |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| difficulty() | | F | difficulty of the current block |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
| gaslimit() | | F | block gas limit of the current block |
|
|
|
|
+-------------------------+-----+---+-----------------------------------------------------------------+
|
|
|
|
|
2020-01-21 13:18:05 +00:00
|
|
|
.. _yul-call-return-area:
|
|
|
|
|
|
|
|
.. note::
|
|
|
|
The ``call*`` instructions use the ``out`` and ``outsize`` parameters to define an area in memory where
|
2020-12-03 17:02:51 +00:00
|
|
|
the return or failure data is placed. This area is written to depending on how many bytes the called contract returns.
|
2020-01-21 13:18:05 +00:00
|
|
|
If it returns more data, only the first ``outsize`` bytes are written. You can access the rest of the data
|
|
|
|
using the ``returndatacopy`` opcode. If it returns less data, then the remaining bytes are not touched at all.
|
|
|
|
You need to use the ``returndatasize`` opcode to check which part of this memory area contains the return data.
|
2020-12-03 17:02:51 +00:00
|
|
|
The remaining bytes will retain their values as of before the call.
|
2020-01-21 13:18:05 +00:00
|
|
|
|
2020-05-04 13:05:14 +00:00
|
|
|
|
|
|
|
In some internal dialects, there are additional functions:
|
|
|
|
|
|
|
|
datasize, dataoffset, datacopy
|
|
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
|
2020-06-18 11:50:36 +00:00
|
|
|
The functions ``datasize(x)``, ``dataoffset(x)`` and ``datacopy(t, f, l)``
|
2020-05-04 13:05:14 +00:00
|
|
|
are used to access other parts of a Yul object.
|
|
|
|
|
|
|
|
``datasize`` and ``dataoffset`` can only take string literals (the names of other objects)
|
|
|
|
as arguments and return the size and offset in the data area, respectively.
|
|
|
|
For the EVM, the ``datacopy`` function is equivalent to ``codecopy``.
|
|
|
|
|
|
|
|
|
|
|
|
setimmutable, loadimmutable
|
|
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
|
2020-10-15 14:40:45 +00:00
|
|
|
The functions ``setimmutable(offset, "name", value)`` and ``loadimmutable("name")`` are
|
2020-06-18 11:50:36 +00:00
|
|
|
used for the immutable mechanism in Solidity and do not nicely map to pure Yul.
|
2020-10-15 14:40:45 +00:00
|
|
|
The call to ``setimmutable(offset, "name", value)`` assumes that the runtime code of the contract
|
|
|
|
containing the given named immutable was copied to memory at offset ``offset`` and will write ``value`` to all
|
|
|
|
positions in memory (relative to ``offset``) that contain the placeholder that was generated for calls
|
|
|
|
to ``loadimmutable("name")`` in the runtime code.
|
2020-05-04 13:05:14 +00:00
|
|
|
|
|
|
|
|
2020-06-19 11:32:40 +00:00
|
|
|
linkersymbol
|
|
|
|
^^^^^^^^^^^^
|
2021-10-14 18:57:15 +00:00
|
|
|
The function ``linkersymbol("library_id")`` is a placeholder for an address literal to be substituted
|
|
|
|
by the linker.
|
|
|
|
Its first and only argument must be a string literal and uniquely represents the address to be inserted.
|
|
|
|
Identifiers can be arbitrary but when the compiler produces Yul code from Solidity sources,
|
|
|
|
it uses a library name qualified with the name of the source unit that defines that library.
|
|
|
|
To link the code with a particular library address, the same identifier must be provided to the
|
|
|
|
``--libraries`` option on the command line.
|
2020-06-19 11:32:40 +00:00
|
|
|
|
|
|
|
For example this code
|
|
|
|
|
|
|
|
.. code-block:: yul
|
|
|
|
|
|
|
|
let a := linkersymbol("file.sol:Math")
|
|
|
|
|
|
|
|
is equivalent to
|
|
|
|
|
|
|
|
.. code-block:: yul
|
|
|
|
|
|
|
|
let a := 0x1234567890123456789012345678901234567890
|
|
|
|
|
2021-01-02 09:24:26 +00:00
|
|
|
when the linker is invoked with ``--libraries "file.sol:Math=0x1234567890123456789012345678901234567890``
|
2020-06-19 11:32:40 +00:00
|
|
|
option.
|
|
|
|
|
|
|
|
See :ref:`Using the Commandline Compiler <commandline-compiler>` for details about the Solidity linker.
|
|
|
|
|
2020-07-02 10:48:20 +00:00
|
|
|
memoryguard
|
|
|
|
^^^^^^^^^^^
|
|
|
|
|
|
|
|
This function is available in the EVM dialect with objects. The caller of
|
2020-09-16 08:47:13 +00:00
|
|
|
``let ptr := memoryguard(size)`` (where ``size`` has to be a literal number)
|
|
|
|
promises that they only use memory in either the range ``[0, size)`` or the
|
2020-09-17 15:25:37 +00:00
|
|
|
unbounded range starting at ``ptr``.
|
2020-09-16 08:47:13 +00:00
|
|
|
|
|
|
|
Since the presence of a ``memoryguard`` call indicates that all memory access
|
|
|
|
adheres to this restriction, it allows the optimizer to perform additional
|
|
|
|
optimization steps, for example the stack limit evader, which attempts to move
|
|
|
|
stack variables that would otherwise be unreachable to memory.
|
|
|
|
|
|
|
|
The Yul optimizer promises to only use the memory range ``[size, ptr)`` for its purposes.
|
|
|
|
If the optimizer does not need to reserve any memory, it holds that ``ptr == size``.
|
2020-07-02 10:48:20 +00:00
|
|
|
|
|
|
|
``memoryguard`` can be called multiple times, but needs to have the same literal as argument
|
|
|
|
within one Yul subobject. If at least one ``memoryguard`` call is found in a subobject,
|
2020-09-16 08:47:13 +00:00
|
|
|
the additional optimiser steps will be run on it.
|
|
|
|
|
2020-05-04 13:05:14 +00:00
|
|
|
|
2021-09-22 13:14:31 +00:00
|
|
|
.. _yul-verbatim:
|
|
|
|
|
2021-03-17 18:37:39 +00:00
|
|
|
verbatim
|
|
|
|
^^^^^^^^
|
|
|
|
|
|
|
|
The set of ``verbatim...`` builtin functions lets you create bytecode for opcodes
|
|
|
|
that are not known to the Yul compiler. It also allows you to create
|
|
|
|
bytecode sequences that will not be modified by the optimizer.
|
|
|
|
|
|
|
|
The functions are ``verbatim_<n>i_<m>o("<data>", ...)``, where
|
2021-07-14 15:55:05 +00:00
|
|
|
|
|
|
|
- ``n`` is a decimal between 0 and 99 that specifies the number of input stack slots / variables
|
|
|
|
- ``m`` is a decimal between 0 and 99 that specifies the number of output stack slots / variables
|
|
|
|
- ``data`` is a string literal that contains the sequence of bytes
|
2021-03-17 18:37:39 +00:00
|
|
|
|
|
|
|
If you for example want to define a function that multiplies the input
|
|
|
|
by two, without the optimizer touching the constant two, you can use
|
|
|
|
|
|
|
|
.. code-block:: yul
|
|
|
|
|
|
|
|
let x := calldataload(0)
|
|
|
|
let double := verbatim_1i_1o(hex"600202", x)
|
|
|
|
|
|
|
|
This code will result in a ``dup1`` opcode to retrieve ``x``
|
|
|
|
(the optimizer might directly re-use result of the
|
|
|
|
``calldataload`` opcode, though)
|
|
|
|
directly followed by ``600202``. The code is assumed to
|
|
|
|
consume the copied value of ``x`` and produce the result
|
|
|
|
on the top of the stack. The compiler then generates code
|
|
|
|
to allocate a stack slot for ``double`` and store the result there.
|
|
|
|
|
|
|
|
As with all opcodes, the arguments are arranged on the stack
|
|
|
|
with the leftmost argument on the top, while the return values
|
|
|
|
are assumed to be laid out such that the rightmost variable is
|
|
|
|
at the top of the stack.
|
|
|
|
|
|
|
|
Since ``verbatim`` can be used to generate arbitrary opcodes
|
|
|
|
or even opcodes unknown to the Solidity compiler, care has to be taken
|
|
|
|
when using ``verbatim`` together with the optimizer. Even when the
|
|
|
|
optimizer is switched off, the code generator has to determine
|
|
|
|
the stack layout, which means that e.g. using ``verbatim`` to modify
|
|
|
|
the stack height can lead to undefined behaviour.
|
|
|
|
|
|
|
|
The following is a non-exhaustive list of restrictions on
|
|
|
|
verbatim bytecode that are not checked by
|
|
|
|
the compiler. Violations of these restrictions can result in
|
|
|
|
undefined behaviour.
|
|
|
|
|
2021-07-14 15:55:05 +00:00
|
|
|
- Control-flow should not jump into or out of verbatim blocks,
|
|
|
|
but it can jump within the same verbatim block.
|
|
|
|
- Stack contents apart from the input and output parameters
|
|
|
|
should not be accessed.
|
|
|
|
- The stack height difference should be exactly ``m - n``
|
|
|
|
(output slots minus input slots).
|
|
|
|
- Verbatim bytecode cannot make any assumptions about the
|
|
|
|
surrounding bytecode. All required parameters have to be
|
|
|
|
passed in as stack variables.
|
2021-03-17 18:37:39 +00:00
|
|
|
|
|
|
|
The optimizer does not analyze verbatim bytecode and always
|
|
|
|
assumes that it modifies all aspects of state and thus can only
|
|
|
|
do very few optimizations across ``verbatim`` function calls.
|
|
|
|
|
|
|
|
The optimizer treats verbatim bytecode as an opaque block of code.
|
|
|
|
It will not split it but might move, duplicate
|
|
|
|
or combine it with identical verbatim bytecode blocks.
|
|
|
|
If a verbatim bytecode block is unreachable by the control-flow,
|
|
|
|
it can be removed.
|
|
|
|
|
|
|
|
|
|
|
|
.. warning::
|
|
|
|
|
|
|
|
During discussions about whether or not EVM improvements
|
|
|
|
might break existing smart contracts, features inside ``verbatim``
|
|
|
|
cannot receive the same consideration as those used by the Solidity
|
|
|
|
compiler itself.
|
|
|
|
|
|
|
|
.. note::
|
|
|
|
|
|
|
|
To avoid confusion, all identifiers starting with the string ``verbatim`` are reserved
|
|
|
|
and cannot be used for user-defined identifiers.
|
|
|
|
|
2020-01-09 17:35:22 +00:00
|
|
|
.. _yul-object:
|
2017-04-21 16:35:56 +00:00
|
|
|
|
2018-06-05 17:43:23 +00:00
|
|
|
Specification of Yul Object
|
|
|
|
===========================
|
2017-04-21 16:35:56 +00:00
|
|
|
|
2018-11-14 16:33:02 +00:00
|
|
|
Yul objects are used to group named code and data sections.
|
|
|
|
The functions ``datasize``, ``dataoffset`` and ``datacopy``
|
|
|
|
can be used to access these sections from within code.
|
|
|
|
Hex strings can be used to specify data in hex encoding,
|
|
|
|
regular strings in native encoding. For code,
|
|
|
|
``datacopy`` will access its assembled binary representation.
|
|
|
|
|
docs: use Yul lexer to highlight Yul code segments.
Many commits squashed; turns out that with the combination of:
* Python v2.7,
* Sphinx v1.8.5, and
* Pygments v2.3.1
versions (old!) used in the CI, the only viable approach is:
* to use `code-block` directives with explicit language specification,
* to provide no file-local default using `highlight`, and
* to set language as `none` for grammar specifications.
Underlying are the following issues (again, for the old versions
listed above):
* Generic RST `code` doesn't work when language is `none`:
Warning, treated as error:
/root/project/docs/yul.rst:430:Cannot analyze code. No Pygments lexer found for "none".
Additionally, it might be trying to fall back to the default
(Solidity) if left unspecified.
* If a file-local default is specified using `highlight`, then
`code-block` _must_ also provide a language:
Warning, treated as error:
/root/project/docs/yul.rst:185:Error in "code-block" directive:
1 argument(s) required, 0 supplied.
* Sphinx seems to try the file-local default "yul" (specified with
`highlight`) on `code` marked having language `json`:
Warning, treated as error:
/root/project/docs/yul.rst:130:Could not lex literal_block as "yul". Highlighting skipped.
* The only well-lexed highlighter for two of the three grammar
specifications is `peg`, but it was added in Pygments v2.6.
One of the grammars - in the "Formal Specification" section,
the one after "We will use a destructuring notation for the
AST nodes." - _must_ be left unhighlighted, with language set
to `none`: all lexers do really poorly.
... And one should never, ever start treating warnings as mere
warnings, without having exhausted all other options.
Otherwise, it's a slippery slope, - and look where that brought
Gandhi: to being a strawman in every lousy argument to be had!..
2020-04-26 08:36:05 +00:00
|
|
|
.. code-block:: none
|
2017-04-21 16:35:56 +00:00
|
|
|
|
2018-11-28 10:32:05 +00:00
|
|
|
Object = 'object' StringLiteral '{' Code ( Object | Data )* '}'
|
2017-04-21 16:35:56 +00:00
|
|
|
Code = 'code' Block
|
2018-11-14 16:33:02 +00:00
|
|
|
Data = 'data' StringLiteral ( HexLiteral | StringLiteral )
|
2017-04-21 16:35:56 +00:00
|
|
|
HexLiteral = 'hex' ('"' ([0-9a-fA-F]{2})* '"' | '\'' ([0-9a-fA-F]{2})* '\'')
|
|
|
|
StringLiteral = '"' ([^"\r\n\\] | '\\' .)* '"'
|
|
|
|
|
2018-06-05 17:43:23 +00:00
|
|
|
Above, ``Block`` refers to ``Block`` in the Yul code grammar explained in the previous chapter.
|
2017-04-21 16:35:56 +00:00
|
|
|
|
2021-06-08 14:35:37 +00:00
|
|
|
.. note::
|
|
|
|
|
|
|
|
Data objects or sub-objects whose names contain a ``.`` can be defined
|
|
|
|
but it is not possible to access them through ``datasize``,
|
|
|
|
``dataoffset`` or ``datacopy`` because ``.`` is used as a separator
|
|
|
|
to access objects inside another object.
|
|
|
|
|
|
|
|
.. note::
|
|
|
|
|
|
|
|
The data object called ``".metadata"`` has a special meaning:
|
|
|
|
It cannot be accessed from code and is always appended to the very end of the
|
|
|
|
bytecode, regardless of its position in the object.
|
|
|
|
|
|
|
|
Other data objects with special significance might be added in the
|
|
|
|
future, but their names will always start with a ``.``.
|
|
|
|
|
|
|
|
|
2018-06-05 17:43:23 +00:00
|
|
|
An example Yul Object is shown below:
|
2017-04-21 16:35:56 +00:00
|
|
|
|
docs: use Yul lexer to highlight Yul code segments.
Many commits squashed; turns out that with the combination of:
* Python v2.7,
* Sphinx v1.8.5, and
* Pygments v2.3.1
versions (old!) used in the CI, the only viable approach is:
* to use `code-block` directives with explicit language specification,
* to provide no file-local default using `highlight`, and
* to set language as `none` for grammar specifications.
Underlying are the following issues (again, for the old versions
listed above):
* Generic RST `code` doesn't work when language is `none`:
Warning, treated as error:
/root/project/docs/yul.rst:430:Cannot analyze code. No Pygments lexer found for "none".
Additionally, it might be trying to fall back to the default
(Solidity) if left unspecified.
* If a file-local default is specified using `highlight`, then
`code-block` _must_ also provide a language:
Warning, treated as error:
/root/project/docs/yul.rst:185:Error in "code-block" directive:
1 argument(s) required, 0 supplied.
* Sphinx seems to try the file-local default "yul" (specified with
`highlight`) on `code` marked having language `json`:
Warning, treated as error:
/root/project/docs/yul.rst:130:Could not lex literal_block as "yul". Highlighting skipped.
* The only well-lexed highlighter for two of the three grammar
specifications is `peg`, but it was added in Pygments v2.6.
One of the grammars - in the "Formal Specification" section,
the one after "We will use a destructuring notation for the
AST nodes." - _must_ be left unhighlighted, with language set
to `none`: all lexers do really poorly.
... And one should never, ever start treating warnings as mere
warnings, without having exhausted all other options.
Otherwise, it's a slippery slope, - and look where that brought
Gandhi: to being a strawman in every lousy argument to be had!..
2020-04-26 08:36:05 +00:00
|
|
|
.. code-block:: yul
|
2017-04-21 16:35:56 +00:00
|
|
|
|
2020-01-09 17:35:22 +00:00
|
|
|
// A contract consists of a single object with sub-objects representing
|
|
|
|
// the code to be deployed or other contracts it can create.
|
|
|
|
// The single "code" node is the executable code of the object.
|
2017-04-21 16:35:56 +00:00
|
|
|
// Every (other) named object or data section is serialized and
|
|
|
|
// made accessible to the special built-in functions datacopy / dataoffset / datasize
|
2020-01-24 00:11:12 +00:00
|
|
|
// The current object, sub-objects and data items inside the current object
|
|
|
|
// are in scope.
|
2018-11-14 16:33:02 +00:00
|
|
|
object "Contract1" {
|
2020-01-09 17:35:22 +00:00
|
|
|
// This is the constructor code of the contract.
|
2017-04-21 16:35:56 +00:00
|
|
|
code {
|
2019-05-10 04:11:23 +00:00
|
|
|
function allocate(size) -> ptr {
|
|
|
|
ptr := mload(0x40)
|
|
|
|
if iszero(ptr) { ptr := 0x60 }
|
|
|
|
mstore(0x40, add(ptr, size))
|
|
|
|
}
|
|
|
|
|
2020-01-24 00:11:12 +00:00
|
|
|
// first create "Contract2"
|
|
|
|
let size := datasize("Contract2")
|
2019-05-10 04:11:23 +00:00
|
|
|
let offset := allocate(size)
|
2020-01-09 17:35:22 +00:00
|
|
|
// This will turn into codecopy for EVM
|
2020-01-24 00:11:12 +00:00
|
|
|
datacopy(offset, dataoffset("Contract2"), size)
|
2018-11-14 16:33:02 +00:00
|
|
|
// constructor parameter is a single number 0x1234
|
|
|
|
mstore(add(offset, size), 0x1234)
|
2019-05-10 04:11:23 +00:00
|
|
|
pop(create(offset, add(size, 32), 0))
|
2018-11-14 16:33:02 +00:00
|
|
|
|
2020-01-09 17:35:22 +00:00
|
|
|
// now return the runtime object (the currently
|
|
|
|
// executing code is the constructor code)
|
2018-11-14 16:33:02 +00:00
|
|
|
size := datasize("runtime")
|
|
|
|
offset := allocate(size)
|
2020-10-30 19:44:59 +00:00
|
|
|
// This will turn into a memory->memory copy for Ewasm and
|
2018-11-14 16:33:02 +00:00
|
|
|
// a codecopy for EVM
|
|
|
|
datacopy(offset, dataoffset("runtime"), size)
|
2017-04-21 16:35:56 +00:00
|
|
|
return(offset, size)
|
|
|
|
}
|
|
|
|
|
|
|
|
data "Table2" hex"4123"
|
|
|
|
|
|
|
|
object "runtime" {
|
|
|
|
code {
|
2019-05-10 04:11:23 +00:00
|
|
|
function allocate(size) -> ptr {
|
|
|
|
ptr := mload(0x40)
|
|
|
|
if iszero(ptr) { ptr := 0x60 }
|
|
|
|
mstore(0x40, add(ptr, size))
|
|
|
|
}
|
|
|
|
|
2017-04-21 16:35:56 +00:00
|
|
|
// runtime code
|
|
|
|
|
2020-01-24 00:11:12 +00:00
|
|
|
mstore(0, "Hello, World!")
|
|
|
|
return(0, 0x20)
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
// Embedded object. Use case is that the outside is a factory contract,
|
|
|
|
// and Contract2 is the code to be created by the factory
|
|
|
|
object "Contract2" {
|
|
|
|
code {
|
|
|
|
// code here ...
|
2017-04-21 16:35:56 +00:00
|
|
|
}
|
|
|
|
|
2020-01-24 00:11:12 +00:00
|
|
|
object "runtime" {
|
2017-04-21 16:35:56 +00:00
|
|
|
code {
|
|
|
|
// code here ...
|
|
|
|
}
|
|
|
|
}
|
2020-01-24 00:11:12 +00:00
|
|
|
|
|
|
|
data "Table1" hex"4123"
|
2017-04-21 16:35:56 +00:00
|
|
|
}
|
|
|
|
}
|
2020-01-09 17:35:22 +00:00
|
|
|
|
|
|
|
Yul Optimizer
|
|
|
|
=============
|
|
|
|
|
|
|
|
The Yul optimizer operates on Yul code and uses the same language for input, output and
|
|
|
|
intermediate states. This allows for easy debugging and verification of the optimizer.
|
|
|
|
|
2021-04-12 14:53:42 +00:00
|
|
|
Please refer to the general :ref:`optimizer documentation <optimizer>`
|
|
|
|
for more details about the different optimization stages and how to use the optimizer.
|
2020-01-09 17:35:22 +00:00
|
|
|
|
2021-07-28 15:53:19 +00:00
|
|
|
If you want to use Solidity in stand-alone Yul mode, you activate the optimizer using ``--optimize``
|
|
|
|
and optionally specify the :ref:`expected number of contract executions <optimizer-parameter-runs>` with
|
|
|
|
``--optimize-runs``:
|
2020-01-09 17:35:22 +00:00
|
|
|
|
docs: use Yul lexer to highlight Yul code segments.
Many commits squashed; turns out that with the combination of:
* Python v2.7,
* Sphinx v1.8.5, and
* Pygments v2.3.1
versions (old!) used in the CI, the only viable approach is:
* to use `code-block` directives with explicit language specification,
* to provide no file-local default using `highlight`, and
* to set language as `none` for grammar specifications.
Underlying are the following issues (again, for the old versions
listed above):
* Generic RST `code` doesn't work when language is `none`:
Warning, treated as error:
/root/project/docs/yul.rst:430:Cannot analyze code. No Pygments lexer found for "none".
Additionally, it might be trying to fall back to the default
(Solidity) if left unspecified.
* If a file-local default is specified using `highlight`, then
`code-block` _must_ also provide a language:
Warning, treated as error:
/root/project/docs/yul.rst:185:Error in "code-block" directive:
1 argument(s) required, 0 supplied.
* Sphinx seems to try the file-local default "yul" (specified with
`highlight`) on `code` marked having language `json`:
Warning, treated as error:
/root/project/docs/yul.rst:130:Could not lex literal_block as "yul". Highlighting skipped.
* The only well-lexed highlighter for two of the three grammar
specifications is `peg`, but it was added in Pygments v2.6.
One of the grammars - in the "Formal Specification" section,
the one after "We will use a destructuring notation for the
AST nodes." - _must_ be left unhighlighted, with language set
to `none`: all lexers do really poorly.
... And one should never, ever start treating warnings as mere
warnings, without having exhausted all other options.
Otherwise, it's a slippery slope, - and look where that brought
Gandhi: to being a strawman in every lousy argument to be had!..
2020-04-26 08:36:05 +00:00
|
|
|
.. code-block:: sh
|
2020-01-09 17:35:22 +00:00
|
|
|
|
2021-07-28 15:53:19 +00:00
|
|
|
solc --strict-assembly --optimize --optimize-runs 200
|
2020-01-09 17:35:22 +00:00
|
|
|
|
|
|
|
In Solidity mode, the Yul optimizer is activated together with the regular optimizer.
|
2020-05-04 13:45:08 +00:00
|
|
|
|
2021-04-12 14:53:42 +00:00
|
|
|
Optimization Step Sequence
|
2020-05-04 13:45:08 +00:00
|
|
|
--------------------------
|
|
|
|
|
|
|
|
By default the Yul optimizer applies its predefined sequence of optimization steps to the generated assembly.
|
2020-05-04 19:25:57 +00:00
|
|
|
You can override this sequence and supply your own using the ``--yul-optimizations`` option:
|
2020-05-04 13:45:08 +00:00
|
|
|
|
|
|
|
.. code-block:: sh
|
|
|
|
|
|
|
|
solc --optimize --ir-optimized --yul-optimizations 'dhfoD[xarrscLMcCTU]uljmul'
|
|
|
|
|
2020-05-08 18:59:04 +00:00
|
|
|
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 already
|
|
|
|
applied so repeating steps is often beneficial.
|
2020-05-04 19:25:57 +00:00
|
|
|
By enclosing part of the sequence in square brackets (``[]``) you tell the optimizer to repeatedly
|
2020-05-04 13:45:08 +00:00
|
|
|
apply 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:
|
|
|
|
|
|
|
|
============ ===============================
|
|
|
|
Abbreviation Full name
|
|
|
|
============ ===============================
|
2020-05-04 19:25:57 +00:00
|
|
|
``f`` ``BlockFlattener``
|
|
|
|
``l`` ``CircularReferencesPruner``
|
|
|
|
``c`` ``CommonSubexpressionEliminator``
|
|
|
|
``C`` ``ConditionalSimplifier``
|
|
|
|
``U`` ``ConditionalUnsimplifier``
|
|
|
|
``n`` ``ControlFlowSimplifier``
|
|
|
|
``D`` ``DeadCodeEliminator``
|
|
|
|
``v`` ``EquivalentFunctionCombiner``
|
|
|
|
``e`` ``ExpressionInliner``
|
|
|
|
``j`` ``ExpressionJoiner``
|
|
|
|
``s`` ``ExpressionSimplifier``
|
|
|
|
``x`` ``ExpressionSplitter``
|
|
|
|
``I`` ``ForLoopConditionIntoBody``
|
|
|
|
``O`` ``ForLoopConditionOutOfBody``
|
|
|
|
``o`` ``ForLoopInitRewriter``
|
|
|
|
``i`` ``FullInliner``
|
|
|
|
``g`` ``FunctionGrouper``
|
|
|
|
``h`` ``FunctionHoister``
|
2021-03-25 10:54:55 +00:00
|
|
|
``F`` ``FunctionSpecializer``
|
2020-05-04 19:25:57 +00:00
|
|
|
``T`` ``LiteralRematerialiser``
|
|
|
|
``L`` ``LoadResolver``
|
|
|
|
``M`` ``LoopInvariantCodeMotion``
|
|
|
|
``r`` ``RedundantAssignEliminator``
|
2020-09-14 14:56:45 +00:00
|
|
|
``R`` ``ReasoningBasedSimplifier`` - highly experimental
|
2020-05-04 19:25:57 +00:00
|
|
|
``m`` ``Rematerialiser``
|
|
|
|
``V`` ``SSAReverser``
|
|
|
|
``a`` ``SSATransform``
|
|
|
|
``t`` ``StructuralSimplifier``
|
|
|
|
``u`` ``UnusedPruner``
|
2021-10-08 17:51:23 +00:00
|
|
|
``p`` ``UnusedFunctionParameterPruner``
|
2020-05-04 19:25:57 +00:00
|
|
|
``d`` ``VarDeclInitializer``
|
2020-05-04 13:45:08 +00:00
|
|
|
============ ===============================
|
|
|
|
|
2020-05-04 19:25:57 +00:00
|
|
|
Some steps depend on properties ensured by ``BlockFlattener``, ``FunctionGrouper``, ``ForLoopInitRewriter``.
|
2020-05-04 13:45:08 +00:00
|
|
|
For this reason the Yul optimizer always applies them before applying any steps supplied by the user.
|
2020-04-16 09:57:07 +00:00
|
|
|
|
2020-09-14 14:56:45 +00:00
|
|
|
The ReasoningBasedSimplifier is an optimizer step that is currently not enabled
|
|
|
|
in the default set of steps. It uses an SMT solver to simplify arithmetic expressions
|
|
|
|
and boolean conditions. It has not received thorough testing or validation yet and can produce
|
|
|
|
non-reproducible results, so please use with care!
|
2020-04-16 09:57:07 +00:00
|
|
|
|
|
|
|
.. _erc20yul:
|
|
|
|
|
|
|
|
Complete ERC20 Example
|
|
|
|
======================
|
|
|
|
|
|
|
|
.. code-block:: yul
|
|
|
|
|
|
|
|
object "Token" {
|
|
|
|
code {
|
|
|
|
// Store the creator in slot zero.
|
|
|
|
sstore(0, caller())
|
|
|
|
|
|
|
|
// Deploy the contract
|
|
|
|
datacopy(0, dataoffset("runtime"), datasize("runtime"))
|
|
|
|
return(0, datasize("runtime"))
|
|
|
|
}
|
|
|
|
object "runtime" {
|
|
|
|
code {
|
|
|
|
// Protection against sending Ether
|
|
|
|
require(iszero(callvalue()))
|
|
|
|
|
|
|
|
// Dispatcher
|
|
|
|
switch selector()
|
|
|
|
case 0x70a08231 /* "balanceOf(address)" */ {
|
|
|
|
returnUint(balanceOf(decodeAsAddress(0)))
|
|
|
|
}
|
|
|
|
case 0x18160ddd /* "totalSupply()" */ {
|
|
|
|
returnUint(totalSupply())
|
|
|
|
}
|
|
|
|
case 0xa9059cbb /* "transfer(address,uint256)" */ {
|
|
|
|
transfer(decodeAsAddress(0), decodeAsUint(1))
|
|
|
|
returnTrue()
|
|
|
|
}
|
|
|
|
case 0x23b872dd /* "transferFrom(address,address,uint256)" */ {
|
|
|
|
transferFrom(decodeAsAddress(0), decodeAsAddress(1), decodeAsUint(2))
|
|
|
|
returnTrue()
|
|
|
|
}
|
|
|
|
case 0x095ea7b3 /* "approve(address,uint256)" */ {
|
|
|
|
approve(decodeAsAddress(0), decodeAsUint(1))
|
|
|
|
returnTrue()
|
|
|
|
}
|
|
|
|
case 0xdd62ed3e /* "allowance(address,address)" */ {
|
|
|
|
returnUint(allowance(decodeAsAddress(0), decodeAsAddress(1)))
|
|
|
|
}
|
|
|
|
case 0x40c10f19 /* "mint(address,uint256)" */ {
|
|
|
|
mint(decodeAsAddress(0), decodeAsUint(1))
|
|
|
|
returnTrue()
|
|
|
|
}
|
|
|
|
default {
|
|
|
|
revert(0, 0)
|
|
|
|
}
|
|
|
|
|
|
|
|
function mint(account, amount) {
|
|
|
|
require(calledByOwner())
|
|
|
|
|
|
|
|
mintTokens(amount)
|
|
|
|
addToBalance(account, amount)
|
|
|
|
emitTransfer(0, account, amount)
|
|
|
|
}
|
|
|
|
function transfer(to, amount) {
|
|
|
|
executeTransfer(caller(), to, amount)
|
|
|
|
}
|
|
|
|
function approve(spender, amount) {
|
|
|
|
revertIfZeroAddress(spender)
|
|
|
|
setAllowance(caller(), spender, amount)
|
|
|
|
emitApproval(caller(), spender, amount)
|
|
|
|
}
|
|
|
|
function transferFrom(from, to, amount) {
|
|
|
|
decreaseAllowanceBy(from, caller(), amount)
|
|
|
|
executeTransfer(from, to, amount)
|
|
|
|
}
|
|
|
|
|
|
|
|
function executeTransfer(from, to, amount) {
|
|
|
|
revertIfZeroAddress(to)
|
|
|
|
deductFromBalance(from, amount)
|
|
|
|
addToBalance(to, amount)
|
|
|
|
emitTransfer(from, to, amount)
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
/* ---------- calldata decoding functions ----------- */
|
|
|
|
function selector() -> s {
|
|
|
|
s := div(calldataload(0), 0x100000000000000000000000000000000000000000000000000000000)
|
|
|
|
}
|
|
|
|
|
|
|
|
function decodeAsAddress(offset) -> v {
|
|
|
|
v := decodeAsUint(offset)
|
|
|
|
if iszero(iszero(and(v, not(0xffffffffffffffffffffffffffffffffffffffff)))) {
|
|
|
|
revert(0, 0)
|
|
|
|
}
|
|
|
|
}
|
|
|
|
function decodeAsUint(offset) -> v {
|
|
|
|
let pos := add(4, mul(offset, 0x20))
|
|
|
|
if lt(calldatasize(), add(pos, 0x20)) {
|
|
|
|
revert(0, 0)
|
|
|
|
}
|
|
|
|
v := calldataload(pos)
|
|
|
|
}
|
|
|
|
/* ---------- calldata encoding functions ---------- */
|
|
|
|
function returnUint(v) {
|
|
|
|
mstore(0, v)
|
|
|
|
return(0, 0x20)
|
|
|
|
}
|
|
|
|
function returnTrue() {
|
|
|
|
returnUint(1)
|
|
|
|
}
|
|
|
|
|
|
|
|
/* -------- events ---------- */
|
|
|
|
function emitTransfer(from, to, amount) {
|
|
|
|
let signatureHash := 0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef
|
|
|
|
emitEvent(signatureHash, from, to, amount)
|
|
|
|
}
|
|
|
|
function emitApproval(from, spender, amount) {
|
|
|
|
let signatureHash := 0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925
|
|
|
|
emitEvent(signatureHash, from, spender, amount)
|
|
|
|
}
|
|
|
|
function emitEvent(signatureHash, indexed1, indexed2, nonIndexed) {
|
|
|
|
mstore(0, nonIndexed)
|
|
|
|
log3(0, 0x20, signatureHash, indexed1, indexed2)
|
|
|
|
}
|
|
|
|
|
|
|
|
/* -------- storage layout ---------- */
|
|
|
|
function ownerPos() -> p { p := 0 }
|
|
|
|
function totalSupplyPos() -> p { p := 1 }
|
|
|
|
function accountToStorageOffset(account) -> offset {
|
|
|
|
offset := add(0x1000, account)
|
|
|
|
}
|
|
|
|
function allowanceStorageOffset(account, spender) -> offset {
|
|
|
|
offset := accountToStorageOffset(account)
|
|
|
|
mstore(0, offset)
|
|
|
|
mstore(0x20, spender)
|
|
|
|
offset := keccak256(0, 0x40)
|
|
|
|
}
|
|
|
|
|
|
|
|
/* -------- storage access ---------- */
|
|
|
|
function owner() -> o {
|
|
|
|
o := sload(ownerPos())
|
|
|
|
}
|
|
|
|
function totalSupply() -> supply {
|
|
|
|
supply := sload(totalSupplyPos())
|
|
|
|
}
|
|
|
|
function mintTokens(amount) {
|
|
|
|
sstore(totalSupplyPos(), safeAdd(totalSupply(), amount))
|
|
|
|
}
|
|
|
|
function balanceOf(account) -> bal {
|
|
|
|
bal := sload(accountToStorageOffset(account))
|
|
|
|
}
|
|
|
|
function addToBalance(account, amount) {
|
|
|
|
let offset := accountToStorageOffset(account)
|
|
|
|
sstore(offset, safeAdd(sload(offset), amount))
|
|
|
|
}
|
|
|
|
function deductFromBalance(account, amount) {
|
|
|
|
let offset := accountToStorageOffset(account)
|
|
|
|
let bal := sload(offset)
|
|
|
|
require(lte(amount, bal))
|
|
|
|
sstore(offset, sub(bal, amount))
|
|
|
|
}
|
|
|
|
function allowance(account, spender) -> amount {
|
|
|
|
amount := sload(allowanceStorageOffset(account, spender))
|
|
|
|
}
|
|
|
|
function setAllowance(account, spender, amount) {
|
|
|
|
sstore(allowanceStorageOffset(account, spender), amount)
|
|
|
|
}
|
|
|
|
function decreaseAllowanceBy(account, spender, amount) {
|
|
|
|
let offset := allowanceStorageOffset(account, spender)
|
|
|
|
let currentAllowance := sload(offset)
|
|
|
|
require(lte(amount, currentAllowance))
|
|
|
|
sstore(offset, sub(currentAllowance, amount))
|
|
|
|
}
|
|
|
|
|
|
|
|
/* ---------- utility functions ---------- */
|
|
|
|
function lte(a, b) -> r {
|
|
|
|
r := iszero(gt(a, b))
|
|
|
|
}
|
|
|
|
function gte(a, b) -> r {
|
|
|
|
r := iszero(lt(a, b))
|
|
|
|
}
|
|
|
|
function safeAdd(a, b) -> r {
|
|
|
|
r := add(a, b)
|
|
|
|
if or(lt(r, a), lt(r, b)) { revert(0, 0) }
|
|
|
|
}
|
|
|
|
function calledByOwner() -> cbo {
|
|
|
|
cbo := eq(owner(), caller())
|
|
|
|
}
|
|
|
|
function revertIfZeroAddress(addr) {
|
|
|
|
require(addr)
|
|
|
|
}
|
|
|
|
function require(condition) {
|
|
|
|
if iszero(condition) { revert(0, 0) }
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|