English documentation updates up to v0.8.27-125-gfde19a5b1 (2024-10-09)

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.22")
+set(PROJECT_VERSION "0.8.28")
 # 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,34 @@ 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)
+endif()
 
 find_package(Threads)
 
@@ -75,15 +90,15 @@ 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(TESTED_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}))
+    if (NOT ("${Z3_VERSION_STRING}" VERSION_EQUAL ${TESTED_Z3_VERSION}))
       message(
         FATAL_ERROR
-        "SMTChecker tests require Z3 ${LATEST_Z3_VERSION} for all tests to pass.\n\
+        "SMTChecker tests require Z3 ${TESTED_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."
       )
@@ -122,15 +137,11 @@ elseif (${Z3_FOUND})
   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()
+find_program(CVC5_PATH cvc5)
 
-if (NOT (${Z3_FOUND} OR ${CVC4_FOUND}))
+if (NOT (${Z3_FOUND} OR CVC5_PATH))
   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).")
+  \nPlease install Z3 or cvc5 or remove the option disabling them (USE_Z3).")
 endif()
 
 add_subdirectory(libsolutil)
@@ -141,12 +152,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()

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`` ）已经被删除。
 

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;
 }

docs/_static/js/initialize.js

@@ -23,18 +23,24 @@ function rearrangeDom() {
   document.body.prepend(wrapperDiv);
 
   const rstVersions = document.querySelector(".rst-versions");
-  rstVersions.remove();
   const wyNavSide = document.querySelector("nav.wy-nav-side");
-  wyNavSide.appendChild(rstVersions);
+  // NOTE: Since RTD migration to addons, `.rst-versions` is no longer present in the DOM.
+  // The following code is kept for compatibility with older versions.
+  // See: https://github.com/readthedocs/readthedocs.org/issues/11474
+  if (rstVersions && wyNavSide) {
+    rstVersions.remove();
+    wyNavSide.appendChild(rstVersions);
+  }
   const backdrop = document.createElement("div");
   backdrop.classList.add("backdrop");
   wrapperDiv.appendChild(backdrop);
 
   const content = document.querySelector(".wy-nav-content");
-  content.id = "content";
-  const oldWrap = document.querySelector("section.wy-nav-content-wrap");
-  oldWrap.remove();
-  document.querySelector(".wy-grid-for-nav").appendChild(content);
+  if (content) {
+    content.id = "content";
+    document.querySelector("section.wy-nav-content-wrap")?.remove();
+    document.querySelector(".wy-grid-for-nav")?.appendChild(content);
+  }
 }
 
 function buildHeader() {
@@ -144,8 +150,15 @@ const updateActiveNavLink = () => {
 document.addEventListener("locationchange", updateActiveNavLink);
 
 function updateGitHubEditPath() {
-  // Replaces the version number in the GitHub edit path with "develop"
+  // Replaces the version number in the GitHub edit path with "develop" if it exists.
+  // This is to ensure that the edit path always points to the `develop` branch instead of the specific version branch.
+  // Note that it will fail silently if the anchor element is not found, i.e. the page is not editable or
+  // if the sphinx_rtd_theme is updated to a version that changes the anchor element.
+  // See: https://github.com/readthedocs/sphinx_rtd_theme/blob/a1c2147b17cbf0e57b7d7a6450ad4d9a5ff362cf/sphinx_rtd_theme/breadcrumbs.html#L35
+  // TODO: We should consider a more robust way to handle this in the future.
   const gitHubEditAnchor = document.querySelector(".wy-breadcrumbs-aside > a");
+  if (!gitHubEditAnchor) return;
+
   const url = new URL(gitHubEditAnchor.href);
   const split = url.pathname.split("/");
   const versionIndex = split.indexOf("blob") + 1;
@@ -195,10 +208,12 @@ function initialize() {
     .querySelector(":root")
     .setAttribute("style", `--color-scheme: ${mode}`);
 
+  // NOTE: Since RTD migration to addons, the elements below are no longer present in the DOM.
+  // The following code is kept for compatibility with older versions.
   // Remove old input and RTD logo anchor element
-  document.querySelector("input[name=mode]").remove();
-  document.querySelector("label[for=switch]").remove();
-  document.querySelector(".wy-side-nav-search > a").remove();
+  document.querySelector("input[name=mode]")?.remove();
+  document.querySelector("label[for=switch]")?.remove();
+  document.querySelector(".wy-side-nav-search > a")?.remove();
 
   // Add footer note
   addFooterNote();
@@ -239,7 +254,7 @@ document.addEventListener("click", handleClick);
 
 const handleKeyDown = (e) => {
   if (e.metaKey && e.key === "k") {
-    document.querySelector("#rtd-search-form input").focus();
+    document.querySelector("#rtd-search-form input")?.focus();
   } else if (e.key === "Escape") {
     toggleMenu({ force: false });
   }

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``。
 
@@ -238,8 +248,27 @@ Solidity 支持上面介绍的除了元祖之外的所有同名类型。
     }
 
 
+<<<<<<< HEAD
 因此，对于我们的例子 ``Foo``，如果我们想用 ``69`` 和 ``true`` 做参数调用 ``baz``，
 我们总共需要传送 68 字节，可以分解为：
+=======
+Thus, for our ``Foo`` example, if we wanted to call ``bar`` with the argument ``["abc", "def"]``, we would pass 68 bytes total, broken down into:
+
+- ``0xfce353f6``: the Method ID. This is derived from the signature ``bar(bytes3[2])``.
+- ``0x6162630000000000000000000000000000000000000000000000000000000000``: the first part of the first
+  parameter, a ``bytes3`` value ``"abc"`` (left-aligned).
+- ``0x6465660000000000000000000000000000000000000000000000000000000000``: the second part of the first
+  parameter, a ``bytes3`` value ``"def"`` (left-aligned).
+
+In total:
+
+.. code-block:: none
+
+    0xfce353f661626300000000000000000000000000000000000000000000000000000000006465660000000000000000000000000000000000000000000000000000000000
+
+If we wanted to call ``baz`` with the parameters ``69`` and
+``true``, we would pass 68 bytes total, which can be broken down into:
+>>>>>>> english/develop
 
 - ``0xcdcd77c0``： 方法ID。这源自ASCII格式的 ``baz(uint32,bool)`` 签名的 Keccak 哈希的前 4 字节。
 - ``0x0000000000000000000000000000000000000000000000000000000000000045``： 第一个参数，
@@ -257,6 +286,7 @@ Solidity 支持上面介绍的除了元祖之外的所有同名类型。
 那么它的输出将是一个字节数组 ``0x0000000000000000000000000000000000000000000000000000000000000000``，
 一个 ``bool`` 值。
 
+<<<<<<< HEAD
 如果我们想用 ``["abc", "def"]`` 做参数调用 ``bar``，我们总共需要传送 68 字节，可以分解为：
 
 - ``0xfce353f6``： 方法ID。源自 ``bar(bytes3[2])`` 的签名。
@@ -273,6 +303,10 @@ Solidity 支持上面介绍的除了元祖之外的所有同名类型。
 
 如果我们想用 ``"dave"``， ``true`` 和 ``[1,2,3]`` 作为参数调用 ``sam``，
 我们总共需要传送 292 字节，可以分解为：
+=======
+If we wanted to call ``sam`` with the arguments ``"dave"``, ``true`` and ``[1,2,3]``, we would
+pass 292 bytes total, broken down into:
+>>>>>>> english/develop
 
 - ``0xa5643bf2``： 方法ID。这是从签名 ``sam(bytes,bool,uint256[])`` 中导出的。注意， ``uint`` 被替换为其典型代表 ``uint256``。
 - ``0x0000000000000000000000000000000000000000000000000000000000000060``： 第一个参数（动态类型）的数据部分的位置，即从参数编码块开始位置算起的字节数。在这里，是 ``0x60`` 。

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)
             }
         }
     }
@@ -341,5 +360,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

docs/bugs.json

@@ -1,4 +1,14 @@
 [
+    {
+        "uid": "SOL-2023-3",
+        "name": "VerbatimInvalidDeduplication",
+        "summary": "All ``verbatim`` blocks are considered identical by deduplicator and can incorrectly be unified when surrounded by identical opcodes.",
+        "description": "The block deduplicator is a step of the opcode-based optimizer which identifies equivalent assembly blocks and merges them into a single one. However, when blocks contained ``verbatim``, their comparison was performed incorrectly, leading to the collapse of assembly blocks which are identical except for the contents of the ``verbatim`` items. Since ``verbatim`` is only available in Yul, compilation of Solidity sources is not affected.",
+        "link": "https://blog.soliditylang.org/2023/11/08/verbatim-invalid-deduplication-bug/",
+        "introduced": "0.8.5",
+        "fixed": "0.8.23",
+        "severity": "low"
+    },
     {
         "uid": "SOL-2023-2",
         "name": "FullInlinerNonExpressionSplitArgumentEvaluationOrder",

docs/bugs.rst

@@ -6,9 +6,17 @@
 已知bug列表
 ##################
 
+<<<<<<< HEAD
 下面，您可以找到一个JSON格式的列表，其中包括Solidity编译器中一些已知的与安全有关的错误。
 该文件本身托管在 `Github 仓库 <https://github.com/ethereum/solidity/blob/develop/docs/bugs.json>`_。
 该列表最早可以追溯到0.3.0版本，只有在此之前的版本中已知的错误没有列出。
+=======
+Below, you can find a JSON-formatted list of some of the known security-relevant bugs in the
+Solidity compiler. The file itself is hosted in the `GitHub repository
+<https://github.com/ethereum/solidity/blob/develop/docs/bugs.json>`_.
+The list stretches back as far as version 0.3.0, bugs known to be present only
+in versions preceding that are not listed.
+>>>>>>> english/develop
 
 还有一个文件叫
 `bugs_by_version.json <https://github.com/ethereum/solidity/blob/develop/docs bugs_by_version.json>`_，