Merge pull request #14581 from ethereum/purge-using-namespace-std-from-test-libsolidity-util

Purge using namespace std from test/libsolidity/util

.circleci/README.md

@@ -7,15 +7,15 @@ The docker images are build locally on the developer machine:
 ```sh
 cd .circleci/docker/
 
-docker build -t ethereum/solidity-buildpack-deps:ubuntu2004-<revision> -f Dockerfile.ubuntu2004 .
-docker push ethereum/solidity-buildpack-deps:ubuntu2004-<revision>
+docker build -t ethereum/solidity-buildpack-deps:ubuntu2204-<revision> -f Dockerfile.ubuntu2204 .
+docker push ethereum/solidity-buildpack-deps:ubuntu2204-<revision>
 ```
 
-The current revisions per docker image are stored in [circle ci pipeline parameters](https://github.com/CircleCI-Public/api-preview-docs/blob/master/docs/pipeline-parameters.md#pipeline-parameters) called `<image-desc>-docker-image-rev` (e.g., `ubuntu-2004-docker-image-rev`). Please update the value assigned to the parameter(s) corresponding to the docker image(s) being updated at the time of the update. Please verify that the value assigned to the parameter matches the revision part of the docker image tag (`<revision>` in the docker build/push snippet shown above). Otherwise, the docker image used by circle ci and the one actually pushed to docker hub will differ.
+The current revisions per docker image are stored in [circle ci pipeline parameters](https://github.com/CircleCI-Public/api-preview-docs/blob/master/docs/pipeline-parameters.md#pipeline-parameters) called `<image-desc>-docker-image-rev` (e.g., `ubuntu-2204-docker-image-rev`). Please update the value assigned to the parameter(s) corresponding to the docker image(s) being updated at the time of the update. Please verify that the value assigned to the parameter matches the revision part of the docker image tag (`<revision>` in the docker build/push snippet shown above). Otherwise, the docker image used by circle ci and the one actually pushed to docker hub will differ.
 
 Once the docker image has been built and pushed to Dockerhub, you can find it at:
 
-    https://hub.docker.com/r/ethereum/solidity-buildpack-deps:ubuntu2004-<revision>
+    https://hub.docker.com/r/ethereum/solidity-buildpack-deps:ubuntu2204-<revision>
 
 where the image tag reflects the target OS and revision to build Solidity and run its tests on.
 
@@ -24,7 +24,7 @@ where the image tag reflects the target OS and revision to build Solidity and ru
 ```sh
 cd solidity
 # Mounts your local solidity directory in docker container for testing
-docker run -v `pwd`:/src/solidity -ti ethereum/solidity-buildpack-deps:ubuntu2004-<revision> /bin/bash
+docker run -v `pwd`:/src/solidity -ti ethereum/solidity-buildpack-deps:ubuntu2204-<revision> /bin/bash
 cd /src/solidity
 <commands_to_test_build_with_new_docker_image>
 ```

.circleci/cln-asan.supp

@@ -0,0 +1 @@
+leak:*libcln*

.circleci/compare_bytecode_reports.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+#------------------------------------------------------------------------------
+# Compares bytecode reports generated by prepare_report.py/.js.
+#
+# ------------------------------------------------------------------------------
+# This file is part of solidity.
+#
+# solidity is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# solidity is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with solidity.  If not, see <http://www.gnu.org/licenses/>
+#
+# (c) 2023 solidity contributors.
+#------------------------------------------------------------------------------
+
+no_cli_platforms=(
+    emscripten
+)
+native_platforms=(
+    ubuntu2004-static
+    ubuntu
+    osx
+    windows
+)
+interfaces=(
+    cli
+    standard-json
+)
+
+for preset in "$@"; do
+    report_files=()
+    for platform in "${no_cli_platforms[@]}"; do
+        report_files+=("bytecode-report-${platform}-${preset}.txt")
+    done
+    for platform in "${native_platforms[@]}"; do
+        for interface in "${interfaces[@]}"; do
+            report_files+=("bytecode-report-${platform}-${interface}-${preset}.txt")
+        done
+    done
+
+    echo "Reports to compare:"
+    printf -- "- %s\n" "${report_files[@]}"
+
+    if ! diff --brief --report-identical-files --from-file "${report_files[@]}"; then
+        diff --unified=0 --report-identical-files --from-file "${report_files[@]}" | head --lines 50
+        zip "bytecode-reports-${preset}.zip" "${report_files[@]}"
+        exit 1
+    fi
+done

.circleci/osx_install_dependencies.sh

@@ -52,7 +52,8 @@ function validate_checksum {
 
 if [ ! -f /usr/local/lib/libz3.a ] # if this file does not exists (cache was not restored), rebuild dependencies
 then
-  brew unlink python
+  brew update
+  brew upgrade
   brew install boost
   brew install cmake
   brew install wget
@@ -61,11 +62,11 @@ then
   ./scripts/install_obsolete_jsoncpp_1_7_4.sh
 
   # z3
-  z3_version="4.8.17"
+  z3_version="4.12.1"
   z3_dir="z3-${z3_version}-x64-osx-10.16"
   z3_package="${z3_dir}.zip"
   wget "https://github.com/Z3Prover/z3/releases/download/z3-${z3_version}/${z3_package}"
-  validate_checksum "$z3_package" 189667930517aee07f1ce36485d5924a9a2cb4f8c3c9586b03e714a2c657541a
+  validate_checksum "$z3_package" 7601f844de6d906235140d0f76cca58be7ac716f3e2c29c35845aa24b24f73b9
   unzip "$z3_package"
   rm "$z3_package"
   cp "${z3_dir}/bin/libz3.a" /usr/local/lib
@@ -74,18 +75,11 @@ then
   rm -r "$z3_dir"
 
   # evmone
-  evmone_version="0.8.0"
+  evmone_version="0.10.0"
   evmone_package="evmone-${evmone_version}-darwin-x86_64.tar.gz"
   wget "https://github.com/ethereum/evmone/releases/download/v${evmone_version}/${evmone_package}"
-  validate_checksum "$evmone_package" e8efef478822f0ed6d0493e89004181e895893f93963152a2a81589acc3a0828
+  validate_checksum "$evmone_package" 1b7773779287d7908baca6b8d556a98800cbd7d6e5c910b55fa507642bc0a15c
   tar xzpf "$evmone_package" -C /usr/local
   rm "$evmone_package"
 
-  # hera
-  hera_version="0.5.0"
-  hera_package="hera-${hera_version}-darwin-x86_64.tar.gz"
-  wget "https://github.com/ewasm/hera/releases/download/v${hera_version}/${hera_package}"
-  validate_checksum "$hera_package" 190050d7ace384ecd79ec1b1f607a9ff40e196b4eec75932958d4814d221d059
-  tar xzpf "$hera_package" -C /usr/local
-  rm "$hera_package"
 fi

.circleci/parallel_bytecode_report.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+#------------------------------------------------------------------------------
+# Splits all test source code into multiple files, generates bytecode and metadata
+# for each file and combines it into a single report.txt file.
+#
+# The script is meant to be executed in CI on all supported platforms. All generated
+# reports must be identical for a given compiler version.
+#
+# ------------------------------------------------------------------------------
+# This file is part of solidity.
+#
+# solidity is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# solidity is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with solidity.  If not, see <http://www.gnu.org/licenses/>
+#
+# (c) 2023 solidity contributors.
+#------------------------------------------------------------------------------
+
+(( $# == 4 )) || { >&2 echo "Wrong number of arguments."; exit 1; }
+label="$1"
+binary_type="$2"
+binary_path="$3" # This path must be absolute
+preset="$4"
+
+[[ $binary_type == native || $binary_type == solcjs ]] || { >&2 echo "Invalid binary type: ${binary_type}"; exit 1; }
+
+# NOTE: Locale affects the order of the globbed files.
+export LC_ALL=C
+
+mkdir test-cases/
+cd test-cases/
+
+echo "Preparing input files"
+python3 ../scripts/isolate_tests.py ../test/
+
+# FIXME: These cases crash because of https://github.com/ethereum/solidity/issues/13583
+rm ./*_bytecode_too_large_*.sol ./*_combined_too_large_*.sol
+
+if [[ $binary_type == native ]]; then
+    interface=$(echo -e "standard-json\ncli" | circleci tests split)
+    echo "Selected interface: ${interface}"
+
+    echo "Generating bytecode reports"
+    python3 ../scripts/bytecodecompare/prepare_report.py \
+        "$binary_path" \
+        --interface "$interface" \
+        --preset "$preset" \
+        --report-file "../bytecode-report-${label}-${interface}-${preset}.txt"
+else
+    echo "Installing solc-js"
+    git clone --depth 1 https://github.com/ethereum/solc-js.git solc-js
+    cp "$binary_path" solc-js/soljson.js
+
+    cd solc-js/
+    npm install
+    npm run build
+
+    cd ..
+    npm install ./solc-js/dist
+
+    cp ../scripts/bytecodecompare/prepare_report.js .
+
+    echo "Generating bytecode reports"
+    # shellcheck disable=SC2035
+    ./prepare_report.js \
+        --preset "$preset" \
+        *.sol > "../bytecode-report-${label}-${preset}.txt"
+fi

.circleci/parallel_cli_tests.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+
+import subprocess
+import sys
+
+# Slowest CLI tests, whose execution takes time on the order of minutes (as of June 2023).
+# When adding/removing items here, remember to update `parallelism` value in jobs that run this script.
+# TODO: We should switch to time-based splitting but that requires JUnit XML report support in cmdlineTests.sh.
+tests_to_run_in_parallel = [
+    '~ast_import_export',                   # ~7 min
+    '~ast_export_with_stop_after_parsing',  # ~4 min
+    '~soljson_via_fuzzer',                  # ~3 min
+    '~via_ir_equivalence',                  # ~1 min
+    '~compilation_tests',                   # ~1 min
+    '~documentation_examples',              # ~1 min
+    '*',                                    # This item represents all the remaining tests
+]
+
+# Ask CircleCI to select a subset of tests for this parallel execution.
+# If `parallelism` in CI config is set correctly, we should get just one but we can handle any split.
+selected_tests = subprocess.check_output(
+    ['circleci', 'tests', 'split'],
+    input='\n'.join(tests_to_run_in_parallel),
+    encoding='ascii',
+).strip().split('\n')
+selected_tests = set(selected_tests) - {''}
+excluded_tests = set(tests_to_run_in_parallel) - selected_tests
+assert selected_tests.issubset(set(tests_to_run_in_parallel))
+
+if len(selected_tests) == 0:
+    print("No tests to run.")
+    sys.exit(0)
+
+if '*' in selected_tests:
+    filters = [arg for test_name in excluded_tests for arg in ['--exclude', test_name]]
+else:
+    filters = list(selected_tests)
+
+subprocess.run(
+    ['test/cmdlineTests.sh'] + filters,
+    stdin=sys.stdin,
+    stdout=sys.stdout,
+    stderr=sys.stderr,
+    check=True,
+)

.circleci/soltest.sh

@@ -36,6 +36,7 @@ set -e
 
 OPTIMIZE=${OPTIMIZE:-"0"}
 EVM=${EVM:-"invalid"}
+CPUs=${CPUs:-3}
 REPODIR="$(realpath "$(dirname "$0")/..")"
 
 IFS=" " read -r -a BOOST_TEST_ARGS <<< "$BOOST_TEST_ARGS"
@@ -67,7 +68,6 @@ get_logfile_basename() {
 # long-running test cases are next to each other.
 CIRCLE_NODE_INDEX=$(((CIRCLE_NODE_INDEX + 23 * INDEX_SHIFT) % CIRCLE_NODE_TOTAL))
 
-CPUs=3
 PIDs=()
 for run in $(seq 0 $((CPUs - 1)))
 do
@@ -92,7 +92,7 @@ do
 done
 
 # wait for individual processes to get their exit status
-for pid in ${PIDs[*]}
+for pid in "${PIDs[@]}"
 do
     wait "$pid"
 done

.circleci/soltest_all.sh

@@ -31,8 +31,8 @@ REPODIR="$(realpath "$(dirname "$0")"/..)"
 # shellcheck source=scripts/common.sh
 source "${REPODIR}/scripts/common.sh"
 
-EVM_VALUES=(homestead byzantium constantinople petersburg istanbul berlin london)
-DEFAULT_EVM=london
+EVM_VALUES=(homestead byzantium constantinople petersburg istanbul berlin london paris shanghai)
+DEFAULT_EVM=shanghai
 [[ " ${EVM_VALUES[*]} " =~ $DEFAULT_EVM ]]
 OPTIMIZE_VALUES=(0 1)
 
@@ -50,9 +50,6 @@ for OPTIMIZE in "${OPTIMIZE_VALUES[@]}"
 do
     for EVM in "${EVM_VALUES[@]}"
     do
-        # run tests against hera ewasm evmc vm, only if OPTIMIZE == 0 and evm version is byzantium
-        EWASM_ARGS=""
-        [ "${EVM}" = "byzantium" ] && [ "${OPTIMIZE}" = "0" ] && EWASM_ARGS="--ewasm"
         ENFORCE_GAS_ARGS=""
         [ "${EVM}" = "${DEFAULT_EVM}" ] && ENFORCE_GAS_ARGS="--enforce-gas-cost"
         # Run SMTChecker tests only when OPTIMIZE == 0
@@ -61,11 +58,11 @@ do
 
         EVM="$EVM" \
         OPTIMIZE="$OPTIMIZE" \
-        SOLTEST_FLAGS="$SOLTEST_FLAGS $ENFORCE_GAS_ARGS $EWASM_ARGS" \
+        SOLTEST_FLAGS="$SOLTEST_FLAGS $ENFORCE_GAS_ARGS" \
         BOOST_TEST_ARGS="-t !@nooptions $DISABLE_SMTCHECKER" \
         INDEX_SHIFT="$INDEX_SHIFT" \
         "${REPODIR}/.circleci/soltest.sh"
 
         INDEX_SHIFT=$((INDEX_SHIFT + 1))
     done
-done
+done

.clang-format

@@ -12,7 +12,7 @@ Language: Cpp
 BasedOnStyle: LLVM
 AccessModifierOffset: -4
 AlignAfterOpenBracket: AlwaysBreak
-AlignEscapedNewlinesLeft: true
+AlignEscapedNewlines: Left
 AlwaysBreakAfterReturnType: None
 AlwaysBreakTemplateDeclarations: Yes
 BinPackArguments: false

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,5 +1,10 @@
 ---
 name: Bug Report
+about: Problems, deficiencies, inaccuracies or crashes discovered on Solidity.
+title: ''
+labels: 'bug :bug:'
+assignees: ''
+
 ---
 
 <!--## Prerequisites
@@ -31,7 +36,7 @@ name: Bug Report
 
 <!--
 Please provide a *minimal* source code example to trigger the bug you have found.
-Please also mention any command line flags that are necessary for triggering the bug.
+Please also mention any command-line flags that are necessary for triggering the bug.
 Provide as much information as necessary to reproduce the bug.
 
 ```solidity

.github/ISSUE_TEMPLATE/config.yml

@@ -1,14 +1,5 @@
 blank_issues_enabled: false
 contact_links:
-  - name: Bug Report
-    url: https://github.com/ethereum/solidity/issues/new?template=bug_report.md&projects=ethereum/solidity/43&labels=bug+%3Abug%3A
-    about: Bug reports about the Solidity Compiler.
-  - name: Documentation Issue
-    url: https://github.com/ethereum/solidity/issues/new?template=documentation_issue.md&projects=ethereum/solidity/43&labels=documentation+%3Abook%3A
-    about: Solidity documentation.
-  - name: Feature Request
-    url: https://github.com/ethereum/solidity/issues/new?template=feature_request.md&projects=ethereum/solidity/43&labels=feature
-    about: Solidity language or infrastructure feature requests.
-  - name: Report a security vulnerability
-    url: https://github.com/ethereum/solidity/security/policy
-    about: Please review our security policy for more details.
+  - name: Initiate a language design or feedback discussion
+    url: https://forum.soliditylang.org
+    about: Open a thread on the Solidity forum.

.github/ISSUE_TEMPLATE/documentation_issue.md

@@ -1,5 +1,10 @@
 ---
 name: Documentation Issue
+about: Corrections, improvements or requests for new content on Solidity's documentation.
+title: ''
+labels: 'documentation :book:'
+assignees: ''
+
 ---
 
 ## Page

.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,5 +1,11 @@
 ---
 name: Feature Request
+about: Ideas, comments or messages asking for a particular functionality to be added
+  to Solidity.
+title: ''
+labels: feature
+assignees: ''
+
 ---
 
 <!--## Prerequisites
@@ -10,6 +16,8 @@ name: Feature Request
     - [Solidity chat](https://gitter.im/ethereum/solidity)
     - [Stack Overflow](https://ethereum.stackexchange.com/)
 - Ensure the issue isn't already reported (check `feature` and `language design` labels).
+- If you feel uncertain about your feature request, perhaps it's better to open a language design or feedback forum thread via the issue selector, or by going to the forum directly.
+    - [Solidity forum](https://forum.soliditylang.org/)
 
 *Delete the above section and the instructions in the sections below before submitting*
 -->

.github/workflows/buildpack-deps.yml

@@ -5,9 +5,10 @@ on:
     branches: [ develop ]
     paths:
       - 'scripts/docker/buildpack-deps/Dockerfile.emscripten'
-      - 'scripts/docker/buildpack-deps/Dockerfile.ubuntu1604.clang.ossfuzz'
-      - 'scripts/docker/buildpack-deps/Dockerfile.ubuntu2004.clang'
+      - 'scripts/docker/buildpack-deps/Dockerfile.ubuntu.clang.ossfuzz'
       - 'scripts/docker/buildpack-deps/Dockerfile.ubuntu2004'
+      - 'scripts/docker/buildpack-deps/Dockerfile.ubuntu2204.clang'
+      - 'scripts/docker/buildpack-deps/Dockerfile.ubuntu2204'
 
 jobs:
   buildpack-deps:
@@ -22,7 +23,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        image_variant: [emscripten, ubuntu1604.clang.ossfuzz, ubuntu2004.clang, ubuntu2004]
+        image_variant: [emscripten, ubuntu.clang.ossfuzz, ubuntu2004, ubuntu2204.clang, ubuntu2204]
 
     steps:
       - uses: actions/checkout@v2
@@ -37,6 +38,9 @@ jobs:
 
       - name: comment PR
         if: "env.DOCKER_IMAGE"
-        uses: aarlt/comment-on-pr@v1.2.0
+        # NOTE: Can't update to v1.3.1 due to an error: `/entrypoint.sh:5:in 'require_relative': cannot load such file -- /lib/github (LoadError)`
+        uses: unsplash/comment-on-pr@ffe8f97ccc63ce12c3c23c6885b169db67958d3b #v1.3.0
         with:
-          msg: "`${{ env.DOCKER_IMAGE }} ${{ env.DOCKER_REPO_DIGEST }}`."
+          msg: "`${{ env.DOCKER_IMAGE }} ${{ env.DOCKER_REPO_DIGEST }}`."
+          check_for_duplicate_msg: false
+

.github/workflows/stale.yml

@@ -0,0 +1,51 @@
+name: Check stale issues and pull requests
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '0 12 * * *'
+
+permissions:
+  issues: write
+  pull-requests: write
+
+env:
+  BEFORE_ISSUE_STALE: 90
+  BEFORE_ISSUE_CLOSE: 7
+  BEFORE_PR_STALE: 14
+  BEFORE_PR_CLOSE: 7
+
+jobs:
+  stale:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/stale@v6
+        with:
+          debug-only: false
+          days-before-issue-stale: ${{ env.BEFORE_ISSUE_STALE }}
+          days-before-issue-close: ${{ env.BEFORE_ISSUE_CLOSE }}
+          stale-issue-message: |
+            This issue has been marked as stale due to inactivity for the last ${{ env.BEFORE_ISSUE_STALE }} days.
+            It will be automatically closed in ${{ env.BEFORE_ISSUE_CLOSE }} days.
+          close-issue-message: |
+            Hi everyone! This issue has been automatically closed due to inactivity.
+            If you think this issue is still relevant in the latest Solidity version and you have something to [contribute](https://docs.soliditylang.org/en/latest/contributing.html), feel free to reopen.
+            However, unless the issue is a concrete proposal that can be implemented, we recommend starting a language discussion on the [forum](https://forum.soliditylang.org) instead.
+          ascending: true
+          stale-issue-label: stale
+          close-issue-label: 'closed due inactivity'
+          exempt-issue-labels: 'bug :bug:,epic,roadmap,selected for development,must have,must have eventually,smt'
+          stale-pr-message: |
+            This pull request is stale because it has been open for ${{ env.BEFORE_PR_STALE }} days with no activity.
+            It will be closed in ${{ env.BEFORE_PR_CLOSE }} days unless the `stale` label is removed.
+          close-pr-message: |
+            This pull request was closed due to a lack of activity for ${{ env.BEFORE_PR_CLOSE }} days after it was stale.
+          stale-pr-label: stale
+          close-pr-label: closed-due-inactivity
+          days-before-pr-stale: ${{ env.BEFORE_PR_STALE }}
+          days-before-pr-close: ${{ env.BEFORE_PR_CLOSE }}
+          exempt-pr-labels: 'external contribution :star:,roadmap,epic'
+          exempt-draft-pr: false
+          exempt-all-milestones: true
+          remove-stale-when-updated: true
+          operations-per-run: 256

.github/workflows/welcome-external-pr.yml

@@ -0,0 +1,37 @@
+name: External contributor greeter
+
+on:
+  pull_request_target:
+    types:
+      - opened
+
+env:
+  DRY_RUN: false
+
+jobs:
+  comment-external-pr:
+    runs-on: ubuntu-latest
+    steps:
+      # Note: this step requires that the INTERNAL_CONTRIBUTORS environment variable
+      # is already defined in the repository with the current json list of internal contributors.
+      - name: Comment on external contribution PR
+        if: "!contains(fromJSON(vars.INTERNAL_CONTRIBUTORS), github.event.pull_request.user.login)"
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR: ${{ github.event.pull_request.html_url }}
+        run: |
+          echo "Commenting in a newly submitted or reopened external PR: $PR"
+          if [[ $DRY_RUN == 'false' ]]; then
+            gh pr edit "$PR" --add-label "external contribution :star:"
+            comment_body=(
+              "Thank you for your contribution to the Solidity compiler! A team member will follow up shortly."
+              "\n\n"
+              "If you haven't read our [contributing guidelines](https://docs.soliditylang.org/en/latest/contributing.html) and our "
+              "[review checklist](https://github.com/ethereum/solidity/blob/develop/ReviewChecklist.md) before, "
+              "please do it now, this makes the reviewing process and accepting your contribution smoother."
+              "\n\n"
+              "If you have any questions or need our help, feel free to post them in the PR or talk to us directly on the "
+              "[#solidity-dev](https://matrix.to/#/#ethereum_solidity-dev:gitter.im) channel on Matrix."
+            )
+            gh pr comment $PR --body "$(IFS='' ; echo -e "${comment_body[*]}")"
+          fi

.gitignore

@@ -1,11 +1,16 @@
-commit_hash.txt
-prerelease.txt
+/commit_hash.txt
+/prerelease.txt
+
+# Auth config for ppa release
+/.release_ppa_auth
 
 # Compiled Object files
 *.slo
 *.lo
 *.o
 *.obj
+*.pyc
+__pycache__
 
 # Precompiled Headers
 *.gch
@@ -16,15 +21,15 @@ prerelease.txt
 *.dylib
 *.dll
 
-# Fortran module files
-*.mod
-
 # Compiled Static libraries
 *.lai
 *.la
 *.a
 *.lib
 
+# ignore git mergetool backup files
+*.orig
+
 # Executables
 *.exe
 *.out
@@ -33,14 +38,10 @@ prerelease.txt
 # Build directory
 /build*
 emscripten_build/
-docs/_build
-docs/_static/robots.txt
-__pycache__
-docs/utils/*.pyc
-/deps/downloads/
-deps/install
-deps/cache
-cmake-build-*/
+/docs/_build
+/docs/_static/robots.txt
+/deps
+/reports
 
 # vim stuff
 [._]*.sw[a-p]
@@ -50,18 +51,15 @@ cmake-build-*/
 *~
 
 # IDE files
-.idea
-.vscode
-browse.VC.db
-CMakeLists.txt.user
+/.idea/
+/.vscode/
+/browse.VC.db
+/CMakeLists.txt.user
 /CMakeSettings.json
 /.vs
 /.cproject
 /.project
 
-# place to put local temporary files
-tmp
-
 # OS specific local files
 .DS_Store
 Thumbs.db

.readthedocs.yml

@@ -0,0 +1,18 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+sphinx:
+  builder: html
+  configuration: docs/conf.py
+
+formats:
+  - pdf
+  - epub
+
+python:
+  install:
+    - requirements: docs/requirements.txt

CMakeLists.txt

@@ -1,11 +1,11 @@
 cmake_minimum_required(VERSION 3.13.0)
 
-set(ETH_CMAKE_DIR   "${CMAKE_CURRENT_LIST_DIR}/cmake"   CACHE PATH "The the path to the cmake directory")
+set(ETH_CMAKE_DIR   "${CMAKE_CURRENT_LIST_DIR}/cmake"   CACHE PATH "The path to the cmake directory")
 list(APPEND CMAKE_MODULE_PATH ${ETH_CMAKE_DIR})
 
 # Set the build type, if none was specified.
 if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
-	if(EXISTS "${CMAKE_SOURCE_DIR}/.git")
+	if(EXISTS "${PROJECT_SOURCE_DIR}/.git")
 		set(DEFAULT_BUILD_TYPE "RelWithDebInfo")
 	else()
 		set(DEFAULT_BUILD_TYPE "Release")
@@ -21,7 +21,7 @@ include(EthPolicy)
 eth_policy()
 
 # project name and version should be set after cmake_policy CMP0048
-set(PROJECT_VERSION "0.8.16")
+set(PROJECT_VERSION "0.8.22")
 # OSX target needed in order to support std::visit
 set(CMAKE_OSX_DEPLOYMENT_TARGET "10.14")
 project(solidity VERSION ${PROJECT_VERSION} LANGUAGES C CXX)
@@ -35,6 +35,8 @@ 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(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)
 
 # Setup cccache.
 include(EthCcache)
@@ -48,6 +50,14 @@ include_directories(SYSTEM ${JSONCPP_INCLUDE_DIR})
 
 find_package(Threads)
 
+if(NOT PEDANTIC)
+  message(WARNING "-- Pedantic build flags turned off. Warnings will not make compilation fail. This is NOT recommended in development builds.")
+endif()
+
+if (PROFILE_OPTIMIZER_STEPS)
+    add_definitions(-DPROFILE_OPTIMIZER_STEPS)
+endif()
+
 # Figure out what compiler and system are we using
 include(EthCompilerSettings)
 
@@ -56,17 +66,17 @@ include(EthUtils)
 
 # Create license.h from LICENSE.txt and template
 # Converting to char array is required due to MSVC's string size limit.
-file(READ ${CMAKE_SOURCE_DIR}/LICENSE.txt LICENSE_TEXT HEX)
+file(READ ${PROJECT_SOURCE_DIR}/LICENSE.txt LICENSE_TEXT HEX)
 string(REGEX MATCHALL ".." LICENSE_TEXT "${LICENSE_TEXT}")
 string(REGEX REPLACE ";" ",\n\t0x" LICENSE_TEXT "${LICENSE_TEXT}")
 set(LICENSE_TEXT "0x${LICENSE_TEXT}")
 
-configure_file("${CMAKE_SOURCE_DIR}/cmake/templates/license.h.in" include/license.h)
+configure_file("${PROJECT_SOURCE_DIR}/cmake/templates/license.h.in" include/license.h)
 
 include(EthOptions)
 configure_project(TESTS)
-set(LATEST_Z3_VERSION "4.8.17")
-set(MINIMUM_Z3_VERSION "4.8.0")
+set(LATEST_Z3_VERSION "4.12.1")
+set(MINIMUM_Z3_VERSION "4.8.16")
 find_package(Z3)
 if (${Z3_FOUND})
   if (${STRICT_Z3_VERSION})
@@ -130,6 +140,7 @@ add_subdirectory(libevmasm)
 add_subdirectory(libyul)
 add_subdirectory(libsolidity)
 add_subdirectory(libsolc)
+add_subdirectory(libstdlib)
 add_subdirectory(tools)
 
 if (NOT EMSCRIPTEN)

CODE_OF_CONDUCT.md

@@ -55,10 +55,8 @@ further defined and clarified by project maintainers.
 ## Enforcement
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting the project team at chris@ethereum.org which only goes to
-Christian Reitwiessner or axic@ethereum.org which only goes to Alex Beregszaszi.
-To report an issue involving either of them please email Hudson Jameson at
-hudson@ethereum.org.
+reported by contacting the project team at solidity@ethereum.org.
+To report an issue involving the Solidity team please email José Pedro Cabrita at zepedro@ethereum.org.
 All complaints will be reviewed and investigated and will result in a response that
 is deemed necessary and appropriate to the circumstances. The project team is
 obligated to maintain confidentiality with regard to the reporter of an incident.

CODING_STYLE.md

@@ -51,10 +51,11 @@ To set indentation and tab width settings uniformly, the repository contains an
 ## 1. Namespaces
 
 1. No `using namespace` declarations in header files.
-2. Use `using namespace std;` in cpp files, but avoid importing namespaces from boost and others.
-3. All symbols should be declared in a namespace except for final applications.
-4. Use anonymous namespaces for helpers whose scope is a cpp file only.
-5. Preprocessor symbols should be prefixed with the namespace in all-caps and an underscore.
+2. `using namespace solidity;` and other project local namespaces is fine in cpp files, and generally encouraged.
+3. Avoid `using namespace` at file level for third party libraries, such as boost, ranges, etc.
+4. All symbols should be declared in a namespace except for final applications.
+5. Use anonymous namespaces for helpers whose scope is a cpp file only.
+6. Preprocessor symbols should be prefixed with the namespace in all-caps and an underscore.
 
 Only in the header:
 ```cpp
@@ -65,16 +66,6 @@ std::tuple<float, float> meanAndSigma(std::vector<float> const& _v);
 }
 ```
 
-Only in the cpp file:
-```cpp
-#include <cassert>
-using namespace std;
-tuple<float, float> myNamespace::meanAndSigma(vector<float> const& _v)
-{
-  // ...
-}
-```
-
 ## 2. Preprocessor
 
 1. File comment is always at top, and includes:
@@ -116,7 +107,7 @@ Use `solAssert` and `solUnimplementedAssert` generously to check assumptions tha
 1. {Typename} + {qualifiers} + {name}.
 2. Only one per line.
 3. Associate */& with type, not variable (at ends with parser, but more readable, and safe if in conjunction with (b)).
-4. Favour declarations close to use; don't habitually declare at top of scope ala C.
+4. Favour declarations close to use; do not habitually declare at top of scope ala C.
 5. Pass non-trivial parameters as const reference, unless the data is to be copied into the function, then either pass by const reference or by value and use std::move.
 6. If a function returns multiple values, use std::tuple (std::pair acceptable) or better introduce a struct type. Do not use */& arguments.
 7. Use parameters of pointer type only if ``nullptr`` is a valid argument, use references otherwise. Often, ``std::optional`` is better suited than a raw pointer.
@@ -179,7 +170,7 @@ for (map<ComplexTypeOne, ComplexTypeTwo>::iterator i = l.begin(); i != l.end();
 
 ## 9. Naming
 
-1. Avoid unpronouncable names.
+1. Avoid unpronounceable names.
 2. Names should be shortened only if they are extremely common, but shortening should be generally avoided
 3. Avoid prefixes of initials (e.g. do not use `IMyInterface`, `CMyImplementation`)
 4. Find short, memorable & (at least semi-) descriptive names for commonly used classes or name-fragments:

Changelog.md

@@ -1,3 +1,185 @@
+### 0.8.22 (unreleased)
+
+Language Features:
+ * Allow defining events at file level.
+
+
+Compiler Features:
+ * Parser: Remove the experimental error recovery mode (``--error-recovery`` / ``settings.parserErrorRecovery``).
+ * Yul Optimizer: If ``PUSH0`` is supported, favor zero literals over storing zero values in variables.
+ * Yul Optimizer: Run the ``Rematerializer`` and ``UnusedPruner`` steps at the end of the default clean-up sequence.
+
+
+Bugfixes:
+ * AST: Fix wrong initial ID for Yul nodes in the AST.
+ * Code Generator: Fix output from via-IR code generator being dependent on which files were discovered by import callback. In some cases, a different AST ID assignment would alter the order of functions in internal dispatch, resulting in superficially different but semantically equivalent bytecode.
+ * NatSpec: Fix internal error when requesting userdoc or devdoc for a contract that emits an event defined in a foreign contract or interface.
+ * SMTChecker: Fix encoding error that causes loops to unroll after completion.
+ * SMTChecker: Fix inconsistency on constant condition checks when ``while`` or ``for`` loops are unrolled before the condition check.
+
+
+### 0.8.21 (2023-07-19)
+
+Important Bugfixes:
+ * Code Generator: Always generate code for the expression in ``<expression>.selector`` in the legacy code generation pipeline.
+ * Yul Optimizer: Fix ``FullInliner`` step (``i``) not preserving the evaluation order of arguments passed into inlined functions in code that is not in expression-split form (i.e. when using a custom optimizer sequence in which the step not preceded by ``ExpressionSplitter`` (``x``)).
+
+
+Language Features:
+ * Allow qualified access to events from other contracts.
+ * Relax restrictions on initialization of immutable variables. Reads and writes may now happen at any point at construction time outside of functions and modifiers. Explicit initialization is no longer mandatory.
+
+
+Compiler Features:
+ * Commandline Interface: Add ``--ast-compact-json`` output in assembler mode.
+ * Commandline Interface: Add ``--ir-ast-json`` and ``--ir-optimized-ast-json`` outputs for Solidity input, providing AST in compact JSON format for IR and optimized IR.
+ * Commandline Interface: Respect ``--optimize-yul`` and ``--no-optimize-yul`` in compiler mode and accept them in assembler mode as well. ``--optimize --no-optimize-yul`` combination now allows enabling EVM assembly optimizer without enabling Yul optimizer.
+ * EWasm: Remove EWasm backend.
+ * Parser: Introduce ``pragma experimental solidity``, which will enable an experimental language mode that in particular has no stability guarantees between non-breaking releases and is not suited for production use.
+ * SMTChecker: Add ``--model-checker-print-query`` CLI option and ``settings.modelChecker.printQuery`` JSON option to output the SMTChecker queries in the SMTLIB2 format. This requires using ``smtlib2`` solver only.
+ * Standard JSON Interface: Add ``ast`` file-level output for Yul input.
+ * Standard JSON Interface: Add ``irAst`` and ``irOptimizedAst`` contract-level outputs for Solidity input, providing AST in compact JSON format for IR and optimized IR.
+ * Yul Optimizer: Remove experimental ``ReasoningBasedSimplifier`` optimization step.
+ * Yul Optimizer: Stack-to-memory mover is now enabled by default whenever possible for via IR code generation and pure Yul compilation.
+
+
+Bugfixes:
+ * Code Generator: Disallow complex expressions whose results are types, built-ins, modules or some unassignable functions. The legacy code generation pipeline would not actually evaluate them, discarding any side-effects they might have.
+ * Code Generator: Fix not entirely deterministic order of functions in unoptimized Yul output. The choice of C++ compiler in some cases would result in different (but equivalent) bytecode (especially from native binaries vs emscripten binaries).
+ * Commandline Interface: Fix internal error when using ``--stop-after parsing`` and requesting some of the outputs that require full analysis or compilation.
+ * Commandline Interface: It is no longer possible to specify both ``--optimize-yul`` and ``--no-optimize-yul`` at the same time.
+ * SMTChecker: Fix encoding of side-effects inside ``if`` and ``ternary conditional``statements in the BMC engine.
+ * SMTChecker: Fix false negative when a verification target can be violated only by trusted external call from another public function.
+ * SMTChecker: Fix generation of invalid SMT-LIB2 scripts in BMC engine with trusted mode for external calls when CHC engine times out.
+ * SMTChecker: Fix internal error caused by incorrectly classifying external function call using function pointer as a public getter.
+ * SMTChecker: Fix internal error caused by using external identifier to encode member access to functions that take an internal function as a parameter.
+ * Standard JSON Interface: Fix an incomplete AST being returned when analysis is interrupted by certain kinds of fatal errors.
+ * Type Checker: Disallow using certain unassignable function types in complex expressions.
+ * Type Checker: Function declaration types referring to different declarations are no longer convertible to each other.
+ * Yul Optimizer: Ensure that the assignment of memory slots for variables moved to memory does not depend on AST IDs that may depend on whether additional files are included during compilation.
+ * Yul Optimizer: Fix ``FullInliner`` step not ignoring code that is not in expression-split form.
+ * Yul Optimizer: Fix optimized IR being unnecessarily passed through the Yul optimizer again before bytecode generation.
+
+
+AST Changes:
+ * AST: Add the ``experimentalSolidity`` field to the ``SourceUnit`` nodes, which indicate whether the experimental parsing mode has been enabled via ``pragma experimental solidity``.
+
+
+### 0.8.20 (2023-05-10)
+
+Compiler Features:
+ * Assembler: Use ``push0`` for placing ``0`` on the stack for EVM versions starting from "Shanghai". This decreases the deployment and runtime costs.
+ * EVM: Set default EVM version to "Shanghai".
+ * EVM: Support for the EVM Version "Shanghai".
+ * NatSpec: Add support for NatSpec documentation in ``enum`` definitions.
+ * NatSpec: Add support for NatSpec documentation in ``struct`` definitions.
+ * NatSpec: Include NatSpec from events that are emitted by a contract but defined outside of it in userdoc and devdoc output.
+ * Optimizer: Re-implement simplified version of ``UnusedAssignEliminator`` and ``UnusedStoreEliminator``. It can correctly remove some unused assignments in deeply nested loops that were ignored by the old version.
+ * Parser: Unary plus is no longer recognized as a unary operator in the AST and triggers an error at the parsing stage (rather than later during the analysis).
+ * SMTChecker: Add CLI option ``--model-checker-bmc-loop-iterations`` and a JSON option ``settings.modelChecker.bmcLoopIterations`` that specify how many loop iterations the BMC engine should unroll. Note that false negatives are possible when unrolling loops. This is due to the possibility that bmc loop iteration setting is less than actual number of iterations needed to complete a loop.
+ * SMTChecker: Group all messages about unsupported language features in a single warning. The CLI option ``--model-checker-show-unsupported`` and the JSON option ``settings.modelChecker.showUnsupported`` can be enabled to show the full list.
+ * SMTChecker: Properties that are proved safe are now reported explicitly at the end of analysis. By default, only the number of safe properties is shown. The CLI option ``--model-checker-show-proved-safe`` and the JSON option ``settings.modelChecker.showProvedSafe`` can be enabled to show the full list of safe properties.
+ * Standard JSON Interface: Add experimental support for importing ASTs via Standard JSON.
+ * Yul EVM Code Transform: If available, use ``push0`` instead of ``codesize`` to produce an arbitrary value on stack in order to create equal stack heights between branches.
+
+
+Bugfixes:
+ * ABI: Include events in the ABI that are emitted by a contract but defined outside of it.
+ * Immutables: Disallow initialization of immutables in try/catch statements.
+ * SMTChecker: Fix false positives in ternary operators that contain verification targets in its branches, directly or indirectly.
+
+
+AST Changes:
+ * AST: Add the ``internalFunctionIDs`` field to the AST nodes of contracts containing IDs of functions that may be called via the internal dispatch. The field is a map from function AST IDs to internal dispatch function IDs. These IDs are always generated, but they are only used in via-IR code generation.
+ * AST: Add the ``usedEvents`` field to ``ContractDefinition`` which contains the AST IDs of all events emitted by the contract as well as all events defined and inherited by the contract.
+
+
+### 0.8.19 (2023-02-22)
+
+Language Features:
+ * Allow defining custom operators for user-defined value types via ``using {f as +} for T global`` syntax.
+
+
+Compiler Features:
+ * SMTChecker: New trusted mode that assumes that any compile-time available code is the actual used code even in external calls. This can be used via the CLI option ``--model-checker-ext-calls trusted`` or the JSON field ``settings.modelChecker.extCalls: "trusted"``.
+
+
+Bugfixes:
+ * Assembler: Avoid duplicating subassembly bytecode where possible.
+ * Code Generator: Avoid including references to the deployed label of referenced functions if they are called right away.
+ * ContractLevelChecker: Properly distinguish the case of missing base constructor arguments from having an unimplemented base function.
+ * SMTChecker: Fix internal error caused by unhandled ``z3`` expressions that come from the solver when bitwise operators are used.
+ * SMTChecker: Fix internal error when using the custom NatSpec annotation to abstract free functions.
+ * TypeChecker: Also allow external library functions in ``using for``.
+
+
+AST Changes:
+ * AST: Add ``function`` field to ``UnaryOperation`` and ``BinaryOperation`` AST nodes. ``functionList`` in ``UsingForDirective`` AST nodes will now contain ``operator`` and ``definition`` members instead of ``function`` when the list entry defines an operator.
+
+
+### 0.8.18 (2023-02-01)
+
+Language Features:
+ * Allow named parameters in mapping types.
+
+
+Compiler Features:
+ * Commandline Interface: Add ``--no-cbor-metadata`` that skips CBOR metadata from getting appended at the end of the bytecode.
+ * Commandline Interface: Return exit code ``2`` on uncaught exceptions.
+ * EVM: Deprecate ``block.difficulty`` and disallow ``difficulty()`` in inline assembly for EVM versions >= paris. The change is due to the renaming introduced by [EIP-4399](https://eips.ethereum.org/EIPS/eip-4399).
+ * EVM: Introduce ``block.prevrandao`` in Solidity and ``prevrandao()`` in inline assembly for EVM versions >= paris.
+ * EVM: Set the default EVM version to "Paris".
+ * EVM: Support for the EVM version "Paris".
+ * Language Server: Add basic document hover support.
+ * Natspec: Add event Natspec inheritance for devdoc.
+ * Optimizer: Added optimization rule ``and(shl(X, Y), shl(X, Z)) => shl(X, and(Y, Z))``.
+ * Parser: More detailed error messages about invalid version pragmas.
+ * SMTChecker: Make ``z3`` the default solver for the BMC and CHC engines instead of all solvers.
+ * SMTChecker: Support Eldarica as a Horn solver for the CHC engine when using the CLI option ``--model-checker-solvers eld``. The binary ``eld`` must be available in the system.
+ * Solidity Upgrade Tool: Remove ``solidity-upgrade`` tool.
+ * Standard JSON: Add a boolean field ``settings.metadata.appendCBOR`` that skips CBOR metadata from getting appended at the end of the bytecode.
+ * TypeChecker: Warn when using deprecated builtin ``selfdestruct``.
+ * Yul EVM Code Transform: Generate more optimal code for user-defined functions that always terminate a transaction. No return labels will be pushed for calls to functions that always terminate.
+ * Yul Optimizer: Allow replacing the previously hard-coded cleanup sequence by specifying custom steps after a colon delimiter (``:``) in the sequence string.
+ * Yul Optimizer: Eliminate ``keccak256`` calls if the value was already calculated by a previous call and can be reused.
+
+
+Bugfixes:
+ * Parser: Disallow several ``indexed`` attributes for the same event parameter.
+ * Parser: Disallow usage of the ``indexed`` attribute for modifier parameters.
+ * SMTChecker: Fix display error for negative integers that are one more than powers of two.
+ * SMTChecker: Fix internal error on chain assignments using static fully specified state variables.
+ * SMTChecker: Fix internal error on multiple wrong SMTChecker natspec entries.
+ * SMTChecker: Fix internal error when a public library function is called internally.
+ * SMTChecker: Fix internal error when deleting struct member of function type.
+ * SMTChecker: Fix internal error when using user-defined types as mapping indices or struct members.
+ * SMTChecker: Improved readability for large integers that are powers of two or almost powers of two in error messages.
+ * TypeChecker: Fix bug where private library functions could be attached with ``using for`` outside of their declaration scope.
+ * Yul Optimizer: Hash hex and decimal literals according to their value instead of their representation, improving the detection of equivalent functions.
+
+
+### 0.8.17 (2022-09-08)
+
+Important Bugfixes:
+ * Yul Optimizer: Prevent the incorrect removal of storage writes before calls to Yul functions that conditionally terminate the external EVM call.
+
+
+Compiler Features:
+ * Code Generator: More efficient overflow checks for multiplication.
+ * Language Server: Analyze all files in a project by default (can be customized by setting ``'file-load-strategy'`` to ``'directly-opened-and-on-import'`` in LSP settings object).
+ * Yul Optimizer: Simplify the starting offset of zero-length operations to zero.
+
+
+Bugfixes:
+ * Type Checker: Fix internal compiler error on tuple assignments with invalid left-hand side.
+ * Yul IR Code Generation: Fix internal compiler error when accessing the ``.slot`` member of a mapping through a storage reference in inline assembly.
+
+
+Build System:
+ * Allow disabling pedantic warnings and do not treat warnings as errors during compiler build when ``-DPEDANTIC=OFF`` flag is passed to CMake.
+ * Update emscripten to version 3.1.19.
+
+
 ### 0.8.16 (2022-08-08)
 
 Important Bugfixes:

README.md

@@ -27,11 +27,11 @@ For a good overview and starting point, please check out the official [Solidity
 
 Solidity is a statically-typed curly-braces programming language designed for developing smart contracts
 that run on the Ethereum Virtual Machine. Smart contracts are programs that are executed inside a peer-to-peer
-network where nobody has special authority over the execution, and thus they allow to implement tokens of value,
+network where nobody has special authority over the execution, and thus they allow anyone to implement tokens of value,
 ownership, voting, and other kinds of logic.
 
 When deploying contracts, you should use the latest released version of
-Solidity. This is because breaking changes, as well as new features and bug fixes are
+Solidity. This is because breaking changes, as well as new features and bug fixes, are
 introduced regularly. We currently use a 0.x version
 number [to indicate this fast pace of change](https://semver.org/#spec-item-4).
 
@@ -66,7 +66,7 @@ browser-based IDE. Here are some example contracts:
 
 ## Documentation
 
-The Solidity documentation is hosted at [Read the docs](https://docs.soliditylang.org).
+The Solidity documentation is hosted using [Read the Docs](https://docs.soliditylang.org).
 
 ## Development
 
@@ -79,8 +79,8 @@ You can find our current feature and bug priorities for forthcoming
 releases in the [projects section](https://github.com/ethereum/solidity/projects).
 
 ## Maintainers
-* [@axic](https://github.com/axic)
-* [@chriseth](https://github.com/chriseth)
+The Solidity programming language and compiler are open-source community projects governed by a core team.
+The core team is sponsored by the [Ethereum Foundation](https://ethereum.foundation/).
 
 ## License
 Solidity is licensed under [GNU General Public License v3.0](LICENSE.txt).

ReleaseChecklist.md

@@ -1,29 +1,63 @@
 ## Checklist for making a release:
 
 ### Requirements
- - [ ] Lauchpad (Ubuntu One) account
- - [ ] gnupg key (has to be version 1, gpg2 won't work) for `your-name@ethereum.org` created and uploaded
- - [ ] Readthedocs account, access to the Solidity project
- - [ ] Write access to https://github.com/ethereum/homebrew-ethereum
+ - [ ] GitHub account with access to [solidity](https://github.com/ethereum/solidity), [solc-js](https://github.com/ethereum/solc-js),
+       [solc-bin](https://github.com/ethereum/solc-bin), [homebrew-ethereum](https://github.com/ethereum/homebrew-ethereum),
+       [solidity-website](https://github.com/ethereum/solidity-website).
+ - [ ] DockerHub account with push rights to the [``solc`` image](https://hub.docker.com/r/ethereum/solc).
+ - [ ] Launchpad (Ubuntu One) account with a membership in the ["Ethereum" team](https://launchpad.net/~ethereum) and
+       a gnupg key for your email in the ``ethereum.org`` domain (has to be version 1, gpg2 won't work).
+ - [ ] Ubuntu/Debian dependencies of the PPA scripts: ``devscripts``, ``debhelper``, ``dput``, ``git``, ``wget``, ``ca-certificates``.
+ - [ ] [npm Registry](https://www.npmjs.com) account added as a collaborator for the [``solc`` package](https://www.npmjs.com/package/solc).
+ - [ ] Access to the [solidity_lang Twitter account](https://twitter.com/solidity_lang).
+ - [ ] [Reddit](https://www.reddit.com) account that is at least 10 days old with a minimum of 20 comment karma (``/r/ethereum`` requirements).
 
-### Documentation check
- - [ ] Run `make linkcheck` from within `docs/` and fix any broken links it finds. Ignore false positives caused by `href` anchors and dummy links not meant to work.
+### Pre-flight checks
+At least a day before the release:
+ - [ ] Run ``make linkcheck`` from within ``docs/`` and fix any broken links it finds.
+       Ignore false positives caused by ``href`` anchors and dummy links not meant to work.
+ - [ ] Double-check that [the most recent docs builds at readthedocs](https://readthedocs.org/projects/solidity/builds/) succeeded.
+ - [ ] Make sure that all merged PRs that should have changelog entries do have them.
+ - [ ] Rerun CI on the top commits of main branches in all repositories that do not have daily activity by creating a test branch or PR:
+      - [ ] ``solc-js``
+      - [ ] ``solc-bin`` (make sure the bytecode comparison check did run)
+      - [ ] ``homebrew-ethereum``
+ - [ ] (Optional) Create a prerelease in our Ubuntu PPA by following the steps in the PPA section below on ``develop`` rather than on a tag.
+       This is recommended especially when dealing with PPA for the first time, when we add a new Ubuntu version or when the PPA scripts were modified in this release cycle.
+ - [ ] Verify that the release tarball of ``solc-js`` works.
+       Bump version locally, add ``soljson.js`` from CI, build it, compare the file structure with the previous version, install it locally and try to use it.
+
+### Drafts
+At least a day before the release:
+ - [ ] Create a draft PR to sort the changelog.
+ - [ ] Create draft PRs to bump version in ``solidity`` and ``solc-js``.
+ - [ ] Create a draft of the release on github.
+ - [ ] Create a draft PR to update soliditylang.org.
+ - [ ] Create drafts of blog posts.
+ - [ ] Prepare drafts of Twitter, Reddit and Solidity Forum announcements.
 
 ### Blog Post
- - [ ] Create a post on https://github.com/ethereum/solidity-blog and explain some of the new features or concepts.
+ - [ ] Create a post on [solidity-website](https://github.com/ethereum/solidity-website/tree/main/src/posts) in the ``Releases`` category and explain some of the new features or concepts.
+ - [ ] Create a post on [solidity-website](https://github.com/ethereum/solidity-website/tree/main/src/posts) in the ``Security Alerts`` category in case of important bug(s).
 
 ### Changelog
- - [ ] Sort the changelog entries alphabetically and correct any errors you notice.
- - [ ] Create a commit on a new branch that updates the ``Changelog`` to include a release date.
- - [ ] Run ``./scripts/tests.sh`` to update the bug list.
- - [ ] Create a pull request and wait for the tests, merge it.
+ - [ ] Sort the changelog entries alphabetically and correct any errors you notice. Commit it.
+ - [ ] Update the changelog to include a release date.
+ - [ ] Run ``scripts/update_bugs_by_version.py`` to regenerate ``bugs_by_version.json`` from the changelog and ``bugs.json``.
+       Make sure that the resulting ``bugs_by_version.json`` has a new, empty entry for the new version.
+ - [ ] Commit changes, create a pull request and wait for the tests. Then merge it.
+ - [ ] Copy the changelog into the release blog post.
 
 ### Create the Release
- - [ ] Create Github release page: https://github.com/ethereum/solidity/releases/new
- - [ ] On the release page, select the ``develop`` branch as new target and set tag to the new version (e.g. `v0.8.5`) (make sure you only `SAVE DRAFT` instead of `PUBLISH RELEASE` before the actual release)
- - [ ] Thank voluntary contributors in the Github release page (use ``git shortlog -s -n -e v0.5.3..origin/develop``).
+ - [ ] Create a [release on GitHub](https://github.com/ethereum/solidity/releases/new).
+       Set the target to the ``develop`` branch and the tag to the new version, e.g. ``v0.8.5``.
+       Include the following warning: ``**The release is still in progress and the binaries may not yet be available from all sources.**``.
+       Do not publish it yet - click the ``Save draft`` button instead.
+ - [ ] Thank voluntary contributors in the GitHub release notes.
+       Use ``scripts/list_contributors.sh v<previous version>`` to get initial list of names.
+       Remove different variants of the same name manually before using the output.
  - [ ] Check that all tests on the latest commit in ``develop`` are green.
- - [ ] Click the `PUBLISH RELEASE` button on the release page, creating the tag.
+ - [ ] Click the ``Publish release`` button on the release page, creating the tag.
  - [ ] Wait for the CI runs on the tag itself.
 
 ### Upload Release Artifacts and Publish Binaries
@@ -32,27 +66,32 @@
  - [ ] Run ``scripts/create_source_tarball.sh`` while being on the tag to create the source tarball. This will create the tarball in a directory called ``upload``.
  - [ ] Take the tarball from the upload directory (its name should be ``solidity_x.x.x.tar.gz``, otherwise ``prerelease.txt`` was missing in the step before) and upload the source tarball to the release page.
  - [ ] Take the ``github-binaries.tar`` tarball from ``c_release_binaries`` run of the tagged commit in circle-ci and add all binaries from it to the release page.
-   Make sure it contains four binaries: ``solc-windows.exe``, ``solc-macos``, ``solc-static-linux`` and ``soljson.js``.
+       Make sure it contains four binaries: ``solc-windows.exe``, ``solc-macos``, ``solc-static-linux`` and ``soljson.js``.
  - [ ] Take the ``solc-bin-binaries.tar`` tarball from ``c_release_binaries`` run of the tagged commit in circle-ci and add all binaries from it to solc-bin.
- - [ ] Run ``./update --reuse-hashes`` in ``solc-bin`` and verify that the script has updated ``list.js``, ``list.txt`` and ``list.json`` files correctly and that symlinks to the new release have been added in ``solc-bin/wasm/`` and ``solc-bin/emscripten-wasm32/``.
+ - [ ] Run ``npm run update -- --reuse-hashes`` in ``solc-bin`` and verify that the script has updated ``list.js``, ``list.txt`` and ``list.json`` files correctly and that symlinks to the new release have been added in ``solc-bin/wasm/`` and ``solc-bin/emscripten-wasm32/``.
  - [ ] Create a pull request in solc-bin and merge.
 
 ### Homebrew and MacOS
- - [ ] Update the version and the hash (``sha256sum solidity_$VERSION.tar.gz``) in https://github.com/Homebrew/homebrew-core/blob/master/Formula/solidity.rb
- - [ ] Update the version and the hash (``sha256sum solidity_$VERSION.tar.gz``) in https://github.com/ethereum/homebrew-ethereum/blob/master/solidity.rb
+ - [ ] Update the version and the hash (``sha256sum solidity_$VERSION.tar.gz``) in the [``solidity`` formula in Homebrew core repository](https://github.com/Homebrew/homebrew-core/blob/master/Formula/solidity.rb).
+ - [ ] Update the version and the hash (``sha256sum solidity_$VERSION.tar.gz``) in [our custom ``solidity`` Homebrew formula](https://github.com/ethereum/homebrew-ethereum/blob/master/solidity.rb).
 
 ### Docker
- - [ ] Run ``./scripts/docker_deploy_manual.sh v$VERSION``).
+ - [ ] Run ``./scripts/docker_deploy_manual.sh v$VERSION``.
 
 ### PPA
- - [ ] Make sure the ``ethereum/cpp-build-deps`` PPA repository contains libz3-static-dev builds for all current versions of ubuntu. If not run ``scripts/deps-ppa/static-z3.sh`` (after changing email address and key id and adding the missing ubuntu version) and wait for the builds to succeed before continuing.
- - [ ] Change ``scripts/release_ppa.sh`` to match your key's email and key id; double-check that ``DISTRIBUTIONS`` contains the most recent versions.
- - [ ] Run ``scripts/release_ppa.sh v$VERSION`` to create the PPA release (you need the relevant openssl key).
- - [ ] Wait for the ``~ethereum/ubuntu/ethereum-static`` PPA build to be finished and published for *all platforms*. SERIOUSLY: DO NOT PROCEED EARLIER!!! *After* the static builds are *published*, copy the static package to the ``~ethereum/ubuntu/ethereum`` PPA for the destination series ``Trusty``, ``Xenial`` and ``Bionic`` while selecting ``Copy existing binaries``.
-
-### Documentation
- - [ ] Build the new version on https://readthedocs.org/projects/solidity/ (select `latest` at the bottom of the page and click `BUILD`).
- - [ ] In the admin panel, select `Versions` in the menu and set the default version to the released one.
+ - [ ] Create ``.release_ppa_auth`` at the root of your local Solidity checkout and set ``LAUNCHPAD_EMAIL`` and ``LAUNCHPAD_KEYID`` to your key's email and key id.
+ - [ ] Double-check that the ``DISTRIBUTIONS`` list in ``scripts/release_ppa.sh`` and ``scripts/deps-ppa/static_z3.sh`` contains the most recent versions of Ubuntu.
+ - [ ] Make sure the [``~ethereum/cpp-build-deps`` PPA repository](https://launchpad.net/~ethereum/+archive/ubuntu/cpp-build-deps) contains ``libz3-static-dev builds`` for all current versions of Ubuntu.
+       Note that it may be included in the ``z3-static`` multipackage (follow the ``View package details`` link to check).
+       If not present, run ``scripts/deps-ppa/static_z3.sh`` and wait for the builds to succeed before continuing.
+ - [ ] Run ``scripts/release_ppa.sh v$VERSION`` to create the PPA release.
+       This will create a single package containing static binary for older Ubuntu versions in the [``~ethereum/ethereum-static`` PPA](https://launchpad.net/~ethereum/+archive/ubuntu/ethereum-static)
+       and separate packages with dynamically-linked binaries for recent versions (those listed in ``DISTRIBUTIONS``) in the [``~ethereum/ethereum`` PPA](https://launchpad.net/~ethereum/+archive/ubuntu/ethereum).
+ - [ ] Wait for the build to be finished and published for *all architectures* (currently we only build for ``amd64``, but we may add ``arm`` in the future).
+       **SERIOUSLY: DO NOT PROCEED EARLIER!!!**
+ - [ ] *After* the package with the static build is *published*, use it to create packages for older Ubuntu versions.
+       Copy the static package to the [``~ethereum/ethereum`` PPA](https://launchpad.net/~ethereum/+archive/ubuntu/ethereum)
+       for the destination series ``Trusty``, ``Xenial`` and ``Bionic`` while selecting ``Copy existing binaries``.
 
 ### Release solc-js
  - [ ] Wait until solc-bin was properly deployed. You can test this via remix - a test run through remix is advisable anyway.
@@ -62,9 +101,17 @@
  - [ ] Create a tag using ``git tag --annotate v$VERSION`` and push it with ``git push --tags``.
 
 ### Post-release
- - [ ] Publish the blog post.
+ - [ ] Make sure the documentation for the new release has been published successfully.
+       Go to the [documentation status page at ReadTheDocs](https://readthedocs.org/projects/solidity/) and verify that the new version is listed, works and is marked as default.
+ - [ ] Remove "still in progress" warning from the [release notes](https://github.com/ethereum/solidity/releases).
+ - [ ] Merge the [blog posts](https://github.com/ethereum/solidity-website/pulls) related to the release.
  - [ ] Create a commit to increase the version number on ``develop`` in ``CMakeLists.txt`` and add a new skeleton changelog entry.
- - [ ] Announce on Twitter, including links to the release and the blog post.
- - [ ] Share announcement on Reddit and Solidity forum.
- - [ ] Update the release information section on [soliditylang.org](https://github.com/ethereum/solidity-portal).
- - [ ] Lean back, wait for bug reports and repeat from step 1 :)
+ - [ ] Update the release information section [in the source of soliditylang.org](https://github.com/ethereum/solidity-website/blob/main/src/pages/index.tsx).
+ - [ ] Announce on [Twitter](https://twitter.com/solidity_lang), including links to the release and the blog post.
+ - [ ] Announce on [Fosstodon](https://fosstodon.org/@solidity/), including links to the release and the blog post.
+ - [ ] Share the announcement on Reddit in [``/r/ethdev``](https://reddit.com/r/ethdev/), cross-posted to [``/r/ethereum``](https://reddit.com/r/ethereum/).
+ - [ ] Share the announcement on the [Solidity forum](https://forum.soliditylang.org) in the ``Announcements`` category.
+ - [ ] Share the announcement on [Project Updates](https://discord.com/channels/420394352083337236/798974456704925696)
+ - [ ] Share the announcement on [`#solidity` channel on Matrix](https://matrix.to/#/#ethereum_solidity:gitter.im)
+ - [ ] Share the announcement on [`#solc-tooling`](https://matrix.to/#/#solc-tooling:matrix.org)
+ - [ ] Lean back, wait for bug reports and repeat from step 1 :).

ReviewChecklist.md

@@ -0,0 +1,200 @@
+# PR Review Checklist
+The Solidity compiler is a critical piece of infrastructure in the Ethereum ecosystem.
+For this reason, our review process is quite strict and all PRs have to fulfill certain quality
+expectations and guidelines.
+The list below is meant to reduce the workload on the core team by helping contributors self-identify
+and solve common issues before they are pointed out in the review.
+It is also meant to serve as a final checklist for reviewers to go through before approving a PR.
+
+## Before You Submit a PR
+- [ ] **Do you have any other open PRs?**
+    Work on a PR is not done until it is merged or closed.
+    Our reviewing capacity is limited, so we require that external contributors work on **no more than one PR at a time**.
+    - If your PR is not getting reviewed, feel free to bring it to our attention on the [#solidity-dev](https://gitter.im/ethereum/solidity-dev) channel.
+    - Unless they were requested, we are going to close any excess PRs, leaving only the earliest one open.
+        You may reopen them, one at a time, when your current PR is done.
+- [ ] **Is the issue ready to be worked on?**
+    - If the issue does not have a desirability label (`nice to have`, `should have`,
+        `must have eventually`, `must have`, `roadmap`) we have not yet decided whether to implement it.
+    - If the issue has the `needs design` label, we have not yet decided how it should be implemented.
+    - `good first issue candidate` means that the issue will potentially be a `good first issue`
+        eventually but at the moment it is not yet ready to be worked on.
+- [ ] **Is this a breaking change?** Breaking changes should be based on the `breaking` branch rather than on the `develop` branch.
+- [ ] **Does the PR actually address the issue?**
+    - [ ] Mention the issue number in the PR description.
+        If the PR solves it completely, use the `Fixes #<issue number>` form so that Github will close the issue automatically.
+    - [ ] Do not include the issue number in the PR title, branch name or commit description.
+- [ ] When submitting a PR from a fork **create a branch and give it a descriptive name.**
+    E.g. `fix-array-abi-encoding-bug`.
+    Do not submit PRs directly from the `develop` branch of your fork since it makes rebasing and fetching new changes harder.
+- [ ] **Does the PR depend on other PRs?**
+    - [ ] If the PR has dependencies, mention them in bold in the description.
+    - [ ] Avoid basing PRs from forks on branches other than `develop` or `breaking` because
+        GitHub closes them when the base branch gets merged.
+        Do this only for PRs created directly in the main repo.
+- [ ] **Does the PR update test expectations to match the modified code?** If not, your PR will not pass some of the `_soltest_`,  jobs in CI.
+    In many cases the expectations can be updated automatically:
+    - `cmdlineTests.sh --update` for command-line tests.
+    - `isoltest --enforce-gas-cost --accept-updates` for soltest-based tests.
+        - If your PR affects gas costs, an extra run of `isoltest --enforce-gas-cost --optimize --accept-updates` is needed to update gas expectations with optimizer enabled.
+    - Review updated files before committing them.
+        **Are expectations correct and do updated tests still serve their purpose?**
+
+## Abandoned PRs
+- [ ] **Is the submitter still responsive?**
+    - If the PR had no activity from the submitter in the last 2 weeks (despite receiving reviews and our prompts) we consider it abandoned.
+- [ ] **Is the abandoned PR easy to finish or relevant?**
+    - Apply the `takeover` label if the PR can be finished without significant effort or is something that actually needs to be done right now.
+        Otherwise close it.
+        It can still be taken over later or reopened by the submitter but until then we should not be getting sidetracked by it.
+
+## Light Review
+Before an in-depth review, it is recommended to give new PRs a quick, superficial review, which
+is not meant to provide complete and detailed feedback, but instead give the submitter a rough idea
+if the PR is even on the right track and let them solve the obvious problems on their own.
+
+Light review should focus on the following three areas:
+- [ ] **Are there any obvious mistakes?** Style issues, bad practices, easy to identify bugs, etc.
+- [ ] **Is there anything missing?** Tests (of the right kind), documentation, etc. Does it address the whole issue?
+- [ ] **Is it the right solution?** Are there better ways to do this? Is the change even necessary?
+
+If the answers above are "Yes, Yes, No", thank the contributor for their effort and **close the PR**.
+
+## Coding Style and Good Practices
+- [ ] Does the PR follow our [coding style](CODING_STYLE.md)?
+
+### Reliability
+- [ ] **Use assertions liberally.** If you are certain your assumption will not be broken, prove it with `solAssert()`.
+- [ ] **Validate inputs and handle errors**. Note that assertions are **not** validation.
+
+### Readability
+- [ ] **Choose good names.**
+    - [ ] Is the name straightforward to understand?
+        Do you feel the need to jump back to the definition and remind yourself what it was whenever you see it?
+    - [ ] Is the name unambiguous in the context where it is used?
+    - [ ] Avoid abbreviations.
+- [ ] **Source files, classes and public functions should have docstrings.**
+- [ ] **Avoid code duplication.** But not fanatically. Minimal amounts of duplication are acceptable if it aids readability.
+- [ ] **Do not leave dead or commented-out code behind.** You can still see old code in history.
+      If you really have a good reason to do it, always leave a comment explaining what it is and why it is there.
+- [ ] **Mark hacks as such.** If you have to leave behind a temporary workaround, make
+    sure to include a comment that explains why and in what circumstances it can be removed.
+    Preferably link to an issue you reported upstream.
+- [ ] **Avoid obvious comments.**
+- [ ] **Do include comments when the reader may need extra context to understand the code.**
+
+### Commits and PRs
+- [ ] **Avoid hiding functional changes inside refactors.**
+    E.g. when fixing a small bug, or changing user-visible behavior, put the change in a separate commit.
+    Do not mix it with another change that renames things or reformats the code around, making the fix itself hard to identify.
+- [ ] **Whenever possible, split off refactors or unrelated changes into separate PRs.**
+    Smaller PRs are easier and quicker to review.
+    Splitting off refactors helps focus on the main point of the PR.
+
+### Common Pitfalls
+The following points are all covered by the coding style but come up so often that it is worth singling them out here:
+- [ ] **Always initialize value types in the definition,** even if you are sure you will assign them later.
+- [ ] **Use "east const" style.** I.e. `T const*`, not `const T *`.
+- [ ] **Keep indentation consistent.** See our [`.editorconfig`](.editorconfig).
+    - [ ] Tabs for C++. But use them for indentation only. Any whitespace later on the line must consist of spaces.
+    - [ ] 4 spaces for most other file types.
+- [ ] **Use `auto` sparingly.** Only use it when the actual type is very long and complicated or when it is
+    already used elsewhere in the same expression.
+- [ ] **Indent braces and parentheses in a way that makes nesting clear.**
+- [ ] **Use `using namespace` only in `.cpp` files.** Use it for `std` and our own modules.
+    Avoid unnecessary `std::` prefix in `.cpp` files (except for `std::move` and `std::forward`).
+- [ ] **Use range-based loops and destructuring.**
+- [ ] **Include any headers you use directly,** even if they are implicitly included through other headers.
+
+## Documentation
+- [ ] **Does the PR update relevant documentation?**
+
+### Documentation Style and Good Practices
+- [ ] **Use double backticks in RST (``` ``x`` ```). Prefer single backticks in Markdown (`` `x` ``),**
+    but note that double backticks are valid too and we use them in some cases for legacy reasons.
+- [ ] **Always start a new sentence on a new line.**
+    This way you do not have to rewrap the surrounding text when you rewrite the sentence.
+    This also makes changes actually easier to spot in the diff.
+
+## Testing
+
+### What to Test
+- [ ] **Is newly added code adequately covered by tests?** Have you considered all the important corner cases?
+- If it is a bugfix:
+    - [ ] **The PR must include tests that reproduce the bug.**
+    - [ ] **Are there gaps in test coverage of the buggy feature?** Fill them by adding more tests.
+    - [ ] **Try to break it.** Can you of any similar features that could also be buggy?
+        Play with the repro and include prominent variants as separate test cases, even if they don't trigger a bug.
+- [ ] **Positive cases (code that compiles) should have a semantic test.**
+- [ ] **Negative cases (code with compilation errors) should have a syntax test.**
+- [ ] **Avoid mixing positive and negative cases in the same syntax test.**
+    If the test produces an error, we stop at the analysis stage and we will not detect
+    problems that only occur in code generation, optimizer or assembler.
+    - [ ] If you have to do it, at least mark positive cases inside the file with a short comment.
+        - This way, when the test is updated, it is easier to verify that these cases still do not trigger an error.
+- [ ] New syntax: **does it have an [`ASTJSON`](test/libsolidity/ASTJSON/) test?**
+- [ ] New CLI or StandardJSON option:
+    - [ ] **Does it have a [command-line test](test/cmdlineTests/)?**
+    - [ ] **Is the option listed for every input mode in [`CommandLineParser` tests](test/solc/CommandLineParser.cpp)?**
+- [ ] **Did you consider interactions with other language features?**
+    - [ ] Are all types covered? Structs? Enums? Contracts/libraries/interfaces? User-defined value types?
+        Value types: integers, fixed bytes, `address`, `address payable`, `bool`? Function pointers?
+        Static and dynamic arrays? `string` and `bytes`? Mappings?
+        Values of types that cannot be named: literals, tuples, array slices, storage references?
+    - [ ] If it accepts a function, does it also accept an event or an error? These have function types but are not functions.
+    - [ ] If it affects free functions, what about internal library functions?
+    - [ ] Attached library functions? Functions attached with `using for`?
+    - [ ] Possible combinations of `storage`, `memory`, `calldata`, `immutable`, `constant`?
+        Remember that internal functions can take `storage` arguments.
+    - [ ] Does it work at construction time as well? What if you store it at construction time and read after deployment?
+    - [ ] What about importing it from a different module or inheriting it?
+    - [ ] Have you tested it with the ternary operator?
+
+### Test Style and Good Practices
+- [ ] **Make test case file names long and specific enough** so that it is easy to guess what is inside.
+    When checking if we have the case already covered the name is usually the only clue we see.
+    - [ ] Place them in the right subdirectory.
+    - [ ] **Avoid simply appending numbers to the name to distinguish similar cases.**
+        Coming up with good names is hard but figuring out if any of hundreds of tests with names that
+        match your search actually fits your case is even harder.
+- [ ] **Do not include version pragma and the SPDX comment in semantic and syntax test cases**.
+    In other test types include them if necessary to suppress warnings.
+- [ ] **If you have to use a version pragma, avoid hard-coding version.** Use `pragma solidity *`.
+- [ ] **When writing StandardJSON command-line tests, use `urls` instead of `content`** and put
+    the Solidity or Yul code in a separate file.
+
+## Compiler-specific
+- [ ] **Are error messages sensible and understandable to users?**
+- [ ] **Are error codes consistent?**
+    - [ ] Avoid randomly changing or reassigning error codes.
+    - [ ] Avoid defining separate codes for trivial variants of the same issue.
+        Make it easy for tools to consistently refer to the same error with the same code.
+- [ ] **Error messages should end with a full stop.**
+- [ ] **Prefer Ranges v3 to Boost where possible.**
+
+## Take a Step Back
+- [ ] **Do you fully understand what the PR does and why?**
+- [ ] **Are you confident that the code works and does not break unrelated functionality?**
+- [ ] **Is this a reasonable way to achieve the goal stated in the issue?**
+- [ ] **Is the code simple?** Does the PR achieve its objective at the cost of significant
+    complexity that may be a source of future bugs?
+- [ ] **Is the code efficient?** Does the PR introduce any major performance bottlenecks?
+- [ ] **Does the PR introduce any breaking changes beyond what was agreed in the issue?**
+
+## Final Checks Before Merging
+- [ ] **Is the PR rebased on top of the `develop` branch** (or `breaking` if it is a breaking change)?
+- [ ] **Did all CI checks pass?**
+    - Note that we have a few jobs that tend to randomly fail due to outside factors, especially external tests (with `_ext_` in the name).
+        If these fail, rebase on latest `develop` (or `breaking`) and try rerunning them.
+        Note also that not all of these checks are required for the PR to be merged.
+- [ ] If the change is visible to users, **does the PR have a [changelog](Changelog.md) entry?**
+    - [ ] Is the changelog entry in the right section?
+        Make sure to move it up if there was a release recently.
+- [ ] **Is commit history simple and understandable?**
+    - [ ] Each commit should be a self-contained, logical step leading the goal of the PR, without going back and forth.
+        In particular, review fixups should be squashed into the commits they fix.
+    - [ ] Do not include any merge commits in your branch. Please use rebase to keep up to date with the base branch.
+- [ ] **Is the PR properly labeled?**
+    - Use `external contribution` label to mark PRs not coming from the core team.
+    - If the PR depends on other PRs, use `has dependencies` and set the base branch accordingly.
+    - Labels like `documentation` or `optimizer` are helpful for filtering PRs.

cmake/EthCompilerSettings.cmake

@@ -23,48 +23,63 @@ if(NOT EMSCRIPTEN)
 	endif()
 endif()
 
-eth_add_cxx_compiler_flag_if_supported(-Wimplicit-fallthrough)
+if(PEDANTIC)
+	eth_add_cxx_compiler_flag_if_supported(-Wimplicit-fallthrough)
+endif()
 
 # Prevent the path of the source directory from ending up in the binary via __FILE__ macros.
-eth_add_cxx_compiler_flag_if_supported("-fmacro-prefix-map=${CMAKE_SOURCE_DIR}=/solidity")
+eth_add_cxx_compiler_flag_if_supported("-fmacro-prefix-map=${PROJECT_SOURCE_DIR}=/solidity")
 
 # -Wpessimizing-move warns when a call to std::move would prevent copy elision
 # if the argument was not wrapped in a call.  This happens when moving a local
 # variable in a return statement when the variable is the same type as the
 # return type or using a move to create a new object from a temporary object.
-eth_add_cxx_compiler_flag_if_supported(-Wpessimizing-move)
+if(PEDANTIC)
+	eth_add_cxx_compiler_flag_if_supported(-Wpessimizing-move)
+endif()
 
 # -Wredundant-move warns when an implicit move would already be made, so the
 # std::move call is not needed, such as when moving a local variable in a return
 # that is different from the return type.
-eth_add_cxx_compiler_flag_if_supported(-Wredundant-move)
+if(PEDANTIC)
+	eth_add_cxx_compiler_flag_if_supported(-Wredundant-move)
+endif()
 
 if (("${CMAKE_CXX_COMPILER_ID}" MATCHES "GNU") OR ("${CMAKE_CXX_COMPILER_ID}" MATCHES "Clang"))
 	# Enables all the warnings about constructions that some users consider questionable,
 	# and that are easy to avoid.  Also enable some extra warning flags that are not
 	# enabled by -Wall.   Finally, treat at warnings-as-errors, which forces developers
 	# to fix warnings as they arise, so they don't accumulate "to be fixed later".
-	add_compile_options(-Wall)
-	add_compile_options(-Wextra)
-	add_compile_options(-Werror)
-	add_compile_options(-pedantic)
-	add_compile_options(-Wmissing-declarations)
-	add_compile_options(-Wno-unknown-pragmas)
-	add_compile_options(-Wimplicit-fallthrough)
-	add_compile_options(-Wsign-conversion)
-	add_compile_options(-Wconversion)
+	if(PEDANTIC)
+		add_compile_options(-Wall)
+		add_compile_options(-Wextra)
+		add_compile_options(-Werror)
+		add_compile_options(-pedantic)
+		add_compile_options(-Wmissing-declarations)
+		add_compile_options(-Wno-unknown-pragmas)
+		add_compile_options(-Wimplicit-fallthrough)
+		add_compile_options(-Wsign-conversion)
+		add_compile_options(-Wconversion)
 
-	check_cxx_compiler_flag(-Wextra-semi WEXTRA_SEMI)
-	if(WEXTRA_SEMI)
-		add_compile_options($<$<COMPILE_LANGUAGE:CXX>:-Wextra-semi>)
+		check_cxx_compiler_flag(-Wextra-semi WEXTRA_SEMI)
+		if(WEXTRA_SEMI)
+			add_compile_options($<$<COMPILE_LANGUAGE:CXX>:-Wextra-semi>)
+		endif()
+		# See https://gcc.gnu.org/git/gitweb.cgi?p=gcc.git;h=6b927b1297e66e26e62e722bf15c921dcbbd25b9
+		check_cxx_compiler_flag(-Wno-dangling-reference WNO_DANGLING_REFERENCE)
+		if (WNO_DANGLING_REFERENCE)
+            add_compile_options($<$<COMPILE_LANGUAGE:CXX>:-Wno-dangling-reference>)
+		endif()
+
+
+		eth_add_cxx_compiler_flag_if_supported(-Wfinal-dtor-non-final-class)
+		eth_add_cxx_compiler_flag_if_supported(-Wnewline-eof)
+		eth_add_cxx_compiler_flag_if_supported(-Wsuggest-destructor-override)
+		eth_add_cxx_compiler_flag_if_supported(-Wduplicated-cond)
+		eth_add_cxx_compiler_flag_if_supported(-Wduplicate-enum)
+		eth_add_cxx_compiler_flag_if_supported(-Wlogical-op)
+		eth_add_cxx_compiler_flag_if_supported(-Wno-unknown-attributes)
 	endif()
-	eth_add_cxx_compiler_flag_if_supported(-Wfinal-dtor-non-final-class)
-	eth_add_cxx_compiler_flag_if_supported(-Wnewline-eof)
-	eth_add_cxx_compiler_flag_if_supported(-Wsuggest-destructor-override)
-	eth_add_cxx_compiler_flag_if_supported(-Wduplicated-cond)
-	eth_add_cxx_compiler_flag_if_supported(-Wduplicate-enum)
-	eth_add_cxx_compiler_flag_if_supported(-Wlogical-op)
-	eth_add_cxx_compiler_flag_if_supported(-Wno-unknown-attributes)
 
 	# Configuration-specific compiler settings.
 	set(CMAKE_CXX_FLAGS_DEBUG          "-O0 -g3 -DETH_DEBUG")
@@ -158,7 +173,9 @@ elseif (DEFINED MSVC)
 
 	add_compile_options(/MP)						# enable parallel compilation
 	add_compile_options(/EHsc)						# specify Exception Handling Model in msvc
-	add_compile_options(/WX)						# enable warnings-as-errors
+	if(PEDANTIC)
+		add_compile_options(/WX)					# enable warnings-as-errors
+	endif()
 	add_compile_options(/wd4068)					# disable unknown pragma warning (4068)
 	add_compile_options(/wd4996)					# disable unsafe function warning (4996)
 	add_compile_options(/wd4503)					# disable decorated name length exceeded, name was truncated (4503)

cmake/EthPolicy.cmake

@@ -20,4 +20,16 @@ macro (eth_policy)
 		# Allow selecting MSVC runtime library using CMAKE_MSVC_RUNTIME_LIBRARY.
 		cmake_policy(SET CMP0091 NEW)
 	endif()
+
+	# Avoid warning about DOWNLOAD_EXTRACT_TIMESTAMP in CMake 3.24:
+	if (CMAKE_VERSION VERSION_GREATER_EQUAL "3.24.0")
+		cmake_policy(SET CMP0135 NEW)
+	endif()
+
+	if(POLICY CMP0115)
+		# Require explicit extensions for source files, do not guess.
+		# The extra calls to GetFileAttributesW significantly slow down cmake on Windows.
+		# https://gitlab.kitware.com/cmake/cmake/-/issues/23154
+		cmake_policy(SET CMP0115 NEW)
+	endif()
 endmacro()

cmake/fmtlib.cmake

@@ -2,11 +2,11 @@ include(FetchContent)
 
 FetchContent_Declare(
 	fmtlib
-	PREFIX "${CMAKE_BINARY_DIR}/deps"
-	DOWNLOAD_DIR "${CMAKE_SOURCE_DIR}/deps/downloads"
-	DOWNLOAD_NAME fmt-8.0.1.tar.gz
-	URL https://github.com/fmtlib/fmt/archive/8.0.1.tar.gz
-	URL_HASH SHA256=b06ca3130158c625848f3fb7418f235155a4d389b2abc3a6245fb01cb0eb1e01
+	PREFIX "${PROJECT_BINARY_DIR}/deps"
+	DOWNLOAD_DIR "${PROJECT_SOURCE_DIR}/deps/downloads"
+	DOWNLOAD_NAME fmt-9.1.0.tar.gz
+	URL https://github.com/fmtlib/fmt/archive/9.1.0.tar.gz
+	URL_HASH SHA256=5dea48d1fcddc3ec571ce2058e13910a0d4a6bab4cc09a809d8b1dd1c88ae6f2
 )
 
 if (CMAKE_VERSION VERSION_LESS "3.14.0")

cmake/jsoncpp.cmake

@@ -6,7 +6,7 @@ else()
     set(JSONCPP_CMAKE_COMMAND ${CMAKE_COMMAND})
 endif()
 
-set(prefix "${CMAKE_BINARY_DIR}/deps")
+set(prefix "${PROJECT_BINARY_DIR}/deps")
 set(JSONCPP_LIBRARY "${prefix}/lib/${CMAKE_STATIC_LIBRARY_PREFIX}jsoncpp${CMAKE_STATIC_LIBRARY_SUFFIX}")
 set(JSONCPP_INCLUDE_DIR "${prefix}/include")
 
@@ -42,7 +42,7 @@ endif()
 
 ExternalProject_Add(jsoncpp-project
     PREFIX "${prefix}"
-    DOWNLOAD_DIR "${CMAKE_SOURCE_DIR}/deps/downloads"
+    DOWNLOAD_DIR "${PROJECT_SOURCE_DIR}/deps/downloads"
     DOWNLOAD_NAME jsoncpp-1.9.3.tar.gz
     URL https://github.com/open-source-parsers/jsoncpp/archive/1.9.3.tar.gz
     URL_HASH SHA256=8593c1d69e703563d94d8c12244e2e18893eeb9a8a9f8aa3d09a327aa45c8f7d

cmake/range-v3.cmake

@@ -6,12 +6,12 @@ else()
     set(RANGE_V3_CMAKE_COMMAND ${CMAKE_COMMAND})
 endif()
 
-set(prefix "${CMAKE_BINARY_DIR}/deps")
+set(prefix "${PROJECT_BINARY_DIR}/deps")
 set(RANGE_V3_INCLUDE_DIR "${prefix}/include")
 
 ExternalProject_Add(range-v3-project
     PREFIX "${prefix}"
-    DOWNLOAD_DIR "${CMAKE_SOURCE_DIR}/deps/downloads"
+    DOWNLOAD_DIR "${PROJECT_SOURCE_DIR}/deps/downloads"
     DOWNLOAD_NAME range-v3-0.12.0.tar.gz
     URL https://github.com/ericniebler/range-v3/archive/0.12.0.tar.gz
     URL_HASH SHA256=015adb2300a98edfceaf0725beec3337f542af4915cec4d0b89fa0886f4ba9cb

cmake/templates/ewasm_polyfill.in

@@ -1,13 +0,0 @@
-// The generation of this file is defined in libyul/CMakeLists.txt.
-// This file was generated by using the content of libyul/backends/wasm/polyfill/@EWASM_POLYFILL_NAME@.yul.
-
-#pragma once
-
-namespace solidity::yul::wasm::polyfill
-{
-
-static char const @EWASM_POLYFILL_NAME@[] = {
-	@EWASM_POLYFILL_CONTENT@, 0
-};
-
-} // namespace solidity::yul::wasm::polyfill

docs/050-breaking-changes.rst

@@ -137,7 +137,7 @@ For most of the topics the compiler will provide suggestions.
   ``payable`` or create a new internal function for the program logic that
   uses ``msg.value``.
 
-* For clarity reasons, the command line interface now requires ``-`` if the
+* For clarity reasons, the command-line interface now requires ``-`` if the
   standard input is used as source.
 
 Deprecated Elements
@@ -147,18 +147,18 @@ This section lists changes that deprecate prior features or syntax.  Note that
 many of these changes were already enabled in the experimental mode
 ``v0.5.0``.
 
-Command Line and JSON Interfaces
+Command-line and JSON Interfaces
 --------------------------------
 
-* The command line option ``--formal`` (used to generate Why3 output for
+* The command-line option ``--formal`` (used to generate Why3 output for
   further formal verification) was deprecated and is now removed.  A new
   formal verification module, the SMTChecker, is enabled via ``pragma
   experimental SMTChecker;``.
 
-* The command line option ``--julia`` was renamed to ``--yul`` due to the
+* The command-line option ``--julia`` was renamed to ``--yul`` due to the
   renaming of the intermediate language ``Julia`` to ``Yul``.
 
-* The ``--clone-bin`` and ``--combined-json clone-bin`` command line options
+* The ``--clone-bin`` and ``--combined-json clone-bin`` command-line options
   were removed.
 
 * Remappings with empty prefix are disallowed.

docs/060-breaking-changes.rst

@@ -12,7 +12,7 @@ For the full list check
 Changes the Compiler Might not Warn About
 =========================================
 
-This section lists changes where the behaviour of your code might
+This section lists changes where the behavior of your code might
 change without the compiler telling you about it.
 
 * The resulting type of an exponentiation is the type of the base. It used to be the smallest type
@@ -53,6 +53,8 @@ For most of the topics the compiler will provide suggestions.
   If the name contains a dot, its prefix up to the dot may not conflict with any declaration outside the inline
   assembly block.
 
+* In inline assembly, opcodes that do not take arguments are now represented as "built-in functions" instead of standalone identifiers. So ``gas`` is now ``gas()``.
+
 * State variable shadowing is now disallowed.  A derived contract can only
   declare a state variable ``x``, if there is no visible state variable with
   the same name in any of its bases.
@@ -103,23 +105,23 @@ Interface Changes
 =================
 
 This section lists changes that are unrelated to the language itself, but that have an effect on the interfaces of
-the compiler. These may change the way how you use the compiler on the command line, how you use its programmable
+the compiler. These may change the way how you use the compiler on the command-line, how you use its programmable
 interface, or how you analyze the output produced by it.
 
 New Error Reporter
 ~~~~~~~~~~~~~~~~~~
 
-A new error reporter was introduced, which aims at producing more accessible error messages on the command line.
-It is enabled by default, but passing ``--old-reporter`` falls back to the the deprecated old error reporter.
+A new error reporter was introduced, which aims at producing more accessible error messages on the command-line.
+It is enabled by default, but passing ``--old-reporter`` falls back to the deprecated old error reporter.
 
 Metadata Hash Options
 ~~~~~~~~~~~~~~~~~~~~~
 
 The compiler now appends the `IPFS <https://ipfs.io/>`_ hash of the metadata file to the end of the bytecode by default
 (for details, see documentation on :doc:`contract metadata <metadata>`). Before 0.6.0, the compiler appended the
-`Swarm <https://ethersphere.github.io/swarm-home/>`_ hash by default, and in order to still support this behaviour,
-the new command line option ``--metadata-hash`` was introduced. It allows you to select the hash to be produced and
-appended, by passing either ``ipfs`` or ``swarm`` as value to the ``--metadata-hash`` command line option.
+`Swarm <https://ethersphere.github.io/swarm-home/>`_ hash by default, and in order to still support this behavior,
+the new command-line option ``--metadata-hash`` was introduced. It allows you to select the hash to be produced and
+appended, by passing either ``ipfs`` or ``swarm`` as value to the ``--metadata-hash`` command-line option.
 Passing the value ``none`` completely removes the hash.
 
 These changes can also be used via the :ref:`Standard JSON Interface<compiler-api>` and effect the metadata JSON generated by the compiler.
@@ -174,3 +176,6 @@ This section gives detailed instructions on how to update prior code for every b
   ``override`` to every overriding function. For multiple inheritance, add ``override(A, B, ..)``,
   where you list all contracts that define the overridden function in the parentheses. When
   multiple bases define the same function, the inheriting contract must override all conflicting functions.
+
+* In inline assembly, add ``()`` to all opcodes that do not otherwise accept an argument.
+  For example, change ``pc`` to ``pc()``, and ``gas`` to ``gas()``.

docs/080-breaking-changes.rst

@@ -10,18 +10,18 @@ For the full list check
 Silent Changes of the Semantics
 ===============================
 
-This section lists changes where existing code changes its behaviour without
+This section lists changes where existing code changes its behavior without
 the compiler notifying you about it.
 
 * Arithmetic operations revert on underflow and overflow. You can use ``unchecked { ... }`` to use
-  the previous wrapping behaviour.
+  the previous wrapping behavior.
 
   Checks for overflow are very common, so we made them the default to increase readability of code,
   even if it comes at a slight increase of gas costs.
 
 * ABI coder v2 is activated by default.
 
-  You can choose to use the old behaviour using ``pragma abicoder v1;``.
+  You can choose to use the old behavior using ``pragma abicoder v1;``.
   The pragma ``pragma experimental ABIEncoderV2;`` is still valid, but it is deprecated and has no effect.
   If you want to be explicit, please use ``pragma abicoder v2;`` instead.
 
@@ -57,7 +57,7 @@ New Restrictions
 
 This section lists changes that might cause existing contracts to not compile anymore.
 
-* There are new restrictions related to explicit conversions of literals. The previous behaviour in
+* There are new restrictions related to explicit conversions of literals. The previous behavior in
   the following cases was likely ambiguous:
 
   1. Explicit conversions from negative literals and literals larger than ``type(uint160).max`` to
@@ -106,7 +106,7 @@ This section lists changes that might cause existing contracts to not compile an
 
 * The global functions ``log0``, ``log1``, ``log2``, ``log3`` and ``log4`` have been removed.
 
-  These are low-level functions that were largely unused. Their behaviour can be accessed from inline assembly.
+  These are low-level functions that were largely unused. Their behavior can be accessed from inline assembly.
 
 * ``enum`` definitions cannot contain more than 256 members.
 
@@ -173,4 +173,4 @@ How to update your code
 - Change ``msg.sender.transfer(x)`` to ``payable(msg.sender).transfer(x)`` or use a stored variable of ``address payable`` type.
 - Change ``x**y**z`` to ``(x**y)**z``.
 - Use inline assembly as a replacement for ``log0``, ..., ``log4``.
-- Negate unsigned integers by subtracting them from the maximum value of the type and adding 1 (e.g. ``type(uint256).max - x + 1``, while ensuring that `x` is not zero)
+- Negate unsigned integers by subtracting them from the maximum value of the type and adding 1 (e.g. ``type(uint256).max - x + 1``, while ensuring that ``x`` is not zero)

docs/Makefile

@@ -34,7 +34,6 @@ help:
 	@echo "  epub       to make an epub"
 	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
 	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
-	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
 	@echo "  text       to make text files"
 	@echo "  man        to make manual pages"
 	@echo "  texinfo    to make Texinfo files"
@@ -116,12 +115,6 @@ latexpdf:
 	$(MAKE) -C $(BUILDDIR)/latex all-pdf
 	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
 
-latexpdfja:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo "Running LaTeX files through platex and dvipdfmx..."
-	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
-
 text:
 	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
 	@echo

docs/README.md

@@ -0,0 +1,23 @@
+# Solidity Language Docs
+
+## Local environment setup
+
+1. Install python https://www.python.org/downloads/
+1. Install sphinx (the tool used to generate the docs) https://www.sphinx-doc.org/en/master/usage/installation.html
+
+Go to `/docs` and run `./docs.sh` to install dependencies and build the project:
+
+```sh
+cd docs
+./docs.sh
+```
+
+That will output the generated htmls under _build/
+
+## Serve environment
+
+```py
+python3 -m http.server -d _build/html --cgi 8080
+```
+
+Visit dev server at http://localhost:8080

docs/_static/css/custom-dark.css

@@ -0,0 +1,595 @@
+
+
+/* DARK MODE STYLING */
+
+/* code directives */
+
+:root[style*=dark] .method dt,
+:root[style*=dark] .class dt,
+:root[style*=dark] .data dt,
+:root[style*=dark] .attribute dt,
+:root[style*=dark] .function dt,
+:root[style*=dark] .classmethod dt,
+:root[style*=dark] .exception dt,
+:root[style*=dark] .descclassname,
+:root[style*=dark] .descname {
+  background-color: #2d2d2d !important;
+}
+
+:root[style*=dark] .rst-content dl:not(.docutils) dt {
+  background-color: #0008;
+  border-top: solid 3px #fff2;
+  border-left: solid 3px #fff2;
+}
+
+:root[style*=dark] em.property {
+  color: #888888;
+}
+
+
+/* tables */
+
+:root[style*=dark] .rst-content table.docutils td {
+  border: 0px;
+}
+
+:root[style*=dark] .rst-content table.docutils:not(.field-list) tr:nth-child(2n-1) td {
+  background-color: #0002;
+}
+
+:root[style*=dark] .rst-content pre {
+  background: none;
+}
+
+/* inlined code highlights */
+
+:root[style*=dark] .xref,
+:root[style*=dark] .py-meth {
+  color: #aaddff !important;
+  font-weight: normal !important;
+}
+
+/* highlight color search text */
+
+:root[style*=dark] .rst-content .highlighted {
+  background: #ff5722;
+  box-shadow: 0 0 0 2px #f0978b;
+}
+
+/* notes, warnings, hints */
+
+:root[style*=dark] .hint .admonition-title {
+  background: #2aa87c !important;
+}
+
+:root[style*=dark] .warning .admonition-title {
+  background: #cc4444 !important;
+}
+
+:root[style*=dark] .admonition-title {
+  background: #3a7ca8 !important;
+}
+
+:root[style*=dark] .admonition,
+:root[style*=dark] .note {
+  background-color: #0008 !important;
+}
+
+
+/* table of contents */
+
+:root[style*=dark] .sidebar {
+  background-color: #191919 !important;
+}
+
+:root[style*=dark] .sidebar-title {
+  background-color: #2b2b2b !important;
+}
+
+:root[style*=dark] .wy-menu-vertical code.docutils.literal.notranslate {
+  background: none !important;
+  border: none !important;
+}
+
+
+:root[style*=dark] .toc-backref {
+  color: grey !important;
+}
+
+:root[style*=dark] .highlight {
+  background: #0008;
+  color: #f8f8f2
+}
+
+:root[style*=dark] .highlight .c {
+  color: #888
+}
+
+
+/* Comment */
+
+:root[style*=dark] .highlight .err {
+  color: #960050;
+  background-color: #1e0010
+}
+
+
+/* Error */
+
+:root[style*=dark] .highlight .k {
+  color: #66d9ef
+}
+
+
+/* Keyword */
+
+:root[style*=dark] .highlight .l {
+  color: #ae81ff
+}
+
+
+/* Literal */
+
+:root[style*=dark] .highlight .n {
+  color: #f8f8f2
+}
+
+
+/* Name */
+
+:root[style*=dark] .highlight .o {
+  color: #f92672
+}
+
+
+/* Operator */
+
+:root[style*=dark] .highlight .p {
+  color: #f8f8f2
+}
+
+
+/* Punctuation */
+
+:root[style*=dark] .highlight .ch {
+  color: #888
+}
+
+
+/* Comment.Hashbang */
+
+:root[style*=dark] .highlight .cm {
+  color: #888
+}
+
+
+/* Comment.Multiline */
+
+:root[style*=dark] .highlight .cp {
+  color: #888
+}
+
+
+/* Comment.Preproc */
+
+:root[style*=dark] .highlight .cpf {
+  color: #888
+}
+
+
+/* Comment.PreprocFile */
+
+:root[style*=dark] .highlight .c1 {
+  color: #888
+}
+
+
+/* Comment.Single */
+
+:root[style*=dark] .highlight .cs {
+  color: #888
+}
+
+
+/* Comment.Special */
+
+:root[style*=dark] .highlight .gd {
+  color: #f92672
+}
+
+
+/* Generic.Deleted */
+
+:root[style*=dark] .highlight .ge {
+  font-style: italic
+}
+
+
+/* Generic.Emph */
+
+:root[style*=dark] .highlight .gi {
+  color: #a6e22e
+}
+
+
+/* Generic.Inserted */
+
+:root[style*=dark] .highlight .gs {
+  font-weight: bold
+}
+
+
+/* Generic.Strong */
+
+:root[style*=dark] .highlight .gu {
+  color: #888
+}
+
+
+/* Generic.Subheading */
+
+:root[style*=dark] .highlight .kc {
+  color: #66d9ef
+}
+
+
+/* Keyword.Constant */
+
+:root[style*=dark] .highlight .kd {
+  color: #66d9ef
+}
+
+
+/* Keyword.Declaration */
+
+:root[style*=dark] .highlight .kn {
+  color: #f92672
+}
+
+
+/* Keyword.Namespace */
+
+:root[style*=dark] .highlight .kp {
+  color: #66d9ef
+}
+
+
+/* Keyword.Pseudo */
+
+:root[style*=dark] .highlight .kr {
+  color: #66d9ef
+}
+
+
+/* Keyword.Reserved */
+
+:root[style*=dark] .highlight .kt {
+  color: #66d9ef
+}
+
+
+/* Keyword.Type */
+
+:root[style*=dark] .highlight .ld {
+  color: #e6db74
+}
+
+
+/* Literal.Date */
+
+:root[style*=dark] .highlight .m {
+  color: #ae81ff
+}
+
+
+/* Literal.Number */
+
+:root[style*=dark] .highlight .s {
+  color: #e6db74
+}
+
+
+/* Literal.String */
+
+:root[style*=dark] .highlight .na {
+  color: #a6e22e
+}
+
+
+/* Name.Attribute */
+
+:root[style*=dark] .highlight .nb {
+  color: #f8f8f2
+}
+
+
+/* Name.Builtin */
+
+:root[style*=dark] .highlight .nc {
+  color: #a6e22e
+}
+
+
+/* Name.Class */
+
+:root[style*=dark] .highlight .no {
+  color: #66d9ef
+}
+
+
+/* Name.Constant */
+
+:root[style*=dark] .highlight .nd {
+  color: #a6e22e
+}
+
+
+/* Name.Decorator */
+
+:root[style*=dark] .highlight .ni {
+  color: #f8f8f2
+}
+
+
+/* Name.Entity */
+
+:root[style*=dark] .highlight .ne {
+  color: #a6e22e
+}
+
+
+/* Name.Exception */
+
+:root[style*=dark] .highlight .nf {
+  color: #a6e22e
+}
+
+
+/* Name.Function */
+
+:root[style*=dark] .highlight .nl {
+  color: #f8f8f2
+}
+
+
+/* Name.Label */
+
+:root[style*=dark] .highlight .nn {
+  color: #f8f8f2
+}
+
+
+/* Name.Namespace */
+
+:root[style*=dark] .highlight .nx {
+  color: #a6e22e
+}
+
+
+/* Name.Other */
+
+:root[style*=dark] .highlight .py {
+  color: #f8f8f2
+}
+
+
+/* Name.Property */
+
+:root[style*=dark] .highlight .nt {
+  color: #f92672
+}
+
+
+/* Name.Tag */
+
+:root[style*=dark] .highlight .nv {
+  color: #f8f8f2
+}
+
+
+/* Name.Variable */
+
+:root[style*=dark] .highlight .ow {
+  color: #f92672
+}
+
+
+/* Operator.Word */
+
+:root[style*=dark] .highlight .w {
+  color: #f8f8f2
+}
+
+
+/* Text.Whitespace */
+
+:root[style*=dark] .highlight .mb {
+  color: #ae81ff
+}
+
+
+/* Literal.Number.Bin */
+
+:root[style*=dark] .highlight .mf {
+  color: #ae81ff
+}
+
+
+/* Literal.Number.Float */
+
+:root[style*=dark] .highlight .mh {
+  color: #ae81ff
+}
+
+
+/* Literal.Number.Hex */
+
+:root[style*=dark] .highlight .mi {
+  color: #ae81ff
+}
+
+
+/* Literal.Number.Integer */
+
+:root[style*=dark] .highlight .mo {
+  color: #ae81ff
+}
+
+
+/* Literal.Number.Oct */
+
+:root[style*=dark] .highlight .sa {
+  color: #e6db74
+}
+
+
+/* Literal.String.Affix */
+
+:root[style*=dark] .highlight .sb {
+  color: #e6db74
+}
+
+
+/* Literal.String.Backtick */
+
+:root[style*=dark] .highlight .sc {
+  color: #e6db74
+}
+
+
+/* Literal.String.Char */
+
+:root[style*=dark] .highlight .dl {
+  color: #e6db74
+}
+
+
+/* Literal.String.Delimiter */
+
+:root[style*=dark] .highlight .sd {
+  color: #e6db74
+}
+
+
+/* Literal.String.Doc */
+
+:root[style*=dark] .highlight .s2 {
+  color: #e6db74
+}
+
+
+/* Literal.String.Double */
+
+:root[style*=dark] .highlight .se {
+  color: #ae81ff
+}
+
+
+/* Literal.String.Escape */
+
+:root[style*=dark] .highlight .sh {
+  color: #e6db74
+}
+
+
+/* Literal.String.Heredoc */
+
+:root[style*=dark] .highlight .si {
+  color: #e6db74
+}
+
+
+/* Literal.String.Interpol */
+
+:root[style*=dark] .highlight .sx {
+  color: #e6db74
+}
+
+
+/* Literal.String.Other */
+
+:root[style*=dark] .highlight .sr {
+  color: #e6db74
+}
+
+
+/* Literal.String.Regex */
+
+:root[style*=dark] .highlight .s1 {
+  color: #e6db74
+}
+
+
+/* Literal.String.Single */
+
+:root[style*=dark] .highlight .ss {
+  color: #e6db74
+}
+
+
+/* Literal.String.Symbol */
+
+:root[style*=dark] .highlight .bp {
+  color: #f8f8f2
+}
+
+
+/* Name.Builtin.Pseudo */
+
+:root[style*=dark] .highlight .fm {
+  color: #a6e22e
+}
+
+
+/* Name.Function.Magic */
+
+:root[style*=dark] .highlight .vc {
+  color: #f8f8f2
+}
+
+
+/* Name.Variable.Class */
+
+:root[style*=dark] .highlight .vg {
+  color: #f8f8f2
+}
+
+
+/* Name.Variable.Global */
+
+:root[style*=dark] .highlight .vi {
+  color: #f8f8f2
+}
+
+
+/* Name.Variable.Instance */
+
+:root[style*=dark] .highlight .vm {
+  color: #f8f8f2
+}
+
+
+/* Name.Variable.Magic */
+
+:root[style*=dark] .highlight .il {
+  color: #ae81ff
+}
+
+
+/* Grammar */
+
+:root[style*=dark] .railroad-diagram {
+  fill: white;
+}
+
+:root[style*=dark] .railroad-diagram path {
+  stroke: white;
+}
+
+:root[style*=dark] .railroad-diagram rect {
+  stroke: white;
+}
+
+:root[style*=dark] .a4 .sig-name {
+  background-color: transparent !important;
+}

docs/_static/css/custom.css

@@ -1,23 +1,185 @@
-pre {
-    white-space: pre-wrap;       /* css-3 */
-    white-space: -moz-pre-wrap;  /* Mozilla, since 1999 */
-    white-space: -pre-wrap;      /* Opera 4-6 */
-    white-space: -o-pre-wrap;    /* Opera 7 */
-    word-wrap: break-word;
+/* ROOT DECLARATIONS */
+:root {
+    /* Text */
+    --color-a: #2B247C;
+    --color-b: #672AC8;
+    --color-c: #5554D9;
+    --color-d: #9F94E8;
+    --color-e: #AEC0F1;
+    --color-f: #E6E3EC;
+    /* Background */
+
+    --white: #FAF8FF;
+    --black: #110C4E;
+    --menu-bg: #2B247C06;
+    --shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06);
+
+    --navHeight: 4.5rem;
+    --sideWidth: 300px;
+    --maxWidth: 80rem;
+    --desktopInlinePadding: 2rem;
+    --mobileInlinePadding: 1rem;
+    --currentVersionHeight: 45px;
+
+    text-rendering: geometricPrecision;
+    -webkit-font-smoothing: antialiased;
 }
 
-.wy-table-responsive table td, .wy-table-responsive table th {
+a,
+button {
+    border-radius: 0;
+}
+
+:root[style*=dark] {
+    --color-a: #E6E3EC !important;
+    --color-b: #AEC0F1 !important;
+    --color-c: #9F94E8 !important;
+    --color-d: #5554D9 !important;
+    --color-e: #672AC8 !important;
+    --color-f: #2B247C !important;
+
+    --white: #110C4E !important;
+    --black: #FAF8FF !important;
+    --menu-bg: #E6E3EC06 !important;
+}
+
+html,
+body,
+.unified-header::before,
+.wy-nav-side,
+.rst-versions,
+code,
+div,
+input[type=text],
+a,
+.wy-grid-for-nav {
+    transition: background 150ms ease-in-out;
+}
+
+html,
+body,
+.wy-grid-for-nav {
+    background-color: var(--color-f) !important;
+}
+
+body {
+    font-family: "Overpass", sans-serif;
+}
+
+a {
+    color: var(--color-c);
+}
+
+a, section {
+    scroll-margin-top: calc(var(--navHeight) + 2rem);
+}
+
+hr {
+    margin-block: 2rem;
+    border-color: var(--color-d) !important;
+}
+
+
+/* HEADER STYLES */
+h1 {
+    font-family: 'Overpass', sans-serif;
+    font-weight: 700;
+    font-size: 44px;
+    color: var(--color-a) !important;
+    line-height: 1.1;
+    text-wrap: balance;
+    margin-top: 4rem;
+    margin-bottom: 1.5rem;
+}
+
+section:first-of-type h1:first-of-type {
+    font-family: 'Overpass mono', monospace;
+    font-size: 48px;
+    margin-top: 3rem;
+    margin-bottom: 5rem;
+}
+
+h2 {
+    font-family: 'Overpass', sans-serif;
+    font-weight: 700;
+    font-size: 38px;
+    color: var(--color-a) !important;
+    line-height: 46px;
+    text-wrap: balance;
+    margin-top: 4rem;
+    margin-bottom: 1.5rem;
+}
+
+*:not([role=navigation])>p[role=heading]>span,
+h3 {
+    font-family: 'Overpass', sans-serif;
+    font-weight: 700;
+    font-size: 32px;
+    color: var(--color-a) !important;
+    line-height: 46px;
+    text-wrap: balance;
+    margin-top: 4rem;
+    margin-bottom: 1.5rem;
+}
+
+h4 {
+    font-family: 'Overpass', sans-serif;
+    font-weight: 700;
+    font-size: 32px;
+    color: var(--color-a) !important;
+    line-height: 46px;
+    text-wrap: balance;
+    margin-top: 3rem;
+    margin-bottom: 1.5rem;
+}
+
+h5 {
+    font-family: 'Overpass', sans-serif;
+    font-weight: 700;
+    font-size: 18px;
+    color: var(--color-a) !important;
+    line-height: 1.4;
+    text-wrap: balance;
+}
+
+h6 {
+    font-family: 'Overpass', sans-serif;
+    font-weight: 700;
+    font-size: 16px;
+    color: var(--color-a) !important;
+    line-height: 1.4;
+    text-wrap: balance;
+}
+
+span.pre,
+pre {
+    /* css-3 */
+    white-space: pre-wrap;
+    /* Mozilla, since 1999 */
+    white-space: -moz-pre-wrap;
+    /* Opera 4-6 */
+    white-space: -pre-wrap;
+    /* Opera 7 */
+    white-space: -o-pre-wrap;
+    word-wrap: break-word;
+    font-family: 'Overpass Mono', monospace;
+}
+
+small,
+small * {
+    font-size: 12px;
+}
+
+.wy-table-responsive table td,
+.wy-table-responsive table th {
     white-space: normal;
 }
+
 .rst-content table.docutils td {
     vertical-align: top;
 }
 
 /* links */
-.rst-content a:not(:visited) {
-    color: #002fa7;
-}
-
 .rst-content .highlighted {
     background: #eac545;
 }
@@ -27,60 +189,638 @@ pre {
     background: #fafafa;
 }
 
-.wy-side-nav-search img.logo {
-    width: 100px !important;
-    padding: 0;
-}
-
-.wy-side-nav-search > a {
-    padding: 0;
-    margin: 0;
-}
-
 /* project version (displayed under project logo) */
-.wy-side-nav-search .version {
-    color: #272525 !important;
-}
-
-/* menu section headers */
-.wy-menu .caption {
-    color: #65afff !important;
+.wy-side-nav-search>div.version {
+    color: var(--color-b);
+    margin-top: 0;
+    margin-bottom: 0.5rem;
+    text-align: start;
 }
 
 /* Link to Remix IDE shown next to code snippets */
-p.remix-link-container {
-    position: relative;
-    right: -100%;        /* Positioned next to the the top-right corner of the code block following it. */
-}
-
-a.remix-link {
-    position: absolute;  /* Remove it from normal flow not to affect the original position of the snippet. */
-    top: 0.5em;
-    width: 3.236em;      /* Size of the margin (= right-side padding in .wy-nav-content in the current theme). */
-}
-
-a.remix-link .link-icon {
-    background: url("../img/solid-share-arrow.svg") no-repeat;
+.rst-content p.remix-link-container {
     display: block;
-    width: 1.5em;
-    height: 1.5em;
-    margin: auto;
+    text-align: right;
+    margin: 0;
+    line-height: 1em;
 }
 
-a.remix-link .link-text {
-    display: none;       /* Visible only on hover. */
-    width: 3.3em;        /* Narrow enough to get two lines of text. */
-    margin: auto;
-    text-align: center;
-    font-size: 0.8em;
-    line-height: normal;
-    color: black;
+.rst-content .remix-link-container a.remix-link {
+    font-size: 0.7em;
+    padding: 0.1em 0.5em;
+    background: transparent;
+    color: var(--color-a) !important;
+    border: 1px solid var(--color-a);
+    text-decoration: none;
 }
 
-a.remix-link:hover {
+.rst-content div.highlight-solidity,
+.rst-content div.highlight-yul {
+    margin-top: 0;
+}
+
+/* CUSTOMIZATION UPDATES */
+
+.wy-nav-content-wrap,
+.wy-nav-content {
+    background: transparent !important;
+}
+
+.wy-side-nav-search {
+    background-color: transparent !important;
+    color: var(--color-a) !important;
+    box-shadow: 0 4 4 0 var(--color-a);
+    border-bottom: 1px solid var(--color-d) !important;
+}
+
+.wy-side-nav-search svg {
+    color: var(--color-a) !important;
+}
+
+.wy-nav-top {
+    background-color: transparent !important;
+    color: var(--color-a) !important;
+}
+
+.wy-nav-top a {
+    color: var(--color-a) !important;
+}
+
+.wy-breadcrumbs a.icon-home:before {
+    content: "Documentation";
+    font-family: "Overpass", sans-serif;
+}
+
+.rst-content table.docutils thead {
+    color: var(--color-a);
+}
+
+code.docutils.literal.notranslate {
+    padding: 2px 4px;
+    font-size: 0.875em;
+    font-family: "Overpass Mono", monospace;
+    background: var(--white);
+    color: var(--color-c);
+    border: 0px;
+}
+
+dt code.docutils.literal.notranslate {
+    background: none;
+}
+
+.wy-nav-content {
+    color: var(--color-a);
+}
+
+/* .rst-content a:not(:visited) { */
+/* color: var(--color-b) !important; */
+/* } */
+
+.rst-content a:visited {
+    color: var(--color-c) !important;
+}
+
+.rst-content a {
+    text-decoration: underline;
+}
+
+.rst-content a:where(:focus, :focus-visible, :hover) {
+    color: var(--color-d) !important;
+}
+
+.wy-side-scroll a {
+    color: var(--color-a);
+    background: transparent;
+    font-size: 1rem;
+    line-height: 125%;
+}
+
+.wy-menu-vertical li.current a,
+.wy-menu-vertical li.current li a,
+.wy-menu-vertical li.current li a code {
+    border: none;
+    color: var(--color-a);
+}
+
+ul.current ul,
+.wy-menu-vertical li.current a:hover,
+.wy-menu-vertical li.toctree-l2.current li.toctree-l3>a,
+.wy-menu-vertical li.toctree-l3.current li.toctree-l4>a,
+.wy-menu-vertical li.toctree-l4.current li.toctree-l5>a,
+.wy-menu-vertical li.toctree-l5.current li.toctree-l6>a,
+.wy-menu-vertical li.current {
+    background: var(--menu-bg) !important;
+}
+
+.wy-menu.wy-menu-vertical>ul {
+    margin-bottom: 3rem;
+}
+
+.wy-menu.wy-menu-vertical>p {
+    color: var(--color-c);
+}
+
+.wy-menu-vertical li.on a,
+.wy-menu-vertical li.current>a {
+    background: var(--menu-bg) !important;
+    border-bottom: 0px !important;
+    border-top: 0px !important;
+}
+
+.btn {
+    border-radius: 0;
+    text-decoration: none !important;
+}
+
+.wy-breadcrumbs-aside a,
+.wy-breadcrumbs-aside a:visited,
+a.fa.fa-github,
+a.fa.fa-github:visited,
+a.fa.fa-github:not(:visited),
+a.btn.btn-neutral:visited,
+a.btn.btn-neutral:not(:visited),
+a.btn.btn-neutral {
+    background: transparent !important;
+    color: var(--color-a) !important;
+    border: 2px solid var(--color-a) !important;
+    text-decoration: none;
+}
+
+.rst-content .remix-link-container a.remix-link:hover,
+.wy-breadcrumbs-aside a:hover,
+a.fa.fa-github:hover,
+a.btn.btn-neutral:hover {
+    background: var(--white) !important;
+    color: var(--color-b) !important;
+    border-color: var(--color-b) !important;
+}
+
+footer .rst-footer-buttons {
+    display: flex;
+    justify-content: center;
+    gap: 2rem;
+}
+
+/**
+ * Customization for the unified layout
+ */
+
+/* Site wrapper, and two children: header and rest */
+.unified-wrapper {
+    position: relative;
+    display: flex;
+    flex-direction: column;
+    inset: 0;
+    max-width: var(--maxWidth);
+    margin-inline: auto;
+}
+
+/* Site header */
+.unified-header {
+    position: fixed;
+    top: 0;
+    inset-inline: 0;
+    z-index: 99999;
+    display: flex;
+    align-items: center;
+    box-shadow: var(--shadow);
+}
+
+.unified-header .inner-header {
+    display: flex;
+    margin-inline: auto;
+    width: 100%;
+    max-width: var(--maxWidth);
+    align-items: center;
+    justify-content: space-between;
+    padding-inline: var(--desktopInlinePadding);
+    padding-block: 1rem;
+}
+
+.unified-header::before {
+    content: "";
+    position: absolute;
+    inset: 0;
+    opacity: 95%;
+    background: var(--color-f);
+    z-index: -1;
+    backdrop-filter: blur(3px);
+}
+
+.unified-header .home-link {
+    display: block;
+    text-decoration: none;
+    width: 25px;
+    height: 40px;
+}
+
+.unified-header .home-link:hover .solidity-logo {
+    transform: scale(1.1);
+    transition: transform 100ms ease-in-out;
+}
+
+.unified-header img.solidity-logo {
+    transform: scale(1);
+    transition: transform 100ms ease-in-out;
+    width: 100%;
+    height: 100%;
+}
+
+.unified-header .nav-bar {
+    display: flex;
+    align-items: center;
+    justify-content: flex-end;
+}
+
+.unified-header .nav-bar .nav-button-container {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: 0.5rem;
+}
+
+.unified-header .nav-link {
+    display: inline-block;
+    padding-inline: 8px;
+    padding-block: 4px;
+    font-size: 14px;
+    font-family: 'Overpass Mono', monospace;
+    text-decoration: none;
+    color: var(--color-a);
+    letter-spacing: -0.02em;
+    font-weight: 400;
+    box-sizing: content-box;
+    border-bottom: 1px solid transparent;
+    white-space: nowrap;
+}
+
+.unified-header .nav-link.active {
+    background: var(--white);
+}
+
+.unified-header .nav-link:hover {
+    color: var(--color-c);
+    border-bottom: 1px solid var(--color-c);
+}
+
+/* Rest: Flex-row, with two children: side bar, and content */
+.unified-wrapper .wy-grid-for-nav {
+    position: relative !important;
+    display: flex;
+    margin-inline: auto;
+}
+
+/* First child: Side bar */
+.unified-wrapper .wy-grid-for-nav nav.wy-nav-side {
+    position: fixed;
+    display: flex;
+    flex-direction: column;
+    background: var(--color-f);
+    color: var(--color-a);
+    padding-bottom: unset !important;
+    z-index: 10 !important;
+    min-height: unset !important;
+    width: var(--sideWidth) !important;
+    top: var(--navHeight);
+    bottom: 0;
+    left: auto;
+    overflow: auto;
+}
+
+.unified-wrapper .wy-grid-for-nav nav.wy-nav-side .wy-side-scroll {
+    position: static !important;
+    width: unset !important;
+    overflow: unset !important;
+    height: unset !important;
+    padding-bottom: 2rem;
+}
+
+.unified-wrapper .wy-grid-for-nav nav.wy-nav-side .wy-side-scroll .wy-side-nav-search {
+    margin: 0 !important;
+    width: var(--sideWidth) !important;
+}
+
+.wy-nav-side,
+.wy-side-scroll,
+.wy-side-nav-search,
+.my-menu {
+    width: 100% !important;
+}
+
+.wy-nav-side input[type=text] {
+    font-family: "Overpass", sans-serif;
+    border-radius: 0;
+    border-color: var(--color-d);
+    background: var(--white);
+    box-shadow: none;
+    color: var(--color-a);
+}
+
+.wy-nav-side input[type=text]::placeholder {
+    font-family: "Overpass", sans-serif;
+    color: var(--color-e);
+    font-size: 16px;
+    position: relative;
+    top: 4px;
+}
+
+/* Second child: Content */
+.unified-wrapper .wy-grid-for-nav .wy-nav-content {
+    width: 100%;
+    max-width: unset !important; /* override */
+    padding-inline: var(--desktopInlinePadding);
+    margin-inline-start: var(--sideWidth);
+    margin-top: var(--navHeight);
+}
+
+.unified-wrapper .wy-grid-for-nav .wy-nav-content .rst-content {
+    max-width: min(70ch, calc(100vw -  2 * var(--desktopInlinePadding) - var(--sideWidth)));
+    margin-inline: auto;
+}
+
+.unified-wrapper.menu-open .backdrop {
     opacity: 0.5;
 }
 
-a.remix-link:hover .link-text {
-    display: block;
+.unified-wrapper .wy-nav-side,
+.unified-wrapper .rst-versions {
+    left: auto;
+
 }
+
+.unified-wrapper .backdrop {
+    opacity: 0;
+    transition: opacity 200ms ease-in-out;
+}
+
+@media (max-width: 768px) {
+    h2 {
+        margin-top: 3rem;
+        margin-bottom: 1rem;
+    }
+
+    h3 {
+        margin-top: 3rem;
+        margin-bottom: 1rem;
+    }
+
+    h4 {
+        margin-top: 2rem;
+        margin-bottom: 1rem;
+    }
+
+    /* Menu closed styles */
+    .unified-header .nav-link {
+        display: none;
+    }
+
+    .unified-header .inner-header {
+        padding-inline: var(--mobileInlinePadding);
+    }
+
+    .unified-wrapper .wy-grid-for-nav nav.wy-nav-side {
+        transform: translateX(-100%);
+        transition: transform 200ms ease-in-out;
+    }
+
+    /* Menu open styles */
+    .unified-wrapper.menu-open nav.wy-nav-side {
+        transform: translateX(0);
+        transition: transform 200ms ease-in-out;
+    }
+
+    .unified-wrapper.menu-open .rst-versions {
+        position: sticky;
+        bottom: 0;
+        width: 100%;
+    }
+
+    .unified-wrapper.menu-open .backdrop {
+        display: block;
+        position: fixed;
+        inset: 0;
+        opacity: 1;
+        transition: opacity 200ms ease-in-out;
+        z-index: 5;
+        background: #0006;
+    }
+
+    a.skip-to-content {
+        display: none;
+    }
+
+    .wy-nav-content {
+        margin-inline-start: 0 !important;
+    }
+
+    .rst-content {
+        max-width: 100% !important;
+    }
+
+    .wy-side-scroll {
+        padding-bottom: 0 !important;
+    }
+}
+
+ul.search .context {
+    color: var(--color-a) !important;
+}
+
+.rst-versions {
+    background: var(--color-f);
+}
+
+.rst-versions.shift-up {
+    height: unset !important;
+    max-height: unset !important;
+    overflow-y: unset !important;
+}
+
+.rst-content dl:not(.docutils) dt {
+    color: var(--color-a);
+    background-color: #fff8;
+    border-top: solid 3px #0002;
+    border-inline-start: solid 3px #0002;
+    padding: 2px 6px;
+}
+
+.rst-versions .rst-current-version {
+    border-color: var(--color-d) !important;
+}
+
+.rst-current-version *,
+.rst-current-version .fa:before,
+.rst-current-version .fa-element {
+    color: var(--color-b) !important;
+}
+
+.rst-current-version dt,
+.rst-current-version dd,
+.rst-current-version dd a,
+.rst-other-versions dl:last-of-type dt,
+.rst-other-versions dl:last-of-type dd,
+.rst-other-versions dl:last-of-type dd a {
+    font-size: 14px !important;
+}
+
+.rst-other-versions {
+    background: var(--white) !important;
+    color: var(--color-a) !important;
+    max-height: calc(100vh - var(--navHeight) - var(--currentVersionHeight));
+    overflow-y: scroll;
+}
+
+.rst-other-versions a {
+    text-decoration: underline;
+    color: var(--color-c) !important;
+}
+
+.rst-other-versions dt {
+    color: var(--color-a) !important;
+}
+
+.rst-other-versions dl {
+    margin-bottom: 1.5rem !important;
+}
+
+.rst-other-versions dl:last-of-type {
+    margin-top: 2rem !important;
+}
+
+/* Bottom Search */
+.wy-nav-side input[type=text],
+.rst-other-versions dl:last-of-type dd {
+    width: 100%;
+}
+
+.rst-other-versions dl:last-of-type dt {
+    color: var(--color-b) !important;
+}
+
+.rst-other-versions dl:last-of-type div[style*=padding],
+.rst-other-versions dl dd:first-of-type a {
+    padding-inline-start: 0 !important;
+}
+
+button.toctree-expand {
+    color: var(--black) !important;
+}
+
+/* Light/dark color mode toggle 🌓 */
+button.color-toggle {
+    display: inline-flex;
+    appearance: none;
+    -webkit-box-align: center;
+    align-items: center;
+    -webkit-box-pack: center;
+    justify-content: center;
+    user-select: none;
+    outline: none;
+    height: 28px;
+    width: 28px;
+    background: none;
+    border: none;
+    padding: 6px;
+    margin: 6px;
+    transition-duration: 200ms;
+    transition-property: background-color,
+        color,
+        fill,
+        stroke,
+        opacity;
+}
+
+button.color-toggle:focus-visible {
+    outline: 2px solid var(--color-c);
+    color: var(--color-c);
+}
+
+button.color-toggle:hover {
+    color: var(--color-c);
+    background: #0002;
+}
+
+button.color-toggle .color-toggle-icon {
+    width: 100%;
+    height: 100%;
+    margin: 0;
+    display: inline-block;
+    line-height: 1em;
+    -webkit-flex-shrink: 0;
+    -ms-flex-negative: 0;
+    flex-shrink: 0;
+    vertical-align: middle;
+    /* color: var(--color-a); */
+}
+
+
+button.mobile-menu-button {
+    display: none;
+}
+
+@media (max-width: 768px) {
+    nav.wy-nav-top {
+        display: none;
+    }
+
+    button.mobile-menu-button {
+        display: flex;
+    }
+}
+
+
+.hidden {
+    display: none;
+}
+
+#search-results .search li:first-child,
+#search-results .search li {
+    border-color: var(--color-d);
+}
+
+#search-results .search li:last-child {
+    border: 0px;
+}
+
+.forum-link::after {
+    content: ' ↗';
+    font-size: 14px;
+    font-family: 'Overpass Mono', monospace;
+}
+
+.wy-breadcrumbs>li {
+    padding-top: 8px;
+}
+
+.wy-breadcrumbs-aside a {
+    padding: 0.5rem 0.75rem;
+    font-size: 12px;
+    font-family: "'Overpass'", sans-serif;
+    font-weight: 700;
+}
+
+a.skip-to-content:visited,
+a.skip-to-content:not(:visited),
+a.skip-to-content {
+    display: block;
+    pointer-events: none;
+    width: fit-content;
+    opacity: 0;
+    transition: opacity 200ms ease-in-out;
+    padding: 2px 4px;
+    font-size: 14px;
+    margin-inline-end: auto;
+    margin-inline-start: 1.5rem;
+    color: var(--color-a);
+    white-space: nowrap;
+}
+
+a.skip-to-content:focus {
+    opacity: 1;
+    transition: opacity 200ms ease-in-out;
+}
+
+#content {
+    scroll-margin-top: 6rem;
+    scroll-behavior: smooth;
+}

docs/_static/css/dark.css

@@ -1,635 +0,0 @@
-/* links */
-
-.rst-content a:not(:visited) {
-    color: #aaddff !important;
-}
-
-/* code directives */
-
-.method dt,
-.class dt,
-.data dt,
-.attribute dt,
-.function dt,
-.classmethod dt,
-.exception dt,
-.descclassname,
-.descname {
-    background-color: #2d2d2d !important;
-}
-
-.rst-content dl:not(.docutils) dt {
-    color: #aaddff;
-    background-color: #2d2d2d;
-    border-top: solid 3px #525252;
-    border-left: solid 3px #525252;
-}
-
-em.property {
-    color: #888888;
-}
-
-
-/* tables */
-
-.rst-content table.docutils thead {
-    color: #ddd;
-}
-
-.rst-content table.docutils td {
-    border: 0px;
-}
-
-.rst-content table.docutils:not(.field-list) tr:nth-child(2n-1) td {
-    background-color: #5a5a5a;
-}
-
-.rst-content pre {
-    background: none;
-}
-
-/* inlined code highlights */
-
-.xref,
-.py-meth,
-.rst-content a code {
-    color: #aaddff !important;
-    font-weight: normal !important;
-}
-
-.rst-content code {
-    color: #eee !important;
-    font-weight: normal !important;
-}
-
-code.literal {
-    background-color: #2d2d2d !important;
-    border: 1px solid #6d6d6d !important;
-}
-
-code.docutils.literal.notranslate {
-    color: #ddd;
-}
-
-/* highlight color search text */
-
-.rst-content .highlighted {
-    background: #ff5722;
-    box-shadow: 0 0 0 2px #f0978b;
-}
-
-/* notes, warnings, hints */
-
-.hint .admonition-title {
-    background: #2aa87c !important;
-}
-
-.warning .admonition-title {
-    background: #cc4444 !important;
-}
-
-.admonition-title {
-    background: #3a7ca8 !important;
-}
-
-.admonition,
-.note {
-    background-color: #2d2d2d !important;
-}
-
-
-/* table of contents */
-
-.wy-nav-content-wrap {
-    background-color: rgba(0, 0, 0, 0.6) !important;
-}
-
-.sidebar {
-    background-color: #191919 !important;
-}
-
-.sidebar-title {
-    background-color: #2b2b2b !important;
-}
-
-.wy-menu-vertical a {
-    color: #ddd;
-}
-
-.wy-menu-vertical code.docutils.literal.notranslate {
-    color: #404040;
-    background: none !important;
-    border: none !important;
-}
-
-.wy-nav-content {
-    background: #3c3c3c;
-    color: #dddddd;
-}
-
-.wy-menu-vertical li.on a,
-.wy-menu-vertical li.current>a {
-    background: #a3a3a3;
-    border-bottom: 0px !important;
-    border-top: 0px !important;
-}
-
-.wy-menu-vertical li.current {
-    background: #b3b3b3;
-}
-
-.toc-backref {
-    color: grey !important;
-}
-
-.highlight .hll {
-    background-color: #49483e
-}
-
-.highlight {
-    background: #222;
-    color: #f8f8f2
-}
-
-.highlight .c {
-    color: #888
-}
-
-
-/* Comment */
-
-.highlight .err {
-    color: #960050;
-    background-color: #1e0010
-}
-
-
-/* Error */
-
-.highlight .k {
-    color: #66d9ef
-}
-
-
-/* Keyword */
-
-.highlight .l {
-    color: #ae81ff
-}
-
-
-/* Literal */
-
-.highlight .n {
-    color: #f8f8f2
-}
-
-
-/* Name */
-
-.highlight .o {
-    color: #f92672
-}
-
-
-/* Operator */
-
-.highlight .p {
-    color: #f8f8f2
-}
-
-
-/* Punctuation */
-
-.highlight .ch {
-    color: #888
-}
-
-
-/* Comment.Hashbang */
-
-.highlight .cm {
-    color: #888
-}
-
-
-/* Comment.Multiline */
-
-.highlight .cp {
-    color: #888
-}
-
-
-/* Comment.Preproc */
-
-.highlight .cpf {
-    color: #888
-}
-
-
-/* Comment.PreprocFile */
-
-.highlight .c1 {
-    color: #888
-}
-
-
-/* Comment.Single */
-
-.highlight .cs {
-    color: #888
-}
-
-
-/* Comment.Special */
-
-.highlight .gd {
-    color: #f92672
-}
-
-
-/* Generic.Deleted */
-
-.highlight .ge {
-    font-style: italic
-}
-
-
-/* Generic.Emph */
-
-.highlight .gi {
-    color: #a6e22e
-}
-
-
-/* Generic.Inserted */
-
-.highlight .gs {
-    font-weight: bold
-}
-
-
-/* Generic.Strong */
-
-.highlight .gu {
-    color: #888
-}
-
-
-/* Generic.Subheading */
-
-.highlight .kc {
-    color: #66d9ef
-}
-
-
-/* Keyword.Constant */
-
-.highlight .kd {
-    color: #66d9ef
-}
-
-
-/* Keyword.Declaration */
-
-.highlight .kn {
-    color: #f92672
-}
-
-
-/* Keyword.Namespace */
-
-.highlight .kp {
-    color: #66d9ef
-}
-
-
-/* Keyword.Pseudo */
-
-.highlight .kr {
-    color: #66d9ef
-}
-
-
-/* Keyword.Reserved */
-
-.highlight .kt {
-    color: #66d9ef
-}
-
-
-/* Keyword.Type */
-
-.highlight .ld {
-    color: #e6db74
-}
-
-
-/* Literal.Date */
-
-.highlight .m {
-    color: #ae81ff
-}
-
-
-/* Literal.Number */
-
-.highlight .s {
-    color: #e6db74
-}
-
-
-/* Literal.String */
-
-.highlight .na {
-    color: #a6e22e
-}
-
-
-/* Name.Attribute */
-
-.highlight .nb {
-    color: #f8f8f2
-}
-
-
-/* Name.Builtin */
-
-.highlight .nc {
-    color: #a6e22e
-}
-
-
-/* Name.Class */
-
-.highlight .no {
-    color: #66d9ef
-}
-
-
-/* Name.Constant */
-
-.highlight .nd {
-    color: #a6e22e
-}
-
-
-/* Name.Decorator */
-
-.highlight .ni {
-    color: #f8f8f2
-}
-
-
-/* Name.Entity */
-
-.highlight .ne {
-    color: #a6e22e
-}
-
-
-/* Name.Exception */
-
-.highlight .nf {
-    color: #a6e22e
-}
-
-
-/* Name.Function */
-
-.highlight .nl {
-    color: #f8f8f2
-}
-
-
-/* Name.Label */
-
-.highlight .nn {
-    color: #f8f8f2
-}
-
-
-/* Name.Namespace */
-
-.highlight .nx {
-    color: #a6e22e
-}
-
-
-/* Name.Other */
-
-.highlight .py {
-    color: #f8f8f2
-}
-
-
-/* Name.Property */
-
-.highlight .nt {
-    color: #f92672
-}
-
-
-/* Name.Tag */
-
-.highlight .nv {
-    color: #f8f8f2
-}
-
-
-/* Name.Variable */
-
-.highlight .ow {
-    color: #f92672
-}
-
-
-/* Operator.Word */
-
-.highlight .w {
-    color: #f8f8f2
-}
-
-
-/* Text.Whitespace */
-
-.highlight .mb {
-    color: #ae81ff
-}
-
-
-/* Literal.Number.Bin */
-
-.highlight .mf {
-    color: #ae81ff
-}
-
-
-/* Literal.Number.Float */
-
-.highlight .mh {
-    color: #ae81ff
-}
-
-
-/* Literal.Number.Hex */
-
-.highlight .mi {
-    color: #ae81ff
-}
-
-
-/* Literal.Number.Integer */
-
-.highlight .mo {
-    color: #ae81ff
-}
-
-
-/* Literal.Number.Oct */
-
-.highlight .sa {
-    color: #e6db74
-}
-
-
-/* Literal.String.Affix */
-
-.highlight .sb {
-    color: #e6db74
-}
-
-
-/* Literal.String.Backtick */
-
-.highlight .sc {
-    color: #e6db74
-}
-
-
-/* Literal.String.Char */
-
-.highlight .dl {
-    color: #e6db74
-}
-
-
-/* Literal.String.Delimiter */
-
-.highlight .sd {
-    color: #e6db74
-}
-
-
-/* Literal.String.Doc */
-
-.highlight .s2 {
-    color: #e6db74
-}
-
-
-/* Literal.String.Double */
-
-.highlight .se {
-    color: #ae81ff
-}
-
-
-/* Literal.String.Escape */
-
-.highlight .sh {
-    color: #e6db74
-}
-
-
-/* Literal.String.Heredoc */
-
-.highlight .si {
-    color: #e6db74
-}
-
-
-/* Literal.String.Interpol */
-
-.highlight .sx {
-    color: #e6db74
-}
-
-
-/* Literal.String.Other */
-
-.highlight .sr {
-    color: #e6db74
-}
-
-
-/* Literal.String.Regex */
-
-.highlight .s1 {
-    color: #e6db74
-}
-
-
-/* Literal.String.Single */
-
-.highlight .ss {
-    color: #e6db74
-}
-
-
-/* Literal.String.Symbol */
-
-.highlight .bp {
-    color: #f8f8f2
-}
-
-
-/* Name.Builtin.Pseudo */
-
-.highlight .fm {
-    color: #a6e22e
-}
-
-
-/* Name.Function.Magic */
-
-.highlight .vc {
-    color: #f8f8f2
-}
-
-
-/* Name.Variable.Class */
-
-.highlight .vg {
-    color: #f8f8f2
-}
-
-
-/* Name.Variable.Global */
-
-.highlight .vi {
-    color: #f8f8f2
-}
-
-
-/* Name.Variable.Instance */
-
-.highlight .vm {
-    color: #f8f8f2
-}
-
-
-/* Name.Variable.Magic */
-
-.highlight .il {
-    color: #ae81ff
-}
-
-
-/* Literal.Number.Integer.Long */
-
-
-/* Link to Remix IDE shown over code snippets */
-a.remix-link {
-    filter: invert(1); /* The icon is black. In dark mode we want it white. */
-}

docs/_static/css/fonts.css

@@ -0,0 +1,2 @@
+@import url("https://fonts.cdnfonts.com/css/overpass");
+@import url("https://fonts.cdnfonts.com/css/overpass-mono");

docs/_static/css/pygments.css

@@ -0,0 +1,399 @@
+pre {
+  line-height: 125%;
+}
+
+td.linenos .normal {
+  color: inherit;
+  background-color: transparent;
+  padding-left: 5px;
+  padding-right: 5px;
+}
+
+span.linenos {
+  color: inherit;
+  background-color: transparent;
+  padding-left: 5px;
+  padding-right: 5px;
+}
+
+td.linenos .special {
+  color: #000000;
+  background-color: #ffffc0;
+  padding-left: 5px;
+  padding-right: 5px;
+}
+
+span.linenos.special {
+  color: #000000;
+  background-color: #ffffc0;
+  padding-left: 5px;
+  padding-right: 5px;
+}
+
+.highlight .hll {
+  background-color: #ffffcc
+}
+
+.highlight {
+  background: #eeffcc;
+}
+
+.highlight .c {
+  color: #408090;
+  font-style: italic
+}
+
+/* Comment */
+.highlight .err {
+  border: 1px solid #FF0000
+}
+
+/* Error */
+.highlight .k {
+  color: #007020;
+  font-weight: bold
+}
+
+/* Keyword */
+.highlight .o {
+  color: #666666
+}
+
+/* Operator */
+.highlight .ch {
+  color: #408090;
+  font-style: italic
+}
+
+/* Comment.Hashbang */
+.highlight .cm {
+  color: #408090;
+  font-style: italic
+}
+
+/* Comment.Multiline */
+.highlight .cp {
+  color: #007020
+}
+
+/* Comment.Preproc */
+.highlight .cpf {
+  color: #408090;
+  font-style: italic
+}
+
+/* Comment.PreprocFile */
+.highlight .c1 {
+  color: #408090;
+  font-style: italic
+}
+
+/* Comment.Single */
+.highlight .cs {
+  color: #408090;
+  background-color: #fff0f0
+}
+
+/* Comment.Special */
+.highlight .gd {
+  color: #A00000
+}
+
+/* Generic.Deleted */
+.highlight .ge {
+  font-style: italic
+}
+
+/* Generic.Emph */
+.highlight .gr {
+  color: #FF0000
+}
+
+/* Generic.Error */
+.highlight .gh {
+  color: #000080;
+  font-weight: bold
+}
+
+/* Generic.Heading */
+.highlight .gi {
+  color: #00A000
+}
+
+/* Generic.Inserted */
+.highlight .go {
+  color: #333333
+}
+
+/* Generic.Output */
+.highlight .gp {
+  color: #c65d09;
+  font-weight: bold
+}
+
+/* Generic.Prompt */
+.highlight .gs {
+  font-weight: bold
+}
+
+/* Generic.Strong */
+.highlight .gu {
+  color: #800080;
+  font-weight: bold
+}
+
+/* Generic.Subheading */
+.highlight .gt {
+  color: #0044DD
+}
+
+/* Generic.Traceback */
+.highlight .kc {
+  color: #007020;
+  font-weight: bold
+}
+
+/* Keyword.Constant */
+.highlight .kd {
+  color: #007020;
+  font-weight: bold
+}
+
+/* Keyword.Declaration */
+.highlight .kn {
+  color: #007020;
+  font-weight: bold
+}
+
+/* Keyword.Namespace */
+.highlight .kp {
+  color: #007020
+}
+
+/* Keyword.Pseudo */
+.highlight .kr {
+  color: #007020;
+  font-weight: bold
+}
+
+/* Keyword.Reserved */
+.highlight .kt {
+  color: #902000
+}
+
+/* Keyword.Type */
+.highlight .m {
+  color: #208050
+}
+
+/* Literal.Number */
+.highlight .s {
+  color: #4070a0
+}
+
+/* Literal.String */
+.highlight .na {
+  color: #4070a0
+}
+
+/* Name.Attribute */
+.highlight .nb {
+  color: #007020
+}
+
+/* Name.Builtin */
+.highlight .nc {
+  color: #0e84b5;
+  font-weight: bold
+}
+
+/* Name.Class */
+.highlight .no {
+  color: #60add5
+}
+
+/* Name.Constant */
+.highlight .nd {
+  color: #555555;
+  font-weight: bold
+}
+
+/* Name.Decorator */
+.highlight .ni {
+  color: #d55537;
+  font-weight: bold
+}
+
+/* Name.Entity */
+.highlight .ne {
+  color: #007020
+}
+
+/* Name.Exception */
+.highlight .nf {
+  color: #06287e
+}
+
+/* Name.Function */
+.highlight .nl {
+  color: #002070;
+  font-weight: bold
+}
+
+/* Name.Label */
+.highlight .nn {
+  color: #0e84b5;
+  font-weight: bold
+}
+
+/* Name.Namespace */
+.highlight .nt {
+  color: #062873;
+  font-weight: bold
+}
+
+/* Name.Tag */
+.highlight .nv {
+  color: #bb60d5
+}
+
+/* Name.Variable */
+.highlight .ow {
+  color: #007020;
+  font-weight: bold
+}
+
+/* Operator.Word */
+.highlight .w {
+  color: #bbbbbb
+}
+
+/* Text.Whitespace */
+.highlight .mb {
+  color: #208050
+}
+
+/* Literal.Number.Bin */
+.highlight .mf {
+  color: #208050
+}
+
+/* Literal.Number.Float */
+.highlight .mh {
+  color: #208050
+}
+
+/* Literal.Number.Hex */
+.highlight .mi {
+  color: #208050
+}
+
+/* Literal.Number.Integer */
+.highlight .mo {
+  color: #208050
+}
+
+/* Literal.Number.Oct */
+.highlight .sa {
+  color: #4070a0
+}
+
+/* Literal.String.Affix */
+.highlight .sb {
+  color: #4070a0
+}
+
+/* Literal.String.Backtick */
+.highlight .sc {
+  color: #4070a0
+}
+
+/* Literal.String.Char */
+.highlight .dl {
+  color: #4070a0
+}
+
+/* Literal.String.Delimiter */
+.highlight .sd {
+  color: #4070a0;
+  font-style: italic
+}
+
+/* Literal.String.Doc */
+.highlight .s2 {
+  color: #4070a0
+}
+
+/* Literal.String.Double */
+.highlight .se {
+  color: #4070a0;
+  font-weight: bold
+}
+
+/* Literal.String.Escape */
+.highlight .sh {
+  color: #4070a0
+}
+
+/* Literal.String.Heredoc */
+.highlight .si {
+  color: #70a0d0;
+  font-style: italic
+}
+
+/* Literal.String.Interpol */
+.highlight .sx {
+  color: #c65d09
+}
+
+/* Literal.String.Other */
+.highlight .sr {
+  color: #235388
+}
+
+/* Literal.String.Regex */
+.highlight .s1 {
+  color: #4070a0
+}
+
+/* Literal.String.Single */
+.highlight .ss {
+  color: #517918
+}
+
+/* Literal.String.Symbol */
+.highlight .bp {
+  color: #007020
+}
+
+/* Name.Builtin.Pseudo */
+.highlight .fm {
+  color: #06287e
+}
+
+/* Name.Function.Magic */
+.highlight .vc {
+  color: #bb60d5
+}
+
+/* Name.Variable.Class */
+.highlight .vg {
+  color: #bb60d5
+}
+
+/* Name.Variable.Global */
+.highlight .vi {
+  color: #bb60d5
+}
+
+/* Name.Variable.Instance */
+.highlight .vm {
+  color: #bb60d5
+}
+
+/* Name.Variable.Magic */
+.highlight .il {
+  color: #208050
+}
+
+/* Literal.Number.Integer.Long */

docs/_static/css/toggle.css

@@ -9,6 +9,13 @@ input[type=checkbox] {
     padding: 10px;
     display: flex;
     justify-content: space-between;
+    background-color: var(--color-f);
+    border-top: 1px solid var(--color-c);
+}
+
+.fa-caret-down,
+.fa-book {
+    color: var(--color-a) !important;
 }
 
 .rst-versions .rst-current-version .fa-book,
@@ -76,8 +83,6 @@ html.transition *:after {
     transition-delay: 0 !important;
 }
 
-nav.wy-nav-side {
-    /* The default padding of 2em is too small and the "Keyword Index" link gets obscured
-     * by the version toggle. */
-    padding-bottom: 3em;
-}
+.wy-menu-vertical a:hover {
+    background-color: #0002;
+}

docs/_static/img/hamburger-dark.svg

@@ -0,0 +1,3 @@
+<svg width="24" height="24" viewBox="0 0 24 24" fill="#E6E3EC" xmlns="http://www.w3.org/2000/svg" focusable="false" class="color-toggle-icon" aria-hidden="true">
+<path d="M 3 5 A 1.0001 1.0001 0 1 0 3 7 L 21 7 A 1.0001 1.0001 0 1 0 21 5 L 3 5 z M 3 11 A 1.0001 1.0001 0 1 0 3 13 L 21 13 A 1.0001 1.0001 0 1 0 21 11 L 3 11 z M 3 17 A 1.0001 1.0001 0 1 0 3 19 L 21 19 A 1.0001 1.0001 0 1 0 21 17 L 3 17 z" />
+</svg>

docs/_static/img/hamburger-light.svg

@@ -0,0 +1,3 @@
+<svg width="24px" height="24px" fill="currentColor" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" focusable="false" class="color-toggle-icon" aria-hidden="true">
+<path fill="#2B247C" d="M 3 5 A 1.0001 1.0001 0 1 0 3 7 L 21 7 A 1.0001 1.0001 0 1 0 21 5 L 3 5 z M 3 11 A 1.0001 1.0001 0 1 0 3 13 L 21 13 A 1.0001 1.0001 0 1 0 21 11 L 3 11 z M 3 17 A 1.0001 1.0001 0 1 0 3 19 L 21 19 A 1.0001 1.0001 0 1 0 21 17 L 3 17 z" />
+</svg>

docs/_static/img/logo-dark.svg

@@ -0,0 +1,8 @@
+<svg width="100" height="160" viewBox="0 0 100 160" fill="#E6E3EC" xmlns="http://www.w3.org/2000/svg">
+<path opacity="0.8" d="M50 44.3013L25 1L0 44.3013L25 87.6025L50 44.3013Z" />
+<path opacity="0.45" d="M50 44.3091L75 1.00781L25 1.00781L0 44.3091H50Z" />
+<path opacity="0.6" d="M75 1.00781L25 1.00781L50 44.3091H100L75 1.00781Z" />
+<path opacity="0.8" d="M50 115.699L75 159L100 115.699L75 72.3975L50 115.699Z" />
+<path opacity="0.45" d="M50 115.691L25 158.993H75L100 115.691L50 115.691Z" />
+<path opacity="0.6" d="M25 158.993H75L50 115.691L0 115.691L25 158.993Z" />
+</svg>

docs/_static/img/logo.svg

@@ -0,0 +1,8 @@
+<svg width="100" height="160" viewBox="0 0 100 160" fill="#2B247C" xmlns="http://www.w3.org/2000/svg">
+<path opacity="0.8" d="M50 44.3013L25 1L0 44.3013L25 87.6025L50 44.3013Z" />
+<path opacity="0.45" d="M50 44.3091L75 1.00781L25 1.00781L0 44.3091H50Z" />
+<path opacity="0.6" d="M75 1.00781L25 1.00781L50 44.3091H100L75 1.00781Z" />
+<path opacity="0.8" d="M50 115.699L75 159L100 115.699L75 72.3975L50 115.699Z" />
+<path opacity="0.45" d="M50 115.691L25 158.993H75L100 115.691L50 115.691Z" />
+<path opacity="0.6" d="M25 158.993H75L50 115.691L0 115.691L25 158.993Z" />
+</svg>

docs/_static/img/moon.svg

@@ -0,0 +1,3 @@
+<svg width="24" height="24" viewBox="0 0 24 24" fill="#2B247C" xmlns="http://www.w3.org/2000/svg" focusable="false" class="color-toggle-icon" aria-hidden="true">
+<path d="M21.4,13.7C20.6,13.9,19.8,14,19,14c-5,0-9-4-9-9c0-0.8,0.1-1.6,0.3-2.4c0.1-0.3,0-0.7-0.3-1 c-0.3-0.3-0.6-0.4-1-0.3C4.3,2.7,1,7.1,1,12c0,6.1,4.9,11,11,11c4.9,0,9.3-3.3,10.6-8.1c0.1-0.3,0-0.7-0.3-1 C22.1,13.7,21.7,13.6,21.4,13.7z" />
+</svg>

docs/_static/img/sun.svg

@@ -0,0 +1,13 @@
+<svg width="24" height="24" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" focusable="false" class="color-toggle-icon" aria-hidden="true">
+  <g stroke-linejoin="round" stroke-linecap="round" stroke-width="2" fill="none" stroke="#E6E3EC">
+    <circle cx="12" cy="12" r="5" />
+    <path d="M12 1v2" />
+    <path d="M12 21v2" />
+    <path d="M4.22 4.22l1.42 1.42" />
+    <path d="M18.36 18.36l1.42 1.42" />
+    <path d="M1 12h2" />
+    <path d="M21 12h2" />
+    <path d="M4.22 19.78l1.42-1.42" />
+    <path d="M18.36 5.64l1.42-1.42" />
+  </g>
+</svg>

docs/_static/js/constants.js

@@ -0,0 +1,38 @@
+// Site URL
+const SITE_URL = "https://docs.soliditylang.org"
+const { origin, pathname } = location;
+const pathSplit = pathname.split("/");
+const rootPath = origin.includes(SITE_URL) && pathSplit.length > 3 ? pathSplit.splice(1, 2).join("/") : ''
+const ROOT_URL = `${origin}/${rootPath}`;
+
+// Color mode constants
+const [DARK, LIGHT] = ["dark", "light"];
+const LIGHT_LOGO_PATH = `${ROOT_URL}/_static/img/logo.svg`;
+const DARK_LOGO_PATH = `${ROOT_URL}/_static/img/logo-dark.svg`;
+const SUN_ICON_PATH = `${ROOT_URL}/_static/img/sun.svg`;
+const MOON_ICON_PATH = `${ROOT_URL}/_static/img/moon.svg`;
+const LIGHT_HAMBURGER_PATH = `${ROOT_URL}/_static/img/hamburger-light.svg`;
+const DARK_HAMBURGER_PATH = `${ROOT_URL}/_static/img/hamburger-dark.svg`;
+const COLOR_TOGGLE_ICON_CLASS = "color-toggle-icon";
+const SOLIDITY_LOGO_CLASS = "solidity-logo";
+const LS_COLOR_SCHEME = "color-scheme";
+
+// Solidity navigation constants
+const SOLIDITY_HOME_URL = "https://soliditylang.org";
+const BLOG_URL = `${SOLIDITY_HOME_URL}/blog`;
+const DOCS_URL = "/";
+const USE_CASES_PATH = `${SOLIDITY_HOME_URL}/use-cases`;
+const CONTRIBUTE_PATH = `/en/latest/contributing.html`;
+const ABOUT_PATH = `${SOLIDITY_HOME_URL}/about`;
+const FORUM_URL = "https://forum.soliditylang.org/";
+const NAV_LINKS = [
+  { name: "Blog", href: BLOG_URL },
+  { name: "Documentation", href: DOCS_URL },
+  { name: "Use cases", href: USE_CASES_PATH },
+  { name: "Contribute", href: CONTRIBUTE_PATH },
+  { name: "About", href: ABOUT_PATH },
+  { name: "Forum", href: FORUM_URL },
+];
+
+const MOBILE_MENU_TOGGLE_CLASS = "shift";
+const WRAPPER_CLASS = "unified-wrapper";

docs/_static/js/initialize.js

@@ -0,0 +1,250 @@
+const getLogoSrc = (isDark) => (isDark ? DARK_LOGO_PATH : LIGHT_LOGO_PATH);
+
+const getModeIconSrc = (isDark) => (isDark ? SUN_ICON_PATH : MOON_ICON_PATH);
+
+const getMenuIconSrc = (isDark) =>
+  isDark ? DARK_HAMBURGER_PATH : LIGHT_HAMBURGER_PATH;
+
+function addFooterNote() {
+  const contentInfo = document.querySelector("div[role=contentinfo]");
+  const footerNote = document.createElement("p");
+  footerNote.classList.add("footer-note");
+  footerNote.innerHTML =
+    'Customized with ❤️ by the <a href="https://ethereum.org/" target="_blank">ethereum.org</a> team.';
+  contentInfo.parentNode.insertBefore(footerNote, contentInfo.nextSibling);
+}
+
+function rearrangeDom() {
+  const bodyDivs = document.querySelectorAll("body>div");
+  bodyDivs.forEach((div) => div.remove());
+  const wrapperDiv = document.createElement("div");
+  wrapperDiv.classList.add(WRAPPER_CLASS);
+  bodyDivs.forEach((div) => wrapperDiv.appendChild(div));
+  document.body.prepend(wrapperDiv);
+
+  const rstVersions = document.querySelector(".rst-versions");
+  rstVersions.remove();
+  const wyNavSide = document.querySelector("nav.wy-nav-side");
+  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);
+}
+
+function buildHeader() {
+  const isDarkMode = localStorage.getItem(LS_COLOR_SCHEME) == DARK;
+
+  const header = document.createElement("div");
+  header.classList.add("unified-header");
+  document.querySelector(`.${WRAPPER_CLASS}`).prepend(header);
+
+  const innerHeader = document.createElement("div");
+  innerHeader.classList.add("inner-header");
+  header.appendChild(innerHeader);
+
+  const homeLink = document.createElement("a");
+  homeLink.classList.add("home-link");
+  homeLink.href = SOLIDITY_HOME_URL;
+  homeLink.ariaLabel = "Solidity home";
+  innerHeader.appendChild(homeLink);
+
+  const logo = document.createElement("img");
+  logo.classList.add(SOLIDITY_LOGO_CLASS);
+  logo.src = getLogoSrc(isDarkMode);
+  logo.alt = "Solidity logo";
+  homeLink.appendChild(logo);
+
+  const skipToContent = document.createElement("a");
+  skipToContent.classList.add("skip-to-content");
+  skipToContent.href = "#content";
+  skipToContent.innerText = "{skip to content}";
+  innerHeader.appendChild(skipToContent);
+
+  const navBar = document.createElement("nav");
+  navBar.classList.add("nav-bar");
+  innerHeader.appendChild(navBar);
+
+  const linkElements = NAV_LINKS.map(({ name, href }) => {
+    const link = document.createElement("a");
+    link.classList.add("nav-link");
+    link.setAttribute("key", name);
+    link.setAttribute("href", href);
+    link.setAttribute("aria-label", name);
+    if (href === FORUM_URL) {
+      link.classList.add("forum-link");
+      link.setAttribute("target", "_blank");
+      link.setAttribute("rel", "noopener noreferrer");
+    }
+    link.innerText = name;
+    return link;
+  });
+  linkElements.forEach((link) => navBar.appendChild(link));
+
+  // Flex wrapper for color mode and mobile menu buttons
+  const navButtonContainer = document.createElement("div");
+  navButtonContainer.classList.add("nav-button-container");
+  navBar.appendChild(navButtonContainer);
+
+  // Build color toggle
+  const toggleIcon = document.createElement("img");
+  toggleIcon.classList.add(COLOR_TOGGLE_ICON_CLASS);
+  toggleIcon.src = getModeIconSrc(isDarkMode);
+  toggleIcon.alt = "Color mode toggle icon";
+  toggleIcon.setAttribute("aria-hidden", "true");
+  toggleIcon.setAttribute("key", "toggle icon");
+  const colorModeButton = document.createElement("button");
+  colorModeButton.classList.add("color-toggle");
+  colorModeButton.setAttribute("type", "button");
+  colorModeButton.setAttribute("aria-label", "Toggle light dark mode");
+  colorModeButton.setAttribute("key", "color mode button");
+  colorModeButton.addEventListener("click", toggleColorMode);
+  colorModeButton.appendChild(toggleIcon);
+  navButtonContainer.appendChild(colorModeButton);
+
+  // Build mobile hamburger menu
+  const menuIcon = document.createElement("img");
+  menuIcon.classList.add(COLOR_TOGGLE_ICON_CLASS);
+  menuIcon.src = getMenuIconSrc(isDarkMode);
+  menuIcon.alt = "Toggle menu";
+  menuIcon.setAttribute("aria-hidden", "true");
+  menuIcon.setAttribute("key", "menu icon");
+  const menuButton = document.createElement("button");
+  menuButton.classList.add("color-toggle");
+  menuButton.classList.add("mobile-menu-button");
+  menuButton.setAttribute("type", "button");
+  menuButton.setAttribute("aria-label", "Toggle menu");
+  menuButton.setAttribute("key", "menu button");
+  menuButton.addEventListener("click", toggleMenu);
+  menuButton.appendChild(menuIcon);
+  navButtonContainer.appendChild(menuButton);
+}
+
+const updateActiveNavLink = () => {
+  const navLinks = document.querySelectorAll(".unified-header .nav-link");
+  navLinks.forEach((link) => {
+    const href = link.getAttribute("href");
+    if (document.documentURI.includes("contributing.html")) {
+      link.classList[href.includes("contributing.html") ? "add" : "remove"](
+        "active"
+      );
+    } else {
+      link.classList[document.documentURI.includes(href) ? "add" : "remove"](
+        "active"
+      );
+    }
+  });
+};
+
+document.addEventListener("locationchange", updateActiveNavLink);
+
+function updateGitHubEditPath() {
+  // Replaces the version number in the GitHub edit path with "develop"
+  const gitHubEditAnchor = document.querySelector(".wy-breadcrumbs-aside > a");
+  const url = new URL(gitHubEditAnchor.href);
+  const split = url.pathname.split("/");
+  const versionIndex = split.indexOf("blob") + 1;
+  split[versionIndex] = "develop";
+  url.pathname = split.join("/");
+  gitHubEditAnchor.setAttribute("href", url.toString());
+  gitHubEditAnchor.setAttribute("target", "_blank");
+  gitHubEditAnchor.setAttribute("rel", "noopener noreferrer");
+}
+
+function initialize() {
+  // Rearrange DOM elements for styling
+  rearrangeDom();
+
+  // Check localStorage for existing color scheme preference
+  var prefersDark = localStorage.getItem(LS_COLOR_SCHEME) == DARK;
+  // Check link for search param "color"... it may be "light" or "dark"
+  var urlParams = new URLSearchParams(window.location.search);
+  if (urlParams.size > 0) {
+    // This is used for color mode continuity between the main Solidity Lang site and the docs
+    var colorSchemeParam = urlParams.get("color");
+    // If present, overwrite prefersDark accordingly
+    if (colorSchemeParam) {
+      prefersDark = colorSchemeParam == DARK;
+    }
+
+    // Remove "color" search param from URL
+    const { location, title } = document;
+    const { pathname, origin, search, hash } = location;
+    const newSearchParams = new URLSearchParams(search);
+    newSearchParams.delete("color");
+    const sanitizedSearch =
+      newSearchParams.size < 1 ? "" : "?" + newSearchParams.toString();
+    window.history.replaceState(
+      origin,
+      title,
+      pathname + sanitizedSearch + hash
+    );
+  }
+
+  // In case none existed, establish localStorage color scheme preference
+  var mode = prefersDark ? DARK : LIGHT;
+  localStorage.setItem(LS_COLOR_SCHEME, mode);
+
+  // Select the root element and set the style attribute to denote color-scheme attribute
+  document
+    .querySelector(":root")
+    .setAttribute("style", `--color-scheme: ${mode}`);
+
+  // 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();
+
+  // Add footer note
+  addFooterNote();
+
+  // Build header
+  buildHeader();
+
+  // Close menu
+  toggleMenu({ force: false });
+
+  // Update active nav link
+  updateActiveNavLink();
+
+  // Update GitHub edit path to direct to `develop` branch
+  updateGitHubEditPath();
+}
+
+document.addEventListener("DOMContentLoaded", initialize);
+
+const handleClick = (e) => {
+  if (e.target.closest(".backdrop")) {
+    toggleMenu({ force: false });
+  }
+
+  if (e.target.closest("a")) {
+    const target = e.target.closest("a");
+    const href = target.getAttribute("href");
+    if (href.includes(SOLIDITY_HOME_URL)) {
+      const url = new URL(href);
+      const params = new URLSearchParams(url.search);
+      params.set("color", localStorage.getItem(LS_COLOR_SCHEME));
+      url.search = params.toString();
+      target.setAttribute("href", url.toString());
+    }
+  }
+};
+document.addEventListener("click", handleClick);
+
+const handleKeyDown = (e) => {
+  if (e.metaKey && e.key === "k") {
+    document.querySelector("#rtd-search-form input").focus();
+  } else if (e.key === "Escape") {
+    toggleMenu({ force: false });
+  }
+  if (e.metaKey && e.code === "Backslash") {
+    toggleColorMode();
+  }
+};
+document.addEventListener("keydown", handleKeyDown);

docs/_static/js/toggle.js

@@ -1,39 +1,47 @@
-document.addEventListener('DOMContentLoaded', function() {
+function toggleColorMode() {
+  // Check localStorage for previous color scheme preference, assign the opposite
+  var newMode = localStorage.getItem(LS_COLOR_SCHEME) == DARK ? LIGHT : DARK;
 
-    function toggleCssMode(isDay) {
-        var mode = (isDay ? "Day" : "Night");
-        localStorage.setItem("css-mode", mode);
+  // Update localStorage with new color scheme preference
+  localStorage.setItem(LS_COLOR_SCHEME, newMode);
 
-        var url_root = DOCUMENTATION_OPTIONS.URL_ROOT == "./" ? "" : DOCUMENTATION_OPTIONS.URL_ROOT;
-        var daysheet = $(`link[href="${url_root}_static/pygments.css"]`)[0].sheet;
-        daysheet.disabled = !isDay;
+  // Update the root element with the new color scheme preference
+  document
+    .querySelector(":root")
+    .setAttribute("style", `--color-scheme: ${newMode}`);
 
-        var nightsheet = $(`link[href="${url_root}_static/css/dark.css"]`)[0];
-        if (!isDay && nightsheet === undefined) {
-            var element = document.createElement("link");
-            element.setAttribute("rel", "stylesheet");
-            element.setAttribute("type", "text/css");
-            element.setAttribute("href", `${url_root}_static/css/dark.css`);
-            document.getElementsByTagName("head")[0].appendChild(element);
-            return;
-        }
-        if (nightsheet !== undefined) {
-            nightsheet.sheet.disabled = isDay;
-        }
+  // Update logo
+  document
+    .querySelector(`img.${SOLIDITY_LOGO_CLASS}`)
+    .setAttribute("src", newMode === LIGHT ? LIGHT_LOGO_PATH : DARK_LOGO_PATH);
+
+  // Update color mode toggle icon
+  document
+    .querySelector(`img.${COLOR_TOGGLE_ICON_CLASS}`)
+    .setAttribute("src", newMode === LIGHT ? MOON_ICON_PATH : SUN_ICON_PATH);
+
+  // Update hamburger menu icon color
+  document
+    .querySelector("button.mobile-menu-button img")
+    .setAttribute(
+      "src",
+      newMode === LIGHT ? LIGHT_HAMBURGER_PATH : DARK_HAMBURGER_PATH
+    );
+}
+
+function toggleMenu(options = {}) {
+  const handleClassToggle = ({ classList }, className) => {
+    if (typeof options.force !== "undefined") {
+      classList.toggle(className, options.force);
+    } else {
+      classList.toggle(className);
     }
-
-    var initial = localStorage.getItem("css-mode") != "Night";
-    var checkbox = document.querySelector('input[name=mode]');
-
-    toggleCssMode(initial);
-    checkbox.checked = initial;
-
-    checkbox.addEventListener('change', function() {
-        document.documentElement.classList.add('transition');
-        window.setTimeout(() => {
-            document.documentElement.classList.remove('transition');
-        }, 1000)
-        toggleCssMode(this.checked);
-    })
-
-});
+  };
+  document
+    .querySelectorAll('[data-toggle="rst-versions"]')
+    .forEach((e) => handleClassToggle(e, MOBILE_MENU_TOGGLE_CLASS));
+  document
+    .querySelectorAll('[data-toggle="wy-nav-shift"]')
+    .forEach((e) => handleClassToggle(e, MOBILE_MENU_TOGGLE_CLASS));
+  handleClassToggle(document.querySelector(`.${WRAPPER_CLASS}`), "menu-open");
+}

docs/abi-spec.rst

@@ -13,7 +13,7 @@ The Contract Application Binary Interface (ABI) is the standard way to interact
 from outside the blockchain and for contract-to-contract interaction. Data is encoded according to its type,
 as described in this specification. The encoding is not self describing and thus requires a schema in order to decode.
 
-We assume the interface functions of a contract are strongly typed, known at compilation time and static.
+We assume that the interface functions of a contract are strongly typed, known at compilation time and static.
 We assume that all contracts will have the interface definitions of any contracts they call available at compile-time.
 
 This specification does not address contracts whose interface is dynamic or otherwise known only at run-time.
@@ -29,7 +29,7 @@ first (left, high-order in big-endian) four bytes of the Keccak-256 hash of the
 the function. The signature is defined as the canonical expression of the basic prototype without data
 location specifier, i.e.
 the function name with the parenthesised list of parameter types. Parameter types are split by a single
-comma - no spaces are used.
+comma — no spaces are used.
 
 .. note::
     The return type of a function is not part of this signature. In
@@ -133,7 +133,7 @@ The encoding is designed to have the following properties, which are especially
    previous version of the ABI, the number of reads scaled linearly with the total number of dynamic
    parameters in the worst case.
 
-2. The data of a variable or array element is not interleaved with other data and it is
+2. The data of a variable or an array element is not interleaved with other data and it is
    relocatable, i.e. it only uses relative "addresses".
 
 
@@ -191,9 +191,9 @@ on the type of ``X`` being
 
 - ``T[]`` where ``X`` has ``k`` elements (``k`` is assumed to be of type ``uint256``):
 
-  ``enc(X) = enc(k) enc([X[0], ..., X[k-1]])``
+  ``enc(X) = enc(k) enc((X[0], ..., X[k-1]))``
 
-  i.e. it is encoded as if it were an array of static size ``k``, prefixed with
+  i.e. it is encoded as if it were a tuple with ``k`` elements of the same type (resp. an array of static size ``k``), prefixed with
   the number of elements.
 
 - ``bytes``, of length ``k`` (which is assumed to be of type ``uint256``):
@@ -252,7 +252,7 @@ Given the contract:
     }
 
 
-Thus for our ``Foo`` example if we wanted to call ``baz`` with the parameters ``69`` and
+Thus, for our ``Foo`` example if we wanted to call ``baz`` with the parameters ``69`` and
 ``true``, we would pass 68 bytes total, which can be broken down into:
 
 - ``0xcdcd77c0``: the Method ID. This is derived as the first 4 bytes of the Keccak hash of
@@ -311,7 +311,7 @@ Use of Dynamic Types
 A call to a function with the signature ``f(uint256,uint32[],bytes10,bytes)`` with values
 ``(0x123, [0x456, 0x789], "1234567890", "Hello, world!")`` is encoded in the following way:
 
-We take the first four bytes of ``sha3("f(uint256,uint32[],bytes10,bytes)")``, i.e. ``0x8be65246``.
+We take the first four bytes of ``keccak("f(uint256,uint32[],bytes10,bytes)")``, i.e. ``0x8be65246``.
 Then we encode the head parts of all four arguments. For the static types ``uint256`` and ``bytes10``,
 these are directly the values we want to pass, whereas for the dynamic types ``uint32[]`` and ``bytes``,
 we use the offset in bytes to the start of their data area, measured from the start of the value
@@ -563,7 +563,7 @@ A function description is a JSON object with the fields:
   blockchain state <pure-functions>`), ``view`` (:ref:`specified to not modify the blockchain
   state <view-functions>`), ``nonpayable`` (function does not accept Ether - the default) and ``payable`` (function accepts Ether).
 
-Constructor and fallback function never have ``name`` or ``outputs``. Fallback function doesn't have ``inputs`` either.
+Constructor, receive, and fallback never have ``name`` or ``outputs``. Receive and fallback do not have ``inputs`` either.
 
 .. note::
     Sending non-zero Ether to non-payable function will revert the transaction.
@@ -581,7 +581,7 @@ An event description is a JSON object with fairly similar fields:
   * ``name``: the name of the parameter.
   * ``type``: the canonical type of the parameter (more below).
   * ``components``: used for tuple types (more below).
-  * ``indexed``: ``true`` if the field is part of the log's topics, ``false`` if it one of the log's data segment.
+  * ``indexed``: ``true`` if the field is part of the log's topics, ``false`` if it is one of the log's data segments.
 
 - ``anonymous``: ``true`` if the event was declared as ``anonymous``.
 
@@ -597,7 +597,7 @@ Errors look as follows:
 
 .. note::
   There can be multiple errors with the same name and even with identical signature
-  in the JSON array, for example if the errors originate from different
+  in the JSON array; for example, if the errors originate from different
   files in the smart contract or are referenced from another smart contract.
   For the ABI, only the name of the error itself is relevant and not where it is
   defined.
@@ -646,7 +646,7 @@ would result in the JSON:
 Handling tuple types
 --------------------
 
-Despite that names are intentionally not part of the ABI encoding they do make a lot of sense to be included
+Despite the fact that names are intentionally not part of the ABI encoding, they do make a lot of sense to be included
 in the JSON to enable displaying it to the end user. The structure is nested in the following way:
 
 An object with members ``name``, ``type`` and potentially ``components`` describes a typed variable.
@@ -654,7 +654,7 @@ The canonical type is determined until a tuple type is reached and the string de
 to that point is stored in ``type`` prefix with the word ``tuple``, i.e. it will be ``tuple`` followed by
 a sequence of ``[]`` and ``[k]`` with
 integers ``k``. The components of the tuple are then stored in the member ``components``,
-which is of array type and has the same structure as the top-level object except that
+which is of an array type and has the same structure as the top-level object except that
 ``indexed`` is not allowed there.
 
 As an example, the code
@@ -738,10 +738,10 @@ Strict Encoding Mode
 ====================
 
 Strict encoding mode is the mode that leads to exactly the same encoding as defined in the formal specification above.
-This means offsets have to be as small as possible while still not creating overlaps in the data areas and thus no gaps are
+This means that offsets have to be as small as possible while still not creating overlaps in the data areas, and thus no gaps are
 allowed.
 
-Usually, ABI decoders are written in a straightforward way just following offset pointers, but some decoders
+Usually, ABI decoders are written in a straightforward way by just following offset pointers, but some decoders
 might enforce strict mode. The Solidity ABI decoder currently does not enforce strict mode, but the encoder
 always creates data in strict mode.
 
@@ -777,7 +777,7 @@ More specifically:
   encoding of its elements **with** padding.
 - Dynamically-sized types like ``string``, ``bytes`` or ``uint[]`` are encoded
   without their length field.
-- The encoding of ``string`` or ``bytes`` does not apply padding at the end
+- The encoding of ``string`` or ``bytes`` does not apply padding at the end,
   unless it is part of an array or struct (then it is padded to a multiple of
   32 bytes).
 
@@ -805,7 +805,7 @@ Encoding of Indexed Event Parameters
 ====================================
 
 Indexed event parameters that are not value types, i.e. arrays and structs are not
-stored directly but instead a keccak256-hash of an encoding is stored. This encoding
+stored directly but instead a Keccak-256 hash of an encoding is stored. This encoding
 is defined as follows:
 
 - the encoding of a ``bytes`` and ``string`` value is just the string contents

docs/analysing-compilation-output.rst

@@ -11,7 +11,7 @@ visual diff of the assembly before and after a change is often very enlightening
 
 Consider the following contract (named, say ``contract.sol``):
 
-.. code-block:: Solidity
+.. code-block:: solidity
 
     // SPDX-License-Identifier: GPL-3.0
     pragma solidity >=0.5.0 <0.9.0;

docs/assembly.rst

@@ -289,8 +289,8 @@ perform additional memory optimizations, if it can rely on certain assumptions a
 
 While we recommend to always respect Solidity's memory model, inline assembly allows you to use memory
 in an incompatible way. Therefore, moving stack variables to memory and additional memory optimizations are,
-by default, disabled in the presence of any inline assembly block that contains a memory operation or assigns
-to Solidity variables in memory.
+by default, globally disabled in the presence of any inline assembly block that contains a memory operation
+or assigns to Solidity variables in memory.
 
 However, you can specifically annotate an assembly block to indicate that it in fact respects Solidity's memory
 model as follows:
@@ -362,7 +362,7 @@ in memory is automatically considered memory-safe and does not need to be annota
 .. warning::
     It is your responsibility to make sure that the assembly actually satisfies the memory model. If you annotate
     an assembly block as memory-safe, but violate one of the memory assumptions, this **will** lead to incorrect and
-    undefined behaviour that cannot easily be discovered by testing.
+    undefined behavior that cannot easily be discovered by testing.
 
 In case you are developing a library that is meant to be compatible across multiple versions
 of Solidity, you can use a special comment to annotate an assembly block as memory-safe:
@@ -375,4 +375,4 @@ of Solidity, you can use a special comment to annotate an assembly block as memo
     }
 
 Note that we will disallow the annotation via comment in a future breaking release; so, if you are not concerned with
-backwards-compatibility with older compiler versions, prefer using the dialect string.
+backward-compatibility with older compiler versions, prefer using the dialect string.

docs/brand-guide.rst

@@ -67,7 +67,7 @@ When using the Solidity logo, please respect the Solidity logo guidelines.
 Solidity Logo Guidelines
 ========================
 
-.. image:: logo.svg
+.. image:: solidity_logo.svg
   :width: 256
 
 *(Right click on the logo to download it.)*

docs/bugs.json

@@ -1,9 +1,49 @@
 [
+    {
+        "uid": "SOL-2023-2",
+        "name": "FullInlinerNonExpressionSplitArgumentEvaluationOrder",
+        "summary": "Optimizer sequences containing FullInliner do not preserve the evaluation order of arguments of inlined function calls in code that is not in expression-split form.",
+        "description": "Function call arguments in Yul are evaluated right to left. This order matters when the argument expressions have side-effects, and changing it may change contract behavior. FullInliner is an optimizer step that can replace a function call with the body of that function. The transformation involves assigning argument expressions to temporary variables, which imposes an explicit evaluation order. FullInliner was written with the assumption that this order does not necessarily have to match usual argument evaluation order because the argument expressions have no side-effects. In most circumstances this assumption is true because the default optimization step sequence contains the ExpressionSplitter step. ExpressionSplitter ensures that the code is in *expression-split form*, which means that function calls cannot appear nested inside expressions, and all function call arguments have to be variables. The assumption is, however, not guaranteed to be true in general. Version 0.6.7 introduced a setting allowing users to specify an arbitrary optimization step sequence, making it possible for the FullInliner to actually encounter argument expressions with side-effects, which can result in behavior differences between optimized and unoptimized bytecode. Contracts compiled without optimization or with the default optimization sequence are not affected. To trigger the bug the user has to explicitly choose compiler settings that contain a sequence with FullInliner step not preceded by ExpressionSplitter.",
+        "link": "https://blog.soliditylang.org/2023/07/19/full-inliner-non-expression-split-argument-evaluation-order-bug/",
+        "introduced": "0.6.7",
+        "fixed": "0.8.21",
+        "severity": "low",
+        "conditions": {
+            "yulOptimizer": true
+        }
+    },
+    {
+        "uid": "SOL-2023-1",
+        "name": "MissingSideEffectsOnSelectorAccess",
+        "summary": "Accessing the ``.selector`` member on complex expressions leaves the expression unevaluated in the legacy code generation.",
+        "description": "When accessing the ``.selector`` member on an expression with side-effects, like an assignment, a function call or a conditional, the expression would not be evaluated in the legacy code generation. This would happen in expressions where the functions used in the expression were all known at compilation time, regardless of whether the whole expression could be evaluated at compilation time or not. Note that the code generated by the IR pipeline was unaffected and would behave as expected.",
+        "link": "https://blog.soliditylang.org/2023/07/19/missing-side-effects-on-selector-access-bug/",
+        "introduced": "0.6.2",
+        "fixed": "0.8.21",
+        "severity": "low",
+        "conditions": {
+            "viaIR": false
+        }
+    },
+    {
+        "uid": "SOL-2022-7",
+        "name": "StorageWriteRemovalBeforeConditionalTermination",
+        "summary": "Calling functions that conditionally terminate the external EVM call using the assembly statements ``return(...)`` or ``stop()`` may result in incorrect removals of prior storage writes.",
+        "description": "A call to a Yul function that conditionally terminates the external EVM call could result in prior storage writes being incorrectly removed by the Yul optimizer. This used to happen in cases in which it would have been valid to remove the store, if the Yul function in question never actually terminated the external call, and the control flow always returned back to the caller instead. Conditional termination within the same Yul block instead of within a called function was not affected. In Solidity with optimized via-IR code generation, any storage write before a function conditionally calling ``return(...)`` or ``stop()`` in inline assembly, may have been incorrectly removed, whenever it would have been valid to remove the write without the ``return(...)`` or ``stop()``. In optimized legacy code generation, only inline assembly that did not refer to any Solidity variables and that involved conditionally-terminating user-defined assembly functions could be affected.",
+        "link": "https://blog.soliditylang.org/2022/09/08/storage-write-removal-before-conditional-termination/",
+        "introduced": "0.8.13",
+        "fixed": "0.8.17",
+        "severity": "medium/high",
+        "conditions": {
+            "yulOptimizer": true
+        }
+    },
     {
         "uid": "SOL-2022-6",
         "name": "AbiReencodingHeadOverflowWithStaticArrayCleanup",
         "summary": "ABI-encoding a tuple with a statically-sized calldata array in the last component would corrupt 32 leading bytes of its first dynamically encoded component.",
         "description": "When ABI-encoding a statically-sized calldata array, the compiler always pads the data area to a multiple of 32-bytes and ensures that the padding bytes are zeroed. In some cases, this cleanup used to be performed by always writing exactly 32 bytes, regardless of how many needed to be zeroed. This was done with the assumption that the data that would eventually occupy the area past the end of the array had not yet been written, because the encoder processes tuple components in the order they were given. While this assumption is mostly true, there is an important corner case: dynamically encoded tuple components are stored separately from the statically-sized ones in an area called the *tail* of the encoding and the tail immediately follows the *head*, which is where the statically-sized components are placed. The aforementioned cleanup, if performed for the last component of the head would cross into the tail and overwrite up to 32 bytes of the first component stored there with zeros. The only array type for which the cleanup could actually result in an overwrite were arrays with ``uint256`` or ``bytes32`` as the base element type and in this case the size of the corrupted area was always exactly 32 bytes. The problem affected tuples at any nesting level. This included also structs, which are encoded as tuples in the ABI. Note also that lists of parameters and return values of functions, events and errors are encoded as tuples.",
+        "link": "https://blog.soliditylang.org/2022/08/08/calldata-tuple-reencoding-head-overflow-bug/",
         "introduced": "0.5.8",
         "fixed": "0.8.16",
         "severity": "medium",
@@ -46,7 +86,7 @@
     },
     {
         "uid": "SOL-2022-2",
-        "name": "NestedCallataArrayAbiReencodingSizeValidation",
+        "name": "NestedCalldataArrayAbiReencodingSizeValidation",
         "summary": "ABI-reencoding of nested dynamic calldata arrays did not always perform proper size checks against the size of calldata and could read beyond ``calldatasize()``.",
         "description": "Calldata validation for nested dynamic types is deferred until the first access to the nested values. Such an access may for example be a copy to memory or an index or member access to the outer type. While in most such accesses calldata validation correctly checks that the data area of the nested array is completely contained in the passed calldata (i.e. in the range [0, calldatasize()]), this check may not be performed, when ABI encoding such nested types again directly from calldata. For instance, this can happen, if a value in calldata with a nested dynamic array is passed to an external call, used in ``abi.encode`` or emitted as event. In such cases, if the data area of the nested array extends beyond ``calldatasize()``, ABI encoding it did not revert, but continued reading values from beyond ``calldatasize()`` (i.e. zero values).",
         "link": "https://blog.soliditylang.org/2022/05/17/calldata-reencode-size-check-bug/",

docs/bugs.rst

@@ -68,7 +68,7 @@ conditions
     If no conditions are given, assume that the bug is present.
 check
     This field contains different checks that report whether the smart contract
-    contains the bug or not. The first type of check are Javascript regular
+    contains the bug or not. The first type of check are JavaScript regular
     expressions that are to be matched against the source code ("source-regex")
     if the bug is present.  If there is no match, then the bug is very likely
     not present. If there is a match, the bug might be present.  For improved

docs/bugs_by_version.json

@@ -1085,7 +1085,7 @@
         "bugs": [
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
-            "NestedCallataArrayAbiReencodingSizeValidation",
+            "NestedCalldataArrayAbiReencodingSizeValidation",
             "ABIDecodeTwoDimensionalArrayMemory",
             "KeccakCaching",
             "EmptyByteArrayCopy",
@@ -1103,7 +1103,7 @@
         "bugs": [
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
-            "NestedCallataArrayAbiReencodingSizeValidation",
+            "NestedCalldataArrayAbiReencodingSizeValidation",
             "ABIDecodeTwoDimensionalArrayMemory",
             "KeccakCaching",
             "EmptyByteArrayCopy",
@@ -1120,7 +1120,7 @@
         "bugs": [
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
-            "NestedCallataArrayAbiReencodingSizeValidation",
+            "NestedCalldataArrayAbiReencodingSizeValidation",
             "ABIDecodeTwoDimensionalArrayMemory",
             "KeccakCaching",
             "EmptyByteArrayCopy",
@@ -1137,7 +1137,7 @@
         "bugs": [
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
-            "NestedCallataArrayAbiReencodingSizeValidation",
+            "NestedCalldataArrayAbiReencodingSizeValidation",
             "ABIDecodeTwoDimensionalArrayMemory",
             "KeccakCaching",
             "EmptyByteArrayCopy",
@@ -1154,7 +1154,7 @@
         "bugs": [
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
-            "NestedCallataArrayAbiReencodingSizeValidation",
+            "NestedCalldataArrayAbiReencodingSizeValidation",
             "ABIDecodeTwoDimensionalArrayMemory",
             "KeccakCaching",
             "EmptyByteArrayCopy",
@@ -1173,7 +1173,7 @@
         "bugs": [
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
-            "NestedCallataArrayAbiReencodingSizeValidation",
+            "NestedCalldataArrayAbiReencodingSizeValidation",
             "ABIDecodeTwoDimensionalArrayMemory",
             "KeccakCaching",
             "EmptyByteArrayCopy",
@@ -1191,7 +1191,7 @@
         "bugs": [
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
-            "NestedCallataArrayAbiReencodingSizeValidation",
+            "NestedCalldataArrayAbiReencodingSizeValidation",
             "ABIDecodeTwoDimensionalArrayMemory",
             "KeccakCaching",
             "EmptyByteArrayCopy",
@@ -1208,7 +1208,7 @@
         "bugs": [
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
-            "NestedCallataArrayAbiReencodingSizeValidation",
+            "NestedCalldataArrayAbiReencodingSizeValidation",
             "ABIDecodeTwoDimensionalArrayMemory",
             "KeccakCaching",
             "EmptyByteArrayCopy",
@@ -1348,7 +1348,7 @@
         "bugs": [
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
-            "NestedCallataArrayAbiReencodingSizeValidation",
+            "NestedCalldataArrayAbiReencodingSizeValidation",
             "ABIDecodeTwoDimensionalArrayMemory",
             "KeccakCaching",
             "EmptyByteArrayCopy",
@@ -1369,7 +1369,7 @@
         "bugs": [
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
-            "NestedCallataArrayAbiReencodingSizeValidation",
+            "NestedCalldataArrayAbiReencodingSizeValidation",
             "ABIDecodeTwoDimensionalArrayMemory",
             "KeccakCaching",
             "EmptyByteArrayCopy",
@@ -1389,7 +1389,7 @@
         "bugs": [
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
-            "NestedCallataArrayAbiReencodingSizeValidation",
+            "NestedCalldataArrayAbiReencodingSizeValidation",
             "ABIDecodeTwoDimensionalArrayMemory",
             "KeccakCaching",
             "EmptyByteArrayCopy",
@@ -1407,7 +1407,7 @@
         "bugs": [
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
-            "NestedCallataArrayAbiReencodingSizeValidation",
+            "NestedCalldataArrayAbiReencodingSizeValidation",
             "ABIDecodeTwoDimensionalArrayMemory",
             "KeccakCaching",
             "EmptyByteArrayCopy",
@@ -1422,10 +1422,12 @@
     },
     "0.6.10": {
         "bugs": [
+            "FullInlinerNonExpressionSplitArgumentEvaluationOrder",
+            "MissingSideEffectsOnSelectorAccess",
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
             "DataLocationChangeInInternalOverride",
-            "NestedCallataArrayAbiReencodingSizeValidation",
+            "NestedCalldataArrayAbiReencodingSizeValidation",
             "SignedImmutables",
             "ABIDecodeTwoDimensionalArrayMemory",
             "KeccakCaching",
@@ -1436,10 +1438,12 @@
     },
     "0.6.11": {
         "bugs": [
+            "FullInlinerNonExpressionSplitArgumentEvaluationOrder",
+            "MissingSideEffectsOnSelectorAccess",
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
             "DataLocationChangeInInternalOverride",
-            "NestedCallataArrayAbiReencodingSizeValidation",
+            "NestedCalldataArrayAbiReencodingSizeValidation",
             "SignedImmutables",
             "ABIDecodeTwoDimensionalArrayMemory",
             "KeccakCaching",
@@ -1450,10 +1454,12 @@
     },
     "0.6.12": {
         "bugs": [
+            "FullInlinerNonExpressionSplitArgumentEvaluationOrder",
+            "MissingSideEffectsOnSelectorAccess",
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
             "DataLocationChangeInInternalOverride",
-            "NestedCallataArrayAbiReencodingSizeValidation",
+            "NestedCalldataArrayAbiReencodingSizeValidation",
             "SignedImmutables",
             "ABIDecodeTwoDimensionalArrayMemory",
             "KeccakCaching",
@@ -1464,9 +1470,10 @@
     },
     "0.6.2": {
         "bugs": [
+            "MissingSideEffectsOnSelectorAccess",
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
-            "NestedCallataArrayAbiReencodingSizeValidation",
+            "NestedCalldataArrayAbiReencodingSizeValidation",
             "ABIDecodeTwoDimensionalArrayMemory",
             "KeccakCaching",
             "EmptyByteArrayCopy",
@@ -1481,9 +1488,10 @@
     },
     "0.6.3": {
         "bugs": [
+            "MissingSideEffectsOnSelectorAccess",
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
-            "NestedCallataArrayAbiReencodingSizeValidation",
+            "NestedCalldataArrayAbiReencodingSizeValidation",
             "ABIDecodeTwoDimensionalArrayMemory",
             "KeccakCaching",
             "EmptyByteArrayCopy",
@@ -1498,9 +1506,10 @@
     },
     "0.6.4": {
         "bugs": [
+            "MissingSideEffectsOnSelectorAccess",
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
-            "NestedCallataArrayAbiReencodingSizeValidation",
+            "NestedCalldataArrayAbiReencodingSizeValidation",
             "ABIDecodeTwoDimensionalArrayMemory",
             "KeccakCaching",
             "EmptyByteArrayCopy",
@@ -1515,9 +1524,10 @@
     },
     "0.6.5": {
         "bugs": [
+            "MissingSideEffectsOnSelectorAccess",
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
-            "NestedCallataArrayAbiReencodingSizeValidation",
+            "NestedCalldataArrayAbiReencodingSizeValidation",
             "SignedImmutables",
             "ABIDecodeTwoDimensionalArrayMemory",
             "KeccakCaching",
@@ -1532,9 +1542,10 @@
     },
     "0.6.6": {
         "bugs": [
+            "MissingSideEffectsOnSelectorAccess",
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
-            "NestedCallataArrayAbiReencodingSizeValidation",
+            "NestedCalldataArrayAbiReencodingSizeValidation",
             "SignedImmutables",
             "ABIDecodeTwoDimensionalArrayMemory",
             "KeccakCaching",
@@ -1548,9 +1559,11 @@
     },
     "0.6.7": {
         "bugs": [
+            "FullInlinerNonExpressionSplitArgumentEvaluationOrder",
+            "MissingSideEffectsOnSelectorAccess",
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
-            "NestedCallataArrayAbiReencodingSizeValidation",
+            "NestedCalldataArrayAbiReencodingSizeValidation",
             "SignedImmutables",
             "ABIDecodeTwoDimensionalArrayMemory",
             "KeccakCaching",
@@ -1564,9 +1577,11 @@
     },
     "0.6.8": {
         "bugs": [
+            "FullInlinerNonExpressionSplitArgumentEvaluationOrder",
+            "MissingSideEffectsOnSelectorAccess",
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
-            "NestedCallataArrayAbiReencodingSizeValidation",
+            "NestedCalldataArrayAbiReencodingSizeValidation",
             "SignedImmutables",
             "ABIDecodeTwoDimensionalArrayMemory",
             "KeccakCaching",
@@ -1577,10 +1592,12 @@
     },
     "0.6.9": {
         "bugs": [
+            "FullInlinerNonExpressionSplitArgumentEvaluationOrder",
+            "MissingSideEffectsOnSelectorAccess",
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
             "DataLocationChangeInInternalOverride",
-            "NestedCallataArrayAbiReencodingSizeValidation",
+            "NestedCalldataArrayAbiReencodingSizeValidation",
             "SignedImmutables",
             "ABIDecodeTwoDimensionalArrayMemory",
             "KeccakCaching",
@@ -1592,10 +1609,12 @@
     },
     "0.7.0": {
         "bugs": [
+            "FullInlinerNonExpressionSplitArgumentEvaluationOrder",
+            "MissingSideEffectsOnSelectorAccess",
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
             "DataLocationChangeInInternalOverride",
-            "NestedCallataArrayAbiReencodingSizeValidation",
+            "NestedCalldataArrayAbiReencodingSizeValidation",
             "SignedImmutables",
             "ABIDecodeTwoDimensionalArrayMemory",
             "KeccakCaching",
@@ -1606,10 +1625,12 @@
     },
     "0.7.1": {
         "bugs": [
+            "FullInlinerNonExpressionSplitArgumentEvaluationOrder",
+            "MissingSideEffectsOnSelectorAccess",
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
             "DataLocationChangeInInternalOverride",
-            "NestedCallataArrayAbiReencodingSizeValidation",
+            "NestedCalldataArrayAbiReencodingSizeValidation",
             "SignedImmutables",
             "ABIDecodeTwoDimensionalArrayMemory",
             "KeccakCaching",
@@ -1621,10 +1642,12 @@
     },
     "0.7.2": {
         "bugs": [
+            "FullInlinerNonExpressionSplitArgumentEvaluationOrder",
+            "MissingSideEffectsOnSelectorAccess",
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
             "DataLocationChangeInInternalOverride",
-            "NestedCallataArrayAbiReencodingSizeValidation",
+            "NestedCalldataArrayAbiReencodingSizeValidation",
             "SignedImmutables",
             "ABIDecodeTwoDimensionalArrayMemory",
             "KeccakCaching",
@@ -1635,10 +1658,12 @@
     },
     "0.7.3": {
         "bugs": [
+            "FullInlinerNonExpressionSplitArgumentEvaluationOrder",
+            "MissingSideEffectsOnSelectorAccess",
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
             "DataLocationChangeInInternalOverride",
-            "NestedCallataArrayAbiReencodingSizeValidation",
+            "NestedCalldataArrayAbiReencodingSizeValidation",
             "SignedImmutables",
             "ABIDecodeTwoDimensionalArrayMemory",
             "KeccakCaching",
@@ -1648,10 +1673,12 @@
     },
     "0.7.4": {
         "bugs": [
+            "FullInlinerNonExpressionSplitArgumentEvaluationOrder",
+            "MissingSideEffectsOnSelectorAccess",
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
             "DataLocationChangeInInternalOverride",
-            "NestedCallataArrayAbiReencodingSizeValidation",
+            "NestedCalldataArrayAbiReencodingSizeValidation",
             "SignedImmutables",
             "ABIDecodeTwoDimensionalArrayMemory",
             "KeccakCaching"
@@ -1660,10 +1687,12 @@
     },
     "0.7.5": {
         "bugs": [
+            "FullInlinerNonExpressionSplitArgumentEvaluationOrder",
+            "MissingSideEffectsOnSelectorAccess",
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
             "DataLocationChangeInInternalOverride",
-            "NestedCallataArrayAbiReencodingSizeValidation",
+            "NestedCalldataArrayAbiReencodingSizeValidation",
             "SignedImmutables",
             "ABIDecodeTwoDimensionalArrayMemory",
             "KeccakCaching"
@@ -1672,10 +1701,12 @@
     },
     "0.7.6": {
         "bugs": [
+            "FullInlinerNonExpressionSplitArgumentEvaluationOrder",
+            "MissingSideEffectsOnSelectorAccess",
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
             "DataLocationChangeInInternalOverride",
-            "NestedCallataArrayAbiReencodingSizeValidation",
+            "NestedCalldataArrayAbiReencodingSizeValidation",
             "SignedImmutables",
             "ABIDecodeTwoDimensionalArrayMemory",
             "KeccakCaching"
@@ -1684,10 +1715,12 @@
     },
     "0.8.0": {
         "bugs": [
+            "FullInlinerNonExpressionSplitArgumentEvaluationOrder",
+            "MissingSideEffectsOnSelectorAccess",
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
             "DataLocationChangeInInternalOverride",
-            "NestedCallataArrayAbiReencodingSizeValidation",
+            "NestedCalldataArrayAbiReencodingSizeValidation",
             "SignedImmutables",
             "ABIDecodeTwoDimensionalArrayMemory",
             "KeccakCaching"
@@ -1696,10 +1729,12 @@
     },
     "0.8.1": {
         "bugs": [
+            "FullInlinerNonExpressionSplitArgumentEvaluationOrder",
+            "MissingSideEffectsOnSelectorAccess",
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
             "DataLocationChangeInInternalOverride",
-            "NestedCallataArrayAbiReencodingSizeValidation",
+            "NestedCalldataArrayAbiReencodingSizeValidation",
             "SignedImmutables",
             "ABIDecodeTwoDimensionalArrayMemory",
             "KeccakCaching"
@@ -1708,45 +1743,57 @@
     },
     "0.8.10": {
         "bugs": [
+            "FullInlinerNonExpressionSplitArgumentEvaluationOrder",
+            "MissingSideEffectsOnSelectorAccess",
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
             "DataLocationChangeInInternalOverride",
-            "NestedCallataArrayAbiReencodingSizeValidation"
+            "NestedCalldataArrayAbiReencodingSizeValidation"
         ],
         "released": "2021-11-09"
     },
     "0.8.11": {
         "bugs": [
+            "FullInlinerNonExpressionSplitArgumentEvaluationOrder",
+            "MissingSideEffectsOnSelectorAccess",
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
             "DataLocationChangeInInternalOverride",
-            "NestedCallataArrayAbiReencodingSizeValidation",
+            "NestedCalldataArrayAbiReencodingSizeValidation",
             "AbiEncodeCallLiteralAsFixedBytesBug"
         ],
         "released": "2021-12-20"
     },
     "0.8.12": {
         "bugs": [
+            "FullInlinerNonExpressionSplitArgumentEvaluationOrder",
+            "MissingSideEffectsOnSelectorAccess",
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
             "DataLocationChangeInInternalOverride",
-            "NestedCallataArrayAbiReencodingSizeValidation",
+            "NestedCalldataArrayAbiReencodingSizeValidation",
             "AbiEncodeCallLiteralAsFixedBytesBug"
         ],
         "released": "2022-02-16"
     },
     "0.8.13": {
         "bugs": [
+            "FullInlinerNonExpressionSplitArgumentEvaluationOrder",
+            "MissingSideEffectsOnSelectorAccess",
+            "StorageWriteRemovalBeforeConditionalTermination",
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
             "InlineAssemblyMemorySideEffects",
             "DataLocationChangeInInternalOverride",
-            "NestedCallataArrayAbiReencodingSizeValidation"
+            "NestedCalldataArrayAbiReencodingSizeValidation"
         ],
         "released": "2022-03-16"
     },
     "0.8.14": {
         "bugs": [
+            "FullInlinerNonExpressionSplitArgumentEvaluationOrder",
+            "MissingSideEffectsOnSelectorAccess",
+            "StorageWriteRemovalBeforeConditionalTermination",
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
             "InlineAssemblyMemorySideEffects"
@@ -1755,32 +1802,75 @@
     },
     "0.8.15": {
         "bugs": [
+            "FullInlinerNonExpressionSplitArgumentEvaluationOrder",
+            "MissingSideEffectsOnSelectorAccess",
+            "StorageWriteRemovalBeforeConditionalTermination",
             "AbiReencodingHeadOverflowWithStaticArrayCleanup"
         ],
         "released": "2022-06-15"
     },
     "0.8.16": {
-        "bugs": [],
+        "bugs": [
+            "FullInlinerNonExpressionSplitArgumentEvaluationOrder",
+            "MissingSideEffectsOnSelectorAccess",
+            "StorageWriteRemovalBeforeConditionalTermination"
+        ],
         "released": "2022-08-08"
     },
+    "0.8.17": {
+        "bugs": [
+            "FullInlinerNonExpressionSplitArgumentEvaluationOrder",
+            "MissingSideEffectsOnSelectorAccess"
+        ],
+        "released": "2022-09-08"
+    },
+    "0.8.18": {
+        "bugs": [
+            "FullInlinerNonExpressionSplitArgumentEvaluationOrder",
+            "MissingSideEffectsOnSelectorAccess"
+        ],
+        "released": "2023-02-01"
+    },
+    "0.8.19": {
+        "bugs": [
+            "FullInlinerNonExpressionSplitArgumentEvaluationOrder",
+            "MissingSideEffectsOnSelectorAccess"
+        ],
+        "released": "2023-02-22"
+    },
     "0.8.2": {
         "bugs": [
+            "FullInlinerNonExpressionSplitArgumentEvaluationOrder",
+            "MissingSideEffectsOnSelectorAccess",
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
             "DataLocationChangeInInternalOverride",
-            "NestedCallataArrayAbiReencodingSizeValidation",
+            "NestedCalldataArrayAbiReencodingSizeValidation",
             "SignedImmutables",
             "ABIDecodeTwoDimensionalArrayMemory",
             "KeccakCaching"
         ],
         "released": "2021-03-02"
     },
+    "0.8.20": {
+        "bugs": [
+            "FullInlinerNonExpressionSplitArgumentEvaluationOrder",
+            "MissingSideEffectsOnSelectorAccess"
+        ],
+        "released": "2023-05-10"
+    },
+    "0.8.21": {
+        "bugs": [],
+        "released": "2023-07-19"
+    },
     "0.8.3": {
         "bugs": [
+            "FullInlinerNonExpressionSplitArgumentEvaluationOrder",
+            "MissingSideEffectsOnSelectorAccess",
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
             "DataLocationChangeInInternalOverride",
-            "NestedCallataArrayAbiReencodingSizeValidation",
+            "NestedCalldataArrayAbiReencodingSizeValidation",
             "SignedImmutables",
             "ABIDecodeTwoDimensionalArrayMemory"
         ],
@@ -1788,50 +1878,60 @@
     },
     "0.8.4": {
         "bugs": [
+            "FullInlinerNonExpressionSplitArgumentEvaluationOrder",
+            "MissingSideEffectsOnSelectorAccess",
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
             "DataLocationChangeInInternalOverride",
-            "NestedCallataArrayAbiReencodingSizeValidation",
+            "NestedCalldataArrayAbiReencodingSizeValidation",
             "SignedImmutables"
         ],
         "released": "2021-04-21"
     },
     "0.8.5": {
         "bugs": [
+            "FullInlinerNonExpressionSplitArgumentEvaluationOrder",
+            "MissingSideEffectsOnSelectorAccess",
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
             "DataLocationChangeInInternalOverride",
-            "NestedCallataArrayAbiReencodingSizeValidation",
+            "NestedCalldataArrayAbiReencodingSizeValidation",
             "SignedImmutables"
         ],
         "released": "2021-06-10"
     },
     "0.8.6": {
         "bugs": [
+            "FullInlinerNonExpressionSplitArgumentEvaluationOrder",
+            "MissingSideEffectsOnSelectorAccess",
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
             "DataLocationChangeInInternalOverride",
-            "NestedCallataArrayAbiReencodingSizeValidation",
+            "NestedCalldataArrayAbiReencodingSizeValidation",
             "SignedImmutables"
         ],
         "released": "2021-06-22"
     },
     "0.8.7": {
         "bugs": [
+            "FullInlinerNonExpressionSplitArgumentEvaluationOrder",
+            "MissingSideEffectsOnSelectorAccess",
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
             "DataLocationChangeInInternalOverride",
-            "NestedCallataArrayAbiReencodingSizeValidation",
+            "NestedCalldataArrayAbiReencodingSizeValidation",
             "SignedImmutables"
         ],
         "released": "2021-08-11"
     },
     "0.8.8": {
         "bugs": [
+            "FullInlinerNonExpressionSplitArgumentEvaluationOrder",
+            "MissingSideEffectsOnSelectorAccess",
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
             "DataLocationChangeInInternalOverride",
-            "NestedCallataArrayAbiReencodingSizeValidation",
+            "NestedCalldataArrayAbiReencodingSizeValidation",
             "UserDefinedValueTypesBug",
             "SignedImmutables"
         ],
@@ -1839,10 +1939,12 @@
     },
     "0.8.9": {
         "bugs": [
+            "FullInlinerNonExpressionSplitArgumentEvaluationOrder",
+            "MissingSideEffectsOnSelectorAccess",
             "AbiReencodingHeadOverflowWithStaticArrayCleanup",
             "DirtyBytesArrayToStorage",
             "DataLocationChangeInInternalOverride",
-            "NestedCallataArrayAbiReencodingSizeValidation"
+            "NestedCalldataArrayAbiReencodingSizeValidation"
         ],
         "released": "2021-09-29"
     }

docs/cheatsheet.rst

@@ -2,16 +2,17 @@
 Cheatsheet
 **********
 
-.. index:: operator; precedence
+.. index:: operator;precedence
 
 Order of Precedence of Operators
 ================================
+
 .. include:: types/operator-precedence-table.rst
 
-.. index:: assert, block, coinbase, difficulty, number, block;number, timestamp, block;timestamp, msg, data, gas, sender, value, gas price, origin, revert, require, keccak256, ripemd160, sha256, ecrecover, addmod, mulmod, cryptography, this, super, selfdestruct, balance, codehash, send
+.. index:: abi;decode, abi;encode, abi;encodePacked, abi;encodeWithSelector, abi;encodeCall, abi;encodeWithSignature
 
-Global Variables
-================
+ABI Encoding and Decoding Functions
+===================================
 
 - ``abi.decode(bytes memory encodedData, (...)) returns (...)``: :ref:`ABI <ABI>`-decodes
   the provided data. The types are given in parentheses as second argument.
@@ -24,17 +25,45 @@ Global Variables
 - ``abi.encodeCall(function functionPointer, (...)) returns (bytes memory)``: ABI-encodes a call to ``functionPointer`` with the arguments found in the
   tuple. Performs a full type-check, ensuring the types match the function signature. Result equals ``abi.encodeWithSelector(functionPointer.selector, (...))``
 - ``abi.encodeWithSignature(string memory signature, ...) returns (bytes memory)``: Equivalent
-  to ``abi.encodeWithSelector(bytes4(keccak256(bytes(signature)), ...)``
+  to ``abi.encodeWithSelector(bytes4(keccak256(bytes(signature))), ...)``
+
+.. index:: bytes;concat, string;concat
+
+Members of ``bytes`` and  ``string``
+====================================
+
 - ``bytes.concat(...) returns (bytes memory)``: :ref:`Concatenates variable number of
   arguments to one byte array<bytes-concat>`
+
 - ``string.concat(...) returns (string memory)``: :ref:`Concatenates variable number of
   arguments to one string array<string-concat>`
+
+.. index:: address;balance, address;codehash, address;send, address;code, address;transfer
+
+Members of ``address``
+======================
+
+- ``<address>.balance`` (``uint256``): balance of the :ref:`address` in Wei
+- ``<address>.code`` (``bytes memory``): code at the :ref:`address` (can be empty)
+- ``<address>.codehash`` (``bytes32``): the codehash of the :ref:`address`
+- ``<address payable>.send(uint256 amount) returns (bool)``: send given amount of Wei to :ref:`address`,
+  returns ``false`` on failure
+- ``<address payable>.transfer(uint256 amount)``: send given amount of Wei to :ref:`address`, throws on failure
+
+.. index:: blockhash, block, block;basefree, block;chainid, block;coinbase, block;difficulty, block;gaslimit, block;number, block;prevrandao, block;timestamp
+.. index:: gasleft, msg;data, msg;sender, msg;sig, msg;value, tx;gasprice, tx;origin
+
+Block and Transaction Properties
+================================
+
+- ``blockhash(uint blockNumber) returns (bytes32)``: hash of the given block - only works for 256 most recent blocks
 - ``block.basefee`` (``uint``): current block's base fee (`EIP-3198 <https://eips.ethereum.org/EIPS/eip-3198>`_ and `EIP-1559 <https://eips.ethereum.org/EIPS/eip-1559>`_)
 - ``block.chainid`` (``uint``): current chain id
 - ``block.coinbase`` (``address payable``): current block miner's address
-- ``block.difficulty`` (``uint``): current block difficulty
+- ``block.difficulty`` (``uint``): current block difficulty (``EVM < Paris``). For other EVM versions it behaves as a deprecated alias for ``block.prevrandao`` that will be removed in the next breaking release
 - ``block.gaslimit`` (``uint``): current block gaslimit
 - ``block.number`` (``uint``): current block number
+- ``block.prevrandao`` (``uint``): random number provided by the beacon chain (``EVM >= Paris``) (see `EIP-4399 <https://eips.ethereum.org/EIPS/eip-4399>`_ )
 - ``block.timestamp`` (``uint``): current block timestamp in seconds since Unix epoch
 - ``gasleft() returns (uint256)``: remaining gas
 - ``msg.data`` (``bytes``): complete calldata
@@ -43,6 +72,12 @@ Global Variables
 - ``msg.value`` (``uint``): number of wei sent with the message
 - ``tx.gasprice`` (``uint``): gas price of the transaction
 - ``tx.origin`` (``address``): sender of the transaction (full call chain)
+
+.. index:: assert, require, revert
+
+Validations and Assertions
+==========================
+
 - ``assert(bool condition)``: abort execution and revert state changes if condition is ``false`` (use for internal error)
 - ``require(bool condition)``: abort execution and revert state changes if condition is ``false`` (use
   for malformed input or error in external component)
@@ -50,7 +85,12 @@ Global Variables
   condition is ``false`` (use for malformed input or error in external component). Also provide error message.
 - ``revert()``: abort execution and revert state changes
 - ``revert(string memory message)``: abort execution and revert state changes providing an explanatory string
-- ``blockhash(uint blockNumber) returns (bytes32)``: hash of the given block - only works for 256 most recent blocks
+
+.. index:: cryptography, keccak256, sha256, ripemd160, ecrecover, addmod, mulmod
+
+Mathematical and Cryptographic Functions
+========================================
+
 - ``keccak256(bytes memory) returns (bytes32)``: compute the Keccak-256 hash of the input
 - ``sha256(bytes memory) returns (bytes32)``: compute the SHA-256 hash of the input
 - ``ripemd160(bytes memory) returns (bytes20)``: compute the RIPEMD-160 hash of the input
@@ -60,15 +100,21 @@ Global Variables
   arbitrary precision and does not wrap around at ``2**256``. Assert that ``k != 0`` starting from version 0.5.0.
 - ``mulmod(uint x, uint y, uint k) returns (uint)``: compute ``(x * y) % k`` where the multiplication is performed
   with arbitrary precision and does not wrap around at ``2**256``. Assert that ``k != 0`` starting from version 0.5.0.
+
+.. index:: this, super, selfdestruct
+
+Contract-related
+================
+
 - ``this`` (current contract's type): the current contract, explicitly convertible to ``address`` or ``address payable``
-- ``super``: the contract one level higher in the inheritance hierarchy
+- ``super``: a contract one level higher in the inheritance hierarchy
 - ``selfdestruct(address payable recipient)``: destroy the current contract, sending its funds to the given address
-- ``<address>.balance`` (``uint256``): balance of the :ref:`address` in Wei
-- ``<address>.code`` (``bytes memory``): code at the :ref:`address` (can be empty)
-- ``<address>.codehash`` (``bytes32``): the codehash of the :ref:`address`
-- ``<address payable>.send(uint256 amount) returns (bool)``: send given amount of Wei to :ref:`address`,
-  returns ``false`` on failure
-- ``<address payable>.transfer(uint256 amount)``: send given amount of Wei to :ref:`address`, throws on failure
+
+.. index:: type;name, type;creationCode, type;runtimeCode, type;interfaceId, type;min, type;max
+
+Type Information
+================
+
 - ``type(C).name`` (``string``): the name of the contract
 - ``type(C).creationCode`` (``bytes memory``): creation bytecode of the given contract, see :ref:`Type Information<meta-type>`.
 - ``type(C).runtimeCode`` (``bytes memory``): runtime bytecode of the given contract, see :ref:`Type Information<meta-type>`.
@@ -104,11 +150,11 @@ Modifiers
 - ``view`` for functions: Disallows modification of state.
 - ``payable`` for functions: Allows them to receive Ether together with a call.
 - ``constant`` for state variables: Disallows assignment (except initialisation), does not occupy storage slot.
-- ``immutable`` for state variables: Allows exactly one assignment at construction time and is constant afterwards. Is stored in code.
+- ``immutable`` for state variables: Allows assignment at construction time and is constant when deployed. Is stored in code.
 - ``anonymous`` for events: Does not store event signature as topic.
 - ``indexed`` for event parameters: Stores the parameter as topic.
 - ``virtual`` for functions and modifiers: Allows the function's or modifier's
-  behaviour to be changed in derived contracts.
+  behavior to be changed in derived contracts.
 - ``override``: States that this function, modifier or public state variable changes
-  the behaviour of a function or modifier in a base contract.
+  the behavior of a function or modifier in a base contract.
 

docs/common-patterns.rst

@@ -18,7 +18,7 @@ introduces a potential security risk. You may read
 more about this on the :ref:`security_considerations` page.
 
 The following is an example of the withdrawal pattern in practice in
-a contract where the goal is to send the most money to the
+a contract where the goal is to send the most of some compensation, e.g. Ether, to the
 contract in order to become the "richest", inspired by
 `King of the Ether <https://www.kingoftheether.com/>`_.
 
@@ -34,7 +34,7 @@ you receive the funds of the person who is now the richest.
         address public richest;
         uint public mostSent;
 
-        mapping (address => uint) pendingWithdrawals;
+        mapping(address => uint) pendingWithdrawals;
 
         /// The amount of Ether sent was not higher than
         /// the currently highest amount.
@@ -55,7 +55,7 @@ you receive the funds of the person who is now the richest.
         function withdraw() public {
             uint amount = pendingWithdrawals[msg.sender];
             // Remember to zero the pending refund before
-            // sending to prevent re-entrancy attacks
+            // sending to prevent reentrancy attacks
             pendingWithdrawals[msg.sender] = 0;
             payable(msg.sender).transfer(amount);
         }

docs/conf.py

@@ -31,7 +31,10 @@ def setup(sphinx):
     sphinx.add_lexer('Solidity', SolidityLexer)
     sphinx.add_lexer('Yul', YulLexer)
 
+    sphinx.add_css_file('css/fonts.css')
     sphinx.add_css_file('css/custom.css')
+    sphinx.add_css_file('css/custom-dark.css')
+    sphinx.add_css_file('css/pygments.css')
 
 # -- General configuration ------------------------------------------------
 
@@ -45,6 +48,7 @@ extensions = [
     'sphinx_a4doc',
     'html_extra_template_renderer',
     'remix_code_links',
+    'sphinx.ext.imgconverter',
 ]
 
 a4_base_path = os.path.dirname(__file__) + '/grammar'
@@ -63,7 +67,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = 'Solidity'
-project_copyright = '2016-2021, Ethereum'
+project_copyright = '2016-2023, The Solidity Authors'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -131,7 +135,6 @@ html_theme = 'sphinx_rtd_theme'
 # documentation.
 html_theme_options = {
     'logo_only': True,
-    'style_nav_header_background': '#65afff',
     'display_version': True,
 }
 
@@ -147,12 +150,12 @@ html_theme_options = {
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-html_logo = "logo.svg"
+# html_logo = "logo.svg"
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.
-#html_favicon = None
+html_favicon = "_static/img/favicon.ico"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -161,7 +164,7 @@ html_static_path = ['_static']
 
 html_css_files = ["css/toggle.css"]
 
-html_js_files = ["js/toggle.js"]
+html_js_files = ["js/constants.js", "js/initialize.js", "js/toggle.js"]
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
@@ -209,7 +212,7 @@ html_extra_templates = {
 #html_show_sourcelink = True
 
 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
-#html_show_sphinx = True
+html_show_sphinx = False
 
 # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
 #html_show_copyright = True

docs/contracts/constant-state-variables.rst

@@ -30,19 +30,23 @@ Not all types for constants and immutables are implemented at this time. The onl
 .. code-block:: solidity
 
     // SPDX-License-Identifier: GPL-3.0
-    pragma solidity >=0.7.4;
+    pragma solidity ^0.8.21;
 
     uint constant X = 32**22 + 8;
 
     contract C {
         string constant TEXT = "abc";
         bytes32 constant MY_HASH = keccak256("abc");
-        uint immutable decimals;
+        uint immutable decimals = 18;
         uint immutable maxBalance;
         address immutable owner = msg.sender;
 
         constructor(uint decimals_, address ref) {
-            decimals = decimals_;
+            if (decimals_ != 0)
+                // Immutables are only immutable when deployed.
+                // At construction time they can be assigned to any number of times.
+                decimals = decimals_;
+
             // Assignments to immutables can even access the environment.
             maxBalance = ref.balance;
         }
@@ -74,25 +78,34 @@ Immutable
 =========
 
 Variables declared as ``immutable`` are a bit less restricted than those
-declared as ``constant``: Immutable variables can be assigned an arbitrary
-value in the constructor of the contract or at the point of their declaration.
-They can be assigned only once and can, from that point on, be read even during
-construction time.
+declared as ``constant``: Immutable variables can be assigned a
+value at construction time.
+The value can be changed at any time before deployment and then it becomes permanent.
+
+One additional restriction is that immutables can only be assigned to inside expressions for which
+there is no possibility of being executed after creation.
+This excludes all modifier definitions and functions other than constructors.
+
+There are no restrictions on reading immutable variables.
+The read is even allowed to happen before the variable is written to for the first time because variables in
+Solidity always have a well-defined initial value.
+For this reason it is also allowed to never explicitly assign a value to an immutable.
+
+.. warning::
+    When accessing immutables at construction time, please keep the :ref:`initialization order
+    <state-variable-initialization-order>` in mind.
+    Even if you provide an explicit initializer, some expressions may end up being evaluated before
+    that initializer, especially when they are at a different level in inheritance hierarchy.
+
+.. note::
+    Before Solidity 0.8.21 initialization of immutable variables was more restrictive.
+    Such variables had to be initialized exactly once at construction time and could not be read
+    before then.
 
 The contract creation code generated by the compiler will modify the
 contract's runtime code before it is returned by replacing all references
 to immutables with the values assigned to them. This is important if
 you are comparing the
 runtime code generated by the compiler with the one actually stored in the
-blockchain.
-
-.. note::
-  Immutables that are assigned at their declaration are only considered
-  initialized once the constructor of the contract is executing.
-  This means you cannot initialize immutables inline with a value
-  that depends on another immutable. You can do this, however,
-  inside the constructor of the contract.
-
-  This is a safeguard against different interpretations about the order
-  of state variable initialization and constructor execution, especially
-  with regards to inheritance.
+blockchain. The compiler outputs where these immutables are located in the deployed bytecode
+in the ``immutableReferences`` field of the :ref:`compiler JSON standard output <compiler-api>`.

docs/contracts/creating-contracts.rst

@@ -8,7 +8,7 @@ Contracts can be created "from outside" via Ethereum transactions or from within
 
 IDEs, such as `Remix <https://remix.ethereum.org/>`_, make the creation process seamless using UI elements.
 
-One way to create contracts programmatically on Ethereum is via the JavaScript API `web3.js <https://github.com/ethereum/web3.js>`_.
+One way to create contracts programmatically on Ethereum is via the JavaScript API `web3.js <https://github.com/web3/web3.js>`_.
 It has a function called `web3.eth.Contract <https://web3js.readthedocs.io/en/1.0/web3-eth-contract.html#new-contract>`_
 to facilitate contract creation.
 

docs/contracts/events.rst

@@ -9,9 +9,10 @@ Events
 Solidity events give an abstraction on top of the EVM's logging functionality.
 Applications can subscribe and listen to these events through the RPC interface of an Ethereum client.
 
-Events are inheritable members of contracts. When you call them, they cause the
+Events can be defined at file level or as inheritable members of contracts (including interfaces and libraries).
+When you call them, they cause the
 arguments to be stored in the transaction's log - a special data structure
-in the blockchain. These logs are associated with the address of the contract,
+in the blockchain. These logs are associated with the address of the contract that emitted them,
 are incorporated into the blockchain, and stay there as long as a block is
 accessible (forever as of now, but this might
 change with Serenity). The Log and its event data is not accessible from within
@@ -151,6 +152,6 @@ The output of the above looks like the following (trimmed):
 Additional Resources for Understanding Events
 =============================================
 
-- `Javascript documentation <https://github.com/ethereum/web3.js/blob/1.x/docs/web3-eth-contract.rst#events>`_
+- `JavaScript documentation <https://github.com/web3/web3.js/blob/1.x/docs/web3-eth-contract.rst#events>`_
 - `Example usage of events <https://github.com/ethchange/smart-exchange/blob/master/lib/contracts/SmartExchange.sol>`_
 - `How to access them in js <https://github.com/ethchange/smart-exchange/blob/master/lib/exchange_transactions.js>`_

docs/contracts/function-modifiers.rst

@@ -6,7 +6,7 @@
 Function Modifiers
 ******************
 
-Modifiers can be used to change the behaviour of functions in a declarative way.
+Modifiers can be used to change the behavior of functions in a declarative way.
 For example,
 you can use a modifier to automatically check a condition prior to executing the function.
 
@@ -19,6 +19,7 @@ if they are marked ``virtual``. For details, please see
 
     // SPDX-License-Identifier: GPL-3.0
     pragma solidity >=0.7.1 <0.9.0;
+    // This will report a warning due to deprecated selfdestruct
 
     contract owned {
         constructor() { owner = payable(msg.sender); }
@@ -60,7 +61,7 @@ if they are marked ``virtual``. For details, please see
     }
 
     contract Register is priced, destructible {
-        mapping (address => bool) registeredAddresses;
+        mapping(address => bool) registeredAddresses;
         uint price;
 
         constructor(uint initialPrice) { price = initialPrice; }
@@ -111,6 +112,12 @@ whitespace-separated list and are evaluated in the order presented.
 Modifiers cannot implicitly access or change the arguments and return values of functions they modify.
 Their values can only be passed to them explicitly at the point of invocation.
 
+In function modifiers, it is necessary to specify when you want the function to which the modifier is
+applied to be run. The placeholder statement (denoted by a single underscore character ``_``) is used to
+denote where the body of the function being modified should be inserted. Note that the
+placeholder operator is different from using underscores as leading or trailing characters in variable
+names, which is a stylistic choice.
+
 Explicit returns from a modifier or function body only leave the current
 modifier or function body. Return variables are assigned and
 control flow continues after the ``_`` in the preceding modifier.
@@ -125,7 +132,7 @@ variables are set to their :ref:`default values<default-value>` just as if the f
 body.
 
 The ``_`` symbol can appear in the modifier multiple times. Each occurrence is replaced with
-the function body.
+the function body, and the function returns the return value of the final occurrence.
 
 Arbitrary expressions are allowed for modifier arguments and in this context,
 all symbols visible from the function are visible in the modifier. Symbols

docs/contracts/functions.rst

@@ -1,4 +1,4 @@
-.. index:: ! functions
+.. index:: ! functions, ! function;free
 
 .. _functions:
 
@@ -72,16 +72,6 @@ with two integers, you would use something like the following:
 
 Function parameters can be used as any other local variable and they can also be assigned to.
 
-.. note::
-
-  An :ref:`external function<external-function-calls>` cannot accept a
-  multi-dimensional array as an input
-  parameter. This functionality is possible if you enable the ABI coder v2
-  by adding ``pragma abicoder v2;`` to your source file.
-
-  An :ref:`internal function<external-function-calls>` can accept a
-  multi-dimensional array without enabling the feature.
-
 .. index:: return array, return string, array, string, array of strings, dynamic array, variably sized array, return struct, struct
 
 Return Variables
@@ -139,12 +129,16 @@ If you use an early ``return`` to leave a function that has return variables,
 you must provide return values together with the return statement.
 
 .. note::
-    You cannot return some types from non-internal functions, notably
-    multi-dimensional dynamic arrays and structs. If you enable the
-    ABI coder v2 by adding ``pragma abicoder v2;``
-    to your source file then more types are available, but
-    ``mapping`` types are still limited to inside a single contract and you
-    cannot transfer them.
+    You cannot return some types from non-internal functions.
+    This includes the types listed below and any composite types that recursively contain them:
+
+    - mappings,
+    - internal function types,
+    - reference types with location set to ``storage``,
+    - multi-dimensional arrays (applies only to :ref:`ABI coder v1 <abi_coder>`),
+    - structs (applies only to :ref:`ABI coder v1 <abi_coder>`).
+
+    This restriction does not apply to library functions because of their different :ref:`internal ABI <library-selectors>`.
 
 .. _multi-return:
 
@@ -256,7 +250,7 @@ Reverting a state change is not considered a "state modification", as only chang
 state made previously in code that did not have the ``view`` or ``pure`` restriction
 are reverted and that code has the option to catch the ``revert`` and not pass it on.
 
-This behaviour is also in line with the ``STATICCALL`` opcode.
+This behavior is also in line with the ``STATICCALL`` opcode.
 
 .. warning::
   It is not possible to prevent functions from reading the state at the level
@@ -283,7 +277,7 @@ This behaviour is also in line with the ``STATICCALL`` opcode.
 Special Functions
 =================
 
-.. index:: ! receive ether function, function;receive ! receive
+.. index:: ! receive ether function, function;receive, ! receive
 
 .. _receive-ether-function:
 
@@ -303,7 +297,7 @@ on plain Ether transfers (e.g. via ``.send()`` or ``.transfer()``). If no such
 function exists, but a payable :ref:`fallback function <fallback-function>`
 exists, the fallback function will be called on a plain Ether transfer. If
 neither a receive Ether nor a payable fallback function is present, the
-contract cannot receive Ether through regular transactions and throws an
+contract cannot receive Ether through a transaction that does not represent a payable function call and throws an
 exception.
 
 In the worst case, the ``receive`` function can only rely on 2300 gas being

docs/contracts/inheritance.rst

@@ -40,7 +40,7 @@ Details are given in the following example.
 
     // SPDX-License-Identifier: GPL-3.0
     pragma solidity >=0.7.0 <0.9.0;
-
+    // This will report a warning due to deprecated selfdestruct
 
     contract Owned {
         constructor() { owner = payable(msg.sender); }
@@ -54,7 +54,7 @@ Details are given in the following example.
     // accessed externally via `this`, though.
     contract Destructible is Owned {
         // The keyword `virtual` means that the function can change
-        // its behaviour in derived classes ("overriding").
+        // its behavior in derived classes ("overriding").
         function destroy() virtual public {
             if (msg.sender == owner) selfdestruct(owner);
         }
@@ -115,7 +115,7 @@ Details are given in the following example.
 
         // Here, we only specify `override` and not `virtual`.
         // This means that contracts deriving from `PriceFeed`
-        // cannot change the behaviour of `destroy` anymore.
+        // cannot change the behavior of `destroy` anymore.
         function destroy() public override(Destructible, Named) { Named.destroy(); }
         function get() public view returns(uint r) { return info; }
 
@@ -130,6 +130,7 @@ seen in the following example:
 
     // SPDX-License-Identifier: GPL-3.0
     pragma solidity >=0.7.0 <0.9.0;
+    // This will report a warning due to deprecated selfdestruct
 
     contract owned {
         constructor() { owner = payable(msg.sender); }
@@ -162,6 +163,7 @@ explicitly in the final override, but this function will bypass
 
     // SPDX-License-Identifier: GPL-3.0
     pragma solidity >=0.7.0 <0.9.0;
+    // This will report a warning due to deprecated selfdestruct
 
     contract owned {
         constructor() { owner = payable(msg.sender); }
@@ -291,7 +293,7 @@ and ends at a contract mentioning a function with that signature
 that does not override.
 
 If you do not mark a function that overrides as ``virtual``, derived
-contracts can no longer change the behaviour of that function.
+contracts can no longer change the behavior of that function.
 
 .. note::
 
@@ -434,11 +436,11 @@ You can use internal parameters in a constructor (for example storage pointers).
 the contract has to be marked :ref:`abstract <abstract-contract>`, because these parameters
 cannot be assigned valid values from outside but only through the constructors of derived contracts.
 
-.. warning ::
+.. warning::
     Prior to version 0.4.22, constructors were defined as functions with the same name as the contract.
     This syntax was deprecated and is not allowed anymore in version 0.5.0.
 
-.. warning ::
+.. warning::
     Prior to version 0.7.0, you had to specify the visibility of constructors as either
     ``internal`` or ``public``.
 
@@ -485,7 +487,7 @@ One way is directly in the inheritance list (``is Base(7)``).  The other is in
 the way a modifier is invoked as part of
 the derived constructor (``Base(y * y)``). The first way to
 do it is more convenient if the constructor argument is a
-constant and defines the behaviour of the contract or
+constant and defines the behavior of the contract or
 describes it. The second way has to be used if the
 constructor arguments of the base depend on those of the
 derived contract. Arguments have to be given either in the

docs/contracts/interfaces.rst

@@ -65,7 +65,7 @@ inheritance.
 Types defined inside interfaces and other contract-like structures
 can be accessed from other contracts: ``Token.TokenType`` or ``Token.Coin``.
 
-.. warning:
+.. warning::
 
     Interfaces have supported ``enum`` types since :doc:`Solidity version 0.5.0 <050-breaking-changes>`, make
     sure the pragma version specifies this version as a minimum.

docs/contracts/using-for.rst

@@ -1,4 +1,4 @@
-.. index:: ! using for, library
+.. index:: ! using for, library, ! operator;user-defined, function;free
 
 .. _using-for:
 
@@ -6,36 +6,87 @@
 Using For
 *********
 
-The directive ``using A for B;`` can be used to attach
-functions (``A``) as member functions to any type (``B``).
-These functions will receive the object they are called on
+The directive ``using A for B`` can be used to attach
+functions (``A``) as operators to user-defined value types
+or as member functions to any type (``B``).
+The member functions receive the object they are called on
 as their first parameter (like the ``self`` variable in Python).
+The operator functions receive operands as parameters.
 
 It is valid either at file level or inside a contract,
 at contract level.
 
 The first part, ``A``, can be one of:
 
-- a list of file-level or library functions (``using {f, g, h, L.t} for uint;``) -
-  only those functions will be attached to the type.
-- the name of a library (``using L for uint;``) -
-  all functions (both public and internal ones) of the library are attached to the type
+- A list of functions, optionally with an operator name assigned (e.g.
+  ``using {f, g as +, h, L.t} for uint``).
+  If no operator is specified, the function can be either a library function or a free function and
+  is attached to the type as a member function.
+  Otherwise it must be a free function and it becomes the definition of that operator on the type.
+- The name of a library (e.g. ``using L for uint``) -
+  all non-private functions of the library are attached to the type
+  as member functions
 
 At file level, the second part, ``B``, has to be an explicit type (without data location specifier).
-Inside contracts, you can also use ``using L for *;``,
+Inside contracts, you can also use ``*`` in place of the type (e.g. ``using L for *;``),
 which has the effect that all functions of the library ``L``
 are attached to *all* types.
 
-If you specify a library, *all* functions in the library are attached,
+If you specify a library, *all* non-private functions in the library get attached,
 even those where the type of the first parameter does not
 match the type of the object. The type is checked at the
 point the function is called and function overload
 resolution is performed.
 
-If you use a list of functions (``using {f, g, h, L.t} for uint;``),
+If you use a list of functions (e.g. ``using {f, g, h, L.t} for uint``),
 then the type (``uint``) has to be implicitly convertible to the
 first parameter of each of these functions. This check is
 performed even if none of these functions are called.
+Note that private library functions can only be specified when ``using for`` is inside a library.
+
+If you define an operator (e.g. ``using {f as +} for T``), then the type (``T``) must be a
+:ref:`user-defined value type <user-defined-value-types>` and the definition must be a ``pure`` function.
+Operator definitions must be global.
+The following operators can be defined this way:
+
++------------+----------+---------------------------------------------+
+| Category   | Operator | Possible signatures                         |
++============+==========+=============================================+
+| Bitwise    | ``&``    | ``function (T, T) pure returns (T)``        |
+|            +----------+---------------------------------------------+
+|            | ``|``    | ``function (T, T) pure returns (T)``        |
+|            +----------+---------------------------------------------+
+|            | ``^``    | ``function (T, T) pure returns (T)``        |
+|            +----------+---------------------------------------------+
+|            | ``~``    | ``function (T) pure returns (T)``           |
++------------+----------+---------------------------------------------+
+| Arithmetic | ``+``    | ``function (T, T) pure returns (T)``        |
+|            +----------+---------------------------------------------+
+|            | ``-``    | ``function (T, T) pure returns (T)``        |
+|            +          +---------------------------------------------+
+|            |          | ``function (T) pure returns (T)``           |
+|            +----------+---------------------------------------------+
+|            | ``*``    | ``function (T, T) pure returns (T)``        |
+|            +----------+---------------------------------------------+
+|            | ``/``    | ``function (T, T) pure returns (T)``        |
+|            +----------+---------------------------------------------+
+|            | ``%``    | ``function (T, T) pure returns (T)``        |
++------------+----------+---------------------------------------------+
+| Comparison | ``==``   | ``function (T, T) pure returns (bool)``     |
+|            +----------+---------------------------------------------+
+|            | ``!=``   | ``function (T, T) pure returns (bool)``     |
+|            +----------+---------------------------------------------+
+|            | ``<``    | ``function (T, T) pure returns (bool)``     |
+|            +----------+---------------------------------------------+
+|            | ``<=``   | ``function (T, T) pure returns (bool)``     |
+|            +----------+---------------------------------------------+
+|            | ``>``    | ``function (T, T) pure returns (bool)``     |
+|            +----------+---------------------------------------------+
+|            | ``>=``   | ``function (T, T) pure returns (bool)``     |
++------------+----------+---------------------------------------------+
+
+Note that unary and binary ``-`` need separate definitions.
+The compiler will choose the right definition based on how the operator is invoked.
 
 The ``using A for B;`` directive is active only within the current
 scope (either the contract or the current module/source unit),
@@ -45,7 +96,7 @@ outside of the contract or module in which it is used.
 When the directive is used at file level and applied to a
 user-defined type which was defined at file level in the same file,
 the word ``global`` can be added at the end. This will have the
-effect that the functions are attached to the type everywhere
+effect that the functions and operators are attached to the type everywhere
 the type is available (including other files), not only in the
 scope of the using statement.
 
@@ -149,3 +200,37 @@ if you pass memory or value types, a copy will be performed, even in case of the
 ``self`` variable. The only situation where no copy will be performed
 is when storage reference variables are used or when internal library
 functions are called.
+
+Another example shows how to define a custom operator for a user-defined type:
+
+.. code-block:: solidity
+
+    // SPDX-License-Identifier: GPL-3.0
+    pragma solidity ^0.8.19;
+
+    type UFixed16x2 is uint16;
+
+    using {
+        add as +,
+        div as /
+    } for UFixed16x2 global;
+
+    uint32 constant SCALE = 100;
+
+    function add(UFixed16x2 a, UFixed16x2 b) pure returns (UFixed16x2) {
+        return UFixed16x2.wrap(UFixed16x2.unwrap(a) + UFixed16x2.unwrap(b));
+    }
+
+    function div(UFixed16x2 a, UFixed16x2 b) pure returns (UFixed16x2) {
+        uint32 a32 = UFixed16x2.unwrap(a);
+        uint32 b32 = UFixed16x2.unwrap(b);
+        uint32 result32 = a32 * SCALE / b32;
+        require(result32 <= type(uint16).max, "Divide overflow");
+        return UFixed16x2.wrap(uint16(a32 * SCALE / b32));
+    }
+
+    contract Math {
+        function avg(UFixed16x2 a, UFixed16x2 b) public pure returns (UFixed16x2) {
+            return (a + b) / UFixed16x2.wrap(200);
+        }
+    }

docs/contracts/visibility-and-getters.rst

@@ -200,12 +200,12 @@ The next example is more complex:
         struct Data {
             uint a;
             bytes3 b;
-            mapping (uint => uint) map;
+            mapping(uint => uint) map;
             uint[3] c;
             uint[] d;
             bytes e;
         }
-        mapping (uint => mapping(bool => Data[])) public data;
+        mapping(uint => mapping(bool => Data[])) public data;
     }
 
 It generates a function of the following form. The mapping and arrays (with the

docs/contributing.rst

@@ -12,7 +12,7 @@ In particular, we appreciate support in the following areas:
   `"good first issue" <https://github.com/ethereum/solidity/labels/good%20first%20issue>`_ which are
   meant as introductory issues for external contributors.
 * Improving the documentation.
-* Translating the documentation into more languages.
+* `Translating <https://github.com/solidity-docs>`_ the documentation into more languages.
 * Responding to questions from other users on `StackExchange
   <https://ethereum.stackexchange.com>`_ and the `Solidity Gitter Chat
   <https://gitter.im/ethereum/solidity>`_.
@@ -28,12 +28,11 @@ Team Calls
 ==========
 
 If you have issues or pull requests to discuss, or are interested in hearing what
-the team and contributors are working on, you can join our public team calls:
+the team and contributors are working on, you can join our public team call:
 
-- Mondays at 3pm CET/CEST.
-- Wednesdays at 2pm CET/CEST.
+- Wednesdays at 3PM CET/CEST.
 
-Both calls take place on `Jitsi <https://meet.ethereum.org/solidity>`_.
+The call takes place on `Jitsi <https://meet.soliditylang.org/>`_.
 
 How to Report Issues
 ====================
@@ -46,11 +45,14 @@ reporting issues, please mention the following details:
 * Source code (if applicable).
 * Operating system.
 * Steps to reproduce the issue.
-* Actual vs. expected behaviour.
+* Actual vs. expected behavior.
 
 Reducing the source code that caused the issue to a bare minimum is always
 very helpful, and sometimes even clarifies a misunderstanding.
 
+For technical discussions about language design, a post in the
+`Solidity forum <https://forum.soliditylang.org/>`_ is the correct place (see :ref:`solidity_language_design`).
+
 Workflow for Pull Requests
 ==========================
 
@@ -78,6 +80,9 @@ Finally, please make sure you respect the `coding style
 for this project. Also, even though we do CI testing, please test your code and
 ensure that it builds locally before submitting a pull request.
 
+We highly recommend going through our `review checklist <https://github.com/ethereum/solidity/blob/develop/ReviewChecklist.md>`_ before submitting the pull request.
+We thoroughly review every PR and will help you get it right, but there are many common problems that can be easily avoided, making the review much smoother.
+
 Thank you for your help!
 
 Running the Compiler Tests
@@ -88,8 +93,7 @@ Prerequisites
 
 For running all compiler tests you may want to optionally install a few
 dependencies (`evmone <https://github.com/ethereum/evmone/releases>`_,
-`libz3 <https://github.com/Z3Prover/z3>`_, and
-`libhera <https://github.com/ewasm/hera>`_).
+`libz3 <https://github.com/Z3Prover/z3>`_).
 
 On macOS systems, some of the testing scripts expect GNU coreutils to be installed.
 This can be easiest accomplished using Homebrew: ``brew install coreutils``.
@@ -97,9 +101,9 @@ This can be easiest accomplished using Homebrew: ``brew install coreutils``.
 On Windows systems, make sure that you have a privilege to create symlinks,
 otherwise several tests may fail.
 Administrators should have that privilege, but you may also
-`grant it to other users <https://docs.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/create-symbolic-links#policy-management>`_
+`grant it to other users <https://learn.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/create-symbolic-links#policy-management>`_
 or
-`enable Developer Mode <https://docs.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development>`_.
+`enable Developer Mode <https://learn.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development>`_.
 
 Running the Tests
 -----------------
@@ -110,7 +114,7 @@ Running ``build/test/soltest`` or its wrapper ``scripts/soltest.sh`` is sufficie
 
 The ``./scripts/tests.sh`` script executes most Solidity tests automatically,
 including those bundled into the `Boost C++ Test Framework <https://www.boost.org/doc/libs/release/libs/test/doc/html/index.html>`_
-application ``soltest`` (or its wrapper ``scripts/soltest.sh``), as well as command line tests and
+application ``soltest`` (or its wrapper ``scripts/soltest.sh``), as well as command-line tests and
 compilation tests.
 
 The test system automatically tries to discover the location of
@@ -124,13 +128,7 @@ for the ``evmone`` shared object can be specified via the ``ETH_EVMONE`` environ
 If you do not have it installed, you can skip these tests by passing the ``--no-semantic-tests``
 flag to ``scripts/soltest.sh``.
 
-Running Ewasm tests is disabled by default and can be explicitly enabled
-via ``./scripts/soltest.sh --ewasm`` and requires `hera <https://github.com/ewasm/hera>`_
-to be found by ``soltest``.
-The mechanism for locating the ``hera`` library is the same as for ``evmone``, except that the
-variable for specifying an explicit location is called ``ETH_HERA``.
-
-The ``evmone`` and ``hera`` libraries should both end with the file name
+The ``evmone`` library should both end with the file name
 extension ``.so`` on Linux, ``.dll`` on Windows systems and ``.dylib`` on macOS.
 
 For running SMT tests, the ``libz3`` library must be installed and locatable
@@ -141,7 +139,7 @@ SMT tests by exporting ``SMT_FLAGS=--no-smt`` before running ``./scripts/tests.s
 running ``./scripts/soltest.sh --no-smt``.
 These tests are ``libsolidity/smtCheckerTests`` and ``libsolidity/smtCheckerTestsJSON``.
 
-.. note ::
+.. note::
 
     To get a list of all unit tests run by Soltest, run ``./build/test/soltest --list_content=HRF``.
 
@@ -162,7 +160,7 @@ See especially:
 - `run_test (-t) <https://www.boost.org/doc/libs/release/libs/test/doc/html/boost_test/utf_reference/rt_param_reference/run_test.html>`_ to run specific tests cases, and
 - `report-level (-r) <https://www.boost.org/doc/libs/release/libs/test/doc/html/boost_test/utf_reference/rt_param_reference/report_level.html>`_ give a more detailed report.
 
-.. note ::
+.. note::
 
     Those working in a Windows environment wanting to run the above basic sets
     without libz3. Using Git Bash, you use: ``./build/test/Release/soltest.exe -- --no-smt``.
@@ -170,6 +168,7 @@ See especially:
 
 If you want to debug using GDB, make sure you build differently than the "usual".
 For example, you could run the following command in your ``build`` folder:
+
 .. code-block:: bash
 
    cmake -DCMAKE_BUILD_TYPE=Debug ..
@@ -240,7 +239,7 @@ provides a way to edit, update or skip the current contract file, or quit the ap
 
 It offers several options for failing tests:
 
-- ``edit``: ``isoltest`` tries to open the contract in an editor so you can adjust it. It either uses the editor given on the command line (as ``isoltest --editor /path/to/editor``), in the environment variable ``EDITOR`` or just ``/usr/bin/editor`` (in that order).
+- ``edit``: ``isoltest`` tries to open the contract in an editor so you can adjust it. It either uses the editor given on the command-line (as ``isoltest --editor /path/to/editor``), in the environment variable ``EDITOR`` or just ``/usr/bin/editor`` (in that order).
 - ``update``: Updates the expectations for contract under test. This updates the annotations by removing unmet expectations and adding missing expectations. The test is then run again.
 - ``skip``: Skips the execution of this particular test.
 - ``quit``: Quits ``isoltest``.
@@ -270,6 +269,62 @@ and re-run the test. It now passes again:
     Do not put more than one contract into a single file, unless you are testing inheritance or cross-contract calls.
     Each file should test one aspect of your new feature.
 
+Command-line Tests
+------------------
+
+Our suite of end-to-end command-line tests checks the behaviour of the compiler binary as a whole
+in various scenarios.
+These tests are located in `test/cmdlineTests/ <https://github.com/ethereum/solidity/tree/develop/test/cmdlineTests>`_,
+one per subdirectory, and can be executed using the ``cmdlineTests.sh`` script.
+
+By default the script runs all available tests.
+You can also provide one or more `file name patterns <https://www.gnu.org/software/bash/manual/bash.html#Filename-Expansion>`_,
+in which case only the tests matching at least one pattern will be executed.
+It is also possible to exclude files matching a specific pattern by prefixing it with ``--exclude``.
+
+By default the script assumes that a ``solc`` binary is available inside the ``build/`` subdirectory
+inside the working copy.
+If you build the compiler outside of the source tree, you can use the ``SOLIDITY_BUILD_DIR`` environment
+variable to specify a different location for the build directory.
+
+Example:
+
+.. code-block:: bash
+
+    export SOLIDITY_BUILD_DIR=~/solidity/build/
+    test/cmdlineTests.sh "standard_*" "*_yul_*" --exclude "standard_yul_*"
+
+The commands above will run tests from directories starting with ``test/cmdlineTests/standard_`` and
+subdirectories of ``test/cmdlineTests/`` that have ``_yul_`` somewhere in the name,
+but no test whose name starts with ``standard_yul_`` will be executed.
+It will also assume that the file ``solidity/build/solc/solc`` inside your home directory is the
+compiler binary (unless you are on Windows -- then ``solidity/build/solc/Release/solc.exe``).
+
+There are several kinds of command-line tests:
+
+- *Standard JSON test*: contains at least an ``input.json`` file.
+  In general may contain:
+
+    - ``input.json``: input file to be passed to the ``--standard-json`` option on the command line.
+    - ``output.json``: expected Standard JSON output.
+    - ``args``: extra command-line arguments passed to ``solc``.
+
+- *CLI test*: contains at least an ``input.*`` file (other than ``input.json``).
+  In general may contain:
+
+    - ``input.*``: a single input file, whose name will be supplied to ``solc`` on the command line.
+      Usually ``input.sol`` or ``input.yul``.
+    - ``args``: extra command-line arguments passed to ``solc``.
+    - ``stdin``: content to be passed to ``solc`` via standard input.
+    - ``output``: expected content of the standard output.
+    - ``err``: expected content of the standard error output.
+    - ``exit``: expected exit code. If not provided, zero is expected.
+
+- *Script test*: contains a ``test.*`` file.
+  In general may contain:
+
+    - ``test.*``: a single script to run, usually ``test.sh`` or ``test.py``.
+      The script must be executable.
 
 Running the Fuzzer via AFL
 ==========================
@@ -351,7 +406,7 @@ The AFL documentation states that the corpus (the initial input files) should no
 too large. The files themselves should not be larger than 1 kB and there should be
 at most one input file per functionality, so better start with a small number of.
 There is also a tool called ``afl-cmin`` that can trim input files
-that result in similar behaviour of the binary.
+that result in similar behavior of the binary.
 
 Now run the fuzzer (the ``-m`` extends the size of memory to 60 MB):
 
@@ -398,18 +453,17 @@ contributions to Solidity.
 English Language
 ----------------
 
-Use English, with British English spelling preferred, unless using project or brand names. Try to reduce the usage of
-local slang and references, making your language as clear to all readers as possible. Below are some references to help:
+Use International English, unless using project or brand names. Try to reduce the usage of
+local slang and references, making your language as clear to all readers as possible.
+Below are some references to help:
 
 * `Simplified technical English <https://en.wikipedia.org/wiki/Simplified_Technical_English>`_
 * `International English <https://en.wikipedia.org/wiki/International_English>`_
-* `British English spelling <https://en.oxforddictionaries.com/spelling/british-and-spelling>`_
-
 
 .. note::
 
     While the official Solidity documentation is written in English, there are community contributed :ref:`translations`
-    in other languages available. Please refer to the `translation guide <https://github.com/solidity-docs/translation-guide>`_
+    in other languages available. Please refer to the `translation guide <https://github.com/solidity-docs#solidity-documentation-translation-guide>`_
     for information on how to contribute to the community translations.
 
 Title Case for Headings
@@ -478,6 +532,8 @@ Running Documentation Tests
 Make sure your contributions pass our documentation tests by running ``./docs/docs.sh`` that installs dependencies
 needed for documentation and checks for any problems such as broken links or syntax issues.
 
+.. _solidity_language_design:
+
 Solidity Language Design
 ========================
 

docs/control-structures.rst

@@ -150,8 +150,8 @@ throws an exception or goes out of gas.
     use ``f.value(x).gas(g)()``. This was deprecated in Solidity 0.6.2 and is no
     longer possible since Solidity 0.7.0.
 
-Named Calls and Anonymous Function Parameters
----------------------------------------------
+Function Calls with Named Parameters
+------------------------------------
 
 Function call arguments can be given by name, in any order,
 if they are enclosed in ``{ }`` as can be seen in the following
@@ -173,14 +173,15 @@ parameters from the function declaration, but can be in arbitrary order.
         function set(uint key, uint value) public {
             data[key] = value;
         }
-
     }
 
-Omitted Function Parameter Names
---------------------------------
+Omitted Names in Function Definitions
+-------------------------------------
 
-The names of unused parameters (especially return parameters) can be omitted.
-Those parameters will still be present on the stack, but they are inaccessible.
+The names of parameters and return values in the function declaration can be omitted.
+Those items with omitted names will still be present on the stack, but they are
+inaccessible by name. An omitted return value name
+can still return a value to the caller by use of the ``return`` statement.
 
 .. code-block:: solidity
 
@@ -364,13 +365,13 @@ i.e. the following is not valid: ``(x, uint y) = (1, 2);``
 .. warning::
     Be careful when assigning to multiple variables at the same time when
     reference types are involved, because it could lead to unexpected
-    copying behaviour.
+    copying behavior.
 
 Complications for Arrays and Structs
 ------------------------------------
 
 The semantics of assignments are more complicated for non-value types like arrays and structs,
-including ``bytes`` and ``string``, see :ref:`Data location and assignment behaviour <data-location-assignment>` for details.
+including ``bytes`` and ``string``, see :ref:`Data location and assignment behavior <data-location-assignment>` for details.
 
 In the example below the call to ``g(x)`` has no effect on ``x`` because it creates
 an independent copy of the storage value in memory. However, ``h(x)`` successfully modifies ``x``
@@ -509,7 +510,7 @@ additional checks.
 Since Solidity 0.8.0, all arithmetic operations revert on over- and underflow by default,
 thus making the use of these libraries unnecessary.
 
-To obtain the previous behaviour, an ``unchecked`` block can be used:
+To obtain the previous behavior, an ``unchecked`` block can be used:
 
 .. code-block:: solidity
 
@@ -649,7 +650,7 @@ in the following situations:
 
 For the following cases, the error data from the external call
 (if provided) is forwarded. This means that it can either cause
-an `Error` or a `Panic` (or whatever else was given):
+an ``Error`` or a ``Panic`` (or whatever else was given):
 
 #. If a ``.transfer()`` fails.
 #. If you call a function via a message call but it does not finish
@@ -684,7 +685,7 @@ and ``assert`` for internal error checking.
             addr.transfer(msg.value / 2);
             // Since transfer throws an exception on failure and
             // cannot call back here, there should be no way for us to
-            // still have half of the money.
+            // still have half of the Ether.
             assert(address(this).balance == balanceBeforeTransfer - msg.value / 2);
             return address(this).balance;
         }
@@ -718,7 +719,7 @@ The ``revert`` statement takes a custom error as direct argument without parenth
 
     revert CustomError(arg1, arg2);
 
-For backwards-compatibility reasons, there is also the ``revert()`` function, which uses parentheses
+For backward-compatibility reasons, there is also the ``revert()`` function, which uses parentheses
 and accepts a string:
 
     revert();

docs/examples/blind-auction.rst

@@ -16,11 +16,11 @@ Simple Open Auction
 ===================
 
 The general idea of the following simple auction contract is that everyone can
-send their bids during a bidding period. The bids already include sending money
-/ Ether in order to bind the bidders to their bid. If the highest bid is
-raised, the previous highest bidder gets their money back.  After the end of
+send their bids during a bidding period. The bids already include sending some compensation,
+e.g. Ether, in order to bind the bidders to their bid. If the highest bid is
+raised, the previous highest bidder gets their Ether back.  After the end of
 the bidding period, the contract has to be called manually for the beneficiary
-to receive their money - contracts cannot activate themselves.
+to receive their Ether - contracts cannot activate themselves.
 
 .. code-block:: solidity
 
@@ -92,19 +92,19 @@ to receive their money - contracts cannot activate themselves.
                 revert AuctionAlreadyEnded();
 
             // If the bid is not higher, send the
-            // money back (the revert statement
+            // Ether back (the revert statement
             // will revert all changes in this
             // function execution including
-            // it having received the money).
+            // it having received the Ether).
             if (msg.value <= highestBid)
                 revert BidNotHighEnough(highestBid);
 
             if (highestBid != 0) {
-                // Sending back the money by simply using
+                // Sending back the Ether by simply using
                 // highestBidder.send(highestBid) is a security risk
                 // because it could execute an untrusted contract.
                 // It is always safer to let the recipients
-                // withdraw their money themselves.
+                // withdraw their Ether themselves.
                 pendingReturns[highestBidder] += highestBid;
             }
             highestBidder = msg.sender;
@@ -177,19 +177,19 @@ During the **bidding period**, a bidder does not actually send their bid, but
 only a hashed version of it.  Since it is currently considered practically
 impossible to find two (sufficiently long) values whose hash values are equal,
 the bidder commits to the bid by that.  After the end of the bidding period,
-the bidders have to reveal their bids: They send their values unencrypted and
+the bidders have to reveal their bids: They send their values unencrypted, and
 the contract checks that the hash value is the same as the one provided during
 the bidding period.
 
 Another challenge is how to make the auction **binding and blind** at the same
-time: The only way to prevent the bidder from just not sending the money after
+time: The only way to prevent the bidder from just not sending the Ether after
 they won the auction is to make them send it together with the bid. Since value
 transfers cannot be blinded in Ethereum, anyone can see the value.
 
 The following contract solves this problem by accepting any value that is
 larger than the highest bid. Since this can of course only be checked during
 the reveal phase, some bids might be **invalid**, and this is on purpose (it
-even provides an explicit flag to place invalid bids with high value
+even provides an explicit flag to place invalid bids with high-value
 transfers): Bidders can confuse competition by placing several high or low
 invalid bids.
 

docs/examples/micropayment.rst

@@ -2,7 +2,7 @@
 Micropayment Channel
 ********************
 
-In this section we will learn how to build an example implementation
+In this section, we will learn how to build an example implementation
 of a payment channel. It uses cryptographic signatures to make
 repeated transfers of Ether between the same parties secure, instantaneous, and
 without transaction fees. For the example, we need to understand how to
@@ -17,14 +17,14 @@ Alice is the sender and Bob is the recipient.
 Alice only needs to send cryptographically signed messages off-chain
 (e.g. via email) to Bob and it is similar to writing checks.
 
-Alice and Bob use signatures to authorise transactions, which is possible with smart contracts on Ethereum.
+Alice and Bob use signatures to authorize transactions, which is possible with smart contracts on Ethereum.
 Alice will build a simple smart contract that lets her transmit Ether, but instead of calling a function herself
 to initiate a payment, she will let Bob do that, and therefore pay the transaction fee.
 
 The contract will work as follows:
 
     1. Alice deploys the ``ReceiverPays`` contract, attaching enough Ether to cover the payments that will be made.
-    2. Alice authorises a payment by signing a message with her private key.
+    2. Alice authorizes a payment by signing a message with her private key.
     3. Alice sends the cryptographically signed message to Bob. The message does not need to be kept secret
        (explained later), and the mechanism for sending it does not matter.
     4. Bob claims his payment by presenting the signed message to the smart contract, it verifies the
@@ -36,7 +36,7 @@ Creating the signature
 Alice does not need to interact with the Ethereum network
 to sign the transaction, the process is completely offline.
 In this tutorial, we will sign messages in the browser
-using `web3.js <https://github.com/ethereum/web3.js>`_ and
+using `web3.js <https://github.com/web3/web3.js>`_ and
 `MetaMask <https://metamask.io>`_, using the method described in `EIP-712 <https://github.com/ethereum/EIPs/pull/712>`_,
 as it provides a number of other security benefits.
 
@@ -86,7 +86,7 @@ Packing arguments
 Now that we have identified what information to include in the signed message,
 we are ready to put the message together, hash it, and sign it. For simplicity,
 we concatenate the data. The `ethereumjs-abi <https://github.com/ethereumjs/ethereumjs-abi>`_
-library provides a function called ``soliditySHA3`` that mimics the behaviour of
+library provides a function called ``soliditySHA3`` that mimics the behavior of
 Solidity's ``keccak256`` function applied to arguments encoded using ``abi.encodePacked``.
 Here is a JavaScript function that creates the proper signature for the ``ReceiverPays`` example:
 
@@ -144,6 +144,7 @@ The full contract
 
     // SPDX-License-Identifier: GPL-3.0
     pragma solidity >=0.7.0 <0.9.0;
+    // This will report a warning due to deprecated selfdestruct
     contract ReceiverPays {
         address owner = msg.sender;
 
@@ -259,7 +260,7 @@ Messages are cryptographically signed by the sender and then transmitted directl
 Each message includes the following information:
 
     * The smart contract's address, used to prevent cross-contract replay attacks.
-    * The total amount of Ether that is owed the recipient so far.
+    * The total amount of Ether that is owed to the recipient so far.
 
 A payment channel is closed just once, at the end of a series of transfers.
 Because of this, only one of the messages sent is redeemed. This is why
@@ -341,6 +342,7 @@ The full contract
 
     // SPDX-License-Identifier: GPL-3.0
     pragma solidity >=0.7.0 <0.9.0;
+    // This will report a warning due to deprecated selfdestruct
     contract SimplePaymentChannel {
         address payable public sender;      // The account sending payments.
         address payable public recipient;   // The account receiving the payments.

docs/examples/modular.rst

@@ -7,7 +7,7 @@ Modular Contracts
 A modular approach to building your contracts helps you reduce the complexity
 and improve the readability which will help to identify bugs and vulnerabilities
 during development and code review.
-If you specify and control the behaviour of each module in isolation, the
+If you specify and control the behavior of each module in isolation, the
 interactions you have to consider are only those between the module specifications
 and not every other moving part of the contract.
 In the example below, the contract uses the ``move`` method
@@ -34,7 +34,7 @@ and the sum of all balances is an invariant across the lifetime of the contract.
     contract Token {
         mapping(address => uint256) balances;
         using Balances for *;
-        mapping(address => mapping (address => uint256)) allowed;
+        mapping(address => mapping(address => uint256)) allowed;
 
         event Transfer(address from, address to, uint amount);
         event Approval(address owner, address spender, uint amount);

docs/examples/safe-remote.rst

@@ -6,18 +6,18 @@ Safe Remote Purchase
 
 Purchasing goods remotely currently requires multiple parties that need to trust each other.
 The simplest configuration involves a seller and a buyer. The buyer would like to receive
-an item from the seller and the seller would like to get money (or an equivalent)
+an item from the seller and the seller would like to get some compensation, e.g. Ether,
 in return. The problematic part is the shipment here: There is no way to determine for
 sure that the item arrived at the buyer.
 
 There are multiple ways to solve this problem, but all fall short in one or the other way.
 In the following example, both parties have to put twice the value of the item into the
-contract as escrow. As soon as this happened, the money will stay locked inside
+contract as escrow. As soon as this happened, the Ether will stay locked inside
 the contract until the buyer confirms that they received the item. After that,
 the buyer is returned the value (half of their deposit) and the seller gets three
 times the value (their deposit plus the value). The idea behind
 this is that both parties have an incentive to resolve the situation or otherwise
-their money is locked forever.
+their Ether is locked forever.
 
 This contract of course does not solve the problem, but gives an overview of how
 you can use state machine-like constructs inside a contract.

docs/examples/voting.rst

@@ -193,5 +193,8 @@ of votes.
 Possible Improvements
 =====================
 
-Currently, many transactions are needed to assign the rights
-to vote to all participants. Can you think of a better way?
+Currently, many transactions are needed to
+assign the rights to vote to all participants.
+Moreover, if two or more proposals have the same
+number of votes, ``winningProposal()`` is not able
+to register a tie. Can you think of a way to fix these issues?

docs/ext/remix_code_links.py

@@ -22,23 +22,16 @@ def remix_code_url(source_code, language, solidity_version):
     # NOTE: base64 encoded data may contain +, = and / characters. Remix seems to handle them just
     # fine without any escaping.
     base64_encoded_source = base64.b64encode(source_code.encode('utf-8')).decode('ascii')
-    return f"https://remix.ethereum.org/?language={language}&version={solidity_version}&code={base64_encoded_source}"
+    return f"https://remix.ethereum.org/?#language={language}&version={solidity_version}&code={base64_encoded_source}"
 
 
 def build_remix_link_node(url):
-    link_icon_node = docutils.nodes.inline()
-    link_icon_node.set_class('link-icon')
-
-    link_text_node = docutils.nodes.inline(text="open in Remix")
-    link_text_node.set_class('link-text')
-
-    reference_node = docutils.nodes.reference('', '', internal=False, refuri=url)
+    reference_node = docutils.nodes.reference('', 'open in Remix', internal=False, refuri=url, target='_blank')
     reference_node.set_class('remix-link')
-    reference_node += [link_icon_node, link_text_node]
 
     paragraph_node = docutils.nodes.paragraph()
     paragraph_node.set_class('remix-link-container')
-    paragraph_node += reference_node
+    paragraph_node.append(reference_node)
     return paragraph_node
 
 
@@ -49,22 +42,24 @@ def insert_remix_link(app, doctree, solidity_version):
     for literal_block_node in doctree.traverse(docutils.nodes.literal_block):
         assert 'language' in literal_block_node.attributes
         language = literal_block_node.attributes['language'].lower()
-        if language in ['solidity', 'yul']:
-            text_nodes = list(literal_block_node.traverse(docutils.nodes.Text))
-            assert len(text_nodes) == 1
+        if language not in ['solidity', 'yul']:
+            continue
 
-            remix_url = remix_code_url(text_nodes[0], language, solidity_version)
-            url_length = len(remix_url.encode('utf-8'))
-            if url_length > MAX_SAFE_URL_LENGTH:
-                logger.warning(
-                    "Remix URL generated from the code snippet exceeds the maximum safe URL length "
-                    " (%d > %d bytes).",
-                    url_length,
-                    MAX_SAFE_URL_LENGTH,
-                    location=(literal_block_node.source, literal_block_node.line),
-                )
+        text_nodes = list(literal_block_node.traverse(docutils.nodes.Text))
+        assert len(text_nodes) == 1
 
-            insert_node_before(literal_block_node, build_remix_link_node(remix_url))
+        remix_url = remix_code_url(text_nodes[0], language, solidity_version)
+        url_length = len(remix_url.encode('utf-8'))
+        if url_length > MAX_SAFE_URL_LENGTH:
+            logger.warning(
+                "Remix URL generated from the code snippet exceeds the maximum safe URL length "
+                " (%d > %d bytes).",
+                url_length,
+                MAX_SAFE_URL_LENGTH,
+                location=(literal_block_node.source, literal_block_node.line),
+            )
+
+        insert_node_before(literal_block_node, build_remix_link_node(remix_url))
 
 
 def setup(app):

docs/grammar/SolidityLexer.g4

@@ -62,7 +62,7 @@ New: 'new';
 /**
  * Unit denomination for numbers.
  */
-NumberUnit: 'wei' | 'gwei' | 'ether' | 'seconds' | 'minutes' | 'hours' | 'days' | 'weeks' | 'years';
+SubDenomination: 'wei' | 'gwei' | 'ether' | 'seconds' | 'minutes' | 'hours' | 'days' | 'weeks' | 'years';
 Override: 'override';
 Payable: 'payable';
 Pragma: 'pragma' -> pushMode(PragmaMode);
@@ -90,6 +90,7 @@ Try: 'try';
 Type: 'type';
 Ufixed: 'ufixed' | ('ufixed' [1-9][0-9]+ 'x' [1-9][0-9]+);
 Unchecked: 'unchecked';
+Unicode: 'unicode';
 /**
  * Sized unsigned integer types.
  * uint is an alias of uint256.
@@ -198,9 +199,7 @@ fragment EscapeSequence:
 /**
  * A single quoted string literal allowing arbitrary unicode characters.
  */
-UnicodeStringLiteral:
-	'unicode"' DoubleQuotedUnicodeStringCharacter* '"'
-	| 'unicode\'' SingleQuotedUnicodeStringCharacter* '\'';
+UnicodeStringLiteral: 'unicode' (('"' DoubleQuotedUnicodeStringCharacter* '"') | ('\'' SingleQuotedUnicodeStringCharacter* '\''));
 //@doc:inline
 fragment DoubleQuotedUnicodeStringCharacter: ~["\r\n\\] | EscapeSequence;
 //@doc:inline
@@ -222,6 +221,14 @@ fragment EvenHexDigits: HexCharacter HexCharacter ('_'? HexCharacter HexCharacte
 //@doc:inline
 fragment HexCharacter: [0-9A-Fa-f];
 
+/**
+ * Scanned but not used by any rule, i.e, disallowed.
+ * solc parser considers number starting with '0', not immediately followed by '.' or 'x' as
+ * octal, even if non octal digits '8' and '9' are present.
+ */
+OctalNumber: '0' DecimalDigits ('.' DecimalDigits)?;
+
+
 /**
  * A decimal number literal consists of decimal digits that may be delimited by underscores and
  * an optional positive or negative exponent.
@@ -232,6 +239,12 @@ DecimalNumber: (DecimalDigits | (DecimalDigits? '.' DecimalDigits)) ([eE] '-'? D
 fragment DecimalDigits: [0-9] ('_'? [0-9])* ;
 
 
+/**
+ * This is needed to avoid successfully parsing a number followed by a string with no whitespace between.
+ */
+DecimalNumberFollowedByIdentifier: DecimalNumber Identifier;
+
+
 /**
  * An identifier in solidity has to start with a letter, a dollar-sign or an underscore and
  * may additionally contain numbers after the first symbol.
@@ -291,8 +304,8 @@ YulEVMBuiltin:
 	| 'returndatacopy' | 'extcodehash' | 'create' | 'create2' | 'call' | 'callcode'
 	| 'delegatecall' | 'staticcall' | 'return' | 'revert' | 'selfdestruct' | 'invalid'
 	| 'log0' | 'log1' | 'log2' | 'log3' | 'log4' | 'chainid' | 'origin' | 'gasprice'
-	| 'blockhash' | 'coinbase' | 'timestamp' | 'number' | 'difficulty' | 'gaslimit'
-	| 'basefee';
+	| 'blockhash' | 'coinbase' | 'timestamp' | 'number' | 'difficulty' | 'prevrandao'
+	| 'gaslimit' | 'basefee';
 
 YulLBrace: '{' -> pushMode(YulMode);
 YulRBrace: '}' -> popMode;

docs/grammar/SolidityParser.g4

@@ -22,6 +22,7 @@ sourceUnit: (
 	| enumDefinition
 	| userDefinedValueTypeDefinition
 	| errorDefinition
+	| eventDefinition
 )* EOF;
 
 //@doc: inline
@@ -152,7 +153,7 @@ stateMutability: Pure | View | Payable;
  */
 overrideSpecifier: Override (LParen overrides+=identifierPath (Comma overrides+=identifierPath)* RParen)?;
 /**
- * The definition of contract, library and interface functions.
+ * The definition of contract, library, interface or free functions.
  * Depending on the context in which the function is defined, further restrictions may apply,
  * e.g. functions in interfaces have to be unimplemented, i.e. may not contain a body block.
  */
@@ -161,7 +162,7 @@ locals[
 	boolean visibilitySet = false,
 	boolean mutabilitySet = false,
 	boolean virtualSet = false,
-	boolean overrideSpecifierSet = false
+	boolean overrideSpecifierSet = false,
 ]
 :
 	Function (identifier | Fallback | Receive)
@@ -175,6 +176,7 @@ locals[
 	 )*
 	(Returns LParen returnParameters=parameterList RParen)?
 	(Semicolon | body=block);
+
 /**
  * The definition of a modifier.
  * Note that within the body block of a modifier, the underscore cannot be used as identifier,
@@ -312,10 +314,30 @@ errorDefinition:
 	Semicolon;
 
 /**
- * Using directive to bind library functions and free functions to types.
+ * Operators that users are allowed to implement for some types with `using for`.
+ */
+userDefinableOperator:
+	BitAnd
+	| BitNot
+	| BitOr
+	| BitXor
+	| Add
+	| Div
+	| Mod
+	| Mul
+	| Sub
+	| Equal
+	| GreaterThan
+	| GreaterThanOrEqual
+	| LessThan
+	| LessThanOrEqual
+	| NotEqual;
+
+/**
+ * Using directive to attach library functions and free functions to types.
  * Can occur within contracts and libraries and at the file level.
  */
-usingDirective: Using (identifierPath | (LBrace identifierPath (Comma identifierPath)* RBrace)) For (Mul | typeName) Global? Semicolon;
+usingDirective: Using (identifierPath | (LBrace identifierPath (As userDefinableOperator)? (Comma identifierPath (As userDefinableOperator)?)* RBrace)) For (Mul | typeName) Global? Semicolon;
 /**
  * A type name can be an elementary type, a function type, a mapping type, a user-defined type
  * (e.g. a contract or struct) or an array type.
@@ -347,7 +369,7 @@ dataLocation: Memory | Storage | Calldata;
  */
 expression:
 	expression LBrack index=expression? RBrack # IndexAccess
-	| expression LBrack start=expression? Colon end=expression? RBrack # IndexRangeAccess
+	| expression LBrack startIndex=expression? Colon endIndex=expression? RBrack # IndexRangeAccess
 	| expression Period (identifier | Address) # MemberAccess
 	| expression LBrace (namedArgument (Comma namedArgument)*)? RBrace # FunctionCallOptions
 	| expression callArgumentList # FunctionCall
@@ -368,12 +390,13 @@ expression:
 	| expression Or expression # OrOperation
 	|<assoc=right> expression Conditional expression Colon expression # Conditional
 	|<assoc=right> expression assignOp expression # Assignment
-	| New typeName # NewExpression
+	| New typeName # NewExpr
 	| tupleExpression # Tuple
 	| inlineArrayExpression # InlineArray
  	| (
 		identifier
 		| literal
+		| literalWithSubDenomination
 		| elementaryTypeName[false]
 	  ) # PrimaryExpression
 ;
@@ -392,6 +415,9 @@ inlineArrayExpression: LBrack (expression ( Comma expression)* ) RBrack;
 identifier: Identifier | From | Error | Revert | Global;
 
 literal: stringLiteral | numberLiteral | booleanLiteral | hexStringLiteral | unicodeStringLiteral;
+
+literalWithSubDenomination: numberLiteral SubDenomination;
+
 booleanLiteral: True | False;
 /**
  * A full string literal consists of either one or several consecutive quoted strings.
@@ -409,7 +435,8 @@ unicodeStringLiteral: UnicodeStringLiteral+;
 /**
  * Number literals can be decimal or hexadecimal numbers with an optional unit.
  */
-numberLiteral: (DecimalNumber | HexNumber) NumberUnit?;
+numberLiteral: DecimalNumber | HexNumber;
+
 /**
  * A curly-braced block of statements. Opens its own scope.
  */
@@ -504,7 +531,7 @@ variableDeclarationTuple:
 variableDeclarationStatement: ((variableDeclaration (Assign expression)?) | (variableDeclarationTuple Assign expression)) Semicolon;
 expressionStatement: expression Semicolon;
 
-mappingType: Mapping LParen key=mappingKeyType DoubleArrow value=typeName RParen;
+mappingType: Mapping LParen key=mappingKeyType name=identifier? DoubleArrow value=typeName name=identifier? RParen;
 /**
  * Only elementary types or user defined types are viable as mapping keys.
  */

docs/index.rst

@@ -1,38 +1,35 @@
 Solidity
 ========
 
-Solidity is an object-oriented, high-level language for implementing smart
-contracts. Smart contracts are programs which govern the behaviour of accounts
-within the Ethereum state.
+Solidity is an object-oriented, high-level language for implementing smart contracts.
+Smart contracts are programs that govern the behavior of accounts within the Ethereum state.
 
 Solidity is a `curly-bracket language <https://en.wikipedia.org/wiki/List_of_programming_languages_by_type#Curly-bracket_languages>`_ designed to target the Ethereum Virtual Machine (EVM).
-It is influenced by C++, Python and JavaScript. You can find more details about which languages Solidity has been inspired by in the :doc:`language influences <language-influences>` section.
+It is influenced by C++, Python, and JavaScript.
+You can find more details about which languages Solidity has been inspired by in the :doc:`language influences <language-influences>` section.
 
-Solidity is statically typed, supports inheritance, libraries and complex
-user-defined types among other features.
+Solidity is statically typed, supports inheritance, libraries, and complex user-defined types, among other features.
 
-With Solidity you can create contracts for uses such as voting, crowdfunding, blind auctions,
-and multi-signature wallets.
+With Solidity, you can create contracts for uses such as voting, crowdfunding, blind auctions, and multi-signature wallets.
 
-When deploying contracts, you should use the latest released
-version of Solidity. Apart from exceptional cases, only the latest version receives
+When deploying contracts, you should use the latest released version of Solidity.
+Apart from exceptional cases, only the latest version receives
 `security fixes <https://github.com/ethereum/solidity/security/policy#supported-versions>`_.
-Furthermore, breaking changes as well as
-new features are introduced regularly. We currently use
-a 0.y.z version number `to indicate this fast pace of change <https://semver.org/#spec-item-4>`_.
+Furthermore, breaking changes, as well as new features, are introduced regularly.
+We currently use a 0.y.z version number `to indicate this fast pace of change <https://semver.org/#spec-item-4>`_.
 
 .. warning::
 
-  Solidity recently released the 0.8.x version that introduced a lot of breaking
-  changes. Make sure you read :doc:`the full list <080-breaking-changes>`.
+  Solidity recently released the 0.8.x version that introduced a lot of breaking changes.
+  Make sure you read :doc:`the full list <080-breaking-changes>`.
 
 Ideas for improving Solidity or this documentation are always welcome,
 read our :doc:`contributors guide <contributing>` for more details.
 
 .. Hint::
 
-  You can download this documentation as PDF, HTML or Epub by clicking on the versions
-  flyout menu in the bottom-left corner and selecting the preferred download format.
+  You can download this documentation as PDF, HTML or Epub
+  by clicking on the versions flyout menu in the bottom-left corner and selecting the preferred download format.
 
 
 Getting Started
@@ -40,8 +37,7 @@ Getting Started
 
 **1. Understand the Smart Contract Basics**
 
-If you are new to the concept of smart contracts we recommend you to get started by digging
-into the "Introduction to Smart Contracts" section, which covers:
+If you are new to the concept of smart contracts, we recommend you to get started by digging into the "Introduction to Smart Contracts" section, which covers the following:
 
 * :ref:`A simple example smart contract <simple-smart-contract>` written in Solidity.
 * :ref:`Blockchain Basics <blockchain-basics>`.
@@ -59,29 +55,27 @@ simply choose your preferred option and follow the steps outlined on the :ref:`i
 
 .. hint::
   You can try out code examples directly in your browser with the
-  `Remix IDE <https://remix.ethereum.org>`_. Remix is a web browser based IDE
-  that allows you to write, deploy and administer Solidity smart contracts, without
-  the need to install Solidity locally.
+  `Remix IDE <https://remix.ethereum.org>`_.
+  Remix is a web browser-based IDE that allows you to write, deploy and administer Solidity smart contracts,
+  without the need to install Solidity locally.
 
 .. warning::
-    As humans write software, it can have bugs. You should follow established
-    software development best-practices when writing your smart contracts. This
-    includes code review, testing, audits, and correctness proofs. Smart contract
-    users are sometimes more confident with code than their authors, and
-    blockchains and smart contracts have their own unique issues to
-    watch out for, so before working on production code, make sure you read the
-    :ref:`security_considerations` section.
+    As humans write software, it can have bugs.
+    Therefore, you should follow established software development best practices when writing your smart contracts.
+    This includes code review, testing, audits, and correctness proofs.
+    Smart contract users are sometimes more confident with code than their authors,
+    and blockchains and smart contracts have their own unique issues to watch out for,
+    so before working on production code, make sure you read the :ref:`security_considerations` section.
 
 **4. Learn More**
 
-If you want to learn more about building decentralized applications on Ethereum, the
-`Ethereum Developer Resources <https://ethereum.org/en/developers/>`_
-can help you with further general documentation around Ethereum, and a wide selection of tutorials,
-tools and development frameworks.
+If you want to learn more about building decentralized applications on Ethereum,
+the `Ethereum Developer Resources <https://ethereum.org/en/developers/>`_ can help you with further general documentation around Ethereum,
+and a wide selection of tutorials, tools, and development frameworks.
 
 If you have any questions, you can try searching for answers or asking on the
-`Ethereum StackExchange <https://ethereum.stackexchange.com/>`_, or
-our `Gitter channel <https://gitter.im/ethereum/solidity/>`_.
+`Ethereum StackExchange <https://ethereum.stackexchange.com/>`_,
+or our `Gitter channel <https://gitter.im/ethereum/solidity>`_.
 
 .. _translations:
 
@@ -89,23 +83,26 @@ Translations
 ------------
 
 Community contributors help translate this documentation into several languages.
-Note that they have varying degrees of completeness and up-to-dateness. The English
-version stands as a reference.
+Note that they have varying degrees of completeness and up-to-dateness.
+The English version stands as a reference.
 
 You can switch between languages by clicking on the flyout menu in the bottom-left corner
 and selecting the preferred language.
 
+* `Chinese <https://docs.soliditylang.org/zh/latest/>`_
 * `French <https://docs.soliditylang.org/fr/latest/>`_
 * `Indonesian <https://github.com/solidity-docs/id-indonesian>`_
-* `Persian <https://github.com/solidity-docs/fa-persian>`_
 * `Japanese <https://github.com/solidity-docs/ja-japanese>`_
 * `Korean <https://github.com/solidity-docs/ko-korean>`_
-* `Chinese <https://github.com/solidity-docs/zh-cn-chinese/>`_
+* `Persian <https://github.com/solidity-docs/fa-persian>`_
+* `Russian <https://github.com/solidity-docs/ru-russian>`_
+* `Spanish <https://github.com/solidity-docs/es-spanish>`_
+* `Turkish <https://docs.soliditylang.org/tr/latest/>`_
 
 .. note::
 
-   We recently set up a new GitHub organization and translation workflow to help streamline the
-   community efforts. Please refer to the `translation guide <https://github.com/solidity-docs/translation-guide>`_
+   We set up a GitHub organization and translation workflow to help streamline the community efforts.
+   Please refer to the translation guide in the `solidity-docs org <https://github.com/solidity-docs>`_
    for information on how to start a new language or contribute to the community translations.
 
 Contents
@@ -118,8 +115,8 @@ Contents
    :caption: Basics
 
    introduction-to-smart-contracts.rst
-   installing-solidity.rst
    solidity-by-example.rst
+   installing-solidity.rst
 
 .. toctree::
    :maxdepth: 2
@@ -158,21 +155,31 @@ Contents
 
 .. toctree::
    :maxdepth: 2
-   :caption: Additional Material
+   :caption: Advisory content
 
+   security-considerations.rst
+   bugs.rst
    050-breaking-changes.rst
    060-breaking-changes.rst
    070-breaking-changes.rst
    080-breaking-changes.rst
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Additional Material
+
    natspec-format.rst
-   security-considerations.rst
    smtchecker.rst
-   resources.rst
-   path-resolution.rst
    yul.rst
+   path-resolution.rst
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Resources
+
    style-guide.rst
    common-patterns.rst
-   bugs.rst
+   resources.rst
    contributing.rst
-   brand-guide.rst
    language-influences.rst
+   brand-guide.rst

docs/installing-solidity.rst

@@ -10,12 +10,12 @@ Versioning
 ==========
 
 Solidity versions follow `Semantic Versioning <https://semver.org>`_. In
-addition, patch level releases with major release 0 (i.e. 0.x.y) will not
+addition, patch-level releases with major release 0 (i.e. 0.x.y) will not
 contain breaking changes. That means code that compiles with version 0.x.y
 can be expected to compile with 0.x.z where z > y.
 
-In addition to releases, we provide **nightly development builds** with the
-intention of making it easy for developers to try out upcoming features and
+In addition to releases, we provide **nightly development builds** to make
+it easy for developers to try out upcoming features and
 provide early feedback. Note, however, that while the nightly builds are usually
 very stable, they contain bleeding-edge code from the development branch and are
 not guaranteed to be always working. Despite our best efforts, they might
@@ -33,12 +33,12 @@ Remix
 
 `Access Remix online <https://remix.ethereum.org/>`_, you do not need to install anything.
 If you want to use it without connection to the Internet, go to
-https://github.com/ethereum/remix-live/tree/gh-pages and download the ``.zip`` file as
-explained on that page. Remix is also a convenient option for testing nightly builds
+https://github.com/ethereum/remix-live/tree/gh-pages#readme and follow the instructions on that page.
+Remix is also a convenient option for testing nightly builds
 without installing multiple Solidity versions.
 
-Further options on this page detail installing commandline Solidity compiler software
-on your computer. Choose a commandline compiler if you are working on a larger contract
+Further options on this page detail installing command-line Solidity compiler software
+on your computer. Choose a command-line compiler if you are working on a larger contract
 or if you require more compilation options.
 
 .. _solcjs:
@@ -54,7 +54,7 @@ the full-featured compiler, ``solc``. The usage of ``solcjs`` is documented insi
 `repository <https://github.com/ethereum/solc-js>`_.
 
 Note: The solc-js project is derived from the C++
-`solc` by using Emscripten which means that both use the same compiler source code.
+`solc` by using Emscripten, which means that both use the same compiler source code.
 `solc-js` can be used in JavaScript projects directly (such as Remix).
 Please refer to the solc-js repository for instructions.
 
@@ -64,18 +64,18 @@ Please refer to the solc-js repository for instructions.
 
 .. note::
 
-    The commandline executable is named ``solcjs``.
+    The command-line executable is named ``solcjs``.
 
-    The commandline options of ``solcjs`` are not compatible with ``solc`` and tools (such as ``geth``)
-    expecting the behaviour of ``solc`` will not work with ``solcjs``.
+    The command-line options of ``solcjs`` are not compatible with ``solc`` and tools (such as ``geth``)
+    expecting the behavior of ``solc`` will not work with ``solcjs``.
 
 Docker
 ======
 
-Docker images of Solidity builds are available using the ``solc`` image from the ``ethereum`` organisation.
+Docker images of Solidity builds are available using the ``solc`` image from the ``ethereum`` organization.
 Use the ``stable`` tag for the latest released version, and ``nightly`` for potentially unstable changes in the develop branch.
 
-The Docker image runs the compiler executable, so you can pass all compiler arguments to it.
+The Docker image runs the compiler executable so that you can pass all compiler arguments to it.
 For example, the command below pulls the stable version of the ``solc`` image (if you do not have it already),
 and runs it in a new container, passing the ``--help`` argument.
 
@@ -83,13 +83,13 @@ and runs it in a new container, passing the ``--help`` argument.
 
     docker run ethereum/solc:stable --help
 
-You can also specify release build versions in the tag, for example, for the 0.5.4 release.
+For example, You can specify release build versions in the tag for the 0.5.4 release.
 
 .. code-block:: bash
 
     docker run ethereum/solc:0.5.4 --help
 
-To use the Docker image to compile Solidity files on the host machine mount a
+To use the Docker image to compile Solidity files on the host machine, mount a
 local folder for input and output, and specify the contract to compile. For example.
 
 .. code-block:: bash
@@ -97,7 +97,7 @@ local folder for input and output, and specify the contract to compile. For exam
     docker run -v /local/path:/sources ethereum/solc:stable -o /sources/output --abi --bin /sources/Contract.sol
 
 You can also use the standard JSON interface (which is recommended when using the compiler with tooling).
-When using this interface it is not necessary to mount any directories as long as the JSON input is
+When using this interface, it is not necessary to mount any directories as long as the JSON input is
 self-contained (i.e. it does not refer to any external files that would have to be
 :ref:`loaded by the import callback <initial-vfs-content-standard-json-with-import-callback>`).
 
@@ -130,13 +130,15 @@ The nightly version can be installed using these commands:
     sudo apt-get install solc
 
 Furthermore, some Linux distributions provide their own packages. These packages are not directly
-maintained by us, but usually kept up-to-date by the respective package maintainers.
+maintained by us but usually kept up-to-date by the respective package maintainers.
 
-For example, Arch Linux has packages for the latest development version:
+For example, Arch Linux has packages for the latest development version as AUR packages: `solidity <https://aur.archlinux.org/packages/solidity>`_
+and `solidity-bin <https://aur.archlinux.org/packages/solidity-bin>`_.
 
-.. code-block:: bash
+.. note::
 
-    pacman -S solidity
+    Please be aware that `AUR <https://wiki.archlinux.org/title/Arch_User_Repository>`_ packages
+    are user-produced content and unofficial packages. Exercise caution when using them.
 
 There is also a `snap package <https://snapcraft.io/solc>`_, however, it is **currently unmaintained**.
 It is installable in all the `supported Linux distros <https://snapcraft.io/docs/core/install>`_. To
@@ -212,12 +214,12 @@ out-of-the-box but it is also meant to be friendly to third-party tools:
   HTTPS without any authentication, rate limiting or the need to use git.
 - Content is served with correct `Content-Type` headers and lenient CORS configuration so that it
   can be directly loaded by tools running in the browser.
-- Binaries do not require installation or unpacking (with the exception of older Windows builds
+- Binaries do not require installation or unpacking (exception for older Windows builds
   bundled with necessary DLLs).
-- We strive for a high level of backwards-compatibility. Files, once added, are not removed or moved
+- We strive for a high level of backward-compatibility. Files, once added, are not removed or moved
   without providing a symlink/redirect at the old location. They are also never modified
   in place and should always match the original checksum. The only exception would be broken or
-  unusable files with a potential to cause more harm than good if left as is.
+  unusable files with the potential to cause more harm than good if left as is.
 - Files are served over both HTTP and HTTPS. As long as you obtain the file list in a secure way
   (via git, HTTPS, IPFS or just have it cached locally) and verify hashes of the binaries
   after downloading them, you do not have to use HTTPS for the binaries themselves.
@@ -228,7 +230,7 @@ that we do not rename them if the naming convention changes and we do not add bu
 that were not supported at the time of release. This only happens in ``solc-bin``.
 
 The ``solc-bin`` repository contains several top-level directories, each representing a single platform.
-Each one contains a ``list.json`` file listing the available binaries. For example in
+Each one includes a ``list.json`` file listing the available binaries. For example in
 ``emscripten-wasm32/list.json`` you will find the following information about version 0.7.4:
 
 .. code-block:: json
@@ -259,7 +261,7 @@ This means that:
 - The file might in future be available on Swarm at `16c5f09109c793db99fe35f037c6092b061bd39260ee7a677c8a97f18c955ab1`_.
 - You can verify the integrity of the binary by comparing its keccak256 hash to
   ``0x300330ecd127756b824aa13e843cb1f43c473cb22eaf3750d5fb9c99279af8c3``.  The hash can be computed
-  on the command line using ``keccak256sum`` utility provided by `sha3sum`_ or `keccak256() function
+  on the command-line using ``keccak256sum`` utility provided by `sha3sum`_ or `keccak256() function
   from ethereumjs-util`_ in JavaScript.
 - You can also verify the integrity of the binary by comparing its sha256 hash to
   ``0x2b55ed5fec4d9625b6c7b3ab1abd2b7fb7dd2a9c68543bf0323db2c7e2d55af2``.
@@ -310,7 +312,6 @@ This means that:
 
 Building from Source
 ====================
-
 Prerequisites - All Operating Systems
 -------------------------------------
 
@@ -319,14 +320,15 @@ The following are dependencies for all builds of Solidity:
 +-----------------------------------+-------------------------------------------------------+
 | Software                          | Notes                                                 |
 +===================================+=======================================================+
-| `CMake`_ (version 3.13+)          | Cross-platform build file generator.                  |
+| `CMake`_ (version 3.21.3+ on      | Cross-platform build file generator.                  |
+| Windows, 3.13+ otherwise)         |                                                       |
 +-----------------------------------+-------------------------------------------------------+
 | `Boost`_ (version 1.77+ on        | C++ libraries.                                        |
 | Windows, 1.65+ otherwise)         |                                                       |
 +-----------------------------------+-------------------------------------------------------+
 | `Git`_                            | Command-line tool for retrieving source code.         |
 +-----------------------------------+-------------------------------------------------------+
-| `z3`_ (version 4.8+, Optional)    | For use with SMT checker.                             |
+| `z3`_ (version 4.8.16+, Optional) | For use with SMT checker.                             |
 +-----------------------------------+-------------------------------------------------------+
 | `cvc4`_ (Optional)                | For use with SMT checker.                             |
 +-----------------------------------+-------------------------------------------------------+
@@ -340,7 +342,7 @@ The following are dependencies for all builds of Solidity:
 .. note::
     Solidity versions prior to 0.5.10 can fail to correctly link against Boost versions 1.70+.
     A possible workaround is to temporarily rename ``<Boost install path>/lib/cmake/Boost-1.70.0``
-    prior to running the cmake command to configure solidity.
+    prior to running the cmake command to configure Solidity.
 
     Starting from 0.5.10 linking against Boost 1.70+ should work without manual intervention.
 
@@ -354,6 +356,17 @@ The following are dependencies for all builds of Solidity:
     If you do this, however, please remember to pass the ``--no-smt`` option to ``scripts/tests.sh``
     to skip the SMT tests.
 
+.. note::
+    By default the build is performed in *pedantic mode*, which enables extra warnings and tells the
+    compiler to treat all warnings as errors.
+    This forces developers to fix warnings as they arise, so they do not accumulate "to be fixed later".
+    If you are only interested in creating a release build and do not intend to modify the source code
+    to deal with such warnings, you can pass ``-DPEDANTIC=OFF`` option to CMake to disable this mode.
+    Doing this is not recommended for general use but may be necessary when using a toolchain we are
+    not testing with or trying to build an older version with newer tools.
+    If you encounter such warnings, please consider
+    `reporting them <https://github.com/ethereum/solidity/issues/new>`_.
+
 Minimum Compiler Versions
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -367,7 +380,7 @@ Prerequisites - macOS
 ---------------------
 
 For macOS builds, ensure that you have the latest version of
-`Xcode installed <https://developer.apple.com/xcode/download/>`_.
+`Xcode installed <https://developer.apple.com/xcode/resources/>`_.
 This contains the `Clang C++ compiler <https://en.wikipedia.org/wiki/Clang>`_, the
 `Xcode IDE <https://en.wikipedia.org/wiki/Xcode>`_ and other Apple development
 tools that are required for building C++ applications on OS X.
@@ -417,7 +430,7 @@ in Visual Studio 2019 Build Tools or Visual Studio 2019:
 * C++/CLI support
 
 .. _Visual Studio 2019: https://www.visualstudio.com/vs/
-.. _Visual Studio 2019 Build Tools: https://www.visualstudio.com/downloads/#build-tools-for-visual-studio-2019
+.. _Visual Studio 2019 Build Tools: https://visualstudio.microsoft.com/vs/older-downloads/#visual-studio-2019-and-other-products
 
 We have a helper script which you can use to install all required external dependencies:
 
@@ -437,7 +450,7 @@ To clone the source code, execute the following command:
     git clone --recursive https://github.com/ethereum/solidity.git
     cd solidity
 
-If you want to help developing Solidity,
+If you want to help develop Solidity,
 you should fork Solidity and add your personal fork as a second remote:
 
 .. code-block:: bash
@@ -445,7 +458,7 @@ you should fork Solidity and add your personal fork as a second remote:
     git remote add personal git@github.com:[username]/solidity.git
 
 .. note::
-    This method will result in a prerelease build leading to e.g. a flag
+    This method will result in a pre-release build leading to e.g. a flag
     being set in each bytecode produced by such a compiler.
     If you want to re-build a released Solidity compiler, then
     please use the source tarball on the github release page:
@@ -515,7 +528,7 @@ If you are interested what CMake options are available run ``cmake .. -LH``.
 SMT Solvers
 -----------
 Solidity can be built against SMT solvers and will do so by default if
-they are found in the system. Each solver can be disabled by a `cmake` option.
+they are found in the system. Each solver can be disabled by a ``cmake`` option.
 
 *Note: In some cases, this can also be a potential workaround for build failures.*
 
@@ -568,4 +581,4 @@ Example:
 4. A breaking change is introduced --> version is bumped to 0.5.0.
 5. The 0.5.0 release is made.
 
-This behaviour works well with the  :ref:`version pragma <version_pragma>`.
+This behavior works well with the  :ref:`version pragma <version_pragma>`.

docs/internals/layout_in_storage.rst

@@ -153,7 +153,7 @@ the :ref:`standard JSON interface <compiler-api>`.  The output is a JSON object
 element has the following form:
 
 
-.. code::
+.. code-block:: json
 
 
     {
@@ -181,7 +181,7 @@ The given ``type``, in this case ``t_uint256`` represents an element in
 ``types``, which has the form:
 
 
-.. code::
+.. code-block:: json
 
     {
         "encoding": "inplace",
@@ -208,7 +208,7 @@ of types), arrays have its ``base`` type, and structs list their ``members`` in
 the same format as the top-level ``storage`` (see :ref:`above
 <storage-layout-top-level>`).
 
-.. note ::
+.. note::
   The JSON output format of a contract's storage layout is still considered experimental
   and is subject to change in non-breaking releases of Solidity.
 
@@ -232,13 +232,13 @@ value and reference types, types that are encoded packed, and nested types.
         uint y;
         S s;
         address addr;
-        mapping (uint => mapping (address => bool)) map;
+        mapping(uint => mapping(address => bool)) map;
         uint[] array;
         string s1;
         bytes b1;
     }
 
-.. code:: json
+.. code-block:: json
 
     {
       "storage": [

docs/internals/optimizer.rst

@@ -26,6 +26,10 @@ One can use ``solc --ir-optimized --optimize`` to produce an
 optimized Yul IR for a Solidity source. Similarly, one can use ``solc --strict-assembly --optimize``
 for a stand-alone Yul mode.
 
+.. note::
+    The `peephole optimizer <https://en.wikipedia.org/wiki/Peephole_optimization>`_ is always
+    enabled by default and can only be turned off via the :ref:`Standard JSON <compiler-api>`.
+
 You can find more details on both optimizer modules and their optimization steps below.
 
 Benefits of Optimizing Solidity Code
@@ -277,60 +281,81 @@ The following transformation steps are the main components:
 - Redundant Assign Eliminator
 - Full Inliner
 
+.. _optimizer-steps:
+
 Optimizer Steps
 ---------------
 
 This is a list of all steps the Yul-based optimizer sorted alphabetically. You can find more information
 on the individual steps and their sequence below.
 
-- :ref:`block-flattener`.
-- :ref:`circular-reference-pruner`.
-- :ref:`common-subexpression-eliminator`.
-- :ref:`conditional-simplifier`.
-- :ref:`conditional-unsimplifier`.
-- :ref:`control-flow-simplifier`.
-- :ref:`dead-code-eliminator`.
-- :ref:`equal-store-eliminator`.
-- :ref:`equivalent-function-combiner`.
-- :ref:`expression-joiner`.
-- :ref:`expression-simplifier`.
-- :ref:`expression-splitter`.
-- :ref:`for-loop-condition-into-body`.
-- :ref:`for-loop-condition-out-of-body`.
-- :ref:`for-loop-init-rewriter`.
-- :ref:`expression-inliner`.
-- :ref:`full-inliner`.
-- :ref:`function-grouper`.
-- :ref:`function-hoister`.
-- :ref:`function-specializer`.
-- :ref:`literal-rematerialiser`.
-- :ref:`load-resolver`.
-- :ref:`loop-invariant-code-motion`.
-- :ref:`redundant-assign-eliminator`.
-- :ref:`reasoning-based-simplifier`.
-- :ref:`rematerialiser`.
-- :ref:`SSA-reverser`.
-- :ref:`SSA-transform`.
-- :ref:`structural-simplifier`.
-- :ref:`unused-function-parameter-pruner`.
-- :ref:`unused-pruner`.
-- :ref:`var-decl-initializer`.
+============ ===============================
+Abbreviation Full name
+============ ===============================
+``f``        :ref:`block-flattener`
+``l``        :ref:`circular-reference-pruner`
+``c``        :ref:`common-subexpression-eliminator`
+``C``        :ref:`conditional-simplifier`
+``U``        :ref:`conditional-unsimplifier`
+``n``        :ref:`control-flow-simplifier`
+``D``        :ref:`dead-code-eliminator`
+``E``        :ref:`equal-store-eliminator`
+``v``        :ref:`equivalent-function-combiner`
+``e``        :ref:`expression-inliner`
+``j``        :ref:`expression-joiner`
+``s``        :ref:`expression-simplifier`
+``x``        :ref:`expression-splitter`
+``I``        :ref:`for-loop-condition-into-body`
+``O``        :ref:`for-loop-condition-out-of-body`
+``o``        :ref:`for-loop-init-rewriter`
+``i``        :ref:`full-inliner`
+``g``        :ref:`function-grouper`
+``h``        :ref:`function-hoister`
+``F``        :ref:`function-specializer`
+``T``        :ref:`literal-rematerialiser`
+``L``        :ref:`load-resolver`
+``M``        :ref:`loop-invariant-code-motion`
+``r``        :ref:`redundant-assign-eliminator`
+``m``        :ref:`rematerialiser`
+``V``        :ref:`SSA-reverser`
+``a``        :ref:`SSA-transform`
+``t``        :ref:`structural-simplifier`
+``p``        :ref:`unused-function-parameter-pruner`
+``S``        :ref:`unused-store-eliminator`
+``u``        :ref:`unused-pruner`
+``d``        :ref:`var-decl-initializer`
+============ ===============================
+
+Some steps depend on properties ensured by ``BlockFlattener``, ``FunctionGrouper``, ``ForLoopInitRewriter``.
+For this reason the Yul optimizer always applies them before applying any steps supplied by the user.
+
 
 Selecting Optimizations
 -----------------------
 
-By default the optimizer applies its predefined sequence of optimization steps to
-the generated assembly. You can override this sequence and supply your own using
-the ``--yul-optimizations`` option:
+By default the optimizer applies its predefined sequence of optimization steps to the generated assembly.
+You can override this sequence and supply your own using the ``--yul-optimizations`` option:
 
 .. code-block:: bash
 
-    solc --optimize --ir-optimized --yul-optimizations 'dhfoD[xarrscLMcCTU]uljmul'
+    solc --optimize --ir-optimized --yul-optimizations 'dhfoD[xarrscLMcCTU]uljmul:fDnTOcmu'
+
+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.
 
 The sequence inside ``[...]`` will be applied multiple times in a loop until the Yul code
 remains unchanged or until the maximum number of rounds (currently 12) has been reached.
+Brackets (``[]``) may be used multiple times in a sequence, but can not be nested.
 
-Available abbreviations are listed in the :ref:`Yul optimizer docs <optimization-step-sequence>`.
+An important thing to note, is that there are some hardcoded steps that are always run before and after the
+user-supplied sequence, or the default sequence if one was not supplied by the user.
+
+The cleanup sequence delimiter ``:`` is optional, and is used to supply a custom cleanup sequence
+in order to replace the default one. If omitted, the optimizer will simply apply the default cleanup
+sequence. In addition, the delimiter may be placed at the beginning of the user-supplied sequence,
+which will result in the optimization sequence being empty, whereas conversely, if placed at the end of
+the sequence, will be treated as an empty cleanup sequence.
 
 Preprocessing
 -------------
@@ -545,7 +570,7 @@ It is not applied to loop iteration-condition, because the loop control flow doe
 this "outlining" of the inner expressions in all cases. We can sidestep this limitation by applying
 :ref:`for-loop-condition-into-body` to move the iteration condition into loop body.
 
-The final program should be in a form such that (with the exception of loop conditions)
+The final program should be in an *expression-split form*, where (with the exception of loop conditions)
 function calls cannot appear nested inside expressions
 and all function call arguments have to be variables.
 
@@ -683,7 +708,7 @@ Conflicting values are resolved in the following way:
 
 - "unused", "undecided" -> "undecided"
 - "unused", "used" -> "used"
-- "undecided, "used" -> "used"
+- "undecided", "used" -> "used"
 
 For for-loops, the condition, body and post-part are visited twice, taking
 the joining control-flow at the condition into account.
@@ -796,10 +821,10 @@ if the common subexpression eliminator was run right before it.
 
 .. _expression-simplifier:
 
-Expression Simplifier
-^^^^^^^^^^^^^^^^^^^^^
+ExpressionSimplifier
+^^^^^^^^^^^^^^^^^^^^
 
-The Expression Simplifier uses the Dataflow Analyzer and makes use
+The ExpressionSimplifier uses the Dataflow Analyzer and makes use
 of a list of equivalence transforms on expressions like ``X + 0 -> X``
 to simplify the code.
 
@@ -833,22 +858,6 @@ Works best if the code is in SSA form.
 
 Prerequisite: Disambiguator, ForLoopInitRewriter.
 
-.. _reasoning-based-simplifier:
-
-ReasoningBasedSimplifier
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-This optimizer uses SMT solvers to check whether ``if`` conditions are constant.
-
-- If ``constraints AND condition`` is UNSAT, the condition is never true and the whole body can be removed.
-- If ``constraints AND NOT condition`` is UNSAT, the condition is always true and can be replaced by ``1``.
-
-The simplifications above can only be applied if the condition is movable.
-
-It is only effective on the EVM dialect, but safe to use on other dialects.
-
-Prerequisite: Disambiguator, SSATransform.
-
 Statement-Scale Simplifications
 -------------------------------
 
@@ -929,7 +938,7 @@ DeadCodeEliminator
 This optimization stage removes unreachable code.
 
 Unreachable code is any code within a block which is preceded by a
-leave, return, invalid, break, continue, selfdestruct or revert.
+leave, return, invalid, break, continue, selfdestruct, revert or by a call to a user-defined function that recurses infinitely.
 
 Function definitions are retained as they might be called by earlier
 code and thus are considered reachable.
@@ -1092,6 +1101,52 @@ The step LiteralRematerialiser is not required for correctness. It helps deal wi
 ``function f(x) -> y { revert(y, y} }`` where the literal ``y`` will be replaced by its value ``0``,
 allowing us to rewrite the function.
 
+.. index:: ! unused store eliminator
+.. _unused-store-eliminator:
+
+UnusedStoreEliminator
+^^^^^^^^^^^^^^^^^^^^^
+
+Optimizer component that removes redundant ``sstore`` and memory store statements.
+In case of an ``sstore``, if all outgoing code paths revert (due to an explicit ``revert()``, ``invalid()``, or infinite recursion) or
+lead to another ``sstore`` for which the optimizer can tell that it will overwrite the first store, the statement will be removed.
+However, if there is a read operation between the initial ``sstore`` and the revert, or the overwriting ``sstore``, the statement
+will not be removed.
+Such read operations include: external calls, user-defined functions with any storage access, and ``sload`` of a slot that cannot be
+proven to differ from the slot written by the initial ``sstore``.
+
+For example, the following code
+
+.. code-block:: yul
+
+    {
+        let c := calldataload(0)
+        sstore(c, 1)
+        if c {
+            sstore(c, 2)
+        }
+        sstore(c, 3)
+    }
+
+will be transformed into the code below after the Unused Store Eliminator step is run
+
+.. code-block:: yul
+
+    {
+        let c := calldataload(0)
+        if c { }
+        sstore(c, 3)
+    }
+
+For memory store operations, things are generally simpler, at least in the outermost yul block as all such
+statements will be removed if they are never read from in any code path.
+At function analysis level, however, the approach is similar to ``sstore``, as we do not know whether the memory location will
+be read once we leave the function's scope, so the statement will be removed only if all code paths lead to a memory overwrite.
+
+Best run in SSA form.
+
+Prerequisites: Disambiguator, ForLoopInitRewriter.
+
 .. _equivalent-function-combiner:
 
 EquivalentFunctionCombiner
@@ -1137,7 +1192,7 @@ This component can only be used on sources with unique names.
 FullInliner
 ^^^^^^^^^^^
 
-The Full Inliner replaces certain calls of certain functions
+The FullInliner replaces certain calls of certain functions
 by the function's body. This is not very helpful in most cases, because
 it just increases the code size but does not have a benefit. Furthermore,
 code is usually very expensive and we would often rather have shorter
@@ -1161,6 +1216,11 @@ we can run the optimizer on this specialized function. If it
 results in heavy gains, the specialized function is kept,
 otherwise the original function is used instead.
 
+FunctionHoister and ExpressionSplitter are recommended as prerequisites since they make the step
+more efficient, but are not required for correctness.
+In particular, function calls with other function calls as arguments are not inlined, but running
+ExpressionSplitter beforehand ensures that there are no such calls in the input.
+
 Cleanup
 -------
 
@@ -1203,8 +1263,8 @@ This is a tiny step that helps in reversing the effects of the SSA transform
 if it is combined with the Common Subexpression Eliminator and the
 Unused Pruner.
 
-The SSA form we generate is detrimental to code generation on the EVM and
-WebAssembly alike because it generates many local variables. It would
+The SSA form we generate is detrimental to code generation
+because it produces many local variables. It would
 be better to just re-use existing variables with assignments instead of
 fresh variable declarations.
 
@@ -1322,15 +1382,3 @@ into
     }
 
 The LiteralRematerialiser should be run before this step.
-
-
-WebAssembly specific
---------------------
-
-MainFunction
-^^^^^^^^^^^^
-
-Changes the topmost block to be a function with a specific name ("main") which has no
-inputs nor outputs.
-
-Depends on the Function Grouper.

docs/internals/source_mappings.rst

@@ -26,7 +26,7 @@ that are not part of the original input but are referenced from the source
 mappings. These source files together with their identifiers can be
 obtained via ``output['contracts'][sourceName][contractName]['evm']['bytecode']['generatedSources']``.
 
-.. note ::
+.. note::
     In the case of instructions that are not associated with any particular source file,
     the source mapping assigns an integer identifier of ``-1``. This may happen for
     bytecode sections stemming from compiler-generated inline assembly statements.

docs/internals/variable_cleanup.rst

@@ -4,9 +4,10 @@
 Cleaning Up Variables
 *********************
 
-When a value is shorter than 256 bit, in some cases the remaining bits
-must be cleaned.
-The Solidity compiler is designed to clean such remaining bits before any operations
+Ultimately, all values in the EVM are stored in 256 bit words.
+Thus, in some cases, when the type of a value has less than 256 bits,
+it is necessary to clean the remaining bits.
+The Solidity compiler is designed to do such cleaning before any operations
 that might be adversely affected by the potential garbage in the remaining bits.
 For example, before writing a value to  memory, the remaining bits need
 to be cleared because the memory contents can be used for computing
@@ -28,25 +29,83 @@ the boolean values before they are used as the condition for
 In addition to the design principle above, the Solidity compiler
 cleans input data when it is loaded onto the stack.
 
-Different types have different rules for cleaning up invalid values:
+The following table describes the cleaning rules applied to different types,
+where ``higher bits`` refers to the remaining bits in case the type has less than 256 bits.
 
-+---------------+---------------+-------------------+
-|Type           |Valid Values   |Invalid Values Mean|
-+===============+===============+===================+
-|enum of n      |0 until n - 1  |exception          |
-|members        |               |                   |
-+---------------+---------------+-------------------+
-|bool           |0 or 1         |1                  |
-+---------------+---------------+-------------------+
-|signed integers|sign-extended  |currently silently |
-|               |word           |wraps; in the      |
-|               |               |future exceptions  |
-|               |               |will be thrown     |
-|               |               |                   |
-|               |               |                   |
-+---------------+---------------+-------------------+
-|unsigned       |higher bits    |currently silently |
-|integers       |zeroed         |wraps; in the      |
-|               |               |future exceptions  |
-|               |               |will be thrown     |
-+---------------+---------------+-------------------+
++---------------+---------------+-------------------------+
+|Type           |Valid Values   |Cleanup of Invalid Values|
++===============+===============+=========================+
+|enum of n      |0 until n - 1  |throws exception         |
+|members        |               |                         |
++---------------+---------------+-------------------------+
+|bool           |0 or 1         |results in 1             |
++---------------+---------------+-------------------------+
+|signed integers|higher bits    |currently silently       |
+|               |set to the     |signextends to a valid   |
+|               |sign bit       |value, i.e. all higher   |
+|               |               |bits are set to the sign |
+|               |               |bit; may throw an        |
+|               |               |exception in the future  |
++---------------+---------------+-------------------------+
+|unsigned       |higher bits    |currently silently masks |
+|integers       |zeroed         |to a valid value, i.e.   |
+|               |               |all higher bits are set  |
+|               |               |to zero; may throw an    |
+|               |               |exception in the future  |
++---------------+---------------+-------------------------+
+
+Note that valid and invalid values are dependent on their type size.
+Consider ``uint8``, the unsigned 8-bit type, which has the following valid values:
+
+.. code-block:: none
+
+    0000...0000 0000 0000
+    0000...0000 0000 0001
+    0000...0000 0000 0010
+    ....
+    0000...0000 1111 1111
+
+Any invalid value will have the higher bits set to zero:
+
+.. code-block:: none
+
+    0101...1101 0010 1010   invalid value
+    0000...0000 0010 1010   cleaned value
+
+For ``int8``, the signed 8-bit type, the valid values are:
+
+Negative
+
+.. code-block:: none
+
+    1111...1111 1111 1111
+    1111...1111 1111 1110
+    ....
+    1111...1111 1000 0000
+
+Positive
+
+.. code-block:: none
+
+    0000...0000 0000 0000
+    0000...0000 0000 0001
+    0000...0000 0000 0010
+    ....
+    0000...0000 1111 1111
+
+The compiler will ``signextend`` the sign bit, which is 1 for negative and 0 for
+positive values, overwriting the higher bits:
+
+Negative
+
+.. code-block:: none
+
+    0010...1010 1111 1111   invalid value
+    1111...1111 1111 1111   cleaned value
+
+Positive
+
+.. code-block:: none
+
+    1101...0101 0000 0100   invalid value
+    0000...0000 0000 0100   cleaned value

docs/introduction-to-smart-contracts.rst

@@ -91,7 +91,7 @@ registering with a username and password, all you need is an Ethereum keypair.
         // The keyword "public" makes variables
         // accessible from other contracts
         address public minter;
-        mapping (address => uint) public balances;
+        mapping(address => uint) public balances;
 
         // Events allow clients to react to specific
         // contract changes you declare
@@ -151,7 +151,7 @@ You do not need to do this, the compiler figures it out for you.
 
 .. index:: mapping
 
-The next line, ``mapping (address => uint) public balances;`` also
+The next line, ``mapping(address => uint) public balances;`` also
 creates a public state variable, but it is a more complex datatype.
 The :ref:`mapping <mapping-types>` type maps addresses to :ref:`unsigned integers <integers>`.
 
@@ -185,8 +185,10 @@ arguments ``from``, ``to`` and ``amount``, which makes it possible to track
 transactions.
 
 To listen for this event, you could use the following
-JavaScript code, which uses `web3.js <https://github.com/ethereum/web3.js/>`_ to create the ``Coin`` contract object,
-and any user interface calls the automatically generated ``balances`` function from above::
+JavaScript code, which uses `web3.js <https://github.com/web3/web3.js/>`_ to create the ``Coin`` contract object,
+and any user interface calls the automatically generated ``balances`` function from above:
+
+.. code-block:: javascript
 
     Coin.Sent().watch({}, '', function(error, result) {
         if (!error) {
@@ -280,7 +282,7 @@ the source account is also not modified.
 Furthermore, a transaction is always cryptographically signed by the sender (creator).
 This makes it straightforward to guard access to specific modifications of the
 database. In the example of the electronic currency, a simple check ensures that
-only the person holding the keys to the account can transfer money from it.
+only the person holding the keys to the account can transfer some compensation, e.g. Ether, from it.
 
 .. index:: ! block
 
@@ -298,9 +300,9 @@ and then they will be executed and distributed among all participating nodes.
 If two transactions contradict each other, the one that ends up being second will
 be rejected and not become part of the block.
 
-These blocks form a linear sequence in time and that is where the word "blockchain"
-derives from. Blocks are added to the chain in rather regular intervals - for
-Ethereum this is roughly every 17 seconds.
+These blocks form a linear sequence in time, and that is where the word "blockchain" derives from.
+Blocks are added to the chain at regular intervals, although these intervals may be subject to change in the future.
+For the most up-to-date information, it is recommended to monitor the network, for example, on `Etherscan <https://etherscan.io/chart/blocktime>`_.
 
 As part of the "order selection mechanism" (which is called "mining") it may happen that
 blocks are reverted from time to time, but only at the "tip" of the chain. The more
@@ -504,10 +506,10 @@ operations, loops should be preferred over recursive calls. Furthermore,
 only 63/64th of the gas can be forwarded in a message call, which causes a
 depth limit of a little less than 1000 in practice.
 
-.. index:: delegatecall, callcode, library
+.. index:: delegatecall, library
 
-Delegatecall / Callcode and Libraries
-=====================================
+Delegatecall and Libraries
+==========================
 
 There exists a special variant of a message call, named **delegatecall**
 which is identical to a message call apart from the fact that
@@ -560,6 +562,11 @@ is removed from the state. Removing the contract in theory sounds like a good
 idea, but it is potentially dangerous, as if someone sends Ether to removed
 contracts, the Ether is forever lost.
 
+.. warning::
+    From version 0.8.18 and up, the use of ``selfdestruct`` in both Solidity and Yul will trigger a
+    deprecation warning, since the ``SELFDESTRUCT`` opcode will eventually undergo breaking changes in behavior
+    as stated in `EIP-6049 <https://eips.ethereum.org/EIPS/eip-6049>`_.
+
 .. warning::
     Even if a contract is removed by ``selfdestruct``, it is still part of the
     history of the blockchain and probably retained by most Ethereum nodes.
@@ -584,7 +591,7 @@ Precompiled Contracts
 There is a small set of contract addresses that are special:
 The address range between ``1`` and (including) ``8`` contains
 "precompiled contracts" that can be called as any other contract
-but their behaviour (and their gas consumption) is not defined
+but their behavior (and their gas consumption) is not defined
 by EVM code stored at that address (they do not contain code)
 but instead is implemented in the EVM execution environment itself.
 

docs/ir-breaking-changes.rst

@@ -15,13 +15,13 @@ The IR-based code generator was introduced with an aim to not only allow
 code generation to be more transparent and auditable but also
 to enable more powerful optimization passes that span across functions.
 
-You can enable it on the command line using ``--via-ir``
+You can enable it on the command-line using ``--via-ir``
 or with the option ``{"viaIR": true}`` in standard-json and we
 encourage everyone to try it out!
 
 For several reasons, there are tiny semantic differences between the old
 and the IR-based code generator, mostly in areas where we would not
-expect people to rely on this behaviour anyway.
+expect people to rely on this behavior anyway.
 This section highlights the main differences between the old and the IR-based codegen.
 
 Semantic Only Changes
@@ -30,6 +30,8 @@ Semantic Only Changes
 This section lists the changes that are semantic-only, thus potentially
 hiding new and different behavior in existing code.
 
+.. _state-variable-initialization-order:
+
 - The order of state variable initialization has changed in case of inheritance.
 
   The order used to be:
@@ -122,8 +124,8 @@ hiding new and different behavior in existing code.
           modifier mod() { _; _; }
       }
 
-  If you execute ``f(0)`` in the old code generator, it will return ``2``, while
-  it will return ``1`` when using the new code generator.
+  If you execute ``f(0)`` in the old code generator, it will return ``1``, while
+  it will return ``0`` when using the new code generator.
 
   .. code-block:: solidity
 
@@ -174,8 +176,8 @@ hiding new and different behavior in existing code.
 
   The function ``preincr_u8(1)`` returns the following values:
 
-  - Old code generator: 3 (``1 + 2``) but the return value is unspecified in general
-  - New code generator: 4 (``2 + 2``) but the return value is not guaranteed
+  - Old code generator: ``3`` (``1 + 2``) but the return value is unspecified in general
+  - New code generator: ``4`` (``2 + 2``) but the return value is not guaranteed
 
   .. index:: ! evaluation order; function arguments
 
@@ -247,7 +249,7 @@ hiding new and different behavior in existing code.
           }
       }
 
-  The function `f()` behaves as follows:
+  The function ``f()`` behaves as follows:
 
   - Old code generator: runs out of gas while zeroing the array contents after the large memory allocation
   - New code generator: reverts due to free memory pointer overflow (does not run out of gas)

docs/layout-of-source-files.rst

@@ -56,7 +56,7 @@ you have to add the pragma to all your files if you want to enable it
 in your whole project. If you :ref:`import<import>` another file, the pragma
 from that file does *not* automatically apply to the importing file.
 
-.. index:: ! pragma, version
+.. index:: ! pragma;version
 
 .. _version_pragma:
 
@@ -91,6 +91,9 @@ these follow the same syntax used by `npm <https://docs.npmjs.com/cli/v6/using-n
   required by the pragma. If it does not match, the compiler issues
   an error.
 
+.. index:: ! ABI coder, ! pragma; abicoder, pragma; ABIEncoderV2
+.. _abi_coder:
+
 ABI Coder Pragma
 ----------------
 
@@ -98,12 +101,11 @@ By using ``pragma abicoder v1`` or ``pragma abicoder v2`` you can
 select between the two implementations of the ABI encoder and decoder.
 
 The new ABI coder (v2) is able to encode and decode arbitrarily nested
-arrays and structs. It might produce less optimal code and has not
-received as much testing as the old encoder, but is considered
-non-experimental as of Solidity 0.6.0. You still have to explicitly
-activate it using ``pragma abicoder v2;``. Since it will be
-activated by default starting from Solidity 0.8.0, there is the option to select
-the old coder using ``pragma abicoder v1;``.
+arrays and structs. Apart from supporting more types, it involves more extensive
+validation and safety checks, which may result in higher gas costs, but also heightened
+security. It is considered
+non-experimental as of Solidity 0.6.0 and it is enabled by default starting
+with Solidity 0.8.0. The old ABI coder can still be selected using ``pragma abicoder v1;``.
 
 The set of types supported by the new encoder is a strict superset of
 the ones supported by the old one. Contracts that use it can interact with ones
@@ -126,8 +128,7 @@ enough to make the error go away.
   by using ``pragma experimental ABIEncoderV2``, but it was not possible
   to explicitly select coder v1 because it was the default.
 
-.. index:: ! pragma, experimental
-
+.. index:: ! pragma; experimental
 .. _experimental_pragma:
 
 Experimental Pragma
@@ -137,6 +138,7 @@ The second pragma is the experimental pragma. It can be used to enable
 features of the compiler or language that are not yet enabled by default.
 The following experimental pragmas are currently supported:
 
+.. index:: ! pragma; ABIEncoderV2
 
 ABIEncoderV2
 ~~~~~~~~~~~~
@@ -145,6 +147,7 @@ Because the ABI coder v2 is not considered experimental anymore,
 it can be selected via ``pragma abicoder v2`` (please see above)
 since Solidity 0.7.4.
 
+.. index:: ! pragma; SMTChecker
 .. _smt_checker:
 
 SMTChecker
@@ -179,7 +182,7 @@ Syntax and Semantics
 Solidity supports import statements to help modularise your code that
 are similar to those available in JavaScript
 (from ES6 on). However, Solidity does not support the concept of
-a `default export <https://developer.mozilla.org/en-US/docs/web/javascript/reference/statements/export#Description>`_.
+a `default export <https://developer.mozilla.org/en-US/docs/web/javascript/reference/statements/export#description>`_.
 
 At a global level, you can use import statements of the following form:
 

docs/logo.svg

@@ -1,27 +1,8 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!-- Generator: Adobe Illustrator 16.0.3, SVG Export Plug-In . SVG Version: 6.00 Build 0)  -->
-<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
-<svg version="1.1" id="Layer_1" xmlns:sketch="http://www.bohemiancoding.com/sketch/ns"
-	 xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px" width="1300px" height="1300px"
-	 viewBox="0 0 1300 1300" enable-background="new 0 0 1300 1300" xml:space="preserve">
-<title>Vector 1</title>
-<desc>Created with Sketch.</desc>
-<g id="Page-1" sketch:type="MSPage">
-	<g id="solidity" transform="translate(402.000000, 118.000000)" sketch:type="MSLayerGroup">
-		<g id="Group" sketch:type="MSShapeGroup">
-			<path id="Shape" opacity="0.45" enable-background="new    " d="M371.772,135.308L241.068,367.61H-20.158l130.614-232.302
-				H371.772"/>
-			<path id="Shape_1_" opacity="0.6" enable-background="new    " d="M241.068,367.61h261.318L371.772,135.308H110.456
-				L241.068,367.61z"/>
-			<path id="Shape_2_" opacity="0.8" enable-background="new    " d="M110.456,599.822L241.068,367.61L110.456,135.308
-				L-20.158,367.61L110.456,599.822z"/>
-			<path id="Shape_3_" opacity="0.45" enable-background="new    " d="M111.721,948.275l130.704-232.303h261.318L373.038,948.275
-				H111.721"/>
-			<path id="Shape_4_" opacity="0.6" enable-background="new    " d="M242.424,715.973H-18.893l130.613,232.303h261.317
-				L242.424,715.973z"/>
-			<path id="Shape_5_" opacity="0.8" enable-background="new    " d="M373.038,483.761L242.424,715.973l130.614,232.303
-				l130.704-232.303L373.038,483.761z"/>
-		</g>
-	</g>
-</g>
+<svg width="100" height="160" viewBox="0 0 100 160" fill="#2B247C" xmlns="http://www.w3.org/2000/svg">
+<path opacity="0.8" d="M50 44.3013L25 1L0 44.3013L25 87.6025L50 44.3013Z" />
+<path opacity="0.45" d="M50 44.3091L75 1.00781L25 1.00781L0 44.3091H50Z" />
+<path opacity="0.6" d="M75 1.00781L25 1.00781L50 44.3091H100L75 1.00781Z" />
+<path opacity="0.8" d="M50 115.699L75 159L100 115.699L75 72.3975L50 115.699Z" />
+<path opacity="0.45" d="M50 115.691L25 158.993H75L100 115.691L50 115.691Z" />
+<path opacity="0.6" d="M25 158.993H75L50 115.691L0 115.691L25 158.993Z" />
 </svg>

docs/make.bat

@@ -28,6 +28,7 @@ if "%1" == "help" (
 	echo.  devhelp    to make HTML files and a Devhelp project
 	echo.  epub       to make an epub
 	echo.  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter
+	echo.  latexpdf   to make LaTeX files and run them through pdflatex
 	echo.  text       to make text files
 	echo.  man        to make manual pages
 	echo.  texinfo    to make Texinfo files
@@ -155,16 +156,6 @@ if "%1" == "latexpdf" (
 	goto end
 )
 
-if "%1" == "latexpdfja" (
-	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
-	cd %BUILDDIR%/latex
-	make all-pdf-ja
-	cd %BUILDDIR%/..
-	echo.
-	echo.Build finished; the PDF files are in %BUILDDIR%/latex.
-	goto end
-)
-
 if "%1" == "text" (
 	%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
 	if errorlevel 1 exit /b 1

docs/metadata.rst

@@ -6,122 +6,194 @@ Contract Metadata
 
 .. index:: metadata, contract verification
 
-The Solidity compiler automatically generates a JSON file, the contract
-metadata, that contains information about the compiled contract. You can use
-this file to query the compiler version, the sources used, the ABI and NatSpec
-documentation to more safely interact with the contract and verify its source
-code.
+The Solidity compiler automatically generates a JSON file.
+The file contains two kinds of information about the compiled contract:
+
+- How to interact with the contract: ABI, and NatSpec documentation.
+- How to reproduce the compilation and verify a deployed contract:
+  compiler version, compiler settings, and source files used.
 
 The compiler appends by default the IPFS hash of the metadata file to the end
-of the bytecode (for details, see below) of each contract, so that you can
-retrieve the file in an authenticated way without having to resort to a
-centralized data provider. The other available options are the Swarm hash and
-not appending the metadata hash to the bytecode.  These can be configured via
-the :ref:`Standard JSON Interface<compiler-api>`.
+of the runtime bytecode (not necessarily the creation bytecode) of each contract,
+so that, if published, you can retrieve the file in an authenticated way without
+having to resort to a centralized data provider. The other available options are
+the Swarm hash and not appending the metadata hash to the bytecode. These can be
+configured via the :ref:`Standard JSON Interface<compiler-api>`.
 
 You have to publish the metadata file to IPFS, Swarm, or another service so
 that others can access it. You create the file by using the ``solc --metadata``
-command that generates a file called ``ContractName_meta.json``. It contains
-IPFS and Swarm references to the source code, so you have to upload all source
-files and the metadata file.
+command together with the ``--output-dir`` parameter. Without the parameter,
+the metadata will be written to standard output.
+The metadata contains IPFS and Swarm references to the source code, so you have to
+upload all source files in addition to the metadata file. For IPFS, the hash contained
+in the CID returned by ``ipfs add`` (not the direct sha2-256 hash of the file)
+shall match with the one contained in the bytecode.
 
 The metadata file has the following format. The example below is presented in a
 human-readable way. Properly formatted metadata should use quotes correctly,
-reduce whitespace to a minimum and sort the keys of all objects to arrive at a
-unique formatting. Comments are not permitted and used here only for
+reduce whitespace to a minimum, and sort the keys of all objects in alphabetical order
+to arrive at a canonical formatting. Comments are not permitted and are used here only for
 explanatory purposes.
 
 .. code-block:: javascript
 
     {
-      // Required: The version of the metadata format
-      "version": "1",
-      // Required: Source code language, basically selects a "sub-version"
-      // of the specification
-      "language": "Solidity",
       // Required: Details about the compiler, contents are specific
       // to the language.
       "compiler": {
-        // Required for Solidity: Version of the compiler
-        "version": "0.4.6+commit.2dabbdf0.Emscripten.clang",
         // Optional: Hash of the compiler binary which produced this output
-        "keccak256": "0x123..."
+        "keccak256": "0x123...",
+        // Required for Solidity: Version of the compiler
+        "version": "0.8.2+commit.661d1103"
       },
-      // Required: Compilation source files/source units, keys are file names
-      "sources":
-      {
-        "myFile.sol": {
-          // Required: keccak256 hash of the source file
-          "keccak256": "0x123...",
-          // Required (unless "content" is used, see below): Sorted URL(s)
-          // to the source file, protocol is more or less arbitrary, but a
-          // Swarm URL is recommended
-          "urls": [ "bzzr://56ab..." ],
-          // Optional: SPDX license identifier as given in the source file
-          "license": "MIT"
+      // Required: Source code language, basically selects a "sub-version"
+      // of the specification
+      "language": "Solidity",
+      // Required: Generated information about the contract.
+      "output": {
+        // Required: ABI definition of the contract. See "Contract ABI Specification"
+        "abi": [/* ... */],
+        // Required: NatSpec developer documentation of the contract. See https://docs.soliditylang.org/en/latest/natspec-format.html for details.
+        "devdoc": {
+          // Contents of the @author NatSpec field of the contract
+          "author": "John Doe",
+          // Contents of the @dev NatSpec field of the contract
+          "details": "Interface of the ERC20 standard as defined in the EIP. See https://eips.ethereum.org/EIPS/eip-20 for details",
+          "errors": {
+            "MintToZeroAddress()" : {
+              "details": "Cannot mint to zero address"
+            }
+          },
+          "events": {
+            "Transfer(address,address,uint256)": {
+              "details": "Emitted when `value` tokens are moved from one account (`from`) toanother (`to`).",
+              "params": {
+                "from": "The sender address",
+                "to": "The receiver address",
+                "value": "The token amount"
+              }
+            }
+          },
+          "kind": "dev",
+          "methods": {
+            "transfer(address,uint256)": {
+              // Contents of the @dev NatSpec field of the method
+              "details": "Returns a boolean value indicating whether the operation succeeded. Must be called by the token holder address",
+              // Contents of the @param NatSpec fields of the method
+              "params": {
+                "_value": "The amount tokens to be transferred",
+                "_to": "The receiver address"
+              },
+              // Contents of the @return NatSpec field.
+              "returns": {
+                // Return var name (here "success") if exists. "_0" as key if return var is unnamed
+                "success": "a boolean value indicating whether the operation succeeded"
+              }
+            }
+          },
+          "stateVariables": {
+            "owner": {
+              // Contents of the @dev NatSpec field of the state variable
+              "details": "Must be set during contract creation. Can then only be changed by the owner"
+            }
+          },
+          // Contents of the @title NatSpec field of the contract
+          "title": "MyERC20: an example ERC20",
+          "version": 1 // NatSpec version
         },
-        "destructible": {
-          // Required: keccak256 hash of the source file
-          "keccak256": "0x234...",
-          // Required (unless "url" is used): literal contents of the source file
-          "content": "contract destructible is owned { function destroy() { if (msg.sender == owner) selfdestruct(owner); } }"
+        // Required: NatSpec user documentation of the contract. See "NatSpec Format"
+        "userdoc": {
+          "errors": {
+            "ApprovalCallerNotOwnerNorApproved()": [
+              {
+                "notice": "The caller must own the token or be an approved operator."
+              }
+            ]
+          },
+          "events": {
+            "Transfer(address,address,uint256)": {
+              "notice": "`_value` tokens have been moved from `from` to `to`"
+            }
+          },
+          "kind": "user",
+          "methods": {
+            "transfer(address,uint256)": {
+              "notice": "Transfers `_value` tokens to address `_to`"
+            }
+          },
+          "version": 1 // NatSpec version
         }
       },
-      // Required: Compiler settings
-      "settings":
-      {
-        // Required for Solidity: Sorted list of remappings
-        "remappings": [ ":g=/dir" ],
+      // Required: Compiler settings. Reflects the settings in the JSON input during compilation.
+      // Check the documentation of standard JSON input's "settings" field
+      "settings": {
+        // Required for Solidity: File path and the name of the contract or library this
+        // metadata is created for.
+        "compilationTarget": {
+          "myDirectory/myFile.sol": "MyContract"
+        },
+        // Required for Solidity.
+        "evmVersion": "london",
+        // Required for Solidity: Addresses for libraries used.
+        "libraries": {
+          "MyLib": "0x123123..."
+        },
+        "metadata": {
+          // Reflects the setting used in the input json, defaults to "true"
+          "appendCBOR": true,
+          // Reflects the setting used in the input json, defaults to "ipfs"
+          "bytecodeHash": "ipfs",
+          // Reflects the setting used in the input json, defaults to "false"
+          "useLiteralContent": true
+        },
         // Optional: Optimizer settings. The fields "enabled" and "runs" are deprecated
-        // and are only given for backwards-compatibility.
+        // and are only given for backward-compatibility.
         "optimizer": {
-          "enabled": true,
-          "runs": 500,
           "details": {
-            // peephole defaults to "true"
-            "peephole": true,
-            // inliner defaults to "true"
-            "inliner": true,
+            "constantOptimizer": false,
+            "cse": false,
+            "deduplicate": false,
+            // inliner defaults to "false"
+            "inliner": false,
             // jumpdestRemover defaults to "true"
             "jumpdestRemover": true,
             "orderLiterals": false,
-            "deduplicate": false,
-            "cse": false,
-            "constantOptimizer": false,
+            // peephole defaults to "true"
+            "peephole": true,
             "yul": true,
             // Optional: Only present if "yul" is "true"
             "yulDetails": {
-              "stackAllocation": false,
-              "optimizerSteps": "dhfoDgvulfnTUtnIf..."
+              "optimizerSteps": "dhfoDgvulfnTUtnIf...",
+              "stackAllocation": false
             }
-          }
+          },
+          "enabled": true,
+          "runs": 500
         },
-        "metadata": {
-          // Reflects the setting used in the input json, defaults to false
-          "useLiteralContent": true,
-          // Reflects the setting used in the input json, defaults to "ipfs"
-          "bytecodeHash": "ipfs"
+        // Required for Solidity: Sorted list of import remappings.
+        "remappings": [ ":g=/dir" ]
+      },
+      // Required: Compilation source files/source units, keys are file paths
+      "sources": {
+        "destructible": {
+          // Required (unless "url" is used): literal contents of the source file
+          "content": "contract destructible is owned { function destroy() { if (msg.sender == owner) selfdestruct(owner); } }",
+          // Required: keccak256 hash of the source file
+          "keccak256": "0x234..."
         },
-        // Required for Solidity: File and name of the contract or library this
-        // metadata is created for.
-        "compilationTarget": {
-          "myFile.sol": "MyContract"
-        },
-        // Required for Solidity: Addresses for libraries used
-        "libraries": {
-          "MyLib": "0x123123..."
+        "myDirectory/myFile.sol": {
+          // Required: keccak256 hash of the source file
+          "keccak256": "0x123...",
+          // Optional: SPDX license identifier as given in the source file
+          "license": "MIT",
+          // Required (unless "content" is used, see above): Sorted URL(s)
+          // to the source file, protocol is more or less arbitrary, but an
+          // IPFS URL is recommended
+          "urls": [ "bzz-raw://7d7a...", "dweb:/ipfs/QmN..." ]
         }
       },
-      // Required: Generated information about the contract.
-      "output":
-      {
-        // Required: ABI definition of the contract
-        "abi": [/* ... */],
-        // Required: NatSpec user documentation of the contract
-        "userdoc": [/* ... */],
-        // Required: NatSpec developer documentation of the contract
-        "devdoc": [/* ... */]
-      }
+      // Required: The version of the metadata format
+      "version": 1
     }
 
 .. warning::
@@ -141,71 +213,80 @@ explanatory purposes.
 Encoding of the Metadata Hash in the Bytecode
 =============================================
 
-Because we might support other ways to retrieve the metadata file in the future,
-the mapping ``{"ipfs": <IPFS hash>, "solc": <compiler version>}`` is stored
-`CBOR <https://tools.ietf.org/html/rfc7049>`_-encoded. Since the mapping might
-contain more keys (see below) and the beginning of that
-encoding is not easy to find, its length is added in a two-byte big-endian
-encoding. The current version of the Solidity compiler usually adds the following
-to the end of the deployed bytecode
+The compiler currently by default appends the
+`IPFS hash (in CID v0) <https://docs.ipfs.tech/concepts/content-addressing/#version-0-v0>`_
+of the canonical metadata file and the compiler version to the end of the bytecode.
+Optionally, a Swarm hash instead of the IPFS, or an experimental flag is used.
+Below are all the possible fields:
 
-.. code-block:: text
+.. code-block:: javascript
 
-    0xa2
-    0x64 'i' 'p' 'f' 's' 0x58 0x22 <34 bytes IPFS hash>
-    0x64 's' 'o' 'l' 'c' 0x43 <3 byte version encoding>
-    0x00 0x33
+    {
+      "ipfs": "<metadata hash>",
+      // If "bytecodeHash" was "bzzr1" in compiler settings not "ipfs" but "bzzr1"
+      "bzzr1": "<metadata hash>",
+      // Previous versions were using "bzzr0" instead of "bzzr1"
+      "bzzr0": "<metadata hash>",
+      // If any experimental features that affect code generation are used
+      "experimental": true,
+      "solc": "<compiler version>"
+    }
 
-So in order to retrieve the data, the end of the deployed bytecode can be checked
-to match that pattern and use the IPFS hash to retrieve the file.
+Because we might support other ways to retrieve the
+metadata file in the future, this information is stored
+`CBOR <https://tools.ietf.org/html/rfc7049>`_-encoded. The last two bytes in the bytecode
+indicate the length of the CBOR encoded information. By looking at this length, the
+relevant part of the bytecode can be decoded with a CBOR decoder.
+
+Check the `Metadata Playground <https://playground.sourcify.dev/>`_ to see it in action.
 
 Whereas release builds of solc use a 3 byte encoding of the version as shown
-above (one byte each for major, minor and patch version number), prerelease builds
+above (one byte each for major, minor and patch version number), pre-release builds
 will instead use a complete version string including commit hash and build date.
 
+The commandline flag ``--no-cbor-metadata`` can be used to skip metadata
+from getting appended at the end of the deployed bytecode. Equivalently, the
+boolean field ``settings.metadata.appendCBOR`` in Standard JSON input can be set to false.
+
 .. note::
   The CBOR mapping can also contain other keys, so it is better to fully
-  decode the data instead of relying on it starting with ``0xa264``.
-  For example, if any experimental features that affect code generation
-  are used, the mapping will also contain ``"experimental": true``.
-
-.. note::
-  The compiler currently uses the IPFS hash of the metadata by default, but
-  it may also use the bzzr1 hash or some other hash in the future, so do
-  not rely on this sequence to start with ``0xa2 0x64 'i' 'p' 'f' 's'``.  We
-  might also add additional data to this CBOR structure, so the best option
-  is to use a proper CBOR parser.
-
+  decode the data by looking at the end of the bytecode for the CBOR length,
+  and to use a proper CBOR parser. Do not rely on it starting with ``0xa264``
+  or ``0xa2 0x64 'i' 'p' 'f' 's'``.
 
 Usage for Automatic Interface Generation and NatSpec
 ====================================================
 
 The metadata is used in the following way: A component that wants to interact
-with a contract (e.g. Mist or any wallet) retrieves the code of the contract,
-from that the IPFS/Swarm hash of a file which is then retrieved.  That file
+with a contract (e.g. a wallet) retrieves the code of the contract.
+It decodes the CBOR encoded section containing the IPFS/Swarm hash of the
+metadata file. With that hash, the metadata file is retrieved. That file
 is JSON-decoded into a structure like above.
 
 The component can then use the ABI to automatically generate a rudimentary
 user interface for the contract.
 
-Furthermore, the wallet can use the NatSpec user documentation to display a confirmation message to the user
-whenever they interact with the contract, together with requesting
-authorization for the transaction signature.
+Furthermore, the wallet can use the NatSpec user documentation to display a
+human-readable confirmation message to the user whenever they interact with
+the contract, together with requesting authorization for the transaction signature.
 
 For additional information, read :doc:`Ethereum Natural Language Specification (NatSpec) format <natspec-format>`.
 
 Usage for Source Code Verification
 ==================================
 
-In order to verify the compilation, sources can be retrieved from IPFS/Swarm
-via the link in the metadata file.
-The compiler of the correct version (which is checked to be part of the "official" compilers)
-is invoked on that input with the specified settings. The resulting
-bytecode is compared to the data of the creation transaction or ``CREATE`` opcode data.
-This automatically verifies the metadata since its hash is part of the bytecode.
-Excess data corresponds to the constructor input data, which should be decoded
-according to the interface and presented to the user.
+If pinned/published, it is possible to retrieve the metadata of the contract from IPFS/Swarm.
+The metadata file also contains the URLs or the IPFS hashes of the source files, as well as
+the compilation settings, i.e. everything needed to reproduce a compilation.
 
-In the repository `sourcify <https://github.com/ethereum/sourcify>`_
-(`npm package <https://www.npmjs.com/package/source-verify>`_) you can see
-example code that shows how to use this feature.
+With this information it is then possible to verify the source code of a contract by
+reproducing the compilation, and comparing the bytecode from the compilation with
+the bytecode of the deployed contract.
+
+This automatically verifies the metadata since its hash is part of the bytecode, as well
+as the source codes, because their hashes are part of the metadata. Any change in the files
+or settings would result in a different metadata hash. The metadata here serves
+as a fingerprint of the whole compilation.
+
+`Sourcify <https://sourcify.dev>`_ makes use of this feature for "full/perfect verification",
+as well as pinning the files publicly on IPFS to be accessed with the metadata hash.

docs/natspec-format.rst

@@ -46,7 +46,7 @@ for the purposes of NatSpec.
 
 -  For Vyper, use ``"""`` indented to the inner contents with bare
    comments. See the `Vyper
-   documentation <https://vyper.readthedocs.io/en/latest/natspec.html>`__.
+   documentation <https://docs.vyperlang.org/en/latest/natspec.html>`__.
 
 The following example shows a contract and a function using all available tags.
 
@@ -58,7 +58,7 @@ The following example shows a contract and a function using all available tags.
 
   This may change in the future.
 
-.. code-block:: Solidity
+.. code-block:: solidity
 
     // SPDX-License-Identifier: GPL-3.0
     pragma solidity >=0.8.2 < 0.9.0;
@@ -154,10 +154,6 @@ to the end-user as:
 
 if a function is being called and the input ``a`` is assigned a value of 10.
 
-Specifying these dynamic expressions is outside the scope of the Solidity
-documentation and you may read more at
-`the radspec project <https://github.com/aragon/radspec>`__.
-
 .. _header-inheritance:
 
 Inheritance Notes
@@ -183,7 +179,7 @@ other to be used by the developer.
 If the above contract is saved as ``ex1.sol`` then you can generate the
 documentation using:
 
-.. code::
+.. code-block:: shell
 
    solc --userdoc --devdoc ex1.sol
 
@@ -202,7 +198,7 @@ User Documentation
 The above documentation will produce the following user documentation
 JSON file as output:
 
-.. code::
+.. code-block:: json
 
     {
       "version" : 1,
@@ -230,7 +226,7 @@ Developer Documentation
 Apart from the user documentation file, a developer documentation JSON
 file should also be produced and should look like this:
 
-.. code::
+.. code-block:: json
 
     {
       "version" : 1,

docs/path-resolution.rst

@@ -139,7 +139,7 @@ The initial content of the VFS depends on how you invoke the compiler:
 
 #. **Standard input**
 
-   On the command line it is also possible to provide the source by sending it to compiler's
+   On the command-line it is also possible to provide the source by sending it to compiler's
    standard input:
 
    .. code-block:: bash
@@ -197,7 +197,7 @@ source unit name.
 
     A source unit name is just an identifier and even if its value happens to look like a path, it
     is not subject to the normalization rules you would typically expect in a shell.
-    Any ``/./`` or ``/../`` seguments or sequences of multiple slashes remain a part of it.
+    Any ``/./`` or ``/../`` segments or sequences of multiple slashes remain a part of it.
     When the source is provided via Standard JSON interface it is entirely possible to associate
     different content with source unit names that would refer to the same file on disk.
 
@@ -248,19 +248,15 @@ and is bounded by two path separators.
 A separator is a forward slash or the beginning/end of the string.
 For example in ``./abc/..//`` there are three path segments: ``.``, ``abc`` and ``..``.
 
-The compiler computes a source unit name from the import path in the following way:
+The compiler resolves the import into a source unit name based on the import path, in the following way:
 
-1. First a prefix is computed
+#. We start with the source unit name of the importing source unit.
+#. The last path segment with preceding slashes is removed from the resolved name.
+#. Then, for every segment in the import path, starting from the leftmost one:
 
-    - Prefix is initialized with the source unit name of the importing source unit.
-    - The last path segment with preceding slashes is removed from the prefix.
-    - Then, the leading part of the normalized import path, consisting only of ``/`` and ``.``
-      characters is considered.
-      For every ``..`` segment found in this part the last path segment with preceding slashes is
-      removed from the prefix.
-
-2. Then the prefix is prepended to the normalized import path.
-   If the prefix is non-empty, a single slash is inserted between it and the import path.
+    - If the segment is ``.``, it is skipped.
+    - If the segment is ``..``, the last path segment with preceding slashes is removed from the resolved name.
+    - Otherwise, the segment (preceded by a single slash if the resolved name is not empty), is appended to the resolved name.
 
 The removal of the last path segment with preceding slashes is understood to
 work as follows:
@@ -268,14 +264,10 @@ work as follows:
 1. Everything past the last slash is removed (i.e. ``a/b//c.sol`` becomes ``a/b//``).
 2. All trailing slashes are removed (i.e. ``a/b//`` becomes ``a/b``).
 
-The normalization rules are the same as for UNIX paths, namely:
-
-- All the internal ``.`` segments are removed.
-- Every internal ``..`` segment backtracks one level up in the hierarchy.
-- Multiple slashes are squashed into a single one.
-
-Note that normalization is performed only on the import path.
-The source unit name of the importing module that is used for the prefix remains unnormalized.
+Note that the process normalizes the part of the resolved source unit name that comes from the import path according
+to the usual rules for UNIX paths, i.e. all ``.`` and ``..`` are removed and multiple slashes are
+squashed into a single one.
+On the other hand, the part that comes from the source unit name of the importing module remains unnormalized.
 This ensures that the ``protocol://`` part does not turn into ``protocol:/`` if the importing file
 is identified with a URL.
 
@@ -353,13 +345,13 @@ of the compiler.
 CLI Path Normalization and Stripping
 ------------------------------------
 
-On the command line the compiler behaves just as you would expect from any other program:
+On the command-line the compiler behaves just as you would expect from any other program:
 it accepts paths in a format native to the platform and relative paths are relative to the current
 working directory.
-The source unit names assigned to files whose paths are specified on the command line, however,
+The source unit names assigned to files whose paths are specified on the command-line, however,
 should not change just because the project is being compiled on a different platform or because the
 compiler happens to have been invoked from a different directory.
-To achieve this, paths to source files coming from the command line must be converted to a canonical
+To achieve this, paths to source files coming from the command-line must be converted to a canonical
 form, and, if possible, made relative to the base path or one of the include paths.
 
 The normalization rules are as follows:
@@ -416,7 +408,7 @@ The resulting file path becomes the source unit name.
     Prior to version 0.8.8, CLI path stripping was not performed and the only normalization applied
     was the conversion of path separators.
     When working with older versions of the compiler it is recommended to invoke the compiler from
-    the base path and to only use relative paths on the command line.
+    the base path and to only use relative paths on the command-line.
 
 .. index:: ! allowed paths, ! --allow-paths, remapping; target
 .. _allowed-paths:
@@ -429,7 +421,7 @@ locations that are considered safe by default:
 
 - Outside of Standard JSON mode:
 
-  - The directories containing input files listed on the command line.
+  - The directories containing input files listed on the command-line.
   - The directories used as :ref:`remapping <import-remapping>` targets.
     If the target is not a directory (i.e does not end with ``/``, ``/.`` or ``/..``) the directory
     containing the target is used instead.
@@ -523,7 +515,7 @@ you can use the following in your source file:
 
 The compiler will look for the file in the VFS under ``dapp-bin/library/math.sol``.
 If the file is not available there, the source unit name will be passed to the Host Filesystem
-Loader, which will then look in ``/project/dapp-bin/library/iterable_mapping.sol``.
+Loader, which will then look in ``/project/dapp-bin/library/math.sol``.
 
 .. warning::
 
@@ -559,7 +551,7 @@ you checked out to ``/project/dapp-bin_old``, then you can run:
 This means that all imports in ``module2`` point to the old version but imports in ``module1``
 point to the new version.
 
-Here are the detailed rules governing the behaviour of remappings:
+Here are the detailed rules governing the behavior of remappings:
 
 #. **Remappings only affect the translation between import paths and source unit names.**
 

docs/requirements.txt

@@ -4,7 +4,7 @@
 sphinx_rtd_theme>=0.5.2
 
 pygments-lexer-solidity>=0.7.0
-sphinx-a4doc>=1.2.1
+sphinx-a4doc>=1.6.0
 
 # Sphinx 2.1.0 is the oldest version that accepts a lexer class in add_lexer()
-sphinx>=2.1.0
+sphinx>=2.1.0, <6.0

docs/resources.rst

@@ -23,12 +23,12 @@ Integrated (Ethereum) Development Environments
         Python-based development and testing framework for smart contracts targeting the Ethereum Virtual Machine.
 
     * `Dapp <https://dapp.tools/>`_
-        Tool for building, testing and deploying smart contracts from the command line.
+        Tool for building, testing and deploying smart contracts from the command-line.
 
     * `Embark <https://framework.embarklabs.io/>`_
         Developer platform for building and deploying decentralized applications.
 
-    * `Foundry <https://github.com/gakonst/foundry>`_
+    * `Foundry <https://github.com/foundry-rs/foundry>`_
         Fast, portable and modular toolkit for Ethereum application development written in Rust.
 
     * `Hardhat <https://hardhat.org/>`_
@@ -37,23 +37,12 @@ Integrated (Ethereum) Development Environments
     * `Remix <https://remix.ethereum.org/>`_
         Browser-based IDE with integrated compiler and Solidity runtime environment without server-side components.
 
-    * `Truffle <https://www.trufflesuite.com/truffle>`_
+    * `Truffle <https://trufflesuite.com/truffle/>`_
         Ethereum development framework.
 
 Editor Integrations
 ===================
 
-* Atom
-
-    * `Etheratom <https://github.com/0mkara/etheratom>`_
-        Plugin for the Atom editor that features syntax highlighting, compilation and a runtime environment (Backend node & VM compatible).
-
-    * `Atom Solidity Linter <https://atom.io/packages/linter-solidity>`_
-        Plugin for the Atom editor that provides Solidity linting.
-
-    * `Atom Solium Linter <https://atom.io/packages/linter-solium>`_
-        Configurable Solidity linter for Atom using Solium (now Ethlint) as a base.
-
 * Emacs
 
     * `Emacs Solidity <https://github.com/ethereum/emacs-solidity/>`_
@@ -61,30 +50,42 @@ Editor Integrations
 
 * IntelliJ
 
-    * `IntelliJ IDEA plugin <https://plugins.jetbrains.com/plugin/9475-intellij-solidity>`_
-        Solidity plugin for IntelliJ IDEA (and all other JetBrains IDEs)
+    * `IntelliJ IDEA plugin <https://plugins.jetbrains.com/plugin/9475-solidity/>`_
+        Solidity plugin for IntelliJ IDEA (and all other JetBrains IDEs).
 
-* Sublime
+* Sublime Text
 
     * `Package for SublimeText - Solidity language syntax <https://packagecontrol.io/packages/Ethereum/>`_
         Solidity syntax highlighting for SublimeText editor.
 
 * Vim
 
-    * `Vim Solidity <https://github.com/tomlion/vim-solidity/>`_
-        Plugin for the Vim editor providing syntax highlighting.
+    * `Vim Solidity by Thesis <https://github.com/thesis/vim-solidity/>`_
+        Syntax highlighting for Solidity in Vim.
+
+    * `Vim Solidity by TovarishFin <https://github.com/TovarishFin/vim-solidity>`_
+        Vim syntax file for Solidity.
 
     * `Vim Syntastic <https://github.com/vim-syntastic/syntastic>`_
         Plugin for the Vim editor providing compile checking.
 
-* Visual Studio Code
+* Visual Studio Code (VS Code)
 
-    * `Visual Studio Code extension <https://juan.blanco.ws/solidity-contracts-in-visual-studio-code/>`_
+    * `Ethereum Remix Visual Studio Code extension <https://github.com/ethereum/remix-vscode>`_
+        Ethereum Remix extension pack for VS Code
+
+    * `Solidity Visual Studio Code extension, by Juan Blanco <https://juan.blanco.ws/solidity-contracts-in-visual-studio-code/>`_
         Solidity plugin for Microsoft Visual Studio Code that includes syntax highlighting and the Solidity compiler.
 
+    * `Solidity Visual Studio Code extension, by Nomic Foundation <https://marketplace.visualstudio.com/items?itemName=NomicFoundation.hardhat-solidity>`_
+        Solidity and Hardhat support by the Hardhat team, including: syntax highlighting, jump to definition, renames, quick fixes and inline solc warnings and errors.
+
     * `Solidity Visual Auditor extension <https://marketplace.visualstudio.com/items?itemName=tintinweb.solidity-visual-auditor>`_
         Adds security centric syntax and semantic highlighting to Visual Studio Code.
 
+    * `Truffle for VS Code <https://marketplace.visualstudio.com/items?itemName=trufflesuite-csi.truffle-vscode>`_
+        Build, debug and deploy smart contracts on Ethereum and EVM-compatible blockchains.
+
 Solidity Tools
 ==============
 
@@ -112,9 +113,6 @@ Solidity Tools
 * `leafleth <https://github.com/clemlak/leafleth>`_
     A documentation generator for Solidity smart-contracts.
 
-* `PIET <https://piet.slock.it/>`_
-    A tool to develop, audit and use Solidity smart contracts through a simple graphical interface.
-
 * `Scaffold-ETH <https://github.com/scaffold-eth/scaffold-eth>`_
     Forkable Ethereum development stack focused on fast product iterations.
 

docs/security-considerations.rst

@@ -7,28 +7,28 @@ Security Considerations
 While it is usually quite easy to build software that works as expected,
 it is much harder to check that nobody can use it in a way that was **not** anticipated.
 
-In Solidity, this is even more important because you can use smart contracts
-to handle tokens or, possibly, even more valuable things. Furthermore, every
-execution of a smart contract happens in public and, in addition to that,
-the source code is often available.
+In Solidity, this is even more important because you can use smart contracts to handle tokens or,
+possibly, even more valuable things.
+Furthermore, every execution of a smart contract happens in public and,
+in addition to that, the source code is often available.
 
-Of course you always have to consider how much is at stake:
-You can compare a smart contract with a web service that is open to the
-public (and thus, also to malicious actors) and perhaps even open source.
-If you only store your grocery list on that web service, you might not have
-to take too much care, but if you manage your bank account using that web service,
-you should be more careful.
+Of course, you always have to consider how much is at stake:
+You can compare a smart contract with a web service that is open to the public
+(and thus, also to malicious actors) and perhaps even open-source.
+If you only store your grocery list on that web service, you might not have to take too much care,
+but if you manage your bank account using that web service, you should be more careful.
 
-This section will list some pitfalls and general security recommendations but
-can, of course, never be complete.  Also, keep in mind that even if your smart
-contract code is bug-free, the compiler or the platform itself might have a
-bug. A list of some publicly known security-relevant bugs of the compiler can
-be found in the :ref:`list of known bugs<known_bugs>`, which is also
-machine-readable. Note that there is a bug bounty program that covers the code
-generator of the Solidity compiler.
+This section will list some pitfalls and general security recommendations
+but can, of course, never be complete.
+Also, keep in mind that even if your smart contract code is bug-free,
+the compiler or the platform itself might have a bug.
+A list of some publicly known security-relevant bugs of the compiler can be found
+in the :ref:`list of known bugs<known_bugs>`, which is also machine-readable.
+Note that there is a `Bug Bounty Program <https://ethereum.org/en/bug-bounty/>`_
+that covers the code generator of the Solidity compiler.
 
-As always, with open source documentation, please help us extend this section
-(especially, some examples would not hurt)!
+As always, with open-source documentation,
+please help us extend this section (especially, some examples would not hurt)!
 
 NOTE: In addition to the list below, you can find more security recommendations and best practices
 `in Guy Lando's knowledge list <https://github.com/guylando/KnowledgeLists/blob/master/EthereumSmartContracts.md>`_ and
@@ -41,20 +41,18 @@ Pitfalls
 Private Information and Randomness
 ==================================
 
-Everything you use in a smart contract is publicly visible, even
-local variables and state variables marked ``private``.
+Everything you use in a smart contract is publicly visible,
+even local variables and state variables marked ``private``.
 
-Using random numbers in smart contracts is quite tricky if you do not want
-miners to be able to cheat.
+Using random numbers in smart contracts is quite tricky if you do not want block builders to be able to cheat.
 
-Re-Entrancy
-===========
+Reentrancy
+==========
 
-Any interaction from a contract (A) with another contract (B) and any transfer
-of Ether hands over control to that contract (B). This makes it possible for B
-to call back into A before this interaction is completed. To give an example,
-the following code contains a bug (it is just a snippet and not a
-complete contract):
+Any interaction from a contract (A) with another contract (B)
+and any transfer of Ether hands over control to that contract (B).
+This makes it possible for B to call back into A before this interaction is completed.
+To give an example, the following code contains a bug (it is just a snippet and not a complete contract):
 
 .. code-block:: solidity
 
@@ -72,12 +70,12 @@ complete contract):
         }
     }
 
-The problem is not too serious here because of the limited gas as part
-of ``send``, but it still exposes a weakness: Ether transfer can always
-include code execution, so the recipient could be a contract that calls
-back into ``withdraw``. This would let it get multiple refunds and
-basically retrieve all the Ether in the contract. In particular, the
-following contract will allow an attacker to refund multiple times
+The problem is not too serious here because of the limited gas as part of ``send``,
+but it still exposes a weakness:
+Ether transfer can always include code execution,
+so the recipient could be a contract that calls back into ``withdraw``.
+This would let it get multiple refunds and, basically, retrieve all the Ether in the contract.
+In particular, the following contract will allow an attacker to refund multiple times
 as it uses ``call`` which forwards all remaining gas by default:
 
 .. code-block:: solidity
@@ -97,8 +95,7 @@ as it uses ``call`` which forwards all remaining gas by default:
         }
     }
 
-To avoid re-entrancy, you can use the Checks-Effects-Interactions pattern as
-outlined further below:
+To avoid reentrancy, you can use the Checks-Effects-Interactions pattern as demonstrated below:
 
 .. code-block:: solidity
 
@@ -116,51 +113,58 @@ outlined further below:
         }
     }
 
-Note that re-entrancy is not only an effect of Ether transfer but of any
-function call on another contract. Furthermore, you also have to take
-multi-contract situations into account. A called contract could modify the
-state of another contract you depend on.
+The Checks-Effects-Interactions pattern ensures that all code paths through a contract
+complete all required checks of the supplied parameters before modifying the contract's state (Checks);
+only then it makes any changes to the state (Effects);
+it may make calls to functions in other contracts
+*after* all planned state changes have been written to storage (Interactions).
+This is a common foolproof way to prevent *reentrancy attacks*,
+where an externally called malicious contract can double-spend an allowance,
+double-withdraw a balance, among other things,
+by using logic that calls back into the original contract before it has finalized its transaction.
+
+Note that reentrancy is not only an effect of Ether transfer
+but of any function call on another contract.
+Furthermore, you also have to take multi-contract situations into account.
+A called contract could modify the state of another contract you depend on.
 
 Gas Limit and Loops
 ===================
 
-Loops that do not have a fixed number of iterations, for example, loops that depend on storage values, have to be used carefully:
-Due to the block gas limit, transactions can only consume a certain amount of gas. Either explicitly or just due to
-normal operation, the number of iterations in a loop can grow beyond the block gas limit which can cause the complete
-contract to be stalled at a certain point. This may not apply to ``view`` functions that are only executed
-to read data from the blockchain. Still, such functions may be called by other contracts as part of on-chain operations
-and stall those. Please be explicit about such cases in the documentation of your contracts.
+Loops that do not have a fixed number of iterations, for example,
+loops that depend on storage values, have to be used carefully:
+Due to the block gas limit, transactions can only consume a certain amount of gas.
+Either explicitly or just due to normal operation,
+the number of iterations in a loop can grow beyond the block gas limit
+which can cause the complete contract to be stalled at a certain point.
+This may not apply to ``view`` functions that are only executed to read data from the blockchain.
+Still, such functions may be called by other contracts as part of on-chain operations and stall those.
+Please be explicit about such cases in the documentation of your contracts.
 
 Sending and Receiving Ether
 ===========================
 
-- Neither contracts nor "external accounts" are currently able to prevent that someone sends them Ether.
-  Contracts can react on and reject a regular transfer, but there are ways
-  to move Ether without creating a message call. One way is to simply "mine to"
-  the contract address and the second way is using ``selfdestruct(x)``.
+- Neither contracts nor "external accounts" are currently able to prevent someone from sending them Ether.
+  Contracts can react on and reject a regular transfer, but there are ways to move Ether without creating a message call.
+  One way is to simply "mine to" the contract address and the second way is using ``selfdestruct(x)``.
 
-- If a contract receives Ether (without a function being called),
-  either the :ref:`receive Ether <receive-ether-function>`
+- If a contract receives Ether (without a function being called), either the :ref:`receive Ether <receive-ether-function>`
   or the :ref:`fallback <fallback-function>` function is executed.
-  If it does not have a receive nor a fallback function, the Ether will be
-  rejected (by throwing an exception). During the execution of one of these
-  functions, the contract can only rely on the "gas stipend" it is passed (2300
-  gas) being available to it at that time. This stipend is not enough to modify
-  storage (do not take this for granted though, the stipend might change with
-  future hard forks). To be sure that your contract can receive Ether in that
-  way, check the gas requirements of the receive and fallback functions
+  If it does not have a ``receive`` nor a ``fallback`` function, the Ether will be rejected (by throwing an exception).
+  During the execution of one of these functions, the contract can only rely on the "gas stipend" it is passed (2300 gas)
+  being available to it at that time.
+  This stipend is not enough to modify storage (do not take this for granted though, the stipend might change with future hard forks).
+  To be sure that your contract can receive Ether in that way, check the gas requirements of the receive and fallback functions
   (for example in the "details" section in Remix).
 
-- There is a way to forward more gas to the receiving contract using
-  ``addr.call{value: x}("")``. This is essentially the same as ``addr.transfer(x)``,
-  only that it forwards all remaining gas and opens up the ability for the
-  recipient to perform more expensive actions (and it returns a failure code
-  instead of automatically propagating the error). This might include calling back
-  into the sending contract or other state changes you might not have thought of.
+- There is a way to forward more gas to the receiving contract using ``addr.call{value: x}("")``.
+  This is essentially the same as ``addr.transfer(x)``, only that it forwards all remaining gas
+  and opens up the ability for the recipient to perform more expensive actions
+  (and it returns a failure code instead of automatically propagating the error).
+  This might include calling back into the sending contract or other state changes you might not have thought of.
   So it allows for great flexibility for honest users but also for malicious actors.
 
-- Use the most precise units to represent the wei amount as possible, as you lose
-  any that is rounded due to a lack of precision.
+- Use the most precise units to represent the Wei amount as possible, as you lose any that is rounded due to a lack of precision.
 
 - If you want to send Ether using ``address.transfer``, there are certain details to be aware of:
 
@@ -184,24 +188,28 @@ Sending and Receiving Ether
 Call Stack Depth
 ================
 
-External function calls can fail any time because they exceed the maximum
-call stack size limit of 1024. In such situations, Solidity throws an exception.
+External function calls can fail at any time
+because they exceed the maximum call stack size limit of 1024.
+In such situations, Solidity throws an exception.
 Malicious actors might be able to force the call stack to a high value
-before they interact with your contract. Note that, since `Tangerine Whistle <https://eips.ethereum.org/EIPS/eip-608>`_ hardfork, the `63/64 rule <https://eips.ethereum.org/EIPS/eip-150>`_ makes call stack depth attack impractical. Also note that the call stack and the expression stack are unrelated, even though both have a size limit of 1024 stack slots.
+before they interact with your contract.
+Note that, since `Tangerine Whistle <https://eips.ethereum.org/EIPS/eip-608>`_ hardfork,
+the `63/64 rule <https://eips.ethereum.org/EIPS/eip-150>`_ makes call stack depth attack impractical.
+Also note that the call stack and the expression stack are unrelated,
+even though both have a size limit of 1024 stack slots.
 
-Note that ``.send()`` does **not** throw an exception if the call stack is
-depleted but rather returns ``false`` in that case. The low-level functions
-``.call()``, ``.delegatecall()`` and ``.staticcall()`` behave in the same way.
+Note that ``.send()`` does **not** throw an exception if the call stack is depleted
+but rather returns ``false`` in that case.
+The low-level functions ``.call()``, ``.delegatecall()`` and ``.staticcall()`` behave in the same way.
 
 Authorized Proxies
 ==================
 
-If your contract can act as a proxy, i.e. if it can call arbitrary contracts
-with user-supplied data, then the user can essentially assume the identity
-of the proxy contract. Even if you have other protective measures in place,
-it is best to build your contract system such that the proxy does not have
-any permissions (not even for itself). If needed, you can accomplish that
-using a second proxy:
+If your contract can act as a proxy, i.e. if it can call arbitrary contracts with user-supplied data,
+then the user can essentially assume the identity of the proxy contract.
+Even if you have other protective measures in place, it is best to build your contract system such
+that the proxy does not have any permissions (not even for itself).
+If needed, you can accomplish that using a second proxy:
 
 .. code-block:: solidity
 
@@ -229,7 +237,8 @@ using a second proxy:
 tx.origin
 =========
 
-Never use tx.origin for authorization. Let's say you have a wallet contract like this:
+Never use ``tx.origin`` for authorization.
+Let's say you have a wallet contract like this:
 
 .. code-block:: solidity
 
@@ -272,7 +281,11 @@ Now someone tricks you into sending Ether to the address of this attack wallet:
         }
     }
 
-If your wallet had checked ``msg.sender`` for authorization, it would get the address of the attack wallet, instead of the owner address. But by checking ``tx.origin``, it gets the original address that kicked off the transaction, which is still the owner address. The attack wallet instantly drains all your funds.
+If your wallet had checked ``msg.sender`` for authorization, it would get the address of the attack wallet,
+instead of the owner's address.
+But by checking ``tx.origin``, it gets the original address that kicked off the transaction,
+which is still the owner's address.
+The attack wallet instantly drains all your funds.
 
 .. _underflow-overflow:
 
@@ -312,16 +325,14 @@ Try to use ``require`` to limit the size of inputs to a reasonable range and use
 Clearing Mappings
 =================
 
-The Solidity type ``mapping`` (see :ref:`mapping-types`) is a storage-only
-key-value data structure that does not keep track of the keys that were
-assigned a non-zero value.  Because of that, cleaning a mapping without extra
-information about the written keys is not possible.
-If a ``mapping`` is used as the base type of a dynamic storage array, deleting
-or popping the array will have no effect over the ``mapping`` elements.  The
-same happens, for example, if a ``mapping`` is used as the type of a member
-field of a ``struct`` that is the base type of a dynamic storage array.  The
-``mapping`` is also ignored in assignments of structs or arrays containing a
-``mapping``.
+The Solidity type ``mapping`` (see :ref:`mapping-types`) is a storage-only key-value data structure
+that does not keep track of the keys that were assigned a non-zero value.
+Because of that, cleaning a mapping without extra information about the written keys is not possible.
+If a ``mapping`` is used as the base type of a dynamic storage array,
+deleting or popping the array will have no effect over the ``mapping`` elements.
+The same happens, for example, if a ``mapping`` is used as the type of a member field of a ``struct``
+that is the base type of a dynamic storage array.
+The ``mapping`` is also ignored in assignments of structs or arrays containing a ``mapping``.
 
 .. code-block:: solidity
 
@@ -329,7 +340,7 @@ field of a ``struct`` that is the base type of a dynamic storage array.  The
     pragma solidity >=0.6.0 <0.9.0;
 
     contract Map {
-        mapping (uint => uint)[] array;
+        mapping(uint => uint)[] array;
 
         function allocate(uint newMaps) public {
             for (uint i = 0; i < newMaps; i++)
@@ -349,15 +360,12 @@ field of a ``struct`` that is the base type of a dynamic storage array.  The
         }
     }
 
-Consider the example above and the following sequence of calls: ``allocate(10)``,
-``writeMap(4, 128, 256)``.
+Consider the example above and the following sequence of calls: ``allocate(10)``, ``writeMap(4, 128, 256)``.
 At this point, calling ``readMap(4, 128)`` returns 256.
-If we call ``eraseMaps``, the length of state variable ``array`` is zeroed, but
-since its ``mapping`` elements cannot be zeroed, their information stays alive
-in the contract's storage.
-After deleting ``array``, calling ``allocate(5)`` allows us to access
-``array[4]`` again, and calling ``readMap(4, 128)`` returns 256 even without
-another call to ``writeMap``.
+If we call ``eraseMaps``, the length of the state variable ``array`` is zeroed,
+but since its ``mapping`` elements cannot be zeroed, their information stays alive in the contract's storage.
+After deleting ``array``, calling ``allocate(5)`` allows us to access ``array[4]`` again,
+and calling ``readMap(4, 128)`` returns 256 even without another call to ``writeMap``.
 
 If your ``mapping`` information must be deleted, consider using a library similar to
 `iterable mapping <https://github.com/ethereum/dapp-bin/blob/master/library/iterable_mapping.sol>`_,
@@ -368,10 +376,11 @@ Minor Details
 
 - Types that do not occupy the full 32 bytes might contain "dirty higher order bits".
   This is especially important if you access ``msg.data`` - it poses a malleability risk:
-  You can craft transactions that call a function ``f(uint8 x)`` with a raw byte argument
-  of ``0xff000001`` and with ``0x00000001``. Both are fed to the contract and both will
-  look like the number ``1`` as far as ``x`` is concerned, but ``msg.data`` will
-  be different, so if you use ``keccak256(msg.data)`` for anything, you will get different results.
+  You can craft transactions that call a function ``f(uint8 x)``
+  with a raw byte argument of ``0xff000001`` and with ``0x00000001``.
+  Both are fed to the contract and both will look like the number ``1`` as far as ``x`` is concerned,
+  but ``msg.data`` will be different, so if you use ``keccak256(msg.data)`` for anything,
+  you will get different results.
 
 ***************
 Recommendations
@@ -381,48 +390,45 @@ Take Warnings Seriously
 =======================
 
 If the compiler warns you about something, you should change it.
-Even if you do not think that this particular warning has security
-implications, there might be another issue buried beneath it.
-Any compiler warning we issue can be silenced by slight changes to the
-code.
+Even if you do not think that this particular warning has security implications,
+there might be another issue buried beneath it.
+Any compiler warning we issue can be silenced by slight changes to the code.
 
-Always use the latest version of the compiler to be notified about all recently
-introduced warnings.
+Always use the latest version of the compiler to be notified about all recently introduced warnings.
 
-Messages of type ``info`` issued by the compiler are not dangerous, and simply
-represent extra suggestions and optional information that the compiler thinks
-might be useful to the user.
+Messages of type ``info``, issued by the compiler, are not dangerous
+and simply represent extra suggestions and optional information
+that the compiler thinks might be useful to the user.
 
 Restrict the Amount of Ether
 ============================
 
-Restrict the amount of Ether (or other tokens) that can be stored in a smart
-contract. If your source code, the compiler or the platform has a bug, these
-funds may be lost. If you want to limit your loss, limit the amount of Ether.
+Restrict the amount of Ether (or other tokens) that can be stored in a smart contract.
+If your source code, the compiler or the platform has a bug, these funds may be lost.
+If you want to limit your loss, limit the amount of Ether.
 
 Keep it Small and Modular
 =========================
 
-Keep your contracts small and easily understandable. Single out unrelated
-functionality in other contracts or into libraries. General recommendations
-about source code quality of course apply: Limit the amount of local variables,
-the length of functions and so on. Document your functions so that others
-can see what your intention was and whether it is different than what the code does.
+Keep your contracts small and easily understandable.
+Single out unrelated functionality in other contracts or into libraries.
+General recommendations about the source code quality of course apply:
+Limit the amount of local variables, the length of functions and so on.
+Document your functions so that others can see what your intention was
+and whether it is different than what the code does.
 
 Use the Checks-Effects-Interactions Pattern
 ===========================================
 
-Most functions will first perform some checks (who called the function,
-are the arguments in range, did they send enough Ether, does the person
-have tokens, etc.). These checks should be done first.
+Most functions will first perform some checks and they should be done first
+(who called the function, are the arguments in range, did they send enough Ether,
+does the person have tokens, etc.).
 
-As the second step, if all checks passed, effects to the state variables
-of the current contract should be made. Interaction with other contracts
-should be the very last step in any function.
+As the second step, if all checks passed, effects to the state variables of the current contract should be made.
+Interaction with other contracts should be the very last step in any function.
 
-Early contracts delayed some effects and waited for external function
-calls to return in a non-error state. This is often a serious mistake
-because of the re-entrancy problem explained above.
+Early contracts delayed some effects and waited for external function calls to return in a non-error state.
+This is often a serious mistake because of the reentrancy problem explained above.
 
 Note that, also, calls to known contracts might in turn cause calls to
 unknown contracts, so it is probably better to just always apply this pattern.
@@ -430,24 +436,23 @@ unknown contracts, so it is probably better to just always apply this pattern.
 Include a Fail-Safe Mode
 ========================
 
-While making your system fully decentralised will remove any intermediary,
-it might be a good idea, especially for new code, to include some kind
-of fail-safe mechanism:
+While making your system fully decentralized will remove any intermediary,
+it might be a good idea, especially for new code, to include some kind of fail-safe mechanism:
 
-You can add a function in your smart contract that performs some
-self-checks like "Has any Ether leaked?",
+You can add a function in your smart contract that performs some self-checks like "Has any Ether leaked?",
 "Is the sum of the tokens equal to the balance of the contract?" or similar things.
-Keep in mind that you cannot use too much gas for that, so help through off-chain
-computations might be needed there.
+Keep in mind that you cannot use too much gas for that,
+so help through off-chain computations might be needed there.
 
-If the self-check fails, the contract automatically switches into some kind
-of "failsafe" mode, which, for example, disables most of the features, hands over
-control to a fixed and trusted third party or just converts the contract into
-a simple "give me back my money" contract.
+If the self-check fails, the contract automatically switches into some kind of "failsafe" mode,
+which, for example, disables most of the features,
+hands over control to a fixed and trusted third party
+or just converts the contract into a simple "give me back my Ether" contract.
 
 Ask for Peer Review
 ===================
 
 The more people examine a piece of code, the more issues are found.
-Asking people to review your code also helps as a cross-check to find out whether your code
-is easy to understand - a very important criterion for good smart contracts.
+Asking people to review your code also helps as a cross-check to find out
+whether your code is easy to understand -
+a very important criterion for good smart contracts.