solidity-docs · soldocsbot · Mar 12, 2025 · Mar 14, 2025 · Mar 14, 2025 · Mar 14, 2025
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -21,7 +21,7 @@ include(EthPolicy)
 eth_policy()
 
 # project name and version should be set after cmake_policy CMP0048
-set(PROJECT_VERSION "0.8.24")
+set(PROJECT_VERSION "0.8.31")
 # OSX target needed in order to support std::visit
 set(CMAKE_OSX_DEPLOYMENT_TARGET "10.14")
 project(solidity VERSION ${PROJECT_VERSION} LANGUAGES C CXX)
@@ -34,19 +34,39 @@ endif()
 
 option(SOLC_LINK_STATIC "Link solc executable statically on supported platforms" OFF)
 option(SOLC_STATIC_STDLIBS "Link solc against static versions of libgcc and libstdc++ on supported platforms" OFF)
-option(STRICT_Z3_VERSION "Use the latest version of Z3" ON)
+option(STRICT_Z3_VERSION "Require the exact version of Z3 solver expected by our test suite." ON)
 option(PEDANTIC "Enable extra warnings and pedantic build flags. Treat all warnings as errors." ON)
 option(PROFILE_OPTIMIZER_STEPS "Output performance metrics for the optimiser steps." OFF)
+option(
+	IGNORE_VENDORED_DEPENDENCIES
+	"Ignore libraries provided as submodules of the repository and allow CMake to look for \
+them in the typical locations, including system-wide dirs."
+	OFF
+)
+option(
+	ONLY_BUILD_SOLIDITY_LIBRARIES
+	"Only build library targets that can be statically linked against. Do not build executables or tests."
+	OFF
+)
+mark_as_advanced(PROFILE_OPTIMIZER_STEPS)
+mark_as_advanced(IGNORE_VENDORED_DEPENDENCIES)
+mark_as_advanced(ONLY_BUILD_SOLIDITY_LIBRARIES)
 
 # Setup cccache.
 include(EthCcache)
 
 # Let's find our dependencies
 include(EthDependencies)
-include(fmtlib)
-include(jsoncpp)
-include(range-v3)
-include_directories(SYSTEM ${JSONCPP_INCLUDE_DIR})
+if (NOT IGNORE_VENDORED_DEPENDENCIES)
+  include(fmtlib)
+  include(nlohmann-json)
+  include(range-v3)
+else ()
+  message(WARNING "-- Ignoring vendored dependencies. Will use installed versions if found. Versions may differ from the ones the compiler was tested with. Make sure to run the test suite and thoroughly test the resulting binaries before using them in production.")
+  find_package(fmt REQUIRED)
+  find_package(nlohmann_json REQUIRED)
+  find_package(range-v3 REQUIRED)
+endif()
 
 find_package(Threads)
 
@@ -75,62 +95,31 @@ configure_file("${PROJECT_SOURCE_DIR}/cmake/templates/license.h.in" include/lice
 
 include(EthOptions)
 configure_project(TESTS)
-set(LATEST_Z3_VERSION "4.12.1")
-set(MINIMUM_Z3_VERSION "4.8.16")
-find_package(Z3)
-if (${Z3_FOUND})
-  if (${STRICT_Z3_VERSION})
-    if (NOT ("${Z3_VERSION_STRING}" VERSION_EQUAL ${LATEST_Z3_VERSION}))
-      message(
-        FATAL_ERROR
-        "SMTChecker tests require Z3 ${LATEST_Z3_VERSION} for all tests to pass.\n\
-Build with -DSTRICT_Z3_VERSION=OFF if you want to use a different version. \
-You can also use -DUSE_Z3=OFF to build without Z3. In both cases use --no-smt when running tests."
-      )
-    endif()
-  else()
-    if ("${Z3_VERSION_STRING}" VERSION_LESS ${MINIMUM_Z3_VERSION})
-      message(
-        FATAL_ERROR
-        "Solidity requires Z3 ${MINIMUM_Z3_VERSION} or newer. You can also use -DUSE_Z3=OFF to build without Z3."
-      )
-    endif()
-  endif()
-endif()
 
-if(${USE_Z3_DLOPEN})
-  add_definitions(-DHAVE_Z3)
-  add_definitions(-DHAVE_Z3_DLOPEN)
-  find_package(Python3 COMPONENTS Interpreter)
-  if(${Z3_FOUND})
-    get_target_property(Z3_HEADER_HINTS z3::libz3 INTERFACE_INCLUDE_DIRECTORIES)
-  endif()
-  find_path(Z3_HEADER_PATH z3.h HINTS ${Z3_HEADER_HINTS})
-  if(Z3_HEADER_PATH)
-    set(Z3_FOUND TRUE)
-  else()
-    message(SEND_ERROR "Dynamic loading of Z3 requires Z3 headers to be present at build time.")
-  endif()
-  if(NOT ${Python3_FOUND})
-    message(SEND_ERROR "Dynamic loading of Z3 requires Python 3 to be present at build time.")
-  endif()
-  if(${SOLC_LINK_STATIC})
-    message(SEND_ERROR "solc cannot be linked statically when dynamically loading Z3.")
-  endif()
-elseif (${Z3_FOUND})
-  add_definitions(-DHAVE_Z3)
-  message("Z3 SMT solver found. This enables optional SMT checking with Z3.")
-endif()
-
-find_package(CVC4 QUIET)
-if (${CVC4_FOUND})
-  add_definitions(-DHAVE_CVC4)
-  message("CVC4 SMT solver found. This enables optional SMT checking with CVC4.")
-endif()
-
-if (NOT (${Z3_FOUND} OR ${CVC4_FOUND}))
-  message("No SMT solver found (or it has been forcefully disabled). Optional SMT checking will not be available.\
-  \nPlease install Z3 or CVC4 or remove the option disabling them (USE_Z3, USE_CVC4).")
+if(EMSCRIPTEN)
+    set(TESTED_Z3_VERSION "4.13.3")
+    set(MINIMUM_Z3_VERSION "4.8.16")
+    find_package(Z3)
+    if (${Z3_FOUND})
+      add_definitions(-DEMSCRIPTEN_BUILD)
+      if (${STRICT_Z3_VERSION})
+        if (NOT ("${Z3_VERSION_STRING}" VERSION_EQUAL ${TESTED_Z3_VERSION}))
+          message(
+            FATAL_ERROR
+            "SMTChecker tests require Z3 ${TESTED_Z3_VERSION} for all tests to pass.\n"
+          )
+        endif()
+      else()
+        if ("${Z3_VERSION_STRING}" VERSION_LESS ${MINIMUM_Z3_VERSION})
+          message(
+            FATAL_ERROR
+            "Solidity requires Z3 ${MINIMUM_Z3_VERSION} or newer."
+          )
+        endif()
+      endif()
+    else()
+        message(FATAL_ERROR "Solidity requires Z3 for emscripten build.")
+    endif()
 endif()
 
 add_subdirectory(libsolutil)
@@ -141,12 +130,15 @@ add_subdirectory(libyul)
 add_subdirectory(libsolidity)
 add_subdirectory(libsolc)
 add_subdirectory(libstdlib)
-add_subdirectory(tools)
 
-if (NOT EMSCRIPTEN)
-	add_subdirectory(solc)
-endif()
+if (NOT ONLY_BUILD_SOLIDITY_LIBRARIES)
+	add_subdirectory(tools)
 
-if (TESTS AND NOT EMSCRIPTEN)
-	add_subdirectory(test)
+	if (NOT EMSCRIPTEN)
+		add_subdirectory(solc)
+	endif()
+
+	if (TESTS AND NOT EMSCRIPTEN)
+		add_subdirectory(test)
+	endif()
 endif()
diff --git a/docs/080-breaking-changes.rst b/docs/080-breaking-changes.rst
@@ -132,8 +132,13 @@ Solidity v0.8.0 重大变化
 * ``--combined-json`` 的输出已经改变。JSON字段 ``abi``, ``devdoc``, ``userdoc`` 和
   ``storage-layout`` 现在是子对象。在0.8.0之前，它们曾被序列化为字符串。
 
+<<<<<<< HEAD
 * “传统AST“ 已被删除（ ``--ast-json`` 在命令行界面， ``legacyAST`` 用于标准JSON）。
   使用 “紧凑型AST”（ ``--ast-compact-json`` 参数. ``AST``）作为替代。
+=======
+* The "legacy AST" has been removed (``--ast-json`` on the commandline interface and ``legacyAST`` for standard JSON).
+  Use the "compact AST" (``--ast-compact-json`` resp. ``AST``) as replacement.
+>>>>>>> english/develop
 
 * 旧的错误报告器（ ``--old-reporter`` ）已经被删除。
 

diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css
@@ -93,7 +93,7 @@ h1 {
 }
 
 section:first-of-type h1:first-of-type {
-    font-family: 'Overpass mono', monospace;
+    font-family: 'Overpass Mono', monospace;
     font-size: 48px;
     margin-top: 3rem;
     margin-bottom: 5rem;
@@ -229,7 +229,7 @@ small * {
 .wy-side-nav-search {
     background-color: transparent !important;
     color: var(--color-a) !important;
-    box-shadow: 0 4 4 0 var(--color-a);
+    box-shadow: 0 4px 4px 0 var(--color-a);
     border-bottom: 1px solid var(--color-d) !important;
 }
 
@@ -823,4 +823,4 @@ a.skip-to-content:focus {
 #content {
     scroll-margin-top: 6rem;
     scroll-behavior: smooth;
-}
+}
diff --git a/docs/_static/css/toggle.css b/docs/_static/css/toggle.css
@@ -85,4 +85,9 @@ html.transition *:after {
 
 .wy-menu-vertical a:hover {
     background-color: #0002;
+}
+
+body {
+    font-weight: 300;
+    letter-spacing: 0.5px;
 }
diff --git a/docs/abi-spec.rst b/docs/abi-spec.rst
@@ -16,7 +16,11 @@
 我们假设合约的接口函数是强类型的，在编译时就知道，并且是静态的。
 我们假设所有合约在编译时都有它们所调用的任何合约的接口定义。
 
+<<<<<<< HEAD
 本规范不涉及其接口是动态的或其他只有在运行时才知道的合约。
+=======
+This specification does not address contracts whose interface is dynamic or otherwise known only at run-time. Also, the ABI specification for libraries is :ref:`slightly different <library-selectors>`.
+>>>>>>> english/develop
 
 .. _abi_function_selector:
 .. index:: ! selector; of a function
@@ -44,7 +48,13 @@
 类型
 =====
 
+<<<<<<< HEAD
 以下是基础类型：
+=======
+Note that the library ABIs can take types different than below e.g. for non-storage structs. See :ref:`library selectors <library-selectors>` for details.
+
+The following elementary types exist:
+>>>>>>> english/develop
 
 - ``uint<M>``： ``M`` 位的无符号整数， ``0 < M <= 256``， ``M % 8 == 0``。例如： ``uint32``， ``uint8``， ``uint256``。
 

diff --git a/docs/assembly.rst b/docs/assembly.rst
@@ -7,8 +7,15 @@
 .. index:: ! assembly, ! asm, ! evmasm
 
 
+<<<<<<< HEAD
 您可以用接近Ethereum虚拟机的语言，将Solidity语句与内联汇编交错使用。
 这给了您更精细的控制，这在您通过编写库来增强语言时特别有用。
+=======
+You can interleave Solidity statements with inline assembly in a language close
+to the one of the Ethereum Virtual Machine. This gives you more fine-grained control,
+which is especially useful when you are enhancing the language by writing libraries or
+optimizing gas usage.
+>>>>>>> english/develop
 
 在 Solidity 中用于内联汇编的语言被称为 :ref:`Yul <yul>`，它在自己的章节中被记录。
 本节将只涉及内联汇编代码如何在 Solidity 代码内交互。
@@ -150,6 +157,15 @@
 对于动态的calldata数组，您可以使用 ``x.offset`` 和 ``x.length`` 访问它们的calldata偏移量（字节）和长度（元素数）。
 这两个表达式也可以被赋值，但是和静态情况一样，不会进行验证以确保产生的数据区域在 ``calldatasize()`` 的范围内。
 
+<<<<<<< HEAD
+=======
+For local storage variables or state variables (including transient storage) a single Yul identifier
+is not sufficient, since they do not necessarily occupy a single full storage slot.
+Therefore, their "address" is composed of a slot and a byte-offset
+inside that slot. To retrieve the slot pointed to by the variable ``x``, you
+use ``x.slot``, and to retrieve the byte-offset you use ``x.offset``.
+Using ``x`` itself will result in an error.
+>>>>>>> english/develop
 
 对于本地存储变量或状态变量，一个Yul标识符是不够的，因为它们不一定占据一个完整的存储槽。
 因此，它们的 "地址" 是由一个槽和槽内的字节偏移量组成。要检索变量 ``x`` 所指向的槽，
@@ -166,14 +182,17 @@
     :force:
 
     // SPDX-License-Identifier: GPL-3.0
-    pragma solidity >=0.7.0 <0.9.0;
+    pragma solidity >=0.8.28 <0.9.0;
 
+    // This will report a warning
     contract C {
+        bool transient a;
         uint b;
-        function f(uint x) public view returns (uint r) {
+        function f(uint x) public returns (uint r) {
             assembly {
                 // 我们忽略了存储槽的偏移量，我们知道在这种特殊情况下它是零。
                 r := mul(x, sload(b.slot))
+                tstore(a.slot, true)
             }
         }
     }
@@ -187,11 +206,22 @@
     ``assembly { signextend(<num_bytes_of_x_minus_one>, x) }``
 
 
+<<<<<<< HEAD
 自Solidity 0.6.0以来，内联汇编变量的名称不能影射内联汇编块范围内可见的任何声明
 （包括变量、合约和函数声明）。
 
 自Solidity 0.7.0以来，在内联程序块内声明的变量和函数不能包含 ``.``，
 但使用 ``.`` 可以有效地从内联程序块外访问Solidity变量。
+=======
+Since Solidity 0.6.0, the name of an inline assembly variable may not
+shadow any declaration visible in the scope of the inline assembly block
+(including variable, contract and function declarations).
+
+Since Solidity 0.7.0, variables and functions declared inside the
+inline assembly block may not contain ``.``, but using ``.`` is
+valid to access Solidity variables from outside the inline assembly block.
+However, it is still valid to use dots if you use Solidity in Yul-only mode.
+>>>>>>> english/develop
 
 需要避免的事情
 ---------------
@@ -221,11 +251,23 @@ Solidity的的惯例
 内存管理
 =================
 
+<<<<<<< HEAD
 Solidity以下列方式管理内存。在内存中 ``0x40`` 的位置有一个 "空闲内存指针"。
 如果您想分配内存，从这个指针指向的地方开始使用内存，并更新它。
 不能保证该内存以前没有被使用过，因此您不能假设其内容为零字节。
 没有内置的机制来释放或释放分配的内存。下面是一段汇编代码，
 您可以用它来分配内存，它遵循上述的过程：
+=======
+Solidity manages memory in the following way. There is a "free memory pointer"
+at position ``0x40`` in memory. If you want to allocate memory, use the memory
+starting from where this pointer points at and update it.
+There is no guarantee that the memory has not been used before and thus
+you cannot assume that its contents are zero bytes.
+There is no built-in mechanism to release or free allocated memory.
+Solidity does not guarantee and does not require that the values in memory
+are placed at positions aligned to a multiple of any value.
+Here is an assembly snippet you can use for allocating memory that follows the process outlined above:
+>>>>>>> english/develop
 
 .. code-block:: yul
 
@@ -341,5 +383,31 @@ Solidity中内存数组中的元素总是占据32字节的倍数
         ...
     }
 
+<<<<<<< HEAD
 请注意，我们将在未来的重大变化版本中禁止通过注释的方式进行注解；
 因此，如果您不关心与旧编译器版本的向后兼容问题，请优先使用这种代码字符串形式的写法。
+=======
+Note that we will disallow the annotation via comment in a future breaking release; so, if you are not concerned with
+backward-compatibility with older compiler versions, prefer using the dialect string.
+
+Advanced Safe Use of Memory
+---------------------------
+
+Beyond the strict definition of memory-safety given above, there are cases in which you may want to use more than 64 bytes
+of scratch space starting at memory offset ``0``. If you are careful, it can be admissible to use memory up to (and not
+including) offset ``0x80`` and still safely declare the assembly block as ``memory-safe``.
+This is admissible under either of the following conditions:
+
+- By the end of the assembly block, the free memory pointer at offset ``0x40`` is restored to a sane value (i.e. it is either
+  restored to its original value or an increment of it due to a manual memory allocation), and the memory word at offset ``0x60``
+  is restored to a value of zero.
+
+- The assembly block terminates, i.e. execution can never return to high-level Solidity code. This is the case, for example,
+  if your assembly block unconditionally ends in calling the ``revert`` opcode.
+
+Furthermore, you need to be aware that the default-value of dynamic arrays in Solidity point to memory offset ``0x60``, so
+for the duration of temporarily changing the value at memory offset ``0x60``, you can no longer rely on getting accurate
+length values when reading dynamic arrays, until you restore the zero value at ``0x60``. To be more precise, we only guarantee
+safety when overwriting the zero pointer, if the remainder of the assembly snippet does not interact with the memory of
+high-level Solidity objects (including by reading from offsets previously stored in variables).
+>>>>>>> english/develop
diff --git a/docs/bugs.json b/docs/bugs.json
@@ -151,7 +151,7 @@
     {
         "uid": "SOL-2021-1",
         "name": "KeccakCaching",
-        "summary": "The bytecode optimizer incorrectly re-used previously evaluated Keccak-256 hashes. You are unlikely to be affected if you do not compute Keccak-256 hashes in inline assembly.",
+        "summary": "The bytecode optimizer incorrectly reused previously evaluated Keccak-256 hashes. You are unlikely to be affected if you do not compute Keccak-256 hashes in inline assembly.",
         "description": "Solidity's bytecode optimizer has a step that can compute Keccak-256 hashes, if the contents of the memory are known during compilation time. This step also has a mechanism to determine that two Keccak-256 hashes are equal even if the values in memory are not known during compile time. This mechanism had a bug where Keccak-256 of the same memory content, but different sizes were considered equal. More specifically, ``keccak256(mpos1, length1)`` and ``keccak256(mpos2, length2)`` in some cases were considered equal if ``length1`` and ``length2``, when rounded up to nearest multiple of 32 were the same, and when the memory contents at ``mpos1`` and ``mpos2`` can be deduced to be equal. You maybe affected if you compute multiple Keccak-256 hashes of the same content, but with different lengths inside inline assembly. You are unaffected if your code uses ``keccak256`` with a length that is not a compile-time constant or if it is always a multiple of 32.",
         "link": "https://blog.soliditylang.org/2021/03/23/keccak-optimizer-bug/",
         "fixed": "0.8.3",
@@ -200,7 +200,7 @@
         "uid": "SOL-2020-7",
         "name": "MissingEscapingInFormatting",
         "summary": "String literals containing double backslash characters passed directly to external or encoding function calls can lead to a different string being used when ABIEncoderV2 is enabled.",
-        "description": "When ABIEncoderV2 is enabled, string literals passed directly to encoding functions or external function calls are stored as strings in the intemediate code. Characters outside the printable range are handled correctly, but backslashes are not escaped in this procedure. This leads to double backslashes being reduced to single backslashes and consequently re-interpreted as escapes potentially resulting in a different string being encoded.",
+        "description": "When ABIEncoderV2 is enabled, string literals passed directly to encoding functions or external function calls are stored as strings in the intermediate code. Characters outside the printable range are handled correctly, but backslashes are not escaped in this procedure. This leads to double backslashes being reduced to single backslashes and consequently re-interpreted as escapes potentially resulting in a different string being encoded.",
         "introduced": "0.5.14",
         "fixed": "0.6.8",
         "severity": "very low",